@evoke-build/evoke 0.10.1 → 0.11.0

package/dist/index.d.ts

@@ -7,4 +7,4 @@ export type { Context, Reflex, Result } from "./runtime.ts";
 export type { Adapter, Trace } from "./adapter.ts";
 export { DiagnosticError, EvokeError, FailureError, FaultError } from "./errors.ts";
 export type { Problem } from "./errors.ts";
-export type { Because, Binding, Bound, Cap, Choices, Contained, Contender, Diagnostic, Effect, Fault, Fix, Gate, Judgment, Limits, Missing, Needs, Prompt, Question, NonEmpty, Raw, Recognizer, Span, State, Status, Step, Text, Verdict, Weave, WeaveWhy, Why, Yield, } from "./types.ts";
+export type { Answer, Because, Binding, Bound, Cap, Choices, Contained, Contender, Diagnostic, Effect, Fault, Fix, Gate, Judgment, Limits, Missing, Needs, Pinned, PinnedReflex, Prompt, Question, NonEmpty, Raw, Recognizer, Span, State, Status, Step, Text, Verdict, Weave, WeaveWhy, Why, Yield, } from "./types.ts";

package/dist/ops.d.ts

@@ -108,6 +108,7 @@ export interface Ops {
     compile: {
         input: {
             set: T.Installed;
+            values?: T.Values;
             limits?: T.Limits;
             platform?: T.Platform;
         };
@@ -413,6 +414,46 @@ export interface Ops {
         };
         output: T.Running;
     };
+    "weave.pin": {
+        input: {
+            installed: T.Installed;
+            plan: T.Plan;
+            project: T.Project;
+            lock?: T.Lock;
+            declared: T.Declared;
+            input: string;
+            tags: T.Tag[];
+            weave: T.Weave;
+            answers: T.Answer[];
+        };
+        output: T.Pinned;
+    };
+    "weave.pinned": {
+        input: {
+            path: string;
+            json: T.Json;
+        };
+        output: T.Result<T.Pinned, T.Diagnostic>;
+    };
+    "weave.stale": {
+        input: {
+            path: string;
+            pinned: T.Pinned;
+            installed: T.Installed;
+            plan: T.Plan;
+            lock?: T.Lock;
+            declared: T.Declared;
+        };
+        output: T.Result<null, T.Diagnostic>;
+    };
+    "weave.replan": {
+        input: {
+            path: string;
+            pinned: T.Pinned;
+            plan: T.Plan;
+        };
+        output: T.Result<T.Replanned, T.Diagnostic>;
+    };
     "systemone.settings": {
         input: {
             door: T.Door;

package/dist/project.d.ts

@@ -58,6 +58,15 @@ export interface WeaveOptions<R = AnyReflexes> extends DecideOptions {
      *  runs the plan as it stands. Absent and reached: nothing runs. */
     proceed?: ((plan: W.Weave) => boolean | Promise<boolean>) | undefined;
 }
+/** What `weave` takes for a plan read from a file — a `Pinned`, as `steps` returned it or as `JSON.parse` read it
+ *  back — beside a step's handlers: the yes over the whole plan, asked whatever its verdict, since a file's numbers
+ *  are whoever wrote them. Absent and reached: nothing runs, `unanswered`. The tags are the file's. */
+export interface PinnedOptions<R = AnyReflexes> {
+    confirm?: WeaveOptions<R>["confirm"];
+    ask?: WeaveOptions<R>["ask"];
+    proceed?: ((pinned: W.Pinned) => boolean | Promise<boolean>) | undefined;
+    signal?: AbortSignal | 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;
@@ -120,10 +129,17 @@ export interface Project<R = AnyReflexes> {
     /** 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>;
+     *  one threaded into a later one, sealed as a plan file: the sentence, the plan with its verdict before anything
+     *  runs, every answer the plan took and the pins they were gathered under. `JSON.stringify` writes it; `weave`
+     *  takes it, here or on another machine with the same project. Runs nothing. */
+    steps(input: string, options?: DecideOptions): Promise<W.Pinned>;
     /** 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 plan file run exactly: its pins checked against this project — a `DiagnosticError` names the first that
+     *  moved and its fix — the plan made again from the file's answers under the file's gate and refused when it does
+     *  not read the same, `proceed` asked, then every step run under the same handlers, a value bound at run time
+     *  decided by this project's adapter. */
+    weave(pinned: W.Pinned, options?: PinnedOptions<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: {

package/dist/project.js

@@ -2,8 +2,10 @@
 // once; never fetched, never written. On it: `with`, the same project over a vocabulary of the call's own — a
 // tenant's words, their own plan in milliseconds; `decide`, one input asked, answered, read and gated; `fill`, an
 // ask answered and gated again; `run`, the chosen call's body; `handle`, the whole loop; `steps`, one request
-// read into steps, and `weave`, the steps run stage by stage under the same handlers. In: LoadOptions; inputs;
-// decisions. Out: a Project, decisions, results, plans.
+// read into steps and sealed as a plan file — the sentence, the answers, the pins — and `weave`, the steps run
+// stage by stage under the same handlers, from a sentence or from such a file, whose pins are checked and whose
+// plan is made again from its answers. In: LoadOptions; inputs; decisions; plan files. Out: a Project, decisions,
+// results, plans.
 import { realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { answered } from "./adapter.js";
@@ -24,6 +26,7 @@ export async function load(options) {
     const lock = files.lock === undefined ? undefined : call("lock", { doc: { file: { type: "lock" }, toml: files.lock } }, "load()");
     const adapter = options.adapter ?? (await named(project, root));
     const reflexes = {};
+    const values = {};
     const dirs = {};
     const bodies = {};
     const shipped = {};
@@ -39,6 +42,10 @@ export async function load(options) {
             throw refused(name, `${name} is both in evoke.toml and passed to load`, { type: "remove", reflex: name });
         }
         const configured = held(project.config[name] ?? {});
+        for (const [key, setting] of Object.entries(project.config[name] ?? {})) {
+            if (setting.type === "plain")
+                (values[name] ??= {})[key] = setting.value;
+        }
         if (location.type === "local") {
             if (root === undefined)
                 throw refused(name, `${name} is a local reflex, but load has no root`, { type: "remove", reflex: name });
@@ -94,7 +101,7 @@ export async function load(options) {
     }
     const installed = { reflexes, vocab, adapter: adapter.id, evoke: call("version", {}) };
     const platform = options.platform ?? PLATFORM;
-    return make({ installed, adapter, platform, dirs, bodies, shipped, local }, "load()");
+    return make({ installed, values, project, lock, adapter, platform, dirs, bodies, shipped, local }, "load()");
 }
 /** The adapter evoke.toml names, from its own subpath; a recording is never resolved by name. */
 async function named(project, root) {
@@ -134,11 +141,12 @@ function word(name, doc, overlay) {
     const effective = call("effective", { shipped: manifest, ...(yours === undefined ? {} : { yours }) });
     return { wording: { ok: effective }, manifest };
 }
-/** How each configured key is held: the value, or a variable and whether it is set — never a secret's value. */
+/** How each configured key is held: plain, its value handed beside the set, or a variable and whether it is set —
+ *  never a value, never a secret. */
 function held(settings) {
     const held = {};
     for (const [key, setting] of Object.entries(settings)) {
-        held[key] = setting.type === "plain" ? setting : { type: "env", var: setting.var, set: process.env[setting.var] !== undefined };
+        held[key] = setting.type === "plain" ? { type: "plain" } : { type: "env", var: setting.var, set: process.env[setting.var] !== undefined };
     }
     return held;
 }
@@ -178,11 +186,14 @@ function askedFor(step, tags) {
     const own = narrowed ? step.reflex : undefined;
     return own === undefined ? { text: step.text, tags } : { text: step.text, only: own };
 }
+function gathering() {
+    return { answers: { decided: [] }, traces: new Map(), entries: [] };
+}
 /** The project over its ground: the set compiled, every reflex's status read off the plan. The implementation
  *  speaks the wire's shapes; the app's R lives on the interface alone. */
 function make(ground, invoked) {
-    const { installed, adapter, platform, dirs, bodies, shipped, local } = ground;
-    const plan = call("compile", { set: installed, platform, ...(adapter.limits === undefined ? {} : { limits: adapter.limits }) }, invoked);
+    const { installed, values, project: owned, lock, adapter, platform, dirs, bodies, shipped, local } = ground;
+    const plan = call("compile", { set: installed, values, platform, ...(adapter.limits === undefined ? {} : { limits: adapter.limits }) }, invoked);
     if (adapter.plan !== undefined && adapter.plan !== plan.digest) {
         const message = `the recording was made against plan ${adapter.plan}, not ${plan.digest}`;
         throw new DiagnosticError([{ message, fix: { type: "rerun" }, command: "replay(file, { record: jev() })" }]);
@@ -198,6 +209,8 @@ function make(ground, invoked) {
         }
     }
     const gate = adapter.gate === undefined ? {} : { gate: adapter.gate };
+    const declared = { id: adapter.id, ...(adapter.limits === undefined ? {} : { limits: adapter.limits }), ...gate };
+    const locked = lock === undefined ? {} : { lock };
     const project = {
         reflexes,
         plan: plan.digest,
@@ -218,12 +231,7 @@ function make(ground, invoked) {
         },
         async decide(input, options = {}) {
             nonEmpty(input, "decide");
-            const invoked = invocation(input);
-            const request = call("request", { plan, input, tags: options.tags ?? [], ...(options.only === undefined ? {} : { only: options.only }), scope: "full" }, invoked);
-            const { raw, trace } = await answered(adapter, request, plan.deadline, options.signal, invoked);
-            const reading = call("read", { plan, request, raw }, invoked);
-            const decision = call("gate", { plan, reading, ...gate });
-            return lined(decision, { input, plan: plan.digest, trace: [trace] });
+            return (await decidedText(input, options)).decision;
         },
         fill(decision, given) {
             const asking = own(decision, "fill");
@@ -269,19 +277,23 @@ function make(ground, invoked) {
         },
         async steps(input, options = {}) {
             nonEmpty(input, "steps");
-            return planned(input, options, { decided: [] }, new Map());
+            const gathered = gathering();
+            const weave = await planned(input, options, gathered);
+            return call("weave.pin", { installed, plan, project: owned, ...locked, declared, input, tags: options.tags ?? [], weave, answers: gathered.entries });
         },
         async weave(input, options = {}) {
+            if (typeof input !== "string")
+                return pinnedRun(input, options);
+            const handlers = options;
             nonEmpty(input, "weave");
-            const traces = new Map();
-            const answers = { decided: [] };
-            let woven = await planned(input, options, answers, traces);
+            const gathered = gathering();
+            let woven = await planned(input, handlers, gathered);
             // What the plan asks before anything runs: a step's own question, answered, and the plan made again.
             while (woven.verdict.outcome === "ask") {
-                const filled = await askedUpFront(woven, answers, options, traces);
+                const filled = await askedUpFront(woven, gathered.answers, handlers, gathered.traces);
                 if (filled !== "filled")
                     return { plan: woven, status: filled, steps: [] };
-                const again = await planned(input, options, answers, traces);
+                const again = await planned(input, handlers, gathered);
                 // A plan that asks the same again could not take the answer: unanswered, never a loop.
                 if (JSON.stringify(again.verdict) === JSON.stringify(woven.verdict))
                     return { plan: again, status: "unanswered", steps: [] };
@@ -290,17 +302,28 @@ function make(ground, invoked) {
             if (woven.verdict.outcome === "refuse")
                 return { plan: woven, status: "refused", steps: [] };
             if (woven.verdict.outcome === "confirm") {
-                if (options.proceed === undefined)
+                if (handlers.proceed === undefined)
                     return { plan: woven, status: "unanswered", steps: [] };
-                if (!(await options.proceed(woven)))
+                if (!(await handlers.proceed(woven)))
                     return { plan: woven, status: "declined", steps: [] };
             }
-            return executed(woven, options, traces);
+            return executed(woven, handlers, gathered);
         },
     };
-    /** The plan over the answers gathered so far: the adapter asked and texts decided until it stands. */
-    async function planned(input, options, answers, traces) {
+    /** One text asked, answered, read and gated, its raw answers kept beside the decision — for the plan file. */
+    async function decidedText(input, options) {
+        const invoked = invocation(input);
+        const request = call("request", { plan, input, tags: options.tags ?? [], ...(options.only === undefined ? {} : { only: options.only }), scope: "full" }, invoked);
+        const { raw, trace } = await answered(adapter, request, plan.deadline, options.signal, invoked);
+        const reading = call("read", { plan, request, raw }, invoked);
+        const decision = call("gate", { plan, reading, ...gate });
+        return { decision: lined(decision, { input, plan: plan.digest, trace: [trace] }), raw };
+    }
+    /** The plan over the answers gathered so far: the adapter asked and texts decided until it stands, every answer
+     *  kept as an entry of the plan file. */
+    async function planned(input, options, gathered) {
         const invoked = `steps(${JSON.stringify(shown(input))})`;
+        const { answers, entries } = gathered;
         for (;;) {
             const planning = call("weave.plan", { plan, ...gate, input, tags: options.tags ?? [], answers }, invoked);
             if (planning.type === "done")
@@ -308,26 +331,69 @@ function make(ground, invoked) {
             const { need } = planning;
             if (need.type === "decide") {
                 // Side by side: each text is its own adapter call.
-                answers.decided.push(...(await Promise.all(need.asked.map(async (asked) => [asked, await decided(asked, options, traces)]))));
+                const decisions = await Promise.all(need.asked.map(async (asked) => [asked, await decided(asked, options, gathered)]));
+                answers.decided.push(...decisions);
                 continue;
             }
             const { raw } = await answered(adapter, need.request, plan.deadline, options.signal, invoked);
+            entries.push({ text: need.request.state.request, raw });
             if (need.type === "judge")
                 answers.judged = raw;
             else
                 answers.referred = raw;
         }
     }
-    /** One text decided as the plan asks — over the tags, or one reflex alone — its trace kept by what was asked. */
-    async function decided(asked, options, traces) {
-        const decision = await project.decide(asked.text, {
+    /** One text decided as the plan asks — over the tags, or one reflex alone — its trace kept by what was asked and
+     *  its raw answers as an entry. */
+    async function decided(asked, options, gathered) {
+        const { decision, raw } = await decidedText(asked.text, {
             ...(asked.only === undefined ? { tags: asked.tags ?? [] } : { only: asked.only }),
             ...(options.signal === undefined ? {} : { signal: options.signal }),
         });
-        traces.set(key(asked), decision.trace);
+        gathered.traces.set(key(asked), decision.trace);
+        gathered.entries.push({ text: asked.text, raw });
         // The whole decision crosses: the core reads its own fields and ignores the SDK's.
         return decision;
     }
+    /** A plan file run: read through the core, `plan = 1` required; its pins against this project, the first that
+     *  moved refused; the plan made again from its answers under its gate, refused when it does not read the same;
+     *  a plan that asks or refuses runs nothing, since a file holds no one's answers; then the yes over the whole
+     *  plan, and every step under the handlers, a value bound at run time decided by this project's adapter. */
+    async function pinnedRun(json, options) {
+        const path = "plan";
+        const sentence = typeof json === "object" && json !== null && typeof json.input === "string" ? json.input : "<input>";
+        const pinned = planFile("weave.pinned", { path, json }, sentence);
+        planFile("weave.stale", { path, pinned, installed, plan, ...locked, declared }, pinned.input);
+        const replanned = planFile("weave.replan", { path, pinned, plan }, pinned.input);
+        const woven = replanned.weave;
+        if (woven.verdict.outcome === "ask")
+            return { plan: woven, status: "unanswered", steps: [] };
+        if (woven.verdict.outcome === "refuse")
+            return { plan: woven, status: "refused", steps: [] };
+        if (options.proceed === undefined)
+            return { plan: woven, status: "unanswered", steps: [] };
+        if (!(await options.proceed(pinned)))
+            return { plan: woven, status: "declined", steps: [] };
+        const handlers = {
+            tags: pinned.tags ?? [],
+            ...(options.confirm === undefined ? {} : { confirm: options.confirm }),
+            ...(options.ask === undefined ? {} : { ask: options.ask }),
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+        };
+        return executed(woven, handlers, gathering());
+    }
+    /** One op over a plan file: its refusal a `DiagnosticError` whose save line reads as the call that makes the
+     *  plan again here. */
+    function planFile(op, input, sentence) {
+        const answer = reply(op, input);
+        if ("ok" in answer)
+            return answer.ok;
+        if ("bug" in answer)
+            throw bug(answer.bug);
+        const diagnostic = answer.err;
+        const fixed = diagnostic.fix.type === "save" ? `steps(${JSON.stringify(shown(sentence))})` : command(diagnostic.fix);
+        throw new DiagnosticError([{ ...diagnostic, command: fixed }]);
+    }
     /** The plan's own questions before anything runs. A step's required argument no binding covers is asked as
      *  `handle` asks one — the ask narrowed to what nothing binds — and the step's decision replaced for the plan
      *  to stand again. Several fields, or one record of several, no handler can answer: unanswered. */
@@ -378,9 +444,10 @@ function make(ground, invoked) {
      *  signal aborted mid-run is a cancel: every body's group ended, the rounds under way and every round after
      *  reported `skipped · cancelled`, and the rejection — the signal's reason — carrying the record once it is
      *  whole. */
-    async function executed(woven, options, traces) {
+    async function executed(woven, options, gathered) {
         const invoked = `weave(${JSON.stringify(shown(woven.input))})`;
         const { signal } = options;
+        const { traces } = gathered;
         const progress = { decided: [], handled: [] };
         const rounds = new Map();
         const record = (handling, decision, became) => {
@@ -413,7 +480,7 @@ function make(ground, invoked) {
             const { todo } = running;
             if (todo.type === "decide") {
                 try {
-                    progress.decided.push([todo.asked, await decided(todo.asked, options, traces)]);
+                    progress.decided.push([todo.asked, await decided(todo.asked, options, gathered)]);
                 }
                 catch (error) {
                     // The signal aborted the decision's call: the round it was for never starts.

package/dist/types.d.ts

@@ -157,6 +157,10 @@ export type Fix = {
     type: "test";
 } | {
     type: "help";
+} | {
+    type: "save";
+    file: string;
+    input: string;
 };
 /** A JSON value that keeps its key order: the wire form of every boundary type. */
 export type Json = unknown;
@@ -583,15 +587,16 @@ export interface Item {
     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. */
+/** How a set config key is held: plain, its value handed to `compile` beside the set and never in it, or a variable that is set or not. Never a value, never a secret. */
 export type Held = {
     type: "plain";
-    value: string;
 } | {
     type: "env";
     var: VarName;
     set: boolean;
 };
+/** The plain settings' values, per reflex and key, as `evoke.toml` holds them: handed to `compile` beside the set, so the digest holds no value. */
+export type Values = Record<LocalName, Record<ConfigKey, string>>;
 /** 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. */
@@ -1085,6 +1090,64 @@ export interface Executed {
     steps: StepOutcome[];
     worst: Status;
 }
+/** A plan file: the sentence as typed, the plan, the pins it was decided under, and every engine answer it took. What
+ *  `steps` returns and `weave` takes; `JSON.stringify` writes it. No time, no name, no trace. */
+export interface Pinned {
+    /** Fixed text, ignored on read. */
+    note: string;
+    /** The format revision: `1`. */
+    plan: 1;
+    /** The sentence as typed: what a re-plan plans, since the request as read is not always read the same. */
+    input: string;
+    /** Absent when none. */
+    tags?: Tag[];
+    weave: Weave;
+    /** The evoke that wrote it. */
+    evoke: Version;
+    adapter: LockedAdapter;
+    /** The floors the plan was decided under; absent when the adapter declared none. */
+    gate?: Gate;
+    /** The plan digest of the set it was decided over. */
+    set: Digest;
+    /** Every active reflex, by the hash of its item and its pin. */
+    reflexes: Record<LocalName, PinnedReflex>;
+    /** Every vocabulary, by the hash of its words. */
+    vocab: Record<VocabName, Digest>;
+    /** Every engine answer the plan took, one per text and question set. */
+    answers: Answer[];
+}
+/** One reflex of the plan's set: the hash of its item — wording, consent, settings — and its pin: a remote one's
+ *  ref as the lock writes it, its tag and `h1`; a local one's path as written; a reflex handed as code its item alone. */
+export type PinnedReflex = {
+    item: Digest;
+    ref: string;
+    tag: Version;
+    h1: Digest;
+} | {
+    item: Digest;
+    path: string;
+} | {
+    item: Digest;
+};
+/** One engine answer the plan took: the text it was asked about and the `Raw` as the engine gave it; the weave's own
+ *  questions stand under the whole request's text. */
+export interface Answer {
+    text: string;
+    raw: Raw;
+}
+/** The plan made again from a file: the weave, and per text what a line is rendered from. */
+export interface Replanned {
+    weave: Weave;
+    decided: Decided[];
+}
+/** One text decided from a file's answers: what was asked, the input's candidates, the raw answers, the decision. */
+export interface Decided {
+    asked: Asked;
+    /** Absent when none. */
+    proposed?: Proposed[];
+    raw: Raw;
+    decision: Decision;
+}
 /** What changed in the contract from one version to the next, and how much it matters. */
 export interface ContractDiff {
     level: Level;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evoke-build/evoke",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "You invoke a function; you evoke a reflex. The SDK: load a project of reflexes, decide with Jev, run.",
   "keywords": [
     "jev",