@mark1russell7/coeval 0.7.0 → 0.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.7.0",
+  "version": "0.8.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",
@@ -34,7 +34,7 @@
     "json"
   ],
   "devDependencies": {
-    "@mark1russell7/cue": "github:mark1russell7/cue",
+    "@mark1russell7/cue": "^1.0.2",
     "@types/node": "^26.6.4",
     "esbuild": "^0.28.2",
     "typescript": "^7.0.2",

package/src/agree.ts

@@ -11,9 +11,11 @@ import { type Definitions, reference } from "./reference.ts";
  * - `reference`: the reference interpreter, which compiles nothing.
  * - `traced`: the traced evaluation, `evaluate`.
  * - `again`: a second evaluation of the same plan.
+ * - `folds`: a second plan with the other choice of folds (PLAN.FOLD). It has no folds when the plan has them, and
+ *   it has folds when the option `observe` stops the folds of the plan.
  * - `other`: the second tier of a language, from the option `other`.
  */
-export type Tier = "reference" | "traced" | "again" | "other";
+export type Tier = "reference" | "traced" | "again" | "folds" | "other";
 
 /** What a second tier gives: its result, and its effects when it records them. */
 export interface TierResult {
@@ -41,7 +43,10 @@ export interface AgreeOptions {
   readonly verb?: string;
   /** The definitional code of the compiled evaluators of the machine, for the reference. */
   readonly definitions?: Definitions;
-  /** The tiers to compare with the plan. The default is the reference, the traced evaluation and a second evaluation. */
+  /**
+   * The tiers to compare with the plan. The default is the reference, the traced evaluation, a second evaluation and
+   * the plan with the other choice of folds.
+   */
   readonly tiers?: readonly Exclude<Tier, "other">[];
   /**
    * This function gives the result of the second tier of a language, for example a compiler to loops.
@@ -70,13 +75,17 @@ export interface AgreeOptions {
   /**
    * This function gives what the host saw since its last call, for example the calls of an operation. `agree` uses
    * it before the plan and after each tier, and compares the results. Thus a tier that evaluates a part that the plan
-   * does not evaluate fails.
+   * does not evaluate fails. A fold moves the calls of a part to the compilation, thus with this option the plan has
+   * no folds. The tier `folds` then has folds, and `agree` does not compare its calls.
    *
    * @returns What the host saw.
    */
   readonly observe?: () => unknown;
 }
 
+/** The tiers that `agree` compares when its options name none. */
+const DEFAULT_TIERS: readonly Exclude<Tier, "other">[] = /* @__PURE__ */ Object.freeze(["reference", "traced", "again", "folds"]);
+
 /** The outcome of `agree`: the result of the plan, or the first tier that disagrees with it. */
 export type Agreement =
   | { readonly ok: true; readonly result: Result; readonly effects: readonly Effect[] }
@@ -195,7 +204,9 @@ export function agree(machine: Machine, doc: unknown, context: Context = makeCon
   const tierInput: TierInput = { ...mock, ...(options.verb === undefined ? {} : { verb: options.verb }) };
   const observe = options.observe;
   observe?.();
-  const plan = prepare(machine, doc, declared);
+  // A fold moves host calls to the compilation, thus a plan whose calls the host compares has no folds (PLAN.FOLD).
+  const folds = observe === undefined;
+  const plan = prepare(machine, doc, { ...declared, fold: folds });
   const effects: Effect[] = [];
   const result = plan.evaluate(context, { effects, ...mock });
   const saw = observe?.();
@@ -207,7 +218,7 @@ export function agree(machine: Machine, doc: unknown, context: Context = makeCon
     return sameValue(saw, observe(), options.equal) ? undefined : "The host saw other calls in the tier.";
   };
 
-  for (const tier of options.tiers ?? ["reference", "traced", "again"]) {
+  for (const tier of options.tiers ?? DEFAULT_TIERS) {
     let other: Result;
     let otherEffects: Effect[] = [];
     if (tier === "reference") {
@@ -216,6 +227,16 @@ export function agree(machine: Machine, doc: unknown, context: Context = makeCon
       const traced = evaluate(machine, doc, context, { ...declared, ...mock });
       other = traced.result;
       otherEffects = [...traced.effects];
+    } else if (tier === "folds") {
+      other = prepare(machine, doc, { ...declared, fold: !folds }).evaluate(context, { effects: otherEffects, ...mock });
+      if (observe !== undefined) {
+        // The folds of this tier call the host when it compiles. Thus only the result and the effects compare.
+        observe();
+        if (overflowed(result) || overflowed(other)) continue;
+        const why = resultDiffers(result, other, options) ?? effectsDiffer(effects, otherEffects, options);
+        if (why !== undefined) return { ok: false, tier, plan: result, other, reason: why };
+        continue;
+      }
     } else {
       other = plan.evaluate(context, { effects: otherEffects, ...mock });
     }

package/src/codec.ts

@@ -0,0 +1,185 @@
+import { type Json, isEnvelope, isRecord } from "./doc.ts";
+import { type Result, describe, fail, ok } from "./errors.ts";
+import { type Machine, makeContext, prepare } from "./evaluate.ts";
+import { type Domain, type DomainCodec, domainOf, member } from "./types.ts";
+
+/*
+ * The codec of the values that JSON cannot write (K140, D40). A document holds such a value as a standard extension:
+ * `ext.number` for `NaN`, an infinity and `-0`, `ext.undefined` for `undefined`, and `ext.domain` for a member of a
+ * domain with a codec. Thus the same value has the same document in each language (D12).
+ */
+
+/** The domains of a machine, by their names. */
+type Domains = Readonly<Record<string, Domain>> | undefined;
+
+/** This function gives the codec of a domain, or `undefined` when the domain has no codec. */
+function codecOf(domain: Domain): DomainCodec | undefined {
+  const codec: unknown = domain.codec;
+  if (typeof codec !== "object" || codec === null) return undefined;
+  const { encode, decode } = codec as Partial<DomainCodec>;
+  return typeof encode === "function" && typeof decode === "function" ? (codec as DomainCodec) : undefined;
+}
+
+/**
+ * This function reads the value of an extension `ext.domain` (EXT.DOMAIN). The value is a record with only the text
+ * `domain` and the JSON `data`. The codec of the named domain reads the data, and the result must be a member of the
+ * domain.
+ *
+ * @param data - The value of the extension document.
+ * @param domains - The domains of the machine.
+ * @returns The member, `#NAME?` for a domain without a codec, or `#VALUE!` for data that the codec cannot read.
+ */
+export function decodeDomain(data: Json, domains: Domains): Result {
+  if (!isRecord(data) || typeof data["domain"] !== "string" || !Object.hasOwn(data, "data") || Object.keys(data).length !== 2) {
+    return fail("#VALUE!", "The value of ext.domain is a record with only the text domain and the data.");
+  }
+  const name = data["domain"];
+  const domain = domainOf(name, domains);
+  if (domain === undefined) return fail("#NAME?", `The machine has no domain ${name}.`);
+  const codec = codecOf(domain);
+  if (codec === undefined) return fail("#NAME?", `The domain ${name} has no codec.`);
+  let value: unknown;
+  try {
+    value = codec.decode(data["data"] as Json);
+  } catch (error) {
+    return fail("#VALUE!", `The codec of the domain ${name} cannot read the data: ${describe(error)}`, { cause: error });
+  }
+  if (!member(value, name, domains)) return fail("#VALUE!", `The codec of the domain ${name} gives a value that is not a member of the domain.`);
+  return ok(value);
+}
+
+/**
+ * This function gives the static type of an extension `ext.domain`: the name of its domain when that domain has a
+ * codec. A run then gives a member of the domain or an error, because `decodeDomain` tests the membership.
+ *
+ * @param data - The value of the extension document.
+ * @param domains - The domains of the machine.
+ * @returns The name of the domain, or `unknown`.
+ */
+export function domainTypeOf(data: unknown, domains: Domains): string {
+  if (!isRecord(data) || typeof data["domain"] !== "string") return "unknown";
+  const domain = domainOf(data["domain"], domains);
+  return domain !== undefined && codecOf(domain) !== undefined ? data["domain"] : "unknown";
+}
+
+/** This function sets an own data property. Only the key `__proto__` needs `defineProperty`. */
+function setOwn(target: Record<string, Json>, key: string, value: Json): void {
+  if (key === "__proto__") Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+  else target[key] = value;
+}
+
+/** The state of one call of `encodeValue`. */
+interface Encoder {
+  readonly domains: Domains;
+  /** The domains with a codec, in the order of their names. */
+  readonly codecs: readonly (readonly [string, DomainCodec])[];
+  /** The answer of `isJson` for each container that it examined. */
+  readonly json: WeakMap<object, boolean>;
+  /** The containers on the way from the root to the value. A container on the way again is a cycle. */
+  readonly open: Set<object>;
+}
+
+/**
+ * This function tells if JSON writes a value exactly. Such a value is a finite number other than `-0`, a text, a truth
+ * value, `null`, or a container of such values.
+ */
+function isJson(value: unknown, encoder: Encoder): boolean {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value) && !Object.is(value, -0);
+  const list = Array.isArray(value);
+  if (!list && !isRecord(value)) return false;
+  const container = value as object;
+  const known = encoder.json.get(container);
+  if (known !== undefined) return known;
+  // A cycle is not JSON. The mark stays false until each item is JSON.
+  encoder.json.set(container, false);
+  let all = true;
+  if (list) {
+    const items = value as readonly unknown[];
+    for (let index = 0; index < items.length && all; index += 1) all = isJson(items[index], encoder);
+  } else {
+    const record = value as Readonly<Record<string, unknown>>;
+    for (const key of Object.keys(record)) {
+      if (!isJson(record[key], encoder)) {
+        all = false;
+        break;
+      }
+    }
+  }
+  encoder.json.set(container, all);
+  return all;
+}
+
+/** This function gives the text of a number that JSON cannot write, for `ext.number`. */
+function numberText(value: number): string {
+  if (Number.isNaN(value)) return "NaN";
+  if (value === Number.POSITIVE_INFINITY) return "Infinity";
+  if (value === Number.NEGATIVE_INFINITY) return "-Infinity";
+  return "-0";
+}
+
+/** This function gives the term document of a value in one call of `encodeValue`. */
+function encodeTerm(value: unknown, encoder: Encoder): Json {
+  if (isJson(value, encoder)) return isEnvelope(value) ? { type: "lit", value: value as Json } : (value as Json);
+  if (value === undefined) return { type: ["ext", "undefined"], value: null };
+  if (typeof value === "number") return { type: ["ext", "number"], value: numberText(value) };
+  for (const [name, codec] of encoder.codecs) {
+    if (member(value, name, encoder.domains)) return { type: ["ext", "domain"], value: { domain: name, data: codec.encode(value) } };
+  }
+  if (!Array.isArray(value) && !isRecord(value)) {
+    throw new TypeError(`encodeValue cannot write the value ${describe(value)}: no domain of the machine with a codec holds it.`);
+  }
+  if (encoder.open.has(value)) throw new TypeError("encodeValue cannot write a value with a cycle.");
+  encoder.open.add(value);
+  let out: Json;
+  if (Array.isArray(value)) {
+    // `Array.from` visits each hole of a sparse list as `undefined`.
+    out = { type: "list", value: Array.from(value as readonly unknown[], (item) => encodeTerm(item, encoder)) };
+  } else {
+    const fields: Record<string, Json> = {};
+    const record = value as Readonly<Record<string, unknown>>;
+    for (const key of Object.keys(record)) setOwn(fields, key, encodeTerm(record[key], encoder));
+    out = { type: "record", value: fields };
+  }
+  encoder.open.delete(value);
+  return out;
+}
+
+/**
+ * This function writes a host value as a term document of the formula kit (EXT.ENCODE, D40). Thus the same value has
+ * the same document in each language (D12).
+ *
+ * - A value that JSON writes exactly stays as it is. A literal with the shape of an envelope goes into `lit`.
+ * - `NaN`, an infinity and `-0` become `ext.number`, and `undefined` becomes `ext.undefined`.
+ * - A member of a domain with a codec becomes `ext.domain`. The domains go in the order of their names.
+ * - A list or a plain record with such a value becomes the construct `list` or `record`.
+ *
+ * @param machine - The machine, or only its domains.
+ * @param value - The host value.
+ * @returns The document. `decodeValue` gives the value again (EXT.ROUNDTRIP).
+ * @throws {TypeError} The value has a cycle, or it is not JSON and no domain with a codec holds it.
+ */
+export function encodeValue(machine: Pick<Machine, "domains">, value: unknown): Json {
+  const domains = machine.domains;
+  const codecs: (readonly [string, DomainCodec])[] = [];
+  if (domains !== undefined) {
+    for (const name of Object.keys(domains).sort()) {
+      const domain = domainOf(name, domains);
+      const codec = domain === undefined ? undefined : codecOf(domain);
+      if (codec !== undefined) codecs.push([name, codec]);
+    }
+  }
+  return encodeTerm(value, { domains, codecs, json: new WeakMap(), open: new Set() });
+}
+
+/**
+ * This function reads a document of `encodeValue` again: it evaluates the document as a term, in an empty context.
+ * A bare root value is a literal.
+ *
+ * @param machine - A machine of the formula kit, with the domains of the document.
+ * @param doc - The document.
+ * @returns The value, or the error of the evaluation.
+ */
+export function decodeValue(machine: Machine, doc: unknown): Result {
+  return prepare(machine, doc, { declaredType: "lit" }).evaluate(makeContext());
+}

package/src/conform.ts

@@ -27,12 +27,11 @@ import {
   permits,
   rootContext,
 } from "./evaluate.ts";
-import { type PartSlot, type Split, pathMatches, splitParts } from "./parts.ts";
+import { type PartSlot, type Split, pathMatches, scopesOf, splitParts } from "./parts.ts";
 import { type Definitions, STD_DEFINITIONS } from "./reference.ts";
 import { STD_EVALUATORS } from "./stdlib.ts";
 import { sameValue } from "./agree.ts";
 import { type Random, random } from "./generate.ts";
-import { scopesOf } from "./static.ts";
 import { type Kind, type LazyRule, type Shape, type World, type WorldEntry, isKind, isNamespace, lookupKind } from "./world.ts";
 
 /*
@@ -692,7 +691,7 @@ function finish(shot: Shot, start: () => Result, who: string): Result {
  */
 function instanceOf(env: Env, under: Under, doc: Envelope, split: SplitOk, sample: Sample): Instance {
   const fill = (items: readonly unknown[]): unknown => (split.parts.length === 0 ? doc.value : split.fill(items));
-  const base = { kind: sample.type, typePath: sample.typePath, doc, data: split.data, place: PLACE, fill };
+  const base = { kind: sample.type, typePath: sample.typePath, doc, data: split.data, place: PLACE, machine: env.machine, fill };
   const who = `the ${env.runner ? "runner" : "evaluator"} ${env.name}`;
   if (under.form === "eval" || under.form === "run") {
     if (under.form === "eval") {

package/src/doc.ts

@@ -20,8 +20,8 @@ export type Key = string | number;
 export type TypeRef = string | readonly Key[] | { readonly type: "ref"; readonly value: readonly Json[] };
 
 /**
- * A typed document: an envelope with a header and a value. The header names the type of the value. The value is
- * not changed by the envelope at any time. Thus any JSON value can have a type: a number, a list, a text or a record.
+ * A typed document: an envelope with a header and a value. The header names the type of the value. The envelope
+ * does not change the value at any time. Thus any JSON value can have a type: a number, a list, a text or a record.
  */
 export type Envelope = {
   /** The type: a reference to a kind of the world. */