@evoke-build/evoke 0.8.0 → 0.9.0

package/dist/ops.d.ts

@@ -183,11 +183,12 @@ export interface Ops {
         input: {
             chosen: T.Chosen;
             active: T.Active;
+            taken?: Record<T.ArgName, T.Json>;
             input: T.Input;
             deadline: T.Millis;
             home: string;
         };
-        output: T.Envelope;
+        output: T.Result<T.Envelope, T.Diagnostic>;
     };
     argv: {
         input: {

package/dist/project.js

@@ -248,27 +248,18 @@ function make(ground, invoked) {
             }
             if (outcome !== "run" && outcome !== "confirm")
                 throw new TypeError(`a ${outcome} decision cannot run`);
-            const active = plan.active[chosen.reflex];
-            if (active === undefined)
-                throw refused(chosen.reflex, `${chosen.reflex} is not active`, { type: "rerun" }, "run(d)");
-            const spent = chosen.trace.reduce((sum, entry) => sum + entry.ms, 0);
-            // The whole decision crosses: the core reads the fields of a Chosen and ignores the SDK's own.
-            const wire = chosen;
-            const envelope = call("envelope", { chosen: wire, active, input: chosen.input, deadline: Math.max(plan.deadline - spent, 0), home: homedir() });
-            const what = `running ${chosen.reflex}`;
-            const body = bodies[chosen.reflex];
-            if (body !== undefined)
-                return inline(what, body, envelope, options.signal);
-            const dir = dirs[chosen.reflex];
-            if (dir === undefined)
-                throw refused(chosen.reflex, `${chosen.reflex} has no body to run`, { type: "sync" }, "run(d)");
-            return contained(what, chosen, active, dir, envelope, options.signal);
+            // A whole result is handed by the plan alone: a call that takes one runs only as a step of a weave.
+            taker(chosen);
+            return running(chosen, {}, options);
         },
         async handle(input, options = {}) {
             nonEmpty(input, "handle");
-            const readied = await ready(await project.decide(input, options), options);
+            const decision = await project.decide(input, options);
+            if (decision.outcome !== "abstain")
+                taker(decision);
+            const readied = await ready(decision, options);
             if (readied.ready)
-                return { outcome: "ran", decision: readied.decision, result: await bodied(readied.decision, options.signal) };
+                return { outcome: "ran", decision: readied.decision, result: await running(readied.decision, {}, signalled(options.signal)) };
             if (readied.status === "refused")
                 return { outcome: "abstained", decision: readied.decision };
             return { outcome: readied.status, decision: readied.decision };
@@ -446,7 +437,7 @@ function make(ground, invoked) {
                     record(handling, readied.decision, { status: readied.status, why: readied.why });
                     continue;
                 }
-                bodies.push(ran(readied.decision, signal).then(became => record(handling, readied.decision, became)));
+                bodies.push(ran(readied.decision, handling.taken ?? {}, signal).then(became => record(handling, readied.decision, became)));
             }
             await Promise.all(bodies);
         }
@@ -506,16 +497,40 @@ function make(ground, invoked) {
             ...(ask === undefined ? {} : { ask: (decision) => ask(decision, turn) }),
         };
     }
-    /** A decision ready to run, run: a confirm once confirmed. */
-    function bodied(decision, signal) {
-        const options = signal === undefined ? {} : { signal };
-        return decision.outcome === "confirm" ? project.run(decision, { ...options, confirmed: true }) : project.run(decision, options);
+    /** A reflex that takes a whole result, met outside a weave: refused before any confirm, since only a request of
+     *  several steps hands one. */
+    function taker(decision) {
+        const takes = Object.values(plan.active[decision.reflex]?.takes ?? {});
+        if (takes.length === 0)
+            return;
+        throw refused(decision.reflex, `${decision.reflex} takes ${words(takes)}, which a step before it in the same request returns`, { type: "rerun" }, 'weave("<input>")');
     }
-    /** One body run for a weave: what it returned, or its failure as the step's own outcome, never the weave's; a
-     *  body the signal ended is the round cancelled. */
-    async function ran(decision, signal) {
+    /** The chosen call's body — in-process, in a child through the loader, or as an argv — with the whole results it
+     *  takes beside its values, which only the weave hands; one the plan did not hand is refused by the envelope, the
+     *  last guard. What `run` does for a call that takes none, and every step of a weave for its round. */
+    async function running(decision, taken, options) {
+        const chosen = own(decision, "run");
+        const active = plan.active[chosen.reflex];
+        if (active === undefined)
+            throw refused(chosen.reflex, `${chosen.reflex} is not active`, { type: "rerun" }, "run(d)");
+        const spent = chosen.trace.reduce((sum, entry) => sum + entry.ms, 0);
+        // The whole decision crosses: the core reads the fields of a Chosen and ignores the SDK's own.
+        const wire = chosen;
+        const envelope = call("envelope", { chosen: wire, active, taken, input: chosen.input, deadline: Math.max(plan.deadline - spent, 0), home: homedir() }, "run(d)");
+        const what = `running ${chosen.reflex}`;
+        const body = bodies[chosen.reflex];
+        if (body !== undefined)
+            return inline(what, body, envelope, options.signal);
+        const dir = dirs[chosen.reflex];
+        if (dir === undefined)
+            throw refused(chosen.reflex, `${chosen.reflex} has no body to run`, { type: "sync" }, "run(d)");
+        return contained(what, chosen, active, dir, envelope, options.signal);
+    }
+    /** One body run for a weave, the whole results its step takes beside it: what it returned, or its failure as the
+     *  step's own outcome, never the weave's; a body the signal ended is the round cancelled. */
+    async function ran(decision, taken, signal) {
         try {
-            return { status: "ran", result: await bodied(decision, signal) };
+            return { status: "ran", result: await running(decision, taken, signalled(signal)) };
         }
         catch (error) {
             if (signal?.aborted && error === signal.reason)
@@ -604,6 +619,15 @@ function carrying(reason, woven) {
     }
     return reason;
 }
+/** A signal as run options: none when there is none. */
+function signalled(signal) {
+    return signal === undefined ? {} : { signal };
+}
+/** `a`, `a and b`, `a, b and c`. */
+function words(names) {
+    const last = names.at(-1) ?? "";
+    return names.length < 2 ? last : `${names.slice(0, -1).join(", ")} and ${last}`;
+}
 /** Whether two asks want the same things for the same reasons. */
 function same(after, before) {
     return JSON.stringify(after) === JSON.stringify(before);

package/dist/reflex.d.ts

@@ -10,17 +10,21 @@ export interface InlineManifest {
     effect?: Effect;
     /** The one-line template a person confirms, naming required arguments only. */
     confirm: string;
+    /** The arguments: a question and one source each, or a whole result an earlier step returns, taken by its name. */
     args?: Record<string, InlineArg>;
     /** What the body's `data` yields for a later step to take: per field, the recognizer that reads it, or a list of
      *  records with such fields. */
     yields?: Record<string, Recognizer | {
         each: Record<string, Recognizer>;
     }>;
+    /** The name the body's whole `data` goes by, for a later step to take. */
+    returns?: string;
     examples?: InlineRecords;
     tests?: InlineRecords;
 }
-/** An argument: its question and exactly one source; a flag is optional by nature. */
-export type InlineArg = {
+/** An argument: its question and exactly one source, a flag optional by nature; or `takes` alone, a whole result
+ *  an earlier step returns, by the name that result goes by — filled by the plan, never asked. */
+export type InlineArg = ({
     ask: string;
 } & ({
     options: Record<string, string>;
@@ -37,7 +41,9 @@ export type InlineArg = {
     optional?: boolean;
 } | {
     flag: true;
-});
+})) | {
+    takes: string;
+};
 /** Utterances with what they assert: a record per argument — the text, or `false` for unstated, `true` for a flag —
  *  or `false` for never this reflex. */
 export type InlineRecords = Record<string, Record<string, string | boolean> | false>;
@@ -57,23 +63,34 @@ type Absent<A> = A extends {
 } | {
     flag: true;
 } ? true : false;
+type Taken<A> = A extends {
+    takes: string;
+} ? true : false;
 type Flat<T> = {
     [K in keyof T]: T[K];
 } & {};
 type ArgsOf<M extends InlineManifest> = NonNullable<M["args"]> extends Record<string, InlineArg> ? NonNullable<M["args"]> : Record<never, InlineArg>;
-/** What a decision carries for a reflex handed as code: its arguments as the wire types them, optional ones optional. */
+/** The asked arguments alone: a taken one never travels in a decision. */
+type AskedOf<M extends InlineManifest> = {
+    [N in keyof ArgsOf<M> as Taken<ArgsOf<M>[N]> extends true ? never : N]: ArgsOf<M>[N];
+};
+/** What a decision carries for a reflex handed as code: its asked arguments as the wire types them, optional ones
+ *  optional. */
 export type Carried<M extends InlineManifest> = Flat<{
-    [N in keyof ArgsOf<M> as Absent<ArgsOf<M>[N]> extends true ? never : N]: Typed<ArgsOf<M>[N]>;
+    [N in keyof AskedOf<M> as Absent<AskedOf<M>[N]> extends true ? never : N]: Typed<AskedOf<M>[N]>;
 } & {
-    [N in keyof ArgsOf<M> as Absent<ArgsOf<M>[N]> extends true ? N : never]?: Typed<ArgsOf<M>[N]>;
+    [N in keyof AskedOf<M> as Absent<AskedOf<M>[N]> extends true ? N : never]?: Typed<AskedOf<M>[N]>;
 }>;
 /** What decisions carry for a map of reflexes handed as code: `load<Reflexes & ReflexesOf<typeof own>>` when a
  *  project has installed reflexes beside them. */
 export type ReflexesOf<I> = {
     [K in keyof I]: I[K] extends Inline<infer S> ? S : never;
 };
-/** The body's arguments, plain: what `reflex`'s body receives. */
-export type Args<M extends InlineManifest> = Values<Carried<M>>;
+/** The body's arguments, plain: what `reflex`'s body receives — the asked arguments' values, and each whole result
+ *  it takes as `unknown`, since evoke checks no shape. */
+export type Args<M extends InlineManifest> = Flat<Values<Carried<M>> & {
+    [N in keyof ArgsOf<M> as Taken<ArgsOf<M>[N]> extends true ? N : never]: unknown;
+}>;
 /** What `reflex` returns and `load` takes; `shape` never holds a value — it is what a decision carries, for inference. */
 export interface Inline<S = Record<string, Value>> {
     readonly manifest: InlineManifest;

package/dist/types.d.ts

@@ -175,9 +175,14 @@ export interface Manifest {
     /** What the body may touch; absent, the tightest declaration. Contract, like `run`. */
     needs?: Needs;
     config: Record<ConfigKey, ConfigSpec>;
+    /** The arguments the classifier is asked about: `ask` and one source each. */
     args: Record<ArgName, Argument>;
+    /** The arguments an earlier step's whole result fills, by the name that result goes by; absent when none. Contract. */
+    takes?: Record<ArgName, FieldName>;
     /** What the body's `data` yields for a later step to take, per field. */
     yields: Record<FieldName, Yield>;
+    /** The name the body's whole `data` goes by, for a later step to take; absent when none. Contract. */
+    returns?: FieldName;
     examples: Records;
     tests: Records;
     /** Keys the format does not know: reported, never fatal. */
@@ -604,9 +609,14 @@ export interface Active {
     /** Absent: the tightest declaration. */
     needs?: Needs;
     confirm: Template;
+    /** The arguments the classifier is asked about. */
     args: Record<ArgName, Argument>;
+    /** The arguments an earlier step's whole result fills, by the name that result goes by; absent when none. */
+    takes?: Record<ArgName, FieldName>;
     /** What the body's `data` yields for a later step to take, per field. */
     yields: Record<FieldName, Yield>;
+    /** The name the body's whole `data` goes by, for a later step to take; absent when none. */
+    returns?: FieldName;
     config: Record<ConfigKey, Setting>;
     tags: Tag[];
 }
@@ -799,8 +809,9 @@ 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>;
+    /** An option key, a word's `value` if set else the word, a pick's value, `true` for a flag, and a whole result as
+     *  its source returned it. */
+    args: Record<ArgName, Json>;
     input: Input;
     /** An `env` setting stays a reference; the host resolves it. */
     config: Record<ConfigKey, Setting>;
@@ -883,15 +894,19 @@ export interface Step {
     /** 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. */
+/** How a bound value reaches its step: answering its own ask; the step decided again with the value in its words; or a
+ *  whole result handed beside the decision, never through its words. */
+export type Via = "fill" | "rewrite" | "takes";
+/** A value of one step's result taken by a later step: which field, into which argument, how; or the whole result, by
+ *  the name it goes by. */
 export interface Binding {
     from: number;
     to: number;
     arg: ArgName;
+    /** The field taken; for `takes`, the name the whole result goes by. */
     field: FieldName;
-    kind: Recognizer;
+    /** The recognizer the field is read with; absent for a whole result. */
+    kind?: Recognizer;
     via: Via;
     /** The list field of the source's result whose records carry `field`: the step runs once per record. */
     each?: FieldName;
@@ -920,6 +935,19 @@ export type Because = {
     type: "takes_nothing";
     step: number;
     sources: number[];
+}
+/** A whole result the step takes by name that no step before it returns: refused, nothing answers it. */
+ | {
+    type: "no_source";
+    step: number;
+    name: FieldName;
+}
+/** What the step takes one of that several steps return, or one step once per record: refused. */
+ | {
+    type: "several_sources";
+    step: number;
+    name: FieldName;
+    sources: number[];
 };
 /** The verdict before anything runs, with every reason. */
 export interface Verdict {
@@ -940,19 +968,20 @@ export interface Weave {
     stages: number[][];
     verdict: Verdict;
 }
-/** A value bound into a step at its turn. */
+/** A value bound into a step at its turn; a whole result carries no value here, it stays on its source's line. */
 export interface Bound {
     arg: ArgName;
     from: number;
     field: FieldName;
-    value: string;
+    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. */
+/** One round of a step for a host to take through the foundation's loop, the bound values in place and the whole
+ *  results the body receives beside them. */
 export interface Handling {
     step: number;
     /** From 0; a step bound to a list runs one round per record. */
@@ -960,14 +989,24 @@ export interface Handling {
     decision: Decision;
     input: string;
     bound?: Bound[];
+    /** Per taken argument, its source's whole `data`: the same for every round of the step. */
+    taken?: Record<ArgName, Json>;
 }
 /** 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";
-} | {
+}
+/** The step it names yielded nothing it can take: no such field, no data, or null. */
+ | {
     type: "nothing_to_take";
+    from: number;
+}
+/** The step it names returned a whole result over the cap, a mebibyte of JSON. */
+ | {
+    type: "too_large";
+    from: number;
 } | {
     type: "found_nothing";
 } | {
@@ -1035,7 +1074,7 @@ export interface ContractDiff {
 }
 /** `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. */
+/** One change to the contract, in the order the diff walks: the previous arguments, the added ones, the body, what it may touch, config, what the result yields, what the reflex takes, then what it returns. */
 export type Change = {
     type: "arg_removed";
     arg: ArgName;
@@ -1093,6 +1132,27 @@ export type Change = {
 } | {
     type: "yield_changed";
     field: FieldName;
+} | {
+    type: "takes_added";
+    arg: ArgName;
+    name: FieldName;
+} | {
+    type: "takes_removed";
+    arg: ArgName;
+    name: FieldName;
+} | {
+    type: "takes_changed";
+    arg: ArgName;
+    name: FieldName;
+} | {
+    type: "returns_added";
+    name: FieldName;
+} | {
+    type: "returns_removed";
+    name: FieldName;
+} | {
+    type: "returns_changed";
+    name: FieldName;
 };
 /** `was` is flat and cumulative: a retired name never returns as a live argument, and never leaves the lists. */
 export type WasViolation = {

package/package.json

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