@evoke-build/evoke 0.6.0

package/dist/ops.d.ts

@@ -0,0 +1,458 @@
+import type * as T from "./types.ts";
+/** Every op: its argument object, and its reply's ok value — a Result where the function returns one. */
+export interface Ops {
+    identity: {
+        input: {
+            text: string;
+        };
+        output: T.Identity;
+    };
+    manifest: {
+        input: {
+            doc: T.Document;
+        };
+        output: T.Result<T.Manifest, T.Diagnostic[]>;
+    };
+    overlay: {
+        input: {
+            doc: T.Document;
+            of: T.Manifest;
+        };
+        output: T.Result<T.Overlay, T.Diagnostic[]>;
+    };
+    vocabulary: {
+        input: {
+            doc: T.Document;
+        };
+        output: T.Result<T.Vocabulary, T.Diagnostic[]>;
+    };
+    project: {
+        input: {
+            doc: T.Document;
+        };
+        output: T.Result<T.Project, T.Diagnostic[]>;
+    };
+    lock: {
+        input: {
+            doc: T.Document;
+        };
+        output: T.Result<T.Lock, T.Diagnostic[]>;
+    };
+    render_lock: {
+        input: {
+            lock: T.Lock;
+        };
+        output: string;
+    };
+    location: {
+        input: {
+            location: T.Location;
+        };
+        output: string;
+    };
+    name: {
+        input: {
+            text: string;
+            kind: "local" | "vocab";
+        };
+        output: T.Result<string, string>;
+    };
+    reference: {
+        input: {
+            text: string;
+        };
+        output: T.Result<[T.Reference, T.Version | null], T.Diagnostic>;
+    };
+    digest: {
+        input: {
+            hashed: [T.RelPath, T.Digest][];
+        };
+        output: T.Digest;
+    };
+    fix: {
+        input: {
+            fix: T.Fix;
+            invoked?: string;
+        };
+        output: string;
+    };
+    fault: {
+        input: {
+            fault: T.Fault;
+            invoked?: string;
+        };
+        output: {
+            message: string;
+            command: string;
+        };
+    };
+    version: {
+        input: Record<never, never>;
+        output: T.Version;
+    };
+    effective: {
+        input: {
+            shipped: T.Manifest;
+            yours?: T.Overlay;
+        };
+        output: T.Effective;
+    };
+    report: {
+        input: {
+            previous: T.Manifest;
+            next: T.Manifest;
+            yours?: T.Overlay;
+        };
+        output: T.Report;
+    };
+    compile: {
+        input: {
+            set: T.Installed;
+            limits?: T.Limits;
+        };
+        output: T.Result<T.Plan, T.Diagnostic>;
+    };
+    propose: {
+        input: {
+            input: T.Input;
+        };
+        output: T.Proposed[];
+    };
+    request: {
+        input: {
+            plan: T.Plan;
+            input: string;
+            tags: T.Tag[];
+            only?: T.LocalName;
+            scope: T.Scope;
+        };
+        output: T.Result<T.Request, T.Diagnostic>;
+    };
+    read: {
+        input: {
+            plan: T.Plan;
+            request: T.Request;
+            raw: T.Raw;
+        };
+        output: T.Result<T.Reading, T.Fault>;
+    };
+    gate: {
+        input: {
+            plan: T.Plan;
+            reading: T.Reading;
+            gate?: T.Gate;
+        };
+        output: T.Decision;
+    };
+    fill: {
+        input: {
+            plan: T.Plan;
+            asking: T.Asking;
+            given: Record<T.ArgName, T.Value>;
+            gate?: T.Gate;
+        };
+        output: T.Decision;
+    };
+    by_name: {
+        input: {
+            plan: T.Plan;
+            written: T.Written;
+        };
+        output: T.Result<T.Decision, T.Diagnostic>;
+    };
+    picked: {
+        input: {
+            text: string;
+            recognizer: T.Recognizer;
+        };
+        output: T.Value | null;
+    };
+    values: {
+        input: {
+            args: Record<T.ArgName, T.Value>;
+        };
+        output: Record<T.ArgName, string | number | true>;
+    };
+    call: {
+        input: {
+            text: string;
+        };
+        output: T.Result<T.Written, T.Diagnostic>;
+    };
+    envelope: {
+        input: {
+            chosen: T.Chosen;
+            active: T.Active;
+            input: T.Input;
+            deadline: T.Millis;
+            home: string;
+        };
+        output: T.Envelope;
+    };
+    argv: {
+        input: {
+            chosen: T.Chosen;
+            active: T.Active;
+            home: string;
+        };
+        output: T.Result<string[], T.Diagnostic>;
+    };
+    "needs.resolve": {
+        input: {
+            needs: T.Needs;
+            call: T.Call;
+            active: T.Active;
+            config: Record<T.ConfigKey, string>;
+            home: string;
+        };
+        output: T.Result<T.Policy, T.Diagnostic>;
+    };
+    "needs.widens": {
+        input: {
+            from: T.Needs;
+            to: T.Needs;
+        };
+        output: boolean;
+    };
+    "needs.consent": {
+        input: {
+            locked: T.Needs;
+            upstream: T.Needs;
+        };
+        output: T.NeedsConsent;
+    };
+    "contain.seatbelt": {
+        input: {
+            policy: T.Policy;
+            facts: T.Facts;
+        };
+        output: string;
+    };
+    "contain.node_flags": {
+        input: {
+            policy: T.Policy;
+            facts: T.Facts;
+        };
+        output: string[];
+    };
+    "contain.landlock": {
+        input: {
+            policy: T.Policy;
+            facts: T.Facts;
+        };
+        output: T.Rule[];
+    };
+    "needs.declared_at": {
+        input: {
+            doc: T.Document;
+        };
+        output: T.At;
+    };
+    "needs.lacking": {
+        input: {
+            lacking: T.Lacking;
+            reflex: T.LocalName;
+            active: T.Active;
+            origin: T.Origin;
+            home: string;
+        };
+        output: T.Diagnostic;
+    };
+    "needs.refusal": {
+        input: {
+            policy: T.Policy;
+            upstream?: T.Policy;
+            reflex: T.LocalName;
+            origin: T.Origin;
+            refused: T.Refused;
+            home: string;
+        };
+        output: T.Diagnostic | null;
+    };
+    teach: {
+        input: {
+            plan: T.Plan;
+            utterance: T.Utterance;
+            lesson: T.Lesson;
+        };
+        output: T.Result<T.Edit, T.Diagnostic>;
+    };
+    set_config: {
+        input: {
+            name: T.LocalName;
+            key: T.ConfigKey;
+            setting: T.Setting;
+            spec: T.ConfigSpec;
+        };
+        output: T.Result<T.Edit, T.Diagnostic>;
+    };
+    vocab_edit: {
+        input: {
+            name: T.VocabName;
+            change: T.VocabChange;
+        };
+        output: T.Edit;
+    };
+    add_entry: {
+        input: {
+            name: T.LocalName;
+            location: T.Location;
+        };
+        output: T.Edit;
+    };
+    remove_entry: {
+        input: {
+            name: T.LocalName;
+        };
+        output: T.Edit;
+    };
+    diff: {
+        input: {
+            previous: T.Manifest;
+            next: T.Manifest;
+        };
+        output: T.ContractDiff;
+    };
+    consent: {
+        input: {
+            locked: T.Effect;
+            upstream: T.Effect;
+        };
+        output: T.Consent;
+    };
+    lint: {
+        input: {
+            manifest: T.Manifest;
+        };
+        output: T.Finding[];
+    };
+    reflex_dts: {
+        input: {
+            manifest: T.Manifest;
+        };
+        output: string;
+    };
+    project_dts: {
+        input: {
+            set: T.Installed;
+        };
+        output: string;
+    };
+    cases: {
+        input: {
+            set: T.Installed;
+        };
+        output: T.Case[];
+    };
+    judge: {
+        input: {
+            case: T.Case;
+            decision: T.Decision;
+        };
+        output: T.CaseVerdict;
+    };
+    regressions: {
+        input: {
+            before: T.Baseline;
+            judged: [T.Case, T.NonEmpty<T.CaseVerdict>][];
+        };
+        output: T.Regression[];
+    };
+    baseline: {
+        input: {
+            before: T.Baseline;
+            judged: [T.Case, T.NonEmpty<T.CaseVerdict>][];
+        };
+        output: T.Baseline;
+    };
+    thieves: {
+        input: {
+            newcomers: T.LocalName[];
+            routed: [T.Case, T.LocalName | null][];
+        };
+        output: T.Theft[];
+    };
+    calibrate: {
+        input: {
+            adapter: T.AdapterId;
+            gate?: T.Gate;
+            plan: T.Plan;
+            judged: [T.Case, T.NonEmpty<T.Decision>][];
+        };
+        output: T.Calibration;
+    };
+    "calibrate.log": {
+        input: {
+            adapter: T.AdapterId;
+            gate?: T.Gate;
+            lines: T.Logged[];
+            cases: T.Case[];
+            unread: number;
+        };
+        output: T.LogBlock;
+    };
+    "weave.plan": {
+        input: {
+            plan: T.Plan;
+            input: string;
+            tags: T.Tag[];
+            answers: T.Answers;
+        };
+        output: T.Result<T.Planning, T.Fault>;
+    };
+    "weave.execute": {
+        input: {
+            plan: T.Plan;
+            gate?: T.Gate;
+            weave: T.Weave;
+            progress: T.Progress;
+        };
+        output: T.Running;
+    };
+    "systemone.settings": {
+        input: {
+            door: T.Door;
+            table?: T.Json;
+        };
+        output: T.Result<T.Settings, T.Diagnostic[]>;
+    };
+    "systemone.request": {
+        input: {
+            request: T.Request;
+        };
+        output: T.Json;
+    };
+    "systemone.answers": {
+        input: {
+            status: number;
+            body: string;
+            credential: T.VarName;
+        };
+        output: T.Result<T.Raw, T.Fault>;
+    };
+    "replay.recording": {
+        input: {
+            toml: string;
+        };
+        output: T.Result<T.Recording, string>;
+    };
+    "replay.render": {
+        input: {
+            recording: T.Recording;
+        };
+        output: string;
+    };
+    "replay.answer": {
+        input: {
+            recording: T.Recording;
+            request: T.Request;
+        };
+        output: T.Result<T.Raw, T.Fault>;
+    };
+}
+export type Op = keyof Ops;
+/** One vector of spec/vectors/<op>/: the op's arguments, and what it must answer. */
+export type Vector<O extends Op> = {
+    input: Ops[O]["input"];
+    expect: Ops[O]["output"];
+};

package/dist/ops.js

@@ -0,0 +1,4 @@
+// The op table as types: every op's argument object and what it answers, mirroring crates/evoke-wasm/src/ops.rs
+// name for name. A Result op answers { ok } | { err }; any other answers its value under ok. The vectors pin this
+// table: build/vectors.ts makes every case satisfy Vector<op>.
+export {};

package/dist/project.d.ts

@@ -0,0 +1,138 @@
+import { type Adapter } from "./adapter.ts";
+import type { AnyReflexes, Ask, Confirm, Decision, Given, Handled, Run } from "./decision.ts";
+import { type Problem } from "./errors.ts";
+import type { Inline } from "./reflex.ts";
+import { type Result } from "./runtime.ts";
+import type * as W from "./types.ts";
+export interface LoadOptions<R = AnyReflexes> {
+    /** The project directory: evoke.toml, evoke.lock, overlays/, vocab/, local reflexes. Absent: no files at all. */
+    root?: string | undefined;
+    /** Reflexes handed as code, by local name; a name evoke.toml also lists is an error. Overlays under root apply.
+     *  R is inferred from this map when no root is given; with a root, write `load<Reflexes & ReflexesOf<typeof own>>`. */
+    reflexes?: {
+        [K in keyof R]?: Inline<R[K]> | undefined;
+    } | undefined;
+    /** Who answers. Absent: the adapter evoke.toml names, from its own subpath; required without a root. */
+    adapter?: Adapter | undefined;
+}
+export interface DecideOptions {
+    /** Only reflexes carrying one of these tags are offered. */
+    tags?: string[] | undefined;
+    /** This reflex alone is offered: how a weave decides a fragment, or a step with a value written into its words. */
+    only?: string | undefined;
+    /** Aborts the adapter call; `decide` rejects with the signal's reason. */
+    signal?: AbortSignal | undefined;
+}
+export interface RunOptions {
+    /** Aborts the body: its `signal` in-process, its group otherwise; `run` rejects with the signal's reason. */
+    signal?: AbortSignal | undefined;
+}
+export interface Handlers<R = AnyReflexes> {
+    /** Asked at a confirm: `true` runs, `false` declines. Absent and reached: `unanswered`. */
+    confirm?: ((decision: Confirm<R>) => boolean | Promise<boolean>) | undefined;
+    /** Asked at an ask: answers by argument name, or `undefined` to decline; asked again when an answer does not
+     *  read or leaves something missing, and declined when it changes nothing. Absent and reached: `unanswered`. */
+    ask?: ((decision: Ask<R>) => Given<Ask<R>> | undefined | Promise<Given<Ask<R>> | undefined>) | undefined;
+}
+/** Which step of a weave, and which of its rounds, a handler is asked for. */
+export interface Turn {
+    /** From 1, as the plan numbers them. */
+    step: number;
+    /** From 0; a step bound to a list runs one round per record. */
+    round: number;
+}
+/** What `weave` takes beside the decision's options: `handle`'s handlers, each told which step asks, and one
+ *  more for the plan itself. */
+export interface WeaveOptions<R = AnyReflexes> extends DecideOptions {
+    /** Asked at a step's confirm: `true` runs, `false` declines the step, which ends the weave after its stage.
+     *  Absent and reached: the step is `unanswered`. */
+    confirm?: ((decision: Confirm<R>, turn: Turn) => boolean | Promise<boolean>) | undefined;
+    /** Asked at a step's ask — before anything runs for a required argument no binding covers, else at the step's
+     *  turn — as `handle` asks one. Absent and reached: `unanswered`. */
+    ask?: ((decision: Ask<R>, turn: Turn) => Given<Ask<R>> | undefined | Promise<Given<Ask<R>> | undefined>) | undefined;
+    /** Asked when the plan holds at confirm — a step refers to another whose result it takes nothing from: `true`
+     *  runs the plan as it stands. Absent and reached: nothing runs. */
+    proceed?: ((plan: W.Weave) => boolean | Promise<boolean>) | undefined;
+}
+/** One round of a step as it ran: the decision the loop settled, the input its body saw, what became of it. */
+export interface WovenRound<R = AnyReflexes> {
+    round: number;
+    input: string;
+    decision: Decision<R>;
+    status: W.Status;
+    why?: W.WeaveWhy | undefined;
+    result?: Result | undefined;
+}
+/** What became of one step of a weave. */
+export interface WovenStep<R = AnyReflexes> {
+    step: number;
+    status: W.Status;
+    why?: W.WeaveWhy | undefined;
+    bound: W.Bound[];
+    rounds: WovenRound<R>[];
+}
+/** A request planned and run: the plan; the whole's status — the worst step's, as the exit codes rank them, or
+ *  why nothing ran: refused by the verdict, declined or unanswered at what the plan asked first; per step what
+ *  became of it, none when nothing ran. */
+export interface Woven<R = AnyReflexes> {
+    plan: W.Weave;
+    status: W.Status;
+    steps: WovenStep<R>[];
+}
+/** Vocabularies in the file's form: per name, word → what it means, or `{ what, value? }`. */
+export type Vocab = Record<string, Record<string, string | {
+    what: string;
+    value?: string | undefined;
+}>>;
+/** A reflex the project holds: active, with its effect and how it runs; or inactive, with each problem and its fix. */
+export type ReflexStatus = {
+    active: true;
+    effect: W.Effect;
+    runs: "inline" | "file" | "argv";
+} | {
+    active: false;
+    problems: Problem[];
+};
+export interface Project<R = AnyReflexes> {
+    /** Every reflex the project holds. */
+    readonly reflexes: Readonly<Record<string, ReflexStatus>>;
+    /** The plan's digest — `h1:<hex>` — which every decision carries and a recording may pin. */
+    readonly plan: string;
+    /** This project over vocabularies of the call's own, compiled to their own plan; nothing else changes. */
+    with(options: {
+        vocab: Vocab;
+    }): Project<R>;
+    /** One input decided: asked, answered, read, gated. Runs nothing. */
+    decide(input: string, options?: DecideOptions): Promise<Decision<R>>;
+    /** An ask answered — an option's key, else the text a person typed — and gated again. */
+    fill<D extends Ask<R>>(decision: D, given: Given<D>): Decision<R>;
+    /** The chosen call's body: in-process, in a child through the loader, or as an argv. */
+    run(decision: Run<R>, options?: RunOptions): Promise<Result>;
+    /** A confirm decision runs only once confirmed. */
+    run(decision: Confirm<R>, options: RunOptions & {
+        confirmed: true;
+    }): Promise<Result>;
+    /** The whole loop: decide; ask and fill until nothing is missing; confirm; run. */
+    handle(input: string, options?: DecideOptions & Handlers<R>): Promise<Handled<R>>;
+    /** One request read into its steps, each decided as `decide` decides one, ordered by the words, a result of
+     *  one threaded into a later one: the plan alone, its verdict before anything runs. Runs nothing. */
+    steps(input: string, options?: DecideOptions): Promise<W.Weave>;
+    /** The steps, what the plan asks first answered, then every step run stage by stage under the same handlers. */
+    weave(input: string, options?: WeaveOptions<R>): Promise<Woven<R>>;
+}
+/** A project from its root: its installed reflexes are what `Reflexes` from evoke.d.ts names, so R is written. */
+export declare function load<R extends object = AnyReflexes>(options: {
+    root: string;
+    reflexes?: NoInfer<{
+        [K in keyof R]?: Inline<R[K]> | undefined;
+    }> | undefined;
+    adapter?: Adapter | undefined;
+}): Promise<Project<R>>;
+/** A project from reflexes handed as code alone: R is inferred from them. */
+export declare function load<R extends object = AnyReflexes>(options: {
+    root?: undefined;
+    reflexes?: {
+        [K in keyof R]?: Inline<R[K]> | undefined;
+    } | undefined;
+    adapter: Adapter;
+}): Promise<Project<R>>;