@evoke-build/evoke 0.6.0

package/dist/types.d.ts

@@ -0,0 +1,1363 @@
+/** A `Result` on the wire: `{ ok }` or `{ err }`. */
+export type Result<T, E> = {
+    ok: T;
+} | {
+    err: E;
+};
+/** Text that cannot repaint a terminal: no C0 or C1 control but the line feed, no bidi control. */
+export type Clean = string;
+/** What a person typed: NFC, at most 2 000 characters, spelling kept; untrusted, never cleaned — only its spans are. */
+export type Input = string;
+/** What keys a record: NFC, lower-cased, whitespace collapsed and trimmed, terminal punctuation dropped; the core normalizes any string it is handed as one. */
+export type Identity = string;
+/** An utterance as written, with its identity: the text is what the classifier reads, the id what keys it. */
+export interface Utterance {
+    /** One non-empty line. */
+    text: Clean;
+    /** The identity of `text`; anything else is refused. */
+    id: Identity;
+}
+/** A verbatim piece of one input: character offsets, `start < end`, and the text between them. */
+export interface Span {
+    start: number;
+    end: number;
+    text: Clean;
+}
+/** A list that refuses to be empty; on the wire, a plain array — never `[]`. */
+export type NonEmpty<T> = [T, ...T[]];
+/** The `[reflexes]` key, the overlay's file name, a route option: `[a-z][a-z0-9_]*`, never `none`, `unstated`, `fits` or `weave`. */
+export type LocalName = string;
+/** An argument: `[a-z][a-z0-9_]*`, never a JavaScript reserved word, so a body can destructure it. */
+export type ArgName = string;
+/** An option's key, which the body receives: one clean line, never `none` or `unstated`. */
+export type OptionKey = string;
+/** A vocabulary word: one clean line, trimmed, never `none` or `unstated`; spaces allowed. */
+export type Word = string;
+/** A vocabulary, `vocab/<name>.toml`: `[a-z][a-z0-9_]*`. */
+export type VocabName = string;
+/** A key under `[config]`: `[a-z][a-z0-9_]*`. */
+export type ConfigKey = string;
+/** A field of a result's `data`, as `[yields]` names it: `[a-z][a-z0-9_]*`. */
+export type FieldName = string;
+/** A scope for `--tag`: `[a-z][a-z0-9_]*`. */
+export type Tag = string;
+/** An adapter, by the name it is resolved under: `[a-z][a-z0-9_]*`. */
+export type AdapterName = string;
+/** What an adapter declares itself as: non-empty; compared, never parsed. */
+export type AdapterId = string;
+/** An environment variable: `[A-Za-z_][A-Za-z0-9_]*`. */
+export type VarName = string;
+/** A path inside one reflex directory: relative, plain segments, no `..`. */
+export type RelPath = string;
+/** A `{name}` in `[needs]`: an argument or a config key, whose value fills the entry at the decision. */
+export type ValueName = string;
+/** An absolute path as `[needs]` names one: `/`, or plain segments under it, no `.` or `..`. */
+export type AbsPath = string;
+/** A GitHub owner, user or organization: `[A-Za-z0-9][A-Za-z0-9-]*`. */
+export type Owner = string;
+/** One segment of a ref: `[A-Za-z0-9._][A-Za-z0-9._-]*`, never option-shaped. */
+export type Segment = string;
+/** A problem a person has to fix, ending in the command that fixes it. */
+export interface Diagnostic {
+    /** The reflex the problem belongs to, when it belongs to one. */
+    reflex?: LocalName;
+    /** The line, when the file has lines; a JSON document has none and fixes with `check`. */
+    at?: At;
+    message: string;
+    fix: Fix;
+}
+/** A line of an owned file. */
+export interface At {
+    file: File;
+    line: number;
+    column: number;
+}
+/** One of the project's owned files, by role; it displays as its project-relative path. */
+export type File = {
+    type: "manifest";
+    name: LocalName;
+} | {
+    type: "overlay";
+    name: LocalName;
+} | {
+    type: "vocab";
+    name: VocabName;
+} | {
+    type: "project";
+} | {
+    type: "lock";
+};
+/** The closed set of fixing commands, each rendered as the literal last line of a diagnostic. */
+export type Fix = {
+    type: "vocab_add";
+    vocab: VocabName;
+} | {
+    type: "vocab_remove";
+    vocab: VocabName;
+} | {
+    type: "vocab";
+    vocab: VocabName;
+} | {
+    type: "config_set";
+    reflex: LocalName;
+    key: ConfigKey;
+} | {
+    type: "config_env";
+    reflex: LocalName;
+    key: ConfigKey;
+} | {
+    type: "update";
+    reflex?: LocalName;
+} | {
+    type: "accept";
+    reflex: LocalName;
+} | {
+    type: "trust";
+} | {
+    type: "remove";
+    reflex: LocalName;
+} | {
+    type: "sync";
+} | {
+    type: "check";
+} | {
+    type: "edit_line";
+    at: At;
+} | {
+    type: "export_key";
+    var: VarName;
+} | {
+    type: "rerun";
+} | {
+    type: "add";
+} | {
+    type: "show";
+    reflex?: LocalName;
+} | {
+    type: "add_ref";
+    reference: string;
+    name?: LocalName;
+} | {
+    type: "add_refs";
+    references: string[];
+} | {
+    type: "teach_not";
+    utterance: string;
+    reflex: LocalName;
+} | {
+    type: "new";
+} | {
+    type: "test";
+} | {
+    type: "help";
+};
+/** A JSON value that keeps its key order: the wire form of every boundary type. */
+export type Json = unknown;
+/** A file to parse: its role, and its text as written — TOML, with lines — or as JSON, without. */
+export type Document = {
+    file: File;
+    toml: string;
+} | {
+    file: File;
+    json: Json;
+};
+/** Where in a file, by key: `["args", "state", "ask"]` is `args.state.ask`; a segment is verbatim, unescaped. */
+export type KeyPath = string[];
+/** A reflex's manifest, normalized: `effect` explicit, every table present, records typed. */
+export interface Manifest {
+    description: Description;
+    not_for: Clean[];
+    tags: Tag[];
+    effect: Effect;
+    confirm: Template;
+    /** Absent: inline, a function the SDK holds. */
+    run?: Run;
+    /** What the body may touch; absent, the tightest declaration. Contract, like `run`. */
+    needs?: Needs;
+    config: Record<ConfigKey, ConfigSpec>;
+    args: Record<ArgName, Argument>;
+    /** What the body's `data` yields for a later step to take, per field. */
+    yields: Record<FieldName, Yield>;
+    examples: Records;
+    tests: Records;
+    /** Keys the format does not know: reported, never fatal. */
+    unknown: KeyPath[];
+}
+/** What the reflex does: a summary line, never empty; the rest, when there is one, after a line feed. */
+export type Description = string;
+/** What running the reflex does to the world; greater is tighter: read < write < destructive. */
+export type Effect = "read" | "write" | "destructive";
+/** The confirm prompt: text with `{placeholder}`s, each naming a required, non-flag argument. */
+export type Template = string;
+/** The body: an entrypoint run in a child, or an argv that never touches a shell. */
+export type Run = Entrypoint | Argv;
+/** The program, a literal, then each element. */
+export type Argv = [program: Clean, ...rest: Element[]];
+/** A path inside the reflex directory ending in `.mts` or `.mjs`. */
+export type Entrypoint = RelPath;
+/** One argv element after the program: a literal as written, or an argument's `{name}` — never a flag's. */
+export type Element = string;
+/** A setting the user provides; a secret is set only from an environment variable. */
+export interface ConfigSpec {
+    about: Clean;
+    secret: boolean;
+}
+/** An argument: its question, where its values come from, and its former names. */
+export type Argument = {
+    ask: Clean;
+    /** Flat and cumulative; a retired name never returns. */
+    was: ArgName[];
+} & Kind;
+/** A flag, or a value with exactly one source; a flag is optional by nature. */
+export type Kind = {
+    flag: true;
+} | (Source & {
+    optional: boolean;
+});
+/** Where an argument's values come from: the author, the user or the input. */
+export type Source = {
+    options: Options;
+} | {
+    vocab: VocabName;
+} | Pick;
+/** The author's closed set, never empty: key = what the body receives, value = what it means. */
+export type Options = Record<OptionKey, Clean>;
+/** A built-in recognizer over the input; a range only where a number exists, whole seconds for a duration. */
+export type Pick = {
+    pick: "number" | "duration";
+    range?: Range;
+} | {
+    pick: "email" | "url" | "quoted";
+};
+/** One of the five recognizers, by the name a manifest's `pick` writes. */
+export type Recognizer = "number" | "duration" | "email" | "url" | "quoted";
+/** What a field of a body's `data` holds, for a later step to take: a value the recognizer reads, or a list of records with such fields. Contract. */
+export type Yield = Recognizer | {
+    each: Record<FieldName, Recognizer>;
+};
+/** `[min, max]` on a value, min ≤ max. */
+export type Range = [min: number, max: number];
+/** The declaration: four lists, each absent when empty. */
+export interface Needs {
+    reads?: Entry[];
+    writes?: Entry[];
+    /** `["*"]` for any host, else absent: a name is held by no kernel. */
+    hosts?: Hosts;
+    runs?: Program[];
+}
+/** One path the declaration names: `~/…`, `/…`, or `{name}`, the value of an argument or a config key. */
+export type Entry = string;
+/** Which hosts the body may reach: `[]` none, `["*"]` any. */
+export type Hosts = [] | ["*"];
+/** A program the body may run: a name found on `PATH`, or an absolute path. */
+export type Program = string;
+/** A key of the table, as a line names it. */
+export type NeedsKey = "reads" | "writes" | "hosts" | "runs";
+/** The declaration resolved at a decision: every path absolute, a `{name}` replaced by its value or dropped when unstated. Strings a host holds paths by. */
+export interface Policy {
+    reads?: Place[];
+    writes?: Place[];
+    hosts?: Hosts;
+    runs?: Program[];
+}
+/** A path the body may reach, and the entry it came from. */
+export interface Place {
+    path: string;
+    from: Entry;
+}
+/** Where a declaration comes from, so a fix lands where it is written: a local reflex's manifest at its `[needs]` line, or a fetched reflex, whose author's it is. */
+export type Origin = {
+    type: "local";
+    at: At;
+} | {
+    type: "fetched";
+};
+/** What the machine lacks that the declaration names: a path, or a program `PATH` does not hold. */
+export type Lacking = {
+    type: "place";
+    place: Place;
+    key: NeedsKey;
+} | {
+    type: "program";
+    program: Program;
+};
+/** What refused a body, as the loader reports it: Node's permission or the kernel's syscall, and the path. */
+export interface Refused {
+    what: string;
+    path: string;
+}
+/** What an update does to the needs a person consented to: upstream may keep or narrow them, and widens them only through `evoke update --accept`; `kept` is what the lock records meanwhile. */
+export type NeedsConsent = {
+    type: "kept";
+    needs: Needs;
+} | {
+    type: "tightened";
+    needs: Needs;
+    removed: Needs;
+} | {
+    type: "needs_accept";
+    locked: Needs;
+    upstream: Needs;
+};
+/** What the host knows that the policy does not: where things are. */
+export interface Facts {
+    platform: Platform;
+    /** The runtime a file body runs under; absent for an argv body. */
+    runtime?: Runtime;
+    /** The body's directory: readable, and its working directory. */
+    body_dir: string;
+    /** The private temporary folder made for the run, by its real path. */
+    tmp: string;
+    /** The home: the runtime's installation is readable whole unless that would be the home or above it. */
+    home: string;
+    /** Linux: the file `/etc/resolv.conf` really is when it links out of `/etc`. */
+    resolver?: string;
+    /** What the host found at each of the policy's paths, by the path as the policy spells it. */
+    found?: Record<string, Found>;
+    /** Where each program the policy names is, by the name as the policy spells it. */
+    programs?: Record<string, Executable>;
+}
+export type Platform = "linux" | "macos";
+/** The runtime a file body runs under: its program, as `process.execPath` names it, and whether its permission
+ *  model holds the network, which it does from Node 25, the first to know `--allow-net`. */
+export interface Runtime extends Executable {
+    holds_network?: boolean;
+}
+/** A program as the kernel runs it: its path, and the interpreters the kernel executes to run it. */
+export interface Executable {
+    path: string;
+    interpreters?: string[];
+}
+/** A path as the host found it: its real path, links followed, and whether it is a directory. */
+export interface Found {
+    real: string;
+    dir: boolean;
+}
+/** One Landlock rule: the path, and the rights beneath it. */
+export interface Rule {
+    path: string;
+    rights: Right[];
+}
+/** The file-system rights Landlock names. */
+export type Right = "execute" | "write_file" | "read_file" | "read_dir" | "remove_dir" | "remove_file" | "make_char" | "make_dir" | "make_reg" | "make_sock" | "make_fifo" | "make_block" | "make_sym" | "refer" | "truncate" | "ioctl_dev";
+/** Whether the machine holds the whole declaration: fully; partly, with what it does not hold; not at all, with why. */
+export type Contained = {
+    type: "full";
+} | {
+    type: "partial";
+    why: string;
+} | {
+    type: "none";
+    why: string;
+};
+/** Utterances, each with what it asserts; keyed by spelling, no two sharing an identity. */
+export type Records = Record<Clean, Asserted>;
+/** `false`, or the asserted arguments; `{}` asserts the route alone. */
+export type Asserted = false | Record<ArgName, Assertion>;
+/** One argument's assertion: `false` unstated, `true` a flag, else an option key, a word or a span of the utterance. */
+export type Assertion = boolean | OptionKey | Word | Clean;
+/** Your wording for one reflex, its names already resolved through `was`. Read, never built. */
+export interface Overlay {
+    description?: Description;
+    not_for?: Clean[];
+    tags?: Tag[];
+    effect?: Effect;
+    confirm?: Template;
+    args: Record<ArgName, Wording>;
+    examples: Records;
+    tests: Records;
+    /** Former names the file used, with the name each resolved to. */
+    renamed: [ArgName, ArgName][];
+    /** Keys that address nothing: skipped, the rest applies. */
+    orphaned: KeyPath[];
+}
+/** New wording for an argument: its question, and existing option keys. */
+export interface Wording {
+    ask?: Clean;
+    options: Record<OptionKey, Clean>;
+}
+/** `shipped ⊕ yours`, with the key paths your file decided: what `show` marks. */
+export interface Effective {
+    manifest: Manifest;
+    yours: KeyPath[];
+}
+/** What an update means for your file. */
+export interface Report {
+    renamed: [ArgName, ArgName][];
+    /** You override what upstream changed: yours wins, both are shown once. */
+    stale: KeyPath[];
+    orphaned: KeyPath[];
+}
+/** Your closed set for the arguments that name it; may be empty, which `compile` reports. */
+export type Vocabulary = Record<Word, Meaning>;
+/** What a word means, and what the body receives instead of it when set. */
+export interface Meaning {
+    what: Clean;
+    /** What the body receives instead of the word; never shown to the classifier. */
+    value?: string;
+}
+/** What you wrote: the adapter that decides, the reflexes you installed, their settings, the adapters' own tables. */
+export interface Project {
+    /** Always stated; a name, never a path. */
+    adapter: AdapterName;
+    reflexes: Record<LocalName, Location>;
+    config: Record<LocalName, Record<ConfigKey, Setting>>;
+    /** Inert unless selected; then its adapter validates it. */
+    adapters: Record<AdapterName, Json>;
+}
+/** Where a reflex comes from: a directory as written, resolved by the host, or a repository. */
+export type Location = {
+    type: "local";
+    path: string;
+} | {
+    type: "remote";
+    reference: Reference;
+    pin?: Version;
+};
+/** A repository and a directory in it. */
+export interface Reference {
+    repo: Repo;
+    dir?: RelPath;
+}
+/** A repository on GitHub, or by git URL. */
+export type Repo = {
+    type: "github";
+    owner: Owner;
+    name: Segment;
+} | {
+    type: "url";
+    url: GitUrl;
+};
+/** A git URL over an allow-listed scheme: `https` or `ssh`; a user may stand before the host; no `#` or
+ *  whitespace, and no `@` past the host. */
+export type GitUrl = string;
+/** A tag `[v]X.Y.Z`, printed without the `v`: `"1.2.0"`. */
+export type Version = string;
+/** A config value as you stored it: plain, or a reference to an environment variable. */
+export type Setting = {
+    type: "plain";
+    value: string;
+} | {
+    type: "env";
+    var: VarName;
+};
+/** What `add`, `update` and `remove` write whole and `sync` realises; a local reflex is never in it. */
+export interface Lock {
+    evoke: Version;
+    adapter: LockedAdapter;
+    reflexes: Record<LocalName, Locked>;
+}
+/** The adapter the lock was written under, by name and id. */
+export interface LockedAdapter {
+    name: AdapterName;
+    id: AdapterId;
+}
+/** One remote reflex as pinned; `needs` absent means none consented to. */
+export interface Locked {
+    reference: Reference;
+    tag: Version;
+    commit: Commit;
+    h1: Digest;
+    effect: Effect;
+    needs?: Needs;
+}
+/** A commit as git printed it: 40 or 64 lowercase hex; compared, never parsed. */
+export type Commit = string;
+/** A SHA-256, displayed and serialized as `h1:<hex>`. */
+export type Digest = string;
+/** A choice's key exactly as offered: an option key, a word, a candidate `<start>-<end>`, a flag's `yes` or `no`, a local name, `none` or `unstated`. The plan's slot gives it meaning at read. */
+export type Key = string;
+/** Which question: `route`, `fits.<reflex>`, `<reflex>.<argument>`, or `weave.<name>` — a question evoke asks on its own account beside the plan's. */
+export type QuestionId = string;
+/** One question for the adapter: a choice over keys, or a yes/no with both sides described. */
+export type Question = ({
+    type: "choice";
+} & Choice) | {
+    type: "yesno";
+    ask: Clean;
+    /** The reflex's description. */
+    yes: Text;
+    /** What the reflex is not for. */
+    no: Text;
+};
+/** A choice: the question, its options in order, and which key means "none of these". */
+export interface Choice {
+    ask: Clean;
+    options: Record<Key, Text>;
+    /** One of `options`; absent when the choice has no sentinel. */
+    otherwise?: Key;
+}
+/** What an option means: a line, or a description with what it is not for and examples that assert it. */
+export type Text = Clean | {
+    what: Clean;
+    /** Absent when empty. */
+    not_for?: Clean[];
+    /** Absent when empty. */
+    examples?: Clean[];
+};
+/** The only state an adapter ever sees. */
+export interface State {
+    request: Input;
+}
+/** One call of `answer`: the state, the questions, and the candidate spans the pick questions were built from. */
+export interface Request {
+    state: State;
+    questions: Record<QuestionId, Question>;
+    proposed: Proposed[];
+}
+/** A finite number in `[0, 1]`. */
+export type Prob = number;
+/** Per-call ceilings an adapter declares. */
+export interface Limits {
+    /** The most options one choice may offer; `compile` refuses a plan over it. */
+    options?: number;
+    /** The adapter's own token ceiling, declared for the record; nothing here enforces it. */
+    tokens?: number;
+}
+/** The floors an adapter ships, each meaning P(correct); `read` never above `write`, and no destructive number exists. */
+export interface Gate {
+    route: Prob;
+    /** The runner-up's floor; a plan without `fits` questions skips it. */
+    fits?: Prob;
+    read: Prob;
+    write: Prob;
+}
+/** What an adapter declares about itself. */
+export interface Declared {
+    id: AdapterId;
+    limits?: Limits;
+    gate?: Gate;
+}
+/** Answers as the adapter gave them: per question, a number per key. `read` validates them against their `Request`. */
+export type Raw = Record<QuestionId, Record<Key, number>>;
+/** How an adapter fails, or how its answers failed validation; each ends in a fixing command. */
+export type Fault = {
+    type: "transport";
+    message: string;
+} | {
+    type: "status";
+    status: number;
+} | {
+    type: "refused";
+    credential: VarName;
+} | {
+    type: "retired";
+    id: AdapterId;
+} | {
+    type: "unanswered";
+    question: QuestionId;
+} | {
+    type: "malformed";
+    question: QuestionId;
+    message: string;
+} | {
+    type: "unrecorded";
+    identity: Identity;
+};
+/** Everything the host found; `compile` alone judges activity. */
+export interface Installed {
+    reflexes: Record<LocalName, Item>;
+    vocab: Record<VocabName, Vocabulary>;
+    adapter: AdapterId;
+    evoke: Version;
+}
+/** One installed reflex as found: its wording or why it has none, the effect and the needs consented to — the lock's for a remote reflex, its own for a local one — and how its config is held. */
+export interface Item {
+    wording: Result<Effective, Diagnostic[]>;
+    consented: Effect;
+    /** Absent: none consented to. */
+    needs?: Needs;
+    configured: Record<ConfigKey, Held>;
+}
+/** How a set config key is held: the value itself, or a variable that is set or not. Never a secret's value. */
+export type Held = {
+    type: "plain";
+    value: string;
+} | {
+    type: "env";
+    var: VarName;
+    set: boolean;
+};
+/** A duration in milliseconds; the host makes it an instant. */
+export type Millis = number;
+/** The compiled set: the active reflexes, the inactive ones with a fix per problem, every input-independent question, and the digest that keys what is derived from it. */
+export interface Plan {
+    /** SHA-256 of the compact JSON of `Installed`: keys the decision cache and the baselines. */
+    digest: Digest;
+    active: Record<LocalName, Active>;
+    /** Every problem of every inactive reflex, each with its fix. */
+    inactive: Record<LocalName, NonEmpty<Diagnostic>>;
+    /** The tags of the inactive reflexes whose manifest read; absent when none carries any. */
+    tagged?: Record<LocalName, Tag[]>;
+    /** `route`, then per active reflex `fits.<name>` and every argument, in that order. */
+    slots: Record<QuestionId, Slot>;
+    /** Per vocabulary, the words that carry a value. */
+    values: Record<VocabName, Record<Word, string>>;
+    /** The core's one deadline: 30 000 ms. */
+    deadline: Millis;
+}
+/** An active reflex as the decision needs it; `effect` is the tighter of the manifest's and the consented one, `needs` the manifest's declaration narrowed to what was consented to. */
+export interface Active {
+    effect: Effect;
+    /** Absent: inline, a function the SDK holds. */
+    run?: Run;
+    /** Absent: the tightest declaration. */
+    needs?: Needs;
+    confirm: Template;
+    args: Record<ArgName, Argument>;
+    /** What the body's `data` yields for a later step to take, per field. */
+    yields: Record<FieldName, Yield>;
+    config: Record<ConfigKey, Setting>;
+    tags: Tag[];
+}
+/** A question that does not depend on the input, or a pick whose options exist only per input. */
+export type Slot = Question | {
+    type: "pick";
+    ask: Clean;
+    pick: Recognizer;
+    optional: boolean;
+};
+/** A candidate for a pick: where it is in the input, and what its recognizer read. */
+export interface Proposed {
+    span: Span;
+    value: PickValue;
+}
+/** What a pick hands the body: the number, the seconds, or the text. */
+export type PickValue = {
+    type: "number";
+    value: number;
+} | {
+    type: "duration";
+    value: number;
+} | {
+    type: "email";
+    value: Clean;
+} | {
+    type: "url";
+    value: Clean;
+} | {
+    type: "quoted";
+    value: Clean;
+};
+/** What a request asks: everything, or the route alone — the conflict test at `add`. */
+export type Scope = "full" | "route";
+/** What the answers said: the reflexes ranked, every choice read, and the winner with its values. */
+export interface Reading {
+    /** Sorted by route probability; `try` prints it. */
+    ranking: Contender[];
+    judgments: Judgment[];
+    /** Absent when `none` won. */
+    winner?: Winner;
+}
+/** A reflex in the ranking: its route probability, and its `fits` when that was asked. */
+export interface Contender {
+    reflex: LocalName;
+    route: Prob;
+    fits?: Prob;
+}
+/** The reflex that won the route, with what its arguments read. */
+export interface Winner {
+    reflex: LocalName;
+    args: Record<ArgName, Value>;
+    missing: Missing[];
+    /** Typed spans no argument consumed. */
+    unconsumed: Span[];
+    runner_up?: Contender;
+}
+/** One choice read: which key came out on top, and how probable it was. */
+export interface Judgment {
+    question: QuestionId;
+    top: Key;
+    p: Prob;
+}
+/** An argument without a usable value, and what a person may choose from. */
+export interface Missing {
+    arg: ArgName;
+    /** The argument's question, as the manifest asks it. */
+    ask: Clean;
+    because: Why;
+    choices: Choices;
+}
+/** Why a value is missing: the input never stated it, or a pick fell outside its range. */
+export type Why = {
+    type: "unstated";
+} | {
+    type: "out_of_range";
+    span: Span;
+    range: Range;
+};
+/** What a person may answer with; a vocabulary also prompts to add a word. */
+export type Choices = {
+    type: "options";
+    options: Record<OptionKey, Clean>;
+} | {
+    type: "vocab";
+    words: Record<Word, Clean>;
+} | {
+    type: "pick";
+    pick: Recognizer;
+};
+/** The outcome, tagged by `outcome` on the wire, the chosen call's fields flattened beside it. */
+export type Decision = {
+    outcome: "abstain";
+    contenders: Contender[];
+    judgments: Judgment[];
+} | ({
+    outcome: "run";
+} & Chosen) | ({
+    outcome: "confirm";
+} & Chosen & {
+    prompt: Prompt;
+    because: NonEmpty<Cap>;
+}) | ({
+    outcome: "ask";
+} & Asking & {
+    missing: NonEmpty<Missing>;
+});
+/** A complete call with its effect and, unless called by name, what the classifier judged. */
+export type Chosen = Call & {
+    effect: Effect;
+} & (Judged | Unjudged);
+/** Called by name, so nothing was judged: no field of `Judged` is present. */
+export type Unjudged = {
+    [K in keyof Judged]?: never;
+};
+/** The judgments a decision rests on: confidence is the weakest one's probability, over the route and every argument question of the winner. */
+export interface Judged {
+    /** `weakest.p`: the minimum over `judgments`. */
+    confidence: Prob;
+    weakest: Judgment;
+    judgments: NonEmpty<Judgment>;
+    runner_up?: Contender;
+    /** The ranking. */
+    contenders: Contender[];
+}
+/** An ask in flight: what the gate reads again once the missing values are given. */
+export interface Asking extends Judged {
+    reflex: LocalName;
+    args: Record<ArgName, Value>;
+    /** Typed spans no argument consumed. */
+    unconsumed: Span[];
+}
+/** Why a decision stops at confirm; `because` lists them in this order. */
+export type Cap = {
+    type: "destructive";
+} | {
+    type: "no_gate";
+} | {
+    type: "under_floor";
+    judgment: Judgment;
+    floor: Prob;
+} | {
+    type: "unconsumed_span";
+    span: Span;
+} | {
+    type: "two_things";
+    contender: Contender;
+};
+/** The confirm prompt: `evoke`'s own line, then the manifest's template filled in. */
+export interface Prompt {
+    /** The call, its effect, the weakest judgment and each cap that names itself, joined by ` · `. */
+    own: string;
+    template: Clean;
+}
+/** A call resolved and complete; on the wire `{ reflex, args, call }`, the last being its rendering. */
+export interface Call {
+    reflex: LocalName;
+    args: Record<ArgName, Value>;
+    /** The call on one line: the name, then each argument as `name="value"` or a bare flag. */
+    call: string;
+}
+/** An argument's value: a key, a word, a verbatim span, or a flag that is present. Never minted by the model. */
+export type Value = {
+    type: "option";
+    key: OptionKey;
+} | {
+    type: "word";
+    word: Word;
+    /** What the body receives instead of the word, when the vocabulary sets one. */
+    value?: string;
+} | {
+    type: "pick";
+    span: Span;
+    value: PickValue;
+} | {
+    type: "flag";
+};
+/** A call as typed: `lights room=den state=off`; a bare argument is a flag. Resolved by `by_name` or typed by a lesson, never run as it is. */
+export interface Written {
+    reflex: LocalName;
+    /** As typed; `null` is written bare, so a flag. */
+    args: Record<ArgName, string | null>;
+}
+/** One JSON line on the loader's stdin. */
+export interface Envelope {
+    reflex: LocalName;
+    /** Absent for an inline body. */
+    run?: Run;
+    /** An option key, a word's `value` if set else the word, a pick's value, `true` for a flag. */
+    args: Record<ArgName, string | number | true>;
+    input: Input;
+    /** An `env` setting stays a reference; the host resolves it. */
+    config: Record<ConfigKey, Setting>;
+    deadline: Millis;
+}
+/** A text for the foundation to decide: over the reflexes the tags allow, or one reflex alone. */
+export interface Asked {
+    text: string;
+    tags?: Tag[];
+    only?: LocalName;
+}
+/** What the plan needs a host to do next: judge the split points, name each reference's step, or decide texts. */
+export type Need = {
+    type: "judge";
+    request: Request;
+} | {
+    type: "refer";
+    request: Request;
+} | {
+    type: "decide";
+    asked: Asked[];
+};
+/** What a host gathered for the plan so far. */
+export interface Answers {
+    judged?: Raw;
+    referred?: Raw;
+    decided?: [Asked, Decision][];
+}
+/** The plan, or what it needs first. */
+export type Planning = {
+    type: "done";
+    weave: Weave;
+} | {
+    type: "need";
+    need: Need;
+};
+/** What a connective does: `then` orders what follows after what precedes; the rest coordinate. */
+export type Order = "then" | "and";
+/** A place the request may split: the connective's span in characters, its word, whether it orders, and the engine's probability that the two sides are two things. */
+export interface Split {
+    start: number;
+    end: number;
+    word: string;
+    order: Order;
+    p?: Prob;
+}
+/** The reference word in a step's text, in characters of that text. */
+export interface Where {
+    start: number;
+    end: number;
+    text: string;
+}
+/** A reference in one step to earlier ones: the words, the steps it may name (zero-based), how it was found. */
+export interface Ref {
+    span: Where;
+    from: number[];
+    how: "pronoun" | "phrase" | "engine";
+    /** `the <noun>`: a reference only when something takes it. */
+    weak?: boolean;
+    /** A phrase's noun, singular, which may name a field of the source's result. */
+    noun?: string;
+    /** Plural: over a result of several records, every one. */
+    many?: boolean;
+    p?: Prob;
+}
+/** How a segment that matched nothing on its own was settled. */
+export type Repair = "narrowed" | "spliced" | "merged";
+/** One step of the plan: a segment's text and the foundation's decision on it, in the order it is to happen. */
+export interface Step {
+    /** From 1, as the plan prints it. */
+    n: number;
+    text: string;
+    /** Where the step's words end in the request, in characters. */
+    end: number;
+    decision: Decision;
+    reflex?: LocalName;
+    effect?: Effect;
+    refs?: Ref[];
+    repair?: Repair;
+    /** The steps this one must follow: an explicit `then`, or a binding. */
+    after?: number[];
+}
+/** How a bound value reaches its step: answering its own ask, or the step decided again with the value in its words. */
+export type Via = "fill" | "rewrite";
+/** A value of one step's result taken by a later step: which field, into which argument, how. */
+export interface Binding {
+    from: number;
+    to: number;
+    arg: ArgName;
+    field: FieldName;
+    kind: Recognizer;
+    via: Via;
+    /** The list field of the source's result whose records carry `field`: the step runs once per record. */
+    each?: FieldName;
+}
+/** Why the plan does not simply run; each names its steps. */
+export type Because = {
+    type: "nothing_to_do";
+} | {
+    type: "no_reflex";
+    step: number;
+} | {
+    type: "needs";
+    step: number;
+    arg: ArgName;
+} | {
+    type: "several";
+    step: number;
+    source: number;
+    fields: FieldName[];
+} | {
+    type: "one_of_many";
+    step: number;
+    source: number;
+    field: FieldName;
+} | {
+    type: "takes_nothing";
+    step: number;
+    sources: number[];
+};
+/** The verdict before anything runs, with every reason. */
+export interface Verdict {
+    outcome: "run" | "ask" | "confirm" | "refuse";
+    because?: Because[];
+}
+/** The plan: the request in the words' own order, its split points as judged, the steps, what was left out, the bindings, the schedule and the verdict. */
+export interface Weave {
+    input: string;
+    splits?: Split[];
+    steps: Step[];
+    /** Fragments left out because they begin with a negation. */
+    excluded?: string[];
+    binds?: Binding[];
+    /** Whether a write is among the steps, so none may run beside another. */
+    exclusive: boolean;
+    /** A stage's steps run together; stages run in order. */
+    stages: number[][];
+    verdict: Verdict;
+}
+/** A value bound into a step at its turn. */
+export interface Bound {
+    arg: ArgName;
+    from: number;
+    field: FieldName;
+    value: string;
+}
+/** What a body returned: its text, and data when it gave some. */
+export interface Returned {
+    text: string;
+    data?: Json;
+}
+/** One round of a step for a host to take through the foundation's loop, the bound values in place. */
+export interface Handling {
+    step: number;
+    /** From 0; a step bound to a list runs one round per record. */
+    round: number;
+    decision: Decision;
+    input: string;
+    bound?: Bound[];
+}
+/** What became of a step, or of one of its rounds. */
+export type Status = "ran" | "failed" | "declined" | "refused" | "skipped" | "unanswered";
+/** Why a step did not run, or did not finish. */
+export type WeaveWhy = {
+    type: "earlier_step";
+} | {
+    type: "nothing_to_take";
+} | {
+    type: "found_nothing";
+} | {
+    type: "no_reflex";
+} | {
+    type: "read_as";
+    reflex: LocalName;
+} | {
+    type: "said";
+    message: string;
+};
+/** What a host made of one round. */
+export interface Handled {
+    step: number;
+    round: number;
+    status: Status;
+    why?: WeaveWhy;
+    result?: Returned;
+}
+/** What a host gathered for the run so far. */
+export interface Progress {
+    decided?: [Asked, Decision][];
+    handled?: Handled[];
+}
+/** What the run needs a host to do next. */
+export type Todo = {
+    type: "decide";
+    asked: Asked;
+} | {
+    type: "handle";
+    handling: Handling[];
+};
+/** The run, or what it needs first. */
+export type Running = {
+    type: "done";
+    executed: Executed;
+} | {
+    type: "todo";
+    todo: Todo;
+};
+/** What became of one step. */
+export interface StepOutcome {
+    step: number;
+    status: Status;
+    why?: WeaveWhy;
+    bound?: Bound[];
+    rounds?: Handled[];
+}
+/** The run: per step, what became of it, in plan order; and the whole's status, the worst step's as the exit codes rank them. */
+export interface Executed {
+    steps: StepOutcome[];
+    worst: Status;
+}
+/** What changed in the contract from one version to the next, and how much it matters. */
+export interface ContractDiff {
+    level: Level;
+    changes: Change[];
+    violations: WasViolation[];
+}
+/** `same`: nothing but wording, or a declaration narrowed. `minor`: additions, a declaration widened, and a config key gone. `major`: something a person's files or calls may not survive. */
+export type Level = "same" | "minor" | "major";
+/** One change to the contract, in the order the diff walks: the previous arguments, the added ones, the body, what it may touch, config, then what the result yields. */
+export type Change = {
+    type: "arg_removed";
+    arg: ArgName;
+} | {
+    type: "option_removed";
+    arg: ArgName;
+    key: OptionKey;
+} | {
+    type: "arg_renamed";
+    from: ArgName;
+    to: ArgName;
+} | {
+    type: "source_changed";
+    arg: ArgName;
+} | {
+    type: "range_changed";
+    arg: ArgName;
+} | {
+    type: "run_changed";
+} | {
+    type: "needs_widened";
+    added: Needs;
+} | {
+    type: "needs_narrowed";
+    removed: Needs;
+} | {
+    type: "required";
+    arg: ArgName;
+} | {
+    type: "config_secret";
+    key: ConfigKey;
+    secret: boolean;
+} | {
+    type: "arg_added";
+    arg: ArgName;
+} | {
+    type: "optional";
+    arg: ArgName;
+} | {
+    type: "option_added";
+    arg: ArgName;
+    key: OptionKey;
+} | {
+    type: "config_added";
+    key: ConfigKey;
+} | {
+    type: "config_removed";
+    key: ConfigKey;
+} | {
+    type: "yield_added";
+    field: FieldName;
+} | {
+    type: "yield_removed";
+    field: FieldName;
+} | {
+    type: "yield_changed";
+    field: FieldName;
+};
+/** `was` is flat and cumulative: a retired name never returns as a live argument, and never leaves the lists. */
+export type WasViolation = {
+    type: "returned";
+    arg: ArgName;
+} | {
+    type: "dropped";
+    arg: ArgName;
+};
+/** What an update does to the effect a person consented to: upstream may keep or tighten it, and loosens it only through `evoke update --accept`. */
+export type Consent = {
+    type: "kept";
+    effect: Effect;
+} | {
+    type: "tightened";
+    effect: Effect;
+} | {
+    type: "needs_accept";
+    locked: Effect;
+    upstream: Effect;
+};
+/** What `lint` finds: a size cap passed, or text that addresses the model instead of describing an action. */
+export type LintRule = "size_cap" | "addresses_model";
+/** One thing `lint` found, at the key path it concerns; reported at `add` and by `check`, never a refusal. */
+export interface Finding {
+    rule: LintRule;
+    path: KeyPath;
+    message: string;
+}
+/** One change to an owned file, which the host applies keeping the file's own shape: a key path set, or removed. */
+export type Edit = {
+    type: "set";
+    file: Owned;
+    path: KeyPath;
+    /** The line's value as JSON: a record, a string, `{ env }` or `{ what, value }`. */
+    value: Json;
+} | {
+    type: "remove";
+    file: Owned;
+    path: KeyPath;
+};
+/** A file `evoke` edits in place; the lock and `evoke.d.ts` are rendered whole, never edited. */
+export type Owned = {
+    type: "project";
+} | {
+    type: "overlay";
+    name: LocalName;
+} | {
+    type: "vocab";
+    name: VocabName;
+};
+/** The overlay line itself: which reflex an utterance belongs to and what it asserts; `not <name>` is `false`. */
+export interface Lesson {
+    reflex: LocalName;
+    /** Names follow `was`; each value is typed against the plan at the door. */
+    record: Asserted;
+}
+/** What `evoke vocab <name> add | remove` does to the file. */
+export type VocabChange = {
+    type: "add";
+    word: Word;
+    meaning: Meaning;
+} | {
+    type: "remove";
+    word: Word;
+};
+/** One record as a test: whose it is, what was said, what should come of it, and the table it came from. */
+export interface Case {
+    reflex: LocalName;
+    utterance: Utterance;
+    expect: Expected;
+    from: Table;
+}
+/** Where a case came from: examples are sent to the classifier, tests are held out. */
+export type Table = "examples" | "tests";
+/** What a record expects, as a decision compares to it: `false` for never this reflex, or a claim per argument — `{}` asserts the route alone. */
+export type Expected = false | Record<ArgName, Claim>;
+/** One argument's claim: `false` unstated, `true` a flag raised, or the text a decision's value must show — an option key, a word or a span, which all compare as text. What a decision read takes the same shape. */
+export type Claim = boolean | Clean;
+/** What a decision made of a case: it passed, or where it first missed. */
+export type CaseVerdict = {
+    type: "pass";
+} | {
+    type: "fail";
+    mismatch: Mismatch;
+};
+/** Where a decision missed a case: the route — read as another reflex, or as none — or the first asserted argument read as something else. */
+export type Mismatch = {
+    type: "route";
+    read: LocalName | null;
+} | {
+    type: "arg";
+    arg: ArgName;
+    read: Claim;
+};
+/** The last run's verdict per case, by reflex and utterance identity; the host keeps one per plan digest. */
+export type Baseline = Record<LocalName, Record<Identity, CaseVerdict>>;
+/** A case that passed at the last run and fails now, two of three uncached repeats. */
+export interface Regression {
+    case: Case;
+    now: Mismatch;
+}
+/** A phrase an installed reflex claims that a newcomer wins at `add`. */
+export interface Theft {
+    phrase: Utterance;
+    owner: LocalName;
+    thief: LocalName;
+}
+/** The report `evoke calibrate` prints: every record of the active reflexes decided once, or `repeats` times, and judged; each input counts once, by its first decision, the repeats measuring stability. */
+export interface Calibration {
+    adapter: AdapterId;
+    records: number;
+    reflexes: number;
+    inputs: number;
+    repeats: number;
+    outcomes: Outcomes;
+    /** The whole call right, by the confidence claimed; a bin with no call is left out. */
+    bins: BinRow[];
+    /** Calls no record can judge: a `false` record routed to a reflex no record names. */
+    unknown: number;
+    abstained: Share;
+    bars: Bars;
+    questions: QuestionRow[];
+    brier?: Brier;
+    misses: Miss[];
+    variance?: Variance;
+}
+/** How many inputs ended in each outcome. */
+export interface Outcomes {
+    run: number;
+    confirm: number;
+    ask: number;
+    abstain: number;
+}
+/** One bin: the calls whose confidence lies in `lo..hi` — `hi` inside the last bin — how many were right, the Wilson interval of that share, the mean confidence claimed; `over_confident` when the claim is above the interval, `thin` under a hundred calls. */
+export interface BinRow {
+    lo: Prob;
+    hi: Prob;
+    calls: number;
+    right: number;
+    interval: [Prob, Prob];
+    claimed: Prob;
+    thin: boolean;
+    over_confident: boolean;
+}
+/** A count with how many were right, and the Wilson interval of the share. */
+export interface Share {
+    count: number;
+    right: number;
+    interval: [Prob, Prob];
+}
+/** Each effect's bar, for an effect with a judged call under a gate. */
+export interface Bars {
+    read?: BarRow;
+    write?: BarRow;
+}
+/** The calls of one effect at or over its bar: how many were wrong, per thousand, the one-sided bound at 95 % per thousand, and the neighbourhood at the bar and a step either side. */
+export interface BarRow {
+    bar: Prob;
+    wrong: number;
+    calls: number;
+    per_thousand: number;
+    at_most: number;
+    near: NearRow[];
+}
+/** At a threshold: how many calls would run, and how many of those are wrong. */
+export interface NearRow {
+    at: Prob;
+    run: number;
+    wrong: number;
+}
+/** One kind of judgment on its own: the route, or the arguments by source; right when the record names the argument and the decision read it as claimed. */
+export interface QuestionRow {
+    kind: QuestionKind;
+    judgments: number;
+    right: number;
+    interval: [Prob, Prob];
+    claimed: Prob;
+}
+export type QuestionKind = "route" | "options" | "vocab" | "pick" | "flag";
+/** The Brier score over the calls, and Murphy's parts over the bins. */
+export interface Brier {
+    brier: number;
+    reliability: number;
+    resolution: number;
+    uncertainty: number;
+}
+/** A decision a record proved wrong: the record, what was decided, where it missed; `wrong` counts the repeats that missed the same way. */
+export interface Miss {
+    case: Case;
+    outcome: "run" | "confirm" | "ask" | "abstain";
+    reflex?: LocalName;
+    confidence?: Prob;
+    mismatch: Mismatch;
+    wrong: number;
+}
+/** Over repeats: the inputs whose winner or verdict flipped, the spread of the confidence per input, the inputs straddling the bar of their effect, the calls wrong at or over their bar in any repeat, and what moved most. */
+export interface Variance {
+    flips: number;
+    verdict_flips: number;
+    spread: Spread;
+    straddling: number;
+    wrong_at_bar: number;
+    moved: Moved[];
+}
+export interface Spread {
+    median: number;
+    p90: number;
+    max: number;
+}
+/** One input whose repeats moved: the confidence's range, the route's, each winner and outcome with its count, and how many repeats were wrong. */
+export interface Moved {
+    utterance: string;
+    confidence?: [Prob, Prob];
+    route: [Prob, Prob];
+    winners: Record<string, number>;
+    outcomes: Record<string, number>;
+    wrong: number;
+}
+/** One line of the log as the block reads it: what was decided, which adapters answered — none when the cache did — whether the body ran or failed, and a weave step's status. */
+export interface Logged {
+    input: Input;
+    decision: Decision;
+    adapters?: AdapterId[];
+    ran?: boolean;
+    failed?: boolean;
+    status?: Status;
+}
+/** The log's lines under one adapter, counted by what became of each; the confidence of what stopped at a confirm by segment; the lines whose input is a record, judged; and the lines that did not read. */
+export interface LogBlock {
+    adapter: AdapterId;
+    decisions: number;
+    ran: number;
+    confirmed_ran: number;
+    confirmed_stopped: number;
+    asked: number;
+    abstained: number;
+    failed: number;
+    skipped: number;
+    stopped_by_confidence: Counted[];
+    records: Share;
+    unread: number;
+}
+/** A count of confidences in `lo..hi`. */
+export interface Counted {
+    lo: Prob;
+    hi: Prob;
+    count: number;
+}
+/** A door on the System One wire: which address, under which key, naming which model. Its adapter name. */
+export type Door = "jev" | "openjev";
+/** What both hosts read before the first call. */
+export interface Settings {
+    declared: Declared;
+    /** The variable the API key is read from. */
+    credential: VarName;
+    /** Where a key comes from, as the line that asks for one says it. */
+    issuer: string;
+    /** The endpoint both hosts post to. */
+    url: string;
+    policy: Transport;
+}
+/** The transport policy as a value, executed by each host: the wait after connect, how many times a connect error or a retried status is tried again, and which statuses those are. */
+export interface Transport {
+    timeout: Millis;
+    retries: number;
+    /** `[min, max]`, both retried. */
+    retry_statuses: Range;
+}
+/** Hand-writable answers keyed by utterance identity, with what the adapter declares — `id`, `limits` and `gate` are its `Declared`, flattened. */
+export interface Recording {
+    id: AdapterId;
+    limits?: Limits;
+    gate?: Gate;
+    /** The plan the answers were recorded against; the host compares it with `Plan.digest` before calling `answer`. */
+    plan?: Digest;
+    answers: Record<Identity, Raw>;
+}