@evoke-build/evoke 0.9.0 → 0.10.1

package/dist/contain.d.ts

@@ -1,4 +1,6 @@
-import type { Contained, Facts, NeedsKey, Place, Policy, Program } from "./types.ts";
+import type { Contained, Facts, NeedsKey, Place, Platform, Policy, Program } from "./types.ts";
+/** This machine's platform, which the plan and the layers take. */
+export declare const PLATFORM: Platform;
 /** What the machine lacks that the declaration names: a path, or a program `PATH` does not hold. */
 export type Missing = {
     place: Place;

package/dist/contain.js

@@ -8,7 +8,8 @@ import { accessSync, closeSync, constants, mkdtempSync, openSync, readSync, real
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { call } from "./core.js";
-const PLATFORM = process.platform === "linux" ? "linux" : "macos";
+/** This machine's platform, which the plan and the layers take. */
+export const PLATFORM = process.platform === "linux" ? "linux" : "macos";
 const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
 /** Whether this runtime's permission model holds the network: from Node 25, the first to know `--allow-net`. */
 const HOLDS_NETWORK = process.allowedNodeEnvironmentFlags.has("--allow-net");

package/dist/errors.d.ts

@@ -22,11 +22,13 @@ export declare class FaultError extends EvokeError {
     readonly fault: Fault;
     constructor(fault: Fault, message: string, command: string);
 }
-/** A host or a body failed: what was attempted, why, and what to do; a body's own error is the `cause`. */
+/** A host or a body failed: what was attempted, why, and what to do; a body's own error is the `cause`, and the
+ *  frames of an error a file body threw are `frames`, from the first. */
 export declare class FailureError extends EvokeError {
     readonly kind = "failure";
     readonly what: string;
     readonly why: string | undefined;
     readonly fix: Fix;
-    constructor(what: string, why: string | undefined, fix: Fix, command: string, options?: ErrorOptions);
+    readonly frames: readonly string[];
+    constructor(what: string, why: string | undefined, fix: Fix, command: string, options?: ErrorOptions, frames?: readonly string[]);
 }

package/dist/errors.js

@@ -30,17 +30,20 @@ export class FaultError extends EvokeError {
         this.fault = fault;
     }
 }
-/** A host or a body failed: what was attempted, why, and what to do; a body's own error is the `cause`. */
+/** A host or a body failed: what was attempted, why, and what to do; a body's own error is the `cause`, and the
+ *  frames of an error a file body threw are `frames`, from the first. */
 export class FailureError extends EvokeError {
     kind = "failure";
     what;
     why;
     fix;
-    constructor(what, why, fix, command, options) {
+    frames;
+    constructor(what, why, fix, command, options, frames = []) {
         super(`${what}${why === undefined ? "" : `: ${why}`}  →  ${command}`, command, options);
         this.what = what;
         this.why = why;
         this.fix = fix;
+        this.frames = frames;
     }
 }
 /** The CLI's line for one problem. */

package/dist/ops.d.ts

@@ -109,6 +109,7 @@ export interface Ops {
         input: {
             set: T.Installed;
             limits?: T.Limits;
+            platform?: T.Platform;
         };
         output: T.Result<T.Plan, T.Diagnostic>;
     };
@@ -369,7 +370,8 @@ export interface Ops {
     thieves: {
         input: {
             newcomers: T.LocalName[];
-            routed: [T.Case, T.LocalName | null][];
+            routed: T.Routed[];
+            floor?: T.Prob;
         };
         output: T.Theft[];
     };
@@ -395,6 +397,7 @@ export interface Ops {
     "weave.plan": {
         input: {
             plan: T.Plan;
+            gate?: T.Gate;
             input: string;
             tags: T.Tag[];
             answers: T.Answers;

package/dist/project.d.ts

@@ -14,6 +14,9 @@ export interface LoadOptions<R = AnyReflexes> {
     } | undefined;
     /** Who answers. Absent: the adapter evoke.toml names, from its own subpath; required without a root. */
     adapter?: Adapter | undefined;
+    /** The platform a manifest's `platforms` is judged by: this machine's when absent. A reflex named for another
+     *  is inactive; name one to decide or test as that machine would. A body still runs here. */
+    platform?: W.Platform | undefined;
 }
 export interface DecideOptions {
     /** Only reflexes carrying one of these tags are offered. */
@@ -129,6 +132,7 @@ export declare function load<R extends object = AnyReflexes>(options: {
         [K in keyof R]?: Inline<R[K]> | undefined;
     }> | undefined;
     adapter?: Adapter | undefined;
+    platform?: W.Platform | 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: {
@@ -137,4 +141,5 @@ export declare function load<R extends object = AnyReflexes>(options: {
         [K in keyof R]?: Inline<R[K]> | undefined;
     } | undefined;
     adapter: Adapter;
+    platform?: W.Platform | undefined;
 }): Promise<Project<R>>;

package/dist/project.js

@@ -7,7 +7,7 @@
 import { realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { answered } from "./adapter.js";
-import { facts, scratch, status } from "./contain.js";
+import { PLATFORM, facts, scratch, status } from "./contain.js";
 import { bug, call, command, fromCode, misnamed, problem, reply } from "./core.js";
 import { DiagnosticError, FailureError } from "./errors.js";
 import { entry, snapshot, text } from "./files.js";
@@ -93,7 +93,8 @@ export async function load(options) {
         vocab[name] = call("vocabulary", { doc: { file: { type: "vocab", name }, toml } }, "load()");
     }
     const installed = { reflexes, vocab, adapter: adapter.id, evoke: call("version", {}) };
-    return make({ installed, adapter, dirs, bodies, shipped, local }, "load()");
+    const platform = options.platform ?? PLATFORM;
+    return make({ installed, 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) {
@@ -169,17 +170,19 @@ function shown(input) {
 function key(asked) {
     return JSON.stringify([asked.text, asked.tags ?? [], asked.only ?? null]);
 }
-/** What the planner asked to decide a step, as its repair tells: a fragment narrowed to its neighbour's reflex, or
- *  spliced into its words, was decided under that reflex alone; any other step over the tags. */
+/** What the planner asked to decide a step, as its repair and its shared words tell: a fragment narrowed to its
+ *  neighbour's reflex, or spliced into its words, was decided under that reflex alone, and so were words a shared word
+ *  was written into; any other step over the tags. */
 function askedFor(step, tags) {
-    const own = step.repair === "narrowed" || step.repair === "spliced" ? step.reflex : undefined;
+    const narrowed = step.repair === "narrowed" || step.repair === "spliced" || Object.values(step.shared ?? {}).some(shared => shared.via === "rewrite");
+    const own = narrowed ? step.reflex : undefined;
     return own === undefined ? { text: step.text, tags } : { text: step.text, only: own };
 }
 /** 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, dirs, bodies, shipped, local } = ground;
-    const plan = call("compile", { set: installed, ...(adapter.limits === undefined ? {} : { limits: adapter.limits }) }, invoked);
+    const { installed, adapter, platform, dirs, bodies, shipped, local } = ground;
+    const plan = call("compile", { set: installed, 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() })" }]);
@@ -299,7 +302,7 @@ function make(ground, invoked) {
     async function planned(input, options, answers, traces) {
         const invoked = `steps(${JSON.stringify(shown(input))})`;
         for (;;) {
-            const planning = call("weave.plan", { plan, input, tags: options.tags ?? [], answers }, invoked);
+            const planning = call("weave.plan", { plan, ...gate, input, tags: options.tags ?? [], answers }, invoked);
             if (planning.type === "done")
                 return planning.weave;
             const { need } = planning;

package/dist/runtime.js

@@ -25,13 +25,17 @@ const LOADER = fileURLToPath(new URL("../runtime/loader.mjs", import.meta.url));
 const KEPT = ["PATH", "HOME", "TMPDIR", "LANG", "TERM"];
 /** What a body gets to settle after its signal aborts, and a group after SIGTERM before SIGKILL, in milliseconds. */
 const GRACE = 1000;
+/** Milliseconds as a person reads them: `30 s`, `1.5 s`, `0.05 s`. */
+function seconds(ms) {
+    return `${ms < 1000 ? (ms / 1000).toFixed(2) : Math.round(ms / 100) / 10} s`;
+}
 /** A function body, in-process: its arguments as the envelope carries them, the deadline as its signal. */
 export async function inline(what, body, envelope, signal) {
     signal?.throwIfAborted();
     const config = resolved(what, envelope.config);
     // Referenced timers: a body that hangs holding no handle cannot let the process exit before the deadline.
     const timeout = new AbortController();
-    const timer = setTimeout(() => timeout.abort(new DOMException(`no answer within ${envelope.deadline} ms`, "TimeoutError")), envelope.deadline);
+    const timer = setTimeout(() => timeout.abort(new DOMException(`no answer within ${seconds(envelope.deadline)}`, "TimeoutError")), envelope.deadline);
     const own = signal === undefined ? timeout.signal : AbortSignal.any([signal, timeout.signal]);
     let grace;
     const abandoned = new Promise(resolve => {
@@ -49,7 +53,7 @@ export async function inline(what, body, envelope, signal) {
         if (signal?.aborted)
             throw signal.reason;
         if ("abandoned" in outcome)
-            throw failed(what, `did not finish within ${envelope.deadline} ms`);
+            throw failed(what, `did not finish within ${seconds(envelope.deadline)}`);
         if ("threw" in outcome) {
             throw failed(what, outcome.threw instanceof Error ? outcome.threw.message : String(outcome.threw), undefined, outcome.threw);
         }
@@ -91,7 +95,7 @@ export async function child(what, dir, envelope, layers, signal) {
     if (error !== undefined)
         throw failed(what, error.message);
     if (timedOut)
-        throw failed(what, `did not finish within ${envelope.deadline} ms`);
+        throw failed(what, `did not finish within ${seconds(envelope.deadline)}`);
     const line = output.split("\n")[0] ?? "";
     let parsed;
     try {
@@ -105,7 +109,8 @@ export async function child(what, dir, envelope, layers, signal) {
         if (refused !== null && typeof refused === "object" && "what" in refused && "path" in refused) {
             throw new Refusal(String(parsed.error), { what: String(refused.what), path: String(refused.path) });
         }
-        throw failed(what, String(parsed.error));
+        const frames = "frames" in parsed && Array.isArray(parsed.frames) ? parsed.frames.map(String) : [];
+        throw failed(what, String(parsed.error), undefined, undefined, frames);
     }
     return result(what, parsed);
 }
@@ -139,7 +144,7 @@ export async function program(what, argv, envelope, layers, signal) {
     if (error !== undefined)
         throw failed(what, error.message);
     if (timedOut)
-        throw failed(what, `did not finish within ${envelope.deadline} ms`);
+        throw failed(what, `did not finish within ${seconds(envelope.deadline)}`);
     if (code !== 0)
         throw failed(what, refusedProfile(code) ?? ended(code));
     return { text: output.endsWith("\n") ? output.slice(0, -1) : output };
@@ -249,6 +254,6 @@ function describe(value) {
 function ended(code) {
     return code === null ? "was killed" : `exited ${code}`;
 }
-function failed(what, why, fix = { type: "rerun" }, cause) {
-    return new FailureError(what, why, fix, command(fix, `run(d)`), cause === undefined ? undefined : { cause });
+function failed(what, why, fix = { type: "rerun" }, cause, frames = []) {
+    return new FailureError(what, why, fix, command(fix, `run(d)`), cause === undefined ? undefined : { cause }, frames);
 }

package/dist/types.d.ts

@@ -91,6 +91,13 @@ export type File = {
 export type Fix = {
     type: "vocab_add";
     vocab: VocabName;
+} | {
+    type: "vocab_value";
+    vocab: VocabName;
+    word: Word;
+} | {
+    type: "make_dir";
+    path: string;
 } | {
     type: "vocab_remove";
     vocab: VocabName;
@@ -172,6 +179,8 @@ export interface Manifest {
     confirm: Template;
     /** Absent: inline, a function the SDK holds. */
     run?: Run;
+    /** Where the body runs, when not anywhere; elsewhere the reflex is inactive. Absent when anywhere. Contract, like `run`. */
+    platforms?: Platform[];
     /** What the body may touch; absent, the tightest declaration. Contract, like `run`. */
     needs?: Needs;
     config: Record<ConfigKey, ConfigSpec>;
@@ -650,7 +659,7 @@ export type PickValue = {
     value: Clean;
 };
 /** What a request asks: everything, or the route alone — the conflict test at `add`. */
-export type Scope = "full" | "route";
+export type Scope = "full" | "route" | "fits";
 /** 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. */
@@ -877,8 +886,16 @@ export interface Ref {
     many?: boolean;
     p?: Prob;
 }
-/** How a segment that matched nothing on its own was settled. */
-export type Repair = "narrowed" | "spliced" | "merged";
+/** How a step came to be that is not one part decided on its own: a segment that matched nothing settled narrowed to
+ *  its neighbour's reflex, spliced into its words, or merged back; or a part the engine kept whole split, its parts each
+ *  a reflex of their own. */
+export type Repair = "narrowed" | "spliced" | "merged" | "split";
+/** A word of a vocabulary the request stated for several steps, as it reached one of them: a required argument filled
+ *  as a person's answer would fill it, or an optional one written into the step's words and decided again narrowed. */
+export interface Shared {
+    word: Word;
+    via: Via;
+}
 /** 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. */
@@ -891,6 +908,8 @@ export interface Step {
     effect?: Effect;
     refs?: Ref[];
     repair?: Repair;
+    /** The words the request stated once for several steps that reached this one's arguments, by argument. */
+    shared?: Record<ArgName, Shared>;
     /** The steps this one must follow: an explicit `then`, or a binding. */
     after?: number[];
 }
@@ -1100,6 +1119,12 @@ export type Change = {
 } | {
     type: "needs_narrowed";
     removed: Needs;
+} | {
+    type: "platform_added";
+    platform: Platform;
+} | {
+    type: "platform_removed";
+    platform: Platform;
 } | {
     type: "required";
     arg: ArgName;
@@ -1260,6 +1285,14 @@ export interface Theft {
     phrase: Utterance;
     owner: LocalName;
     thief: LocalName;
+    /** Present when the newcomer did not win the phrase but fits it at or over the floor. */
+    fits?: Prob;
+}
+/** An installed case routed over the new set at `add`: who won, and every reflex offered with its `fits`. */
+export interface Routed {
+    case: Case;
+    winner?: LocalName;
+    ranking?: Contender[];
 }
 /** 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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evoke-build/evoke",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "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

@@ -1,11 +1,11 @@
 // The loader: one envelope line on stdin — { run, args, input, config, deadline } — the body `run` names imported
 // 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 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
+// { text, data? } or { error, refused?, frames? } — `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; `frames` the frames of an error the body threw, without the message and without the frames
+// inside Node itself, for the host to keep. It 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; 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";
@@ -43,8 +43,8 @@ const out = (value) => {
     }
   }
 };
-const fail = (message, refused) => {
-  out(refused === undefined ? { error: message } : { error: message, refused });
+const fail = (message, refused, frames) => {
+  out({ error: message, ...(refused === undefined ? {} : { refused }), ...(frames?.length ? { frames } : {}) });
   process.exit(1);
 };
 
@@ -76,7 +76,7 @@ async function run(line) {
   const { run, args, input, config, deadline } = envelope;
   process.on("SIGTERM", () => stop("terminated", true));
   process.on("uncaughtException", thrown);
-  const timer = setTimeout(() => stop(`timed out after ${deadline} ms`, true), deadline);
+  const timer = setTimeout(() => stop(`timed out after ${seconds(deadline)}`, true), deadline);
   try {
     const module = await import(pathToFileURL(run).href);
     if (module.default === undefined) throw new Error(`${run} has no default export`);
@@ -94,12 +94,11 @@ async function run(line) {
   }
 }
 
-// A body's error, whether its promise rejected with it or a callback threw it: the frames on stderr, then the
-// message and what refused the body, when something did, as the one line.
+// A body's error, whether its promise rejected with it or a callback threw it: the message, what refused the
+// body, when something did, and its frames, as the one line.
 function thrown(error) {
-  const frames = error instanceof Error && error.stack ? where(error.stack) : "";
-  if (frames) process.stderr.write(`${frames}\n`);
-  fail(error instanceof Error ? error.message : String(error), refusal(error));
+  const frames = error instanceof Error && error.stack ? where(error.stack) : [];
+  fail(error instanceof Error ? error.message : String(error), refusal(error), frames);
 }
 
 // What refused the body, when something did. A lookup names the host, whether Node's permission model refused it
@@ -117,12 +116,18 @@ function refusal(error) {
   return { what: text(e.syscall), path: text(e.path) || address };
 }
 
+// The frames of a stack, from the first, each without its indent; none from inside Node.
 function where(stack) {
   const lines = stack.split("\n");
   const first = lines.findIndex((line) => line.startsWith("    at "));
   return (first < 0 ? [] : lines.slice(first))
     .filter((line) => !/[( ]node:/.test(line) && !line.includes("[eval"))
-    .join("\n");
+    .map((line) => line.trim());
+}
+
+// Milliseconds as a person reads them: `30 s`, `1.5 s`, `0.05 s`.
+function seconds(ms) {
+  return `${ms < 1000 ? (ms / 1000).toFixed(2) : Math.round(ms / 100) / 10} s`;
 }
 
 function describe(value) {