@mark1russell7/coeval 0.26.1 → 0.27.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.26.1",
+  "version": "0.27.1",
   "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/errors.ts

@@ -16,6 +16,7 @@ export type KernelCode =
   | "#CAP!"
   | "#CALC!"
   | "#DEPTH!"
+  | "#WORK!"
   | "#ABORT"
   | "#REPLAY!"
   | "#TYPE!";

package/src/evaluate.ts

@@ -541,6 +541,25 @@ export function placeText(place: readonly Key[]): string {
 /** An effect while the kernel waits for its outcome. */
 type Recorded = { -readonly [K in keyof Effect]: Effect[K] };
 
+/**
+ * The most work of one evaluation for a machine without its own `maxWork` (WORK.LIMIT, D134). One application of a
+ * closure is one point.
+ */
+export const WORK_LIMIT = 200000;
+
+/** The work of one node that an equation makes (WORK.NODE, D134). A node costs more than an application. */
+export const NODE_WORK = 8;
+
+/**
+ * This function gives the error of the limit of work. Each tier gives this error (WORK.AGREES).
+ *
+ * @param limit - The limit of the machine.
+ * @returns The error.
+ */
+export function workFailure(limit: number): EvalError {
+  return fail("#WORK!", `The work of one evaluation is more than ${limit} points. The field maxWork of the machine sets the limit.`).error;
+}
+
 /**
  * The runtime of one evaluation or run. Compiled code gets it with the context, and asks it to resolve paths and
  * to cause effects.
@@ -549,6 +568,15 @@ export interface Runtime {
   readonly machine: Machine;
   /** `true` in a run: the host does each effect, and a part that waits needs a parent that can wait. */
   readonly running: boolean;
+  /** `true` when a node that this runtime makes costs work: in an equation of a tree (WORK.NODE) and in a fold. */
+  readonly nested?: boolean;
+  /**
+   * This optional function adds work to the count of the evaluation (WORK.LIMIT). A runtime without it counts nothing.
+   *
+   * @param points - The work.
+   * @throws {Failure} The error `#WORK!`, when the count is over the limit of the machine.
+   */
+  spend?(points: number): void;
   /**
    * This function resolves a path from a context.
    *
@@ -819,6 +847,11 @@ export interface CompiledEvaluator {
    * (TYPE.RULE). Only a check reads it. An evaluator without a rule gives `unknown`.
    */
   readonly type?: TypeRule;
+  /**
+   * `true` when a value that the code gives can use its runtime after the end of the evaluation (WORK.KEEPS). The plan
+   * then marks that end. A compiled evaluator without this field gives no such value.
+   */
+  readonly keeps?: boolean;
 }
 
 /** An evaluator: a function of its input, or a compiler. */
@@ -848,6 +881,7 @@ export type Runner = RunFn | CompiledRunner;
  * A machine: a world of kinds, and the code of each evaluator name, of each `deref` and of each walker.
  *
  * - `maxDepth`: the deepest nesting of documents. The default is 1000.
+ * - `maxWork`: the most work of one evaluation (WORK.LIMIT, D134). The default is `WORK_LIMIT`.
  * - `permits`: the rule of the host for an effect. The default is the function `permits` on the capabilities. A run,
  *   `check` and `effectsOf` ask it (CAP.PERMITS). In a check, its context has only the capabilities and the world.
  * - `known`: the names that the evaluators know, for `check`. Without it, `check` does not check such names.
@@ -859,6 +893,7 @@ export interface Machine extends Navigator {
   /** The runners, by evaluator name. A runner wins over an evaluator of the same name. */
   readonly runners?: Readonly<Record<string, Runner>>;
   readonly maxDepth?: number;
+  readonly maxWork?: number;
   readonly permits?: (caps: readonly Cap[], kind: readonly Key[], context: Context) => boolean;
   /**
    * This function tells if an evaluator knows the name in the path of a kind. An example is the operation
@@ -1157,6 +1192,18 @@ function readingOf(list: Read[] | undefined, root: Context): Reading | undefined
 
 /** This class holds the state of one evaluation or run: the machine, the effects, the clock and the trace. */
 class Session implements Runtime {
+  /**
+   * The count of the work, on the runtime of the root of the evaluation (WORK.LIMIT). The first count adds the field,
+   * thus an evaluation without a counted point has no field.
+   */
+  declare work?: number;
+  /** The count of the applications of closures that run at this time. `formula.fn` writes it (FORMULA.CALL-DEPTH). */
+  declare applying?: number;
+  /**
+   * The count of the applications of closures that run at this time, on the root and on each runtime of an equation
+   * (WORK.AFTER). `formula.fn` writes it on the runtime of the root. The first application adds the field.
+   */
+  declare active?: number;
   readonly machine: Machine;
   /**
    * The epoch of the evaluation: the list of capabilities that the host gave the root (CAP.NARROW-KEPT). A context
@@ -1166,7 +1213,12 @@ class Session implements Runtime {
   readonly running: boolean;
   readonly traced: boolean;
   readonly perform: Perform | undefined;
-  readonly signal: StopSignal | undefined;
+  /**
+   * The runtime of the root, on the runtime of an equation of a tree (WORK.EQUATION). The runtime of a root holds
+   * itself after the end of its evaluation (WORK.AFTER, WORK.KEEPS), thus the end mark adds no field to the object.
+   * Each runtime has this field, thus a tree and its equations have one object shape.
+   */
+  top: Session | undefined;
   /**
    * The record of the reads. Without it, a resolution records nothing. A nested evaluation of an equation of a tree
    * shares the record of the evaluation around it (READS.EQUATION).
@@ -1196,7 +1248,7 @@ class Session implements Runtime {
     running: boolean,
     traced: boolean,
     perform: Perform | undefined,
-    signal: StopSignal | undefined,
+    top: Session | undefined,
     effects: Effect[] | undefined,
     reading: Reading | undefined = undefined,
   ) {
@@ -1205,13 +1257,36 @@ class Session implements Runtime {
     this.running = running;
     this.traced = traced;
     this.perform = perform;
-    this.signal = signal;
+    this.top = top;
     this.reading = reading;
     this.list = effects;
     this.holder = traced ? holderNode() : undefined;
     this.current = this.holder;
   }
 
+  /** This getter gives `true` for the runtime of an equation of a tree (WORK.NODE). */
+  get nested(): boolean {
+    const top = this.top;
+    return top !== undefined && top !== this;
+  }
+
+  /**
+   * This function adds work to the count of the evaluation (WORK.LIMIT). One count is on the runtime of the root, thus
+   * each equation of a tree adds to it. After the end of the evaluation, each entry from the host starts a new count
+   * (WORK.AFTER). An entry is a point with no application of a closure that runs, on any runtime of the evaluation.
+   *
+   * @param points - The work.
+   * @throws {Failure} The error `#WORK!`, when the count is over the limit of the machine.
+   */
+  spend(points: number): void {
+    const root = this.top ?? this;
+    const entry = root.top === root && (root.active ?? 0) === 0;
+    const work = (entry ? 0 : (root.work ?? 0)) + points;
+    root.work = work;
+    const limit = this.machine.maxWork ?? WORK_LIMIT;
+    if (work > limit) throw new Failure(workFailure(limit));
+  }
+
   /** The effects of the evaluation, in their order. */
   get effects(): Effect[] {
     return (this.list ??= []);
@@ -1753,6 +1828,8 @@ interface Compiler {
   readonly guards: ReadonlyMap<string, ValueType> | undefined;
   /** The runtime of the folds of this compilation. The first fold makes it. */
   probe?: Probe;
+  /** `true` when a document of this compilation can use its runtime after the end of the evaluation (WORK.KEEPS). */
+  keeps?: boolean;
 }
 
 function failing(c: Compiler, meta: Meta, place: readonly Key[], code: ErrorCode, reason: string): Compiled {
@@ -1890,6 +1967,7 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
   };
   // A compiler that throws fails its own document when that document evaluates, with its place (PLAN.FAIL-LATE).
   if (runner !== undefined) {
+    c.keeps = true;
     let inner: RunCode;
     try {
       inner = isCompiledRunner(runner) ? runner.compileRun(input) : interpretRun(runner, input, split.fill, kind?.caps?.some((rule) => rule.rule === "grant") === true);
@@ -1901,6 +1979,7 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
     return finish(c, meta, runnerCode(run, place, kindText), run);
   }
 
+  if (!isCompiledEvaluator(evaluator as Evaluator) || (evaluator as CompiledEvaluator).keeps === true) c.keeps = true;
   let inner: Code;
   try {
     inner = isCompiledEvaluator(evaluator as Evaluator) ? (evaluator as CompiledEvaluator).compile(input) : interpret(evaluator as EvalFn, input, split.fill);
@@ -1990,6 +2069,8 @@ class Probe implements Runtime {
   readonly running = false;
   /** `true` after the part asked for something that a fold cannot give. */
   refused = false;
+  /** A node in a fold costs work, thus a tree stops the fold before it evaluates an equation (WORK.PREPARE). */
+  readonly nested = true;
   /** The count of the names that the part read. */
   reads = 0;
   /**
@@ -2058,6 +2139,12 @@ class Probe implements Runtime {
   keepsContext(): void {
     this.refused = true;
   }
+
+  /** This function stops the fold at the first point of work, thus `prepare` does no such work (WORK.PREPARE). */
+  spend(): void {
+    this.refused = true;
+    throw new Failure(workFailure(0));
+  }
 }
 
 /**
@@ -2418,8 +2505,8 @@ export interface InputWithRuntime extends EvalInput {
 /**
  * This function evaluates a plan inside the evaluation of another runtime, for example an equation of a tree inside
  * the evaluation of its tree (READS.EQUATION). The plan gets its own runtime, as in `plan.evaluate`. The reads of the
- * plan go in the record of the reads of `outer`. The context at the root of `outer` tells which reads are free
- * (READS.FREE). Without such a record, the function gives `plan.evaluate(context)`.
+ * plan go in the record of the reads of `outer`, and its work goes in the count of `outer` (WORK.EQUATION). The context
+ * at the root of `outer` tells which reads are free (READS.FREE). Without a session, the function gives `plan.evaluate(context)`.
  *
  * @param plan - The plan.
  * @param context - The context of the plan.
@@ -2427,11 +2514,10 @@ export interface InputWithRuntime extends EvalInput {
  * @returns The result.
  */
 export function evaluateWithin(plan: Plan, context: Context, outer: Runtime | undefined): Result {
-  const reading = outer instanceof Session ? outer.reading : undefined;
-  if (reading === undefined || !(plan instanceof CompiledPlan)) return plan.evaluate(context);
+  if (!(outer instanceof Session) || !(plan instanceof CompiledPlan)) return plan.evaluate(context);
   const machine = plan.machine;
   const ctx = rootContext(machine, context);
-  return plan.code(ctx, new Session(machine, ctx.caps, false, plan.traced, undefined, undefined, undefined, reading));
+  return plan.code(ctx, new Session(machine, ctx.caps, false, plan.traced, undefined, outer.top ?? outer, undefined, outer.reading));
 }
 
 function interpret(fn: EvalFn, input: CompileInput, fill: <P>(handles: readonly P[]) => unknown): Code {
@@ -2570,7 +2656,23 @@ export function prepare(machine: Machine, doc: unknown, options: PrepareOptions
     const result = placed(thrown(error, "the compilation"), []);
     root = { code: () => result, run: undefined };
   }
-  return new CompiledPlan(machine, c.traced, root.code, root.run);
+  return new CompiledPlan(machine, c.traced, c.keeps === true ? endingCode(root.code) : root.code, root.run);
+}
+
+/**
+ * This function gives the code of a plan with a document that can use its runtime after the end of the evaluation. The
+ * code marks that end (WORK.KEEPS). Each other plan has no such step, thus the count adds nothing to a read.
+ *
+ * @param code - The code of the root.
+ * @returns The code that marks the end.
+ */
+function endingCode(code: Code): Code {
+  return (ctx, rt) => {
+    const result = code(ctx, rt);
+    const session = rt as Session;
+    session.top ??= session;
+    return result;
+  };
 }
 
 /**
@@ -2619,8 +2721,10 @@ class CompiledPlan implements Plan {
   run(context: Context = makeContext(), runOptions: PlanRunOptions = {}): Promise<Result> {
     const machine = this.machine;
     const ctx = rootContext(machine, context);
-    const s = new Session(machine, ctx.caps, true, this.traced, runOptions.perform, runOptions.signal, undefined, readingOf(runOptions.reads, ctx));
-    return driveWaiting(this.runCode()(ctx, s), runOptions.signal);
+    const s = new Session(machine, ctx.caps, true, this.traced, runOptions.perform, undefined, undefined, readingOf(runOptions.reads, ctx));
+    return driveWaiting(this.runCode()(ctx, s), runOptions.signal).finally(() => {
+      s.top = s;
+    });
   }
 }
 
@@ -2689,8 +2793,7 @@ export function evaluate(machine: Machine, doc: unknown, context: Context = make
   });
   const ctx = rootContext(machine, context);
   const s = new Session(machine, ctx.caps, false, true, given.perform, undefined, undefined, readingOf(given.reads, ctx));
-  const result = (plan as CompiledPlan).code(ctx, s);
-  return record(s, result);
+  return record(s, (plan as CompiledPlan).code(ctx, s));
 }
 
 /**
@@ -2712,8 +2815,9 @@ export async function run(machine: Machine, doc: unknown, context: Context = mak
     ...(options.verb === undefined ? {} : { verb: options.verb }),
   });
   const ctx = rootContext(machine, context);
-  const s = new Session(machine, ctx.caps, true, true, options.perform, options.signal, undefined, readingOf(options.reads, ctx));
+  const s = new Session(machine, ctx.caps, true, true, options.perform, undefined, undefined, readingOf(options.reads, ctx));
   const result = await driveWaiting((plan as CompiledPlan).runCode()(ctx, s), options.signal);
+  s.top = s;
   return record(s, result);
 }
 

package/src/formula.ts

@@ -139,7 +139,7 @@ export function isClosure(value: unknown): value is Closure {
  * The runtime of an evaluation with the clock of `call` (FORMULA.CALL-DEPTH, D125): the count of the applications of
  * closures that run at this time. The first application adds the field, thus an evaluation without one has no field.
  */
-type Clocked = Runtime & { applying?: number };
+type Clocked = Runtime & { applying?: number; active?: number; top?: Clocked | undefined };
 
 /**
  * The standard extensions: the values that JSON cannot write. `ext.domain` reads a member of a domain through the
@@ -175,8 +175,8 @@ function setOwn(target: Record<string, unknown>, key: string, value: unknown): v
   else target[key] = value;
 }
 
-function compiled(compile: (input: CompileInput) => Code): CompiledEvaluator {
-  return { compile };
+function compiled(compile: (input: CompileInput) => Code, keeps?: true): CompiledEvaluator {
+  return keeps === undefined ? { compile } : { compile, keeps };
 }
 
 /** This function evaluates parts in order. It gives the value of each part, or the first error. */
@@ -756,7 +756,7 @@ function makeEvaluators(profile: FormulaProfile): Readonly<Record<string, Evalua
   for (const name of Object.keys(evaluators)) {
     const evaluator = evaluators[name] as CompiledEvaluator;
     const type = Object.hasOwn(types, name) ? types[name] : undefined;
-    const made = Object.freeze(type === undefined ? evaluator : { compile: evaluator.compile, type });
+    const made = Object.freeze(type === undefined ? evaluator : { ...evaluator, type });
     if (truth !== undefined && TRUTH_READERS.includes(name)) truthByCode.set(made, truth);
     if (PROFILE_READERS.includes(name)) readerByCode.set(made, { name, profile });
     out[name] = made;
@@ -1045,7 +1045,13 @@ function formulaCode(profile: FormulaProfile): Readonly<Record<string, CompiledE
           // Each application counts one level on the runtime of its evaluation, and the count goes down after it (FORMULA.CALL-DEPTH).
           const level = (clock.applying ?? 0) + 1;
           if (level > limit) throw new Failure(fail("#DEPTH!", `The applications of functions nest deeper than ${limit} levels.`).error);
+          // WORK.LIMIT: an application is a place where work can multiply, thus each one counts one point (D134).
+          rt.spend?.(1);
+          // WORK.AFTER: the runtime of the root counts the applications of each runtime of the evaluation. An equation of
+          // a tree in the body has its own runtime, and its work does not start a new count.
+          const root = clock.top ?? clock;
           clock.applying = level;
+          root.active = (root.active ?? 0) + 1;
           try {
             const scope: Record<string, unknown> = { ...ctx.names };
             names.forEach((name, index) => setOwn(scope, name, args[index]));
@@ -1054,12 +1060,14 @@ function formulaCode(profile: FormulaProfile): Readonly<Record<string, CompiledE
             return result.value;
           } finally {
             clock.applying = level - 1;
+            root.active = (root.active ?? 1) - 1;
           }
         };
         Object.defineProperty(closure, CLOSURE, { value: { params: names } });
         return ok(closure);
       };
-    }),
+      // A closure uses its runtime after the end of the evaluation (WORK.KEEPS).
+    }, true),
 
     "formula.call": compiled(({ value }) => {
       const record = partsOf(value);

package/src/generate.ts

@@ -198,7 +198,12 @@ export function generate(world: World, options: GenerateOptions): unknown {
   const envelope = (type: readonly Key[], value: Json, header?: string): Json => {
     const out: Record<string, Json> = { type: renderType(type), value };
     if (header !== undefined) out["name"] = header;
-    if (options.own !== undefined && options.own.length > 0 && rng.chance(0.03)) out["own"] = { eval: rng.pick(options.own) };
+    if (options.own !== undefined && options.own.length > 0 && rng.chance(0.03)) {
+      const code = rng.pick(options.own);
+      // The code of a kind binds the names of its scope rules (C7). An own entry of other code does not, thus a kind
+      // with scope rules gets no own entry (GEN.CONTRACTS). The draws stay, thus each other document stays the same.
+      if ((kindOf(type)?.scope ?? []).length === 0) out["own"] = { eval: code };
+    }
     return out;
   };
 

package/src/index.ts

@@ -91,7 +91,7 @@ export {
   restrictMachine,
   restrictWorld,
 } from "./merge.ts";
-export { type Language, type LanguageCode, type LanguageDefinition, compose, defineLanguage } from "./language.ts";
+export { type Language, type LanguageCode, type LanguageDefinition, boundary, compose, defineLanguage } from "./language.ts";
 export {
   type Answer,
   type AskOptions,
@@ -186,6 +186,7 @@ export {
   prepare,
   resolveCompiled,
   run,
+  WORK_LIMIT,
 } from "./evaluate.ts";
 export {
   type AttributeAnswer,

package/src/language.ts

@@ -1,5 +1,6 @@
 import { type Key, isRecord } from "./doc.ts";
-import type { Machine } from "./evaluate.ts";
+import { type InputWithRuntime, type Machine, type Plan, RUNTIME, evaluateWithin, makeContext, planner } from "./evaluate.ts";
+import { fail } from "./errors.ts";
 import { type MachinePart, type MergeConflict, type WorldPart, MergeError, mergeMachines } from "./merge.ts";
 
 /** The code half of a language: each field of a machine part, without the world. */
@@ -145,3 +146,52 @@ export function compose(...languages: readonly Language[]): Machine {
   if (conflicts.length > 0) throw new MergeError(conflicts);
   return mergeMachines(...parts);
 }
+
+/**
+ * This function makes the language of the boundary kind `lang` (K38, D193). A document of the kind holds the name of a
+ * language and a document in that language: `{ type: "lang", value: { language, doc } }`. The machine of the named
+ * language prepares and evaluates the inner document, as a module of another language (COMPOSE.BOUNDARY).
+ *
+ * The boundary is closed. The inner document gets no names, no capabilities and no node as `self`. Only its result
+ * crosses the boundary. Thus an effect in the inner document fails with `#CAP!`, and the inner machine cannot read the
+ * names of the outer document.
+ *
+ * @param machines - The machine of each language, by the name that a document gives.
+ * @returns The language, for `compose`.
+ */
+export function boundary(machines: Readonly<Record<string, Machine>>): Language {
+  const plans = new Map<string, (doc: unknown) => Plan>();
+  const planOf = (name: string): ((doc: unknown) => Plan) | undefined => {
+    let found = plans.get(name);
+    if (found === undefined && Object.hasOwn(machines, name)) {
+      found = planner(machines[name] as Machine);
+      plans.set(name, found);
+    }
+    return found;
+  };
+  return defineLanguage({
+    name: "boundary",
+    version: "1.0.0",
+    world: {
+      kinds: {
+        lang: {
+          verbs: { eval: "boundary.lang" },
+          summary: "A document in another language. The machine of that language evaluates it, with no names and no capabilities.",
+        },
+      },
+    },
+    code: {
+      evaluators: {
+        "boundary.lang": (input) => {
+          const { data, place } = input;
+          if (!isRecord(data) || typeof data["language"] !== "string" || !("doc" in data)) {
+            return fail("#VALUE!", "A document of the kind lang has the value { language, doc }.", { place });
+          }
+          const plans = planOf(data["language"]);
+          if (plans === undefined) return fail("#NAME?", `The boundary knows no language ${JSON.stringify(data["language"])}.`, { place });
+          return evaluateWithin(plans(data["doc"]), makeContext(), (input as InputWithRuntime)[RUNTIME]);
+        },
+      },
+    },
+  });
+}

package/src/merge.ts

@@ -581,7 +581,7 @@ function checkHidden(m: Merger, draft: MachineDraft): void {
  * - A runner hides the evaluator of its name. Thus one part must give both, or the merge gives a conflict.
  * - The hooks `known` compose in the order of the parts. A hook does not answer for a name that a later part replaces.
  *   The hooks `facts` compose the same way, and the first answer that is not `undefined` wins.
- * - Each other field, for example `permits`, `adopt`, `roots`, `plain` or `maxDepth`, is one value. Two different
+ * - Each other field, for example `permits`, `adopt`, `roots`, `plain`, `maxDepth` or `maxWork`, is one value. Two different
  *   values are a conflict. An absent field has no value.
  *
  * A conflict stops the merge, unless the later part names its path in `replaces`. A part can be a function of the