@mark1russell7/coeval 0.10.0 → 0.11.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "coeval: the kernel of declarative languages. Documents in envelopes, a ladder that finds the evaluator, kind contracts, compiled plans, a static kit, a formula kit and a run side with capabilities.",
   "type": "module",
   "main": "./build/index.js",

package/src/evaluate.ts

@@ -785,17 +785,13 @@ export interface StopSignal {
   addEventListener(type: "abort", listener: () => void, options?: { readonly once?: boolean }): void;
 }
 
-/** The options of a run. */
-export interface RunOptions {
+/**
+ * The options of `plan.run`. A plan keeps the verb and the declared type of its `prepare`, thus these options do not
+ * have them (PLAN.RUN-OPTIONS).
+ */
+export interface PlanRunOptions {
   /** The host code that does each effect. Without it, an effect gives its payload, as in an evaluation. */
   readonly perform?: Perform;
-  /** The type of a bare root value. */
-  readonly declaredType?: string;
-  /**
-   * The verb of `run`, for example `format`. The default is `eval` (VERB.PREPARE). A plan keeps the verb of its
-   * `prepare`, thus `plan.run` does not read this option.
-   */
-  readonly verb?: string;
   /** A signal of the host. When it aborts, the run stops with `#ABORT`. */
   readonly signal?: StopSignal;
   /**
@@ -805,6 +801,14 @@ export interface RunOptions {
   readonly reads?: Read[];
 }
 
+/** The options of `run`: the options of `plan.run`, and the type of a bare root value and the verb for `prepare`. */
+export interface RunOptions extends PlanRunOptions {
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /** The verb of `run`, for example `format`. The default is `eval` (VERB.PREPARE). */
+  readonly verb?: string;
+}
+
 /** The options of an evaluation of a plan. */
 export interface EvalOptions {
   /** A list that gets each effect, in its order. */
@@ -1303,7 +1307,7 @@ export interface Plan {
    * @param options - The host code that does the effects, a signal to stop the run and a list that gets the reads.
    * @returns The result, when the run ends.
    */
-  run(context?: Context, options?: RunOptions): Promise<Result>;
+  run(context?: Context, options?: PlanRunOptions): Promise<Result>;
 }
 
 interface Compiler {
@@ -1471,7 +1475,8 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
   } catch (error) {
     return failingWith(c, meta, placed(thrown(error, `the evaluator ${name}`), place));
   }
-  const done = finish(c, meta, placedCode(inner, place, name), undefined);
+  // Code that cannot fail needs no place and no catch, and it does not read the context of its grant (PLAN.TOTAL).
+  const done = finish(c, meta, TOTAL.has(inner) ? inner : placedCode(inner, place, name), undefined);
   if (frees === undefined || kind === undefined || !pureCode(c, envelope, kind, typePath, name, quick)) return done;
   const free = freeOf(doc, kind, split.parts, frees);
   if (free === undefined) return done;
@@ -1721,6 +1726,24 @@ function copyPlain(value: unknown, memo: Map<object, unknown>): unknown {
  * the split of the value. Thus a plan with these helpers keeps only its code.
  */
 
+/**
+ * The compiled code that cannot fail (PLAN.TOTAL). Such code gives a value and throws nothing. It does not read its
+ * context or its runtime. Only the kits of the kernel mark code, thus the code of a host always gets its grant.
+ */
+const TOTAL: WeakSet<Code> = /* @__PURE__ */ new WeakSet();
+
+/**
+ * This function marks compiled code that cannot fail (PLAN.TOTAL). Then `compileNode` does not wrap the code in
+ * `placedCode`, thus a literal costs one call. The kits of the kernel use it. The package does not export it.
+ *
+ * @param code - The code. It gives a value and throws nothing. It does not read its context or its runtime.
+ * @returns The same code.
+ */
+export function totalCode(code: Code): Code {
+  TOTAL.add(code);
+  return code;
+}
+
 /**
  * This function gives the code of a document: the code of its evaluator, with the place of each error and of each
  * exception. The code gets the context that its grant permits, thus a compiled parent cannot widen it (CAP.NARROW-CODE).
@@ -1952,7 +1975,7 @@ class CompiledPlan implements Plan {
     return this.code(ctx, s);
   }
 
-  run(context: Context = makeContext(), runOptions: RunOptions = {}): Promise<Result> {
+  run(context: Context = makeContext(), runOptions: PlanRunOptions = {}): Promise<Result> {
     const machine = this.machine;
     const ctx = rootContext(machine, context);
     const s = new Session(machine, true, this.traced, runOptions.perform, runOptions.signal, undefined, readingOf(runOptions.reads, ctx));

package/src/formula.ts

@@ -2,7 +2,7 @@ import { type Json, type Key, docEquals, isKey, isRecord } from "./doc.ts";
 import type { Kind, KindFacts, LazyRule, WorldEntry } from "./world.ts";
 import { type CompiledPath, type Context, type Resolution, compilePath, valueOfThing } from "./deref.ts";
 import { type EvalError, type Failed, type Result, Failure, fail, ok, thrown } from "./errors.ts";
-import { type Code, type CompileInput, type CompiledEvaluator, type CompiledPart, type Evaluator, type Machine, type Runtime, resolveCompiled } from "./evaluate.ts";
+import { type Code, type CompileInput, type CompiledEvaluator, type CompiledPart, type Evaluator, type Machine, type Runtime, resolveCompiled, totalCode } from "./evaluate.ts";
 import { type MachinePart, mergeMachines } from "./merge.ts";
 import { type Domain, type ValueType, HEADER_KEYS, STD_DOMAINS, callable, fieldOf, fits, fnOf, holdsEnvelope, isPrecise, isUnknown, itemOf, join, member, stepType, typeText } from "./types.ts";
 import type { TypeInput, TypeRule } from "./typing.ts";
@@ -697,8 +697,9 @@ function formulaCode(profile: FormulaProfile): Readonly<Record<string, CompiledE
 
   return {
     "formula.lit": compiled(({ doc }) => {
+      // A literal cannot fail, thus its code needs no place (PLAN.TOTAL).
       const result = ok(doc.value);
-      return () => result;
+      return totalCode(() => result);
     }),
 
     "formula.ref": compiled(({ doc, parts, fill, address, machine }) => {
@@ -718,7 +719,7 @@ function formulaCode(profile: FormulaProfile): Readonly<Record<string, CompiledE
       // A step document without parts is its own value. A step document with parts gets the result of each part.
       if (parts.length === 0) {
         const same = ok(doc);
-        return () => same;
+        return totalCode(() => same);
       }
       return (ctx, rt) => {
         const values = valuesOf(parts, ctx, rt);

package/src/generate.ts

@@ -146,9 +146,11 @@ export function generate(world: World, options: GenerateOptions): unknown {
   const keys = options.keys ?? KEYS;
   const steps = options.steps ?? 2;
   const roots: readonly Root[] = options.roots ?? ROOTS;
+  // A kind with the verb step walks a step document. With a default of step, each other kind walks one too (GEN.STEPS).
+  const defaultStep = Object.hasOwn(world.defaults, "step");
   const stepTypes = types.filter((type) => {
     const found = lookupKind(world, type);
-    return found.ok && Object.hasOwn(found.kind.verbs, "step");
+    return found.ok && (defaultStep || Object.hasOwn(found.kind.verbs, "step"));
   });
   // A name under each namespace with a fallback that no evaluator knows, for example ["ops", "nope"].
   const unknownNames: readonly (readonly Key[])[] = Object.keys(world.kinds)
@@ -205,7 +207,10 @@ export function generate(world: World, options: GenerateOptions): unknown {
     return out;
   };
 
-  /** A path from a root (D10). It uses the names in scope, and sometimes a step document. */
+  /**
+   * A path from a root (D10). It uses the names in scope, and sometimes a step document. The kind of a step document
+   * has the verb `step`, or the default of the world for `step` serves it.
+   */
   const pathFor = (pos: Position, refKind: Kind | undefined): Json => {
     if (rng.chance(malformed)) return rng.pick<Json>(["names", [], { names: "a" }, ["nowhere", "a"]]);
     const others = roots.filter((name) => name !== "names");

package/src/index.ts

@@ -134,6 +134,7 @@ export {
   type Part,
   type Perform,
   type Plan,
+  type PlanRunOptions,
   type PrepareOptions,
   type Read,
   type Run,