@mark1russell7/coeval 0.25.1 → 0.26.0

package/package.json

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

@@ -5,8 +5,9 @@ import { type CheckOptions, typeCheck } from "./static.ts";
 import { isPrecise, member, typeText } from "./types.ts";
 import { boundariesOf } from "./typing.ts";
 import { type Effect, type Machine, type Perform, type Read, type TraceNode, JOURNAL, evaluate, makeContext, prepare, run, sharedCopy } from "./evaluate.ts";
-import { Held, isClosure } from "./formula.ts";
+import { type FormulaProfile, Held, isClosure } from "./formula.ts";
 import { type Definitions, reference, referenceRun } from "./reference.ts";
+import { stepper } from "./stepper.ts";
 import { type ReplaySettle, recorder, relay, replayer } from "./replay.ts";
 
 /**
@@ -21,7 +22,7 @@ import { type ReplaySettle, recorder, relay, replayer } from "./replay.ts";
  *   each such name, and then with the context of `agree`. `agreeRun` does not have this tier.
  * - `other`: the second tier of a language, from the option `other`.
  */
-export type Tier = "reference" | "traced" | "again" | "folds" | "fixed" | "other";
+export type Tier = "reference" | "traced" | "again" | "folds" | "fixed" | "stepper" | "other";
 
 /** What a second tier gives: its result, and its effects when it records them. */
 export interface TierResult {
@@ -51,9 +52,11 @@ export interface AgreeOptions {
   readonly definitions?: Definitions;
   /**
    * The tiers to compare with the plan. The default is the reference, the traced evaluation, a second evaluation, the
-   * plan with the other choice of folds and the plan with fixed names.
+   * plan with the other choice of folds and the plan with fixed names. The tier `stepper` is not a default.
    */
   readonly tiers?: readonly Exclude<Tier, "other">[];
+  /** The profile of the formula kit, for the tier `stepper`. */
+  readonly profile?: FormulaProfile;
   /**
    * This function gives the result of the second tier of a language, for example a compiler to loops.
    *
@@ -290,6 +293,8 @@ export function agree(machine: Machine, doc: unknown, context: Context = makeCon
     let otherEffects: Effect[] = [];
     if (tier === "reference") {
       other = reference(machine, doc, context, { ...declared, ...mock, effects: otherEffects, ...(options.definitions === undefined ? {} : { definitions: options.definitions }) });
+    } else if (tier === "stepper") {
+      other = stepper(machine, doc, context, { ...declared, ...mock, effects: otherEffects, ...(options.profile === undefined ? {} : { profile: options.profile }), ...(options.definitions === undefined ? {} : { definitions: options.definitions }) });
     } else if (tier === "traced") {
       const traced = evaluate(machine, doc, context, { ...declared, ...mock });
       other = traced.result;
@@ -509,8 +514,8 @@ export async function agreeRun(machine: Machine, doc: unknown, context: Context
   const replay = replayer(log);
 
   for (const tier of options.tiers ?? DEFAULT_TIERS) {
-    // A run has no tier with fixed names (PLAN.FIXED).
-    if (tier === "fixed") continue;
+    // A run has no tier with fixed names (PLAN.FIXED), and the stepper does no runs.
+    if (tier === "fixed" || tier === "stepper") continue;
     const tierReplay = watched(replay);
     const host = { perform: tierReplay.perform };
     let other: Result;

package/src/facts.ts

@@ -185,7 +185,8 @@ export function codeFactsOf(machine: Machine, v: DocVisit, kind: Kind, verb: str
  *
  * - `reads`: each free reference, with the root and the keys of its path. A read under a lazy part has the mark
  *   `lazy`, for example a read in a branch of `if`. A read after a step document has `exact: false`. A kind that
- *   declares `reads` adds a read of each of its roots at each document of the kind. The first document of a tree
+ *   declares `reads` adds a read of each of its roots at each document of the kind. A reference with a step document
+ *   of the kind also has these reads (FACTS.STEP-READS). The first document of a tree
  *   kind also gets the lazy reads of the equations of its kind (FACTS.EQUATIONS). A read from `self` or from a name
  *   of a rung is not one of them, because it is not free (READS.EQUATION).
  * - `side` and `effects`: from the contract of each kind, for the verb of the facts.
@@ -232,6 +233,18 @@ export function factsOf(machine: Machine, doc: unknown, options: FactsOptions =
     reads.push(read);
     if (options.volatile?.(read) === true) volatile = true;
   };
+  /**
+   * This function adds a read of each declared root at the place of a document (FACTS.KIND-READS, FACTS.STEP-READS).
+   * It is one function for the facts, thus a visit makes no new function.
+   */
+  const declare = (list: readonly Root[] | undefined, node: DocVisit | undefined, lazy: boolean, place: DocVisit): void => {
+    if (list === undefined) return;
+    for (const root of list) {
+      // In an equation, the root self is the node, thus its read is not free (READS.EQUATION).
+      if (node !== undefined && root === "self") continue;
+      add({ root, keys: NONE, exact: true, lazy, address: false, path: [root], place: tight(place.place), at: tight(place.at) });
+    }
+  };
   /**
    * This function walks a document. Without `node`, it walks the document of the facts. With `node`, it walks an
    * equation of a tree kind, and each read gets the place of that node: the first document of the kind.
@@ -265,11 +278,7 @@ export function factsOf(machine: Machine, doc: unknown, options: FactsOptions =
           roots = answer?.reads;
         }
         // The code of the kind resolves each of these roots as a whole, at the place of its document (FACTS.KIND-READS).
-        for (const root of roots ?? NONE) {
-          // In an equation, the root self is the node, thus its read is not free (READS.EQUATION).
-          if (node !== undefined && root === "self") continue;
-          add({ root, keys: NONE, exact: true, lazy, address: false, path: [root], place: tight(place.place), at: tight(place.at) });
-        }
+        declare(roots, node, lazy, place);
         // check and effectsOf read the declared effects with the same function (D27). The verb of the facts selects the
         // declaration: effects for eval, and the entry of verbEffects for another verb (D49, D111).
         // The answer of the hook for the code of eval wins over the contract, also for an own entry (D118).
@@ -322,6 +331,8 @@ export function factsOf(machine: Machine, doc: unknown, options: FactsOptions =
           const stepAnswer = walker.name === undefined ? undefined : hook?.(found.path, walker.name);
           if (walker.described) note(stepAnswer?.pure ?? found.kind.pure, stepAnswer?.volatile ?? found.kind.volatile);
           else note(stepAnswer?.pure, stepAnswer?.volatile);
+          // A walker can resolve a root of its own. The read has the place of the reference (FACTS.STEP-READS).
+          declare(stepAnswer?.reads ?? (walker.described ? found.kind.reads : undefined), node, lazy, place);
         }
         const first = path[1];
         // A reference to a name that a kind around it binds reads inside the document: it is not a read. The names of

package/src/formula.ts

@@ -1,7 +1,7 @@
 import { type Json, type Key, docEquals, isKey, isRecord, typeName } from "./doc.ts";
 import { partsOf as docParts } from "./parts.ts";
 import type { Kind, KindFacts, LazyRule, WorldEntry } from "./world.ts";
-import { type CompiledPath, type Context, type Resolution, compilePath, valueOfThing, walkerOf } from "./deref.ts";
+import { type CompiledPath, type Context, type Resolution, type Root, compilePath, valueOfThing, walkerOf } 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, totalCode } from "./evaluate.ts";
 import { type MachinePart, mergeMachines } from "./merge.ts";
@@ -51,6 +51,9 @@ export type ExtFn = (data: Json, context: Context, domains?: Readonly<Record<str
  *   names no operation.
  * - `pureExt`: the pure extensions of `ext`, by their name, for `factsOf` and the folds of a plan (PLAN.FOLD, D47).
  *   The default names no extension. A standard extension is pure without a name here.
+ * - `extReads`: the roots that an extension of `ext` reads from its context, by its name, for `factsOf`
+ *   (FACTS.EXT-READS). A read of a root through the context refuses a fold, thus such a pure extension runs at each
+ *   evaluation.
  * - `volatile`: the operations whose results can change while their arguments stay the same, for example a clock.
  * - `sigs`: the signatures of the operations, by their name, for a check of types (TYPE.SIGNATURE). A list gives
  *   overloads. An operation without a signature takes and gives `unknown` (TYPE.GRADUAL).
@@ -74,6 +77,7 @@ export interface FormulaProfile {
   readonly combine?: (errors: readonly EvalError[]) => EvalError;
   readonly pure?: true | readonly string[];
   readonly pureExt?: readonly string[];
+  readonly extReads?: Readonly<Record<string, readonly Root[]>>;
   readonly volatile?: readonly string[];
   readonly sigs?: Readonly<Record<string, Signature | readonly Signature[]>> | ((name: string) => Signature | readonly Signature[] | undefined);
 }
@@ -776,6 +780,7 @@ const PROFILE_KEYS = /* @__PURE__ */ Object.freeze([
   "combine",
   "pure",
   "pureExt",
+  "extReads",
   "volatile",
   "sigs",
 ] as const satisfies readonly (keyof FormulaProfile)[]);
@@ -1285,7 +1290,11 @@ function makeFacts(profile: FormulaProfile, known: (path: readonly Key[], evalua
     if (code !== "formula.op" && code !== "formula.ext") return undefined;
     const name = path.slice(1).join(".");
     if (code === "formula.ext") {
-      if (profile.ext !== undefined && Object.hasOwn(profile.ext, name)) return pureExt.has(name) ? PURE : NOT_PURE;
+      if (profile.ext !== undefined && Object.hasOwn(profile.ext, name)) {
+        const facts = pureExt.has(name) ? PURE : NOT_PURE;
+        const reads = profile.extReads !== undefined && Object.hasOwn(profile.extReads, name) ? profile.extReads[name] : undefined;
+        return reads === undefined ? facts : { ...facts, reads };
+      }
       return Object.hasOwn(STD_EXT, name) ? PURE : undefined;
     }
     // An operation that the language does not have gives #NAME?. The kit gives it no facts.

package/src/index.ts

@@ -293,6 +293,7 @@ export {
   print,
   syntaxFormat,
 } from "./syntax.ts";
+export { type Configuration, type Frame, type StepperOptions, stepper, stepperNext, stepperStart } from "./stepper.ts";
 export { type Definitions, type ReferenceOptions, type ReferenceRunOptions, STD_DEFINITIONS, formulaDefinitions, reference, referenceRun } from "./reference.ts";
 export { type AgreeOptions, type AgreeRunOptions, type Agreement, type AgreeTypesOptions, type TypeAgreement, agreeTypes, type Tier, type TierInput, type TierResult, agree, agreeRun, sameValue } from "./agree.ts";
 export { type ConformOptions, type ConformProbe, type Finding, type Obligation, conforms } from "./conform.ts";