@mark1russell7/coeval 0.25.0 → 0.26.0

package/package.json

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

@@ -91,6 +91,7 @@ export {
   restrictMachine,
   restrictWorld,
 } from "./merge.ts";
+export { type Language, type LanguageCode, type LanguageDefinition, compose, defineLanguage } from "./language.ts";
 export {
   type Answer,
   type AskOptions,
@@ -292,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";

package/src/language.ts

@@ -0,0 +1,147 @@
+import { type Key, isRecord } from "./doc.ts";
+import type { Machine } from "./evaluate.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. */
+export type LanguageCode = Omit<MachinePart, "world">;
+
+/** The input of `defineLanguage`. */
+export interface LanguageDefinition {
+  /** The name of the language. A composition holds one language of a name. */
+  readonly name: string;
+  /** The version, as `MAJOR.MINOR.PATCH`. */
+  readonly version: string;
+  /** The world of the language, with the verbs that it owns. It is JSON. */
+  readonly world?: WorldPart;
+  /** The lowest compatible version of each language that this language needs, by name (LANG.REQUIRES). */
+  readonly requires?: Readonly<Record<string, string>>;
+  /** The evaluators, the hooks and the other code. A function reads the merge of the languages before it. */
+  readonly code?: LanguageCode | ((prev: Machine) => LanguageCode);
+}
+
+/** One language as one frozen value, for `compose`. */
+export interface Language {
+  readonly name: string;
+  readonly version: string;
+  readonly world: WorldPart;
+  readonly requires: Readonly<Record<string, string>>;
+  readonly code?: LanguageCode | ((prev: Machine) => LanguageCode);
+  /**
+   * The canonical JSON of the data half: `requires` and `world`, with the keys in order. Two equal data halves give
+   * one text, in each order of their keys (LANG.IDENTITY). The name, the version and this text identify a language.
+   */
+  readonly data: string;
+}
+
+const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+function numbers(version: string): readonly [number, number, number] {
+  const found = VERSION.exec(version);
+  if (found === null) throw new TypeError(`A language version has the form MAJOR.MINOR.PATCH. The text ${JSON.stringify(version)} does not.`);
+  return [Number(found[1]), Number(found[2]), Number(found[3])];
+}
+
+/**
+ * This function tells if a version satisfies a lowest version, by the rules of a caret range of SemVer. The first
+ * number that is not zero stays the same, and the version is not lower.
+ */
+function compatible(version: string, lowest: string): boolean {
+  const have = numbers(version);
+  const want = numbers(lowest);
+  const stable = want.findIndex((part) => part !== 0);
+  const fixed = stable < 0 ? 3 : stable + 1;
+  for (let index = 0; index < 3; index += 1) {
+    const [a, b] = [have[index] as number, want[index] as number];
+    if (a !== b) return index >= fixed && a > b;
+  }
+  return true;
+}
+
+/** This function gives the JSON text of a value with its keys in order. A value that is not JSON is an error. */
+function canonical(value: unknown, path: readonly Key[]): string {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "number" && Number.isFinite(value)) return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((item, index) => canonical(item, [...path, index])).join(",")}]`;
+  if (!isRecord(value)) throw new TypeError(`The data half of a language is JSON. The value at ${JSON.stringify(path)} is not.`);
+  const keys = Object.keys(value)
+    .filter((key) => value[key] !== undefined)
+    .sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${canonical(value[key], [...path, key])}`).join(",")}}`;
+}
+
+function frozen<T>(value: T): T {
+  if (typeof value !== "object" || value === null) return value;
+  for (const item of Object.values(value)) frozen(item);
+  return Object.freeze(value);
+}
+
+/**
+ * This function makes one value of a language. The data half is JSON, thus a host can store it and compare it. The
+ * code half binds the evaluator names of the world.
+ *
+ * The language keeps a frozen copy of its data half, thus a later change to the input changes nothing.
+ *
+ * @param definition - The name, the version, the world, the needed languages and the code.
+ * @returns The language.
+ * @throws {TypeError} A version in the definition is not `MAJOR.MINOR.PATCH`, the name is empty, or the
+ *   data half is not JSON.
+ */
+export function defineLanguage(definition: LanguageDefinition): Language {
+  if (definition.name === "") throw new TypeError("A language has a name.");
+  numbers(definition.version);
+  const requires = definition.requires ?? {};
+  for (const name of Object.keys(requires)) numbers(requires[name] as string);
+  const data = canonical({ requires, world: definition.world ?? {} }, []);
+  const copy = frozen(JSON.parse(data) as { readonly requires: Readonly<Record<string, string>>; readonly world: WorldPart });
+  const language = { name: definition.name, version: definition.version, world: copy.world, requires: copy.requires, data };
+  return Object.freeze(definition.code === undefined ? language : { ...language, code: definition.code });
+}
+
+function partOf(language: Language): MachinePart | ((prev: Machine) => MachinePart) {
+  const { code, world } = language;
+  return typeof code === "function" ? (prev) => ({ ...code(prev), world }) : { ...code, world };
+}
+
+/**
+ * This function merges languages into one machine, in the order of the arguments, with `mergeMachines`.
+ *
+ * - A language comes after each language that it names in `requires`, at a compatible version (LANG.REQUIRES).
+ * - One language that comes twice counts once. Thus two languages can share a base.
+ * - Two versions of one name, or two data halves under one name and one version, are conflicts (LANG.COMPOSE).
+ *
+ * @param languages - The languages.
+ * @returns The machine.
+ * @throws {MergeError} The languages do not fit, or their merge has a conflict. The error lists each conflict.
+ */
+export function compose(...languages: readonly Language[]): Machine {
+  const conflicts: MergeConflict[] = [];
+  const parts: (MachinePart | ((prev: Machine) => MachinePart))[] = [];
+  const seen = new Map<string, { readonly language: Language; readonly index: number }>();
+  languages.forEach((language, index) => {
+    const earlier = seen.get(language.name);
+    const conflict = (name: string, other: number, reason: string): void => {
+      conflicts.push({ path: ["languages", name], parts: [Math.min(other, index), Math.max(other, index)], reason });
+    };
+    if (earlier !== undefined) {
+      if (earlier.language.version !== language.version) conflict(language.name, earlier.index, "Two versions of one language.");
+      else if (earlier.language.data !== language.data) conflict(language.name, earlier.index, "Two languages with one name and one version differ.");
+      else if (earlier.language.code !== language.code) parts.push(partOf(language));
+      return;
+    }
+    for (const name of Object.keys(language.requires)) {
+      const needed = language.requires[name] as string;
+      const found = seen.get(name);
+      if (found === undefined) {
+        const later = languages.findIndex((other) => other.name === name);
+        if (later < 0) conflict(name, index, `A language requires ${name}, and the composition does not have it.`);
+        else conflict(name, later, `A language requires ${name}, and ${name} comes after it.`);
+      } else if (!compatible(found.language.version, needed)) {
+        conflict(name, found.index, `A language requires ${name} ${needed}, and the composition has ${found.language.version}.`);
+      }
+    }
+    seen.set(language.name, { language, index });
+    parts.push(partOf(language));
+  });
+  if (conflicts.length > 0) throw new MergeError(conflicts);
+  return mergeMachines(...parts);
+}