@evoke-build/evoke 0.6.0 → 0.8.0

package/dist/project.d.ts

@@ -20,7 +20,8 @@ export interface DecideOptions {
     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. */
+    /** Aborts the adapter call; `decide` rejects with the signal's reason. A weave's run it cancels: every body
+     *  ended, every step that did not finish `skipped · cancelled`, the rejection's reason carrying the record. */
     signal?: AbortSignal | undefined;
 }
 export interface RunOptions {
@@ -73,7 +74,8 @@ export interface WovenStep<R = AnyReflexes> {
 }
 /** 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. */
+ *  became of it, none when nothing ran. A weave the signal cancelled rejects with the signal's reason and carries
+ *  this record on it as `woven`: the steps that finished as they ended, every other one `skipped · cancelled`. */
 export interface Woven<R = AnyReflexes> {
     plan: W.Weave;
     status: W.Status;

package/dist/project.js

@@ -380,9 +380,13 @@ function make(ground, invoked) {
         return "filled";
     }
     /** The plan run: stage by stage, a stage's rounds each taken to the point of running in the words' order, then
-     *  their bodies together; a step decided again with its bound values in its words when the run asks for it. */
+     *  their bodies together; a step decided again with its bound values in its words when the run asks for it. The
+     *  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) {
         const invoked = `weave(${JSON.stringify(shown(woven.input))})`;
+        const { signal } = options;
         const progress = { decided: [], handled: [] };
         const rounds = new Map();
         const record = (handling, decision, became) => {
@@ -397,7 +401,7 @@ function make(ground, invoked) {
             const running = call("weave.execute", { plan, ...gate, weave: woven, progress }, invoked);
             if (running.type === "done") {
                 const { executed } = running;
-                return {
+                const whole = {
                     plan: woven,
                     status: executed.worst,
                     steps: executed.steps.map(step => ({
@@ -408,10 +412,21 @@ function make(ground, invoked) {
                         rounds: rounds.get(step.step) ?? [],
                     })),
                 };
+                if (signal?.aborted)
+                    throw carrying(signal.reason, whole);
+                return whole;
             }
             const { todo } = running;
             if (todo.type === "decide") {
-                progress.decided.push([todo.asked, await decided(todo.asked, options, traces)]);
+                try {
+                    progress.decided.push([todo.asked, await decided(todo.asked, options, traces)]);
+                }
+                catch (error) {
+                    // The signal aborted the decision's call: the round it was for never starts.
+                    if (!signal?.aborted || error !== signal.reason)
+                        throw error;
+                    progress.handled.push({ step: todo.step, round: todo.round, ...CANCELLED });
+                }
                 continue;
             }
             const bodies = [];
@@ -421,12 +436,17 @@ function make(ground, invoked) {
                 const own = step?.reflex === undefined || !handling.bound?.length ? undefined : traces.get(key({ text: handling.input, only: step.reflex }));
                 const trace = own ?? (step === undefined ? undefined : traces.get(key(askedFor(step, options.tags ?? [])))) ?? [];
                 const decision = lined(handling.decision, { input: handling.input, plan: plan.digest, trace });
+                // Nothing starts after the signal: a round handed after it is cancelled without a question asked.
+                if (signal?.aborted) {
+                    record(handling, decision, CANCELLED);
+                    continue;
+                }
                 const readied = await ready(decision, told(options, { step: handling.step, round: handling.round }));
                 if (!readied.ready) {
                     record(handling, readied.decision, { status: readied.status, why: readied.why });
                     continue;
                 }
-                bodies.push(ran(readied.decision, options.signal).then(became => record(handling, readied.decision, became)));
+                bodies.push(ran(readied.decision, signal).then(became => record(handling, readied.decision, became)));
             }
             await Promise.all(bodies);
         }
@@ -491,12 +511,15 @@ function make(ground, invoked) {
         const options = signal === undefined ? {} : { signal };
         return decision.outcome === "confirm" ? project.run(decision, { ...options, confirmed: true }) : project.run(decision, options);
     }
-    /** One body run for a weave: what it returned, or its failure as the step's own outcome, never the weave's. */
+    /** 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) {
         try {
             return { status: "ran", result: await bodied(decision, signal) };
         }
         catch (error) {
+            if (signal?.aborted && error === signal.reason)
+                return CANCELLED;
             if (error instanceof FailureError) {
                 return { status: "failed", why: { type: "said", message: error.why === undefined ? error.what : `${error.what}: ${error.why}` } };
             }
@@ -571,6 +594,16 @@ function make(ground, invoked) {
     }
     return project;
 }
+/** A round the signal cancelled, as its step and the record read it. */
+const CANCELLED = { status: "skipped", why: { type: "cancelled" } };
+/** The signal's reason with the record on it as `woven`, when the reason is something that can carry one: what
+ *  a cancelled `weave` rejects with, so the caller's own test for a cancel holds and the steps are there to read. */
+function carrying(reason, woven) {
+    if (reason !== null && (typeof reason === "object" || typeof reason === "function") && Object.isExtensible(reason)) {
+        Object.assign(reason, { woven });
+    }
+    return reason;
+}
 /** Whether two asks want the same things for the same reasons. */
 function same(after, before) {
     return JSON.stringify(after) === JSON.stringify(before);

package/dist/types.d.ts

@@ -754,6 +754,10 @@ export type Cap = {
 } | {
     type: "two_things";
     contender: Contender;
+}
+/** A weave merged a part that matched nothing on its own back into these words: never run unasked. */
+ | {
+    type: "merged";
 };
 /** The confirm prompt: `evoke`'s own line, then the manifest's template filled in. */
 export interface Prompt {
@@ -971,6 +975,10 @@ export type WeaveWhy = {
 } | {
     type: "read_as";
     reflex: LocalName;
+}
+/** The weave was cancelled: the round the host ended, and every step that had not finished by then. */
+ | {
+    type: "cancelled";
 } | {
     type: "said";
     message: string;
@@ -991,6 +999,8 @@ export interface Progress {
 /** What the run needs a host to do next. */
 export type Todo = {
     type: "decide";
+    step: number;
+    round: number;
     asked: Asked;
 } | {
     type: "handle";

package/package.json

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

package/runtime/loader.mjs

@@ -2,11 +2,12 @@
 // and its default export called with (args, { input, config, signal }), then one result line on stdout:
 // { text, data? } or { error, refused? } — `refused` when the error is a refusal by Node's permission model or the
 // kernel: what was refused, a permission or a syscall, and the path, so the host names the declaration's key. It
-// exits when stdin closes, before or during a body, so its life is bounded by its parent's. The body's console
-// and stdout go to stderr, as do the frames of an error it throws — the frames alone, without the message the
-// host reports, and without the frames inside Node itself; an error thrown from a callback ends the body as a
-// rejection does. SIGTERM and the deadline abort `signal`; a body that has not settled a second later is
-// abandoned. The SDK ships this same file.
+// exits when stdin closes before a body, and during one aborts the body's `signal` first, so its life is bounded
+// by its parent's and the body still hears the end. The body's console and stdout go to stderr, as do the frames
+// of an error it throws — the frames alone, without the message the host reports, and without the frames inside
+// Node itself; an error thrown from a callback ends the body as a rejection does. SIGTERM, the deadline and
+// stdin's end abort `signal`; a body that has not settled a second later is abandoned. The SDK ships this same
+// file.
 import { writeSync } from "node:fs";
 import module from "node:module";
 import { pathToFileURL } from "node:url";
@@ -23,6 +24,12 @@ try {
   // Nothing to warm.
 }
 const controller = new AbortController();
+// The body's signal aborted with the reason, and the loader gone a grace later whatever the body does: with a
+// line for the host when it is still there to read one, silently when it is not.
+const stop = (why, report) => {
+  if (!controller.signal.aborted) controller.abort(new Error(why));
+  setTimeout(() => (report ? fail(why) : process.exit(1)), GRACE);
+};
 // The whole line, however long: `process.stdout` below puts the pipe in non-blocking mode, so one write may take
 // part of it, and the next may be told to wait a moment.
 const out = (value) => {
@@ -56,7 +63,8 @@ process.stdin.on("data", (chunk) => {
     run(buffered.slice(0, end));
   }
 });
-process.stdin.on("end", () => process.exit(started ? 1 : 0));
+// The host is gone: before a body, nothing to do; during one, the body hears it and the loader follows.
+process.stdin.on("end", () => (started ? stop("the host is gone", false) : process.exit(0)));
 
 async function run(line) {
   let envelope;
@@ -66,13 +74,9 @@ async function run(line) {
     return fail(`the envelope is not JSON: ${error.message}`);
   }
   const { run, args, input, config, deadline } = envelope;
-  const stop = (why) => {
-    if (!controller.signal.aborted) controller.abort(new Error(why));
-    setTimeout(() => fail(why), GRACE);
-  };
-  process.on("SIGTERM", () => stop("terminated"));
+  process.on("SIGTERM", () => stop("terminated", true));
   process.on("uncaughtException", thrown);
-  const timer = setTimeout(() => stop(`timed out after ${deadline} ms`), deadline);
+  const timer = setTimeout(() => stop(`timed out after ${deadline} ms`, true), deadline);
   try {
     const module = await import(pathToFileURL(run).href);
     if (module.default === undefined) throw new Error(`${run} has no default export`);