@dallaylaen/ski-interpreter 2.2.0 → 2.3.0

package/lib/ski-interpreter.cjs.js

@@ -59,24 +59,34 @@ var require_internal = __commonJS({
       }
       return out;
     }
-    var ActionWrapper = class {
+    var TraverseControl = class {
       /**
+       * @desc A wrapper for values returned by fold/traverse callbacks
+       *       which instructs the traversal to alter its behavior while
+       *       retaining the value in question.
+       *
+       *       This class is instantiated internally be `SKI.control.*` functions,
+       *       and is not intended to be used directly by client code.
+       *
        * @template T
        * @param {T} value
-       * @param {string} action
+       * @param {function(T): TraverseControl<T>} decoration
        */
-      constructor(value, action) {
+      constructor(value, decoration) {
         this.value = value;
-        this.action = action;
+        this.decoration = decoration;
       }
     };
     function unwrap(value) {
-      if (value instanceof ActionWrapper)
-        return [value.value ?? void 0, value.action];
+      if (value instanceof TraverseControl)
+        return [value.value ?? void 0, value.decoration];
       return [value ?? void 0, void 0];
     }
-    function prepareWrapper(action) {
-      return (value) => new ActionWrapper(value, action);
+    function prepareWrapper(label) {
+      const fun = (value) => new TraverseControl(value, fun);
+      fun.label = label;
+      fun.toString = () => "TraverseControl::" + label;
+      return fun;
     }
     module2.exports = { Tokenizer, restrict, unwrap, prepareWrapper };
   }
@@ -91,11 +101,19 @@ var require_expr = __commonJS({
       max: 1e3,
       maxArgs: 32
     };
+    var ORDER = {
+      "leftmost-outermost": "LO",
+      "leftmost-innermost": "LI",
+      LO: "LO",
+      LI: "LI"
+    };
     var control = {
       descend: prepareWrapper("descend"),
       prune: prepareWrapper("prune"),
+      redo: prepareWrapper("redo"),
       stop: prepareWrapper("stop")
     };
+    var native = {};
     var Expr = class _Expr {
       /**
        *  @descr A combinatory logic expression.
@@ -109,11 +127,44 @@ var require_expr = __commonJS({
        *    env?: { [key: string]: Expr },
        *    src?: string,
        *    parser: object,
-       *  }} [context] // TODO proper type
+       *  }} [context]
+       * @property {number} [arity] - number of arguments the term is waiting for (if known)
+       * @property {string} [note] - a brief description what the term does
+       * @property {string} [fancyName] - how to display in html mode, e.g. &phi; instead of 'f'
+       *                Typically only applicable to descendants of Named.
+       * @property {TermInfo} [props] - properties inferred from the term's behavior
        */
-      constructor() {
-        if (new.target === _Expr)
-          throw new Error("Attempt to instantiate abstract class Expr");
+      /**
+       *
+       * @desc Define properties of the term based on user supplied options and/or inference results.
+       *       Typically useful for declaring Native and Alias terms.
+       * @private
+       * @param {Object} options
+       * @param {string} [options.note] - a brief description what the term does
+       * @param {number} [options.arity] - number of arguments the term is waiting for (if known)
+       * @param {string} [options.fancy] - how to display in html mode, e.g. &phi; instead of 'f'
+       * @param {boolean} [options.canonize] - whether to try to infer the properties
+       * @param {number} [options.max] - maximum number of steps for inference, if canonize is true
+       * @param {number} [options.maxArgs] - maximum number of arguments for inference, if canonize is true
+       * @return {this}
+       */
+      _setup(options = {}) {
+        if (options.fancy !== void 0)
+          this.fancyName = options.fancyName;
+        if (options.note !== void 0)
+          this.note = options.note;
+        if (options.arity !== void 0)
+          this.arity = options.arity;
+        if (options.canonize) {
+          const guess = this.infer(options);
+          if (guess.normal) {
+            this.arity = this.arity ?? guess.arity;
+            this.note = this.note ?? guess.expr.format({ html: true, lambda: ["", " &mapsto; ", ""] });
+            delete guess.steps;
+            this.props = guess;
+          }
+        }
+        return this;
       }
       /**
        * @desc apply self to zero or more terms and return the resulting term,
@@ -137,22 +188,77 @@ var require_expr = __commonJS({
             return e.impl.expand();
         }) ?? this;
       }
+      /**
+       * @desc Returns true if the expression contains only free variables and applications, false otherwise.
+       * @returns {boolean}
+       */
       freeOnly() {
         return !this.any((e) => !(e instanceof FreeVar || e instanceof App));
       }
       /**
        * @desc Traverse the expression tree, applying change() to each node.
        *       If change() returns an Expr, the node is replaced with that value.
-       *       Otherwise, the node is left descended further (if applicable)
-       *       or left unchanged.
+       *       A null/undefined value is interpreted as
+       *       "descend further if applicable, or leave the node unchanged".
+       *
+       *       Returned values may be decorated:
+       *
+       *       SKI.control.prune will suppress further descending even if nothing was returned
+       *       SKI.control.stop will terminate further changes.
+       *       SKI.control.redo will apply the callback to the returned subtree, recursively.
+       *
+       *       Note that if redo was applied at least once to a subtree, a null return from the same subtree
+       *       will be replaced by the last non-null value returned.
+       *
+       *       The traversal order is leftmost-outermost, unless options.order = 'leftmost-innermost' is specified.
+       *       Short aliases 'LO' and 'LI' (case-sensitive) are also accepted.
        *
        *       Returns null if no changes were made, or the new expression otherwise.
        *
-       * @param {(e:Expr) => (Expr|null)} change
+       * @param {{
+       *   order?: 'LO' | 'LI' | 'leftmost-outermost' | 'leftmost-innermost',
+       * }} [options]
+       * @param {(e:Expr) => TraverseValue<Expr>} change
        * @returns {Expr|null}
        */
-      traverse(change) {
-        return change(this);
+      traverse(options, change) {
+        if (typeof options === "function") {
+          change = options;
+          options = {};
+        }
+        const order = ORDER[options.order ?? "LO"];
+        if (order === void 0)
+          throw new Error("Unknown traversal order: " + options.order);
+        const [expr, _] = unwrap(this._traverse_redo({ order }, change));
+        return expr;
+      }
+      /**
+       * @private
+       * @param {Object} options
+       * @param {(e:Expr) => TraverseValue<Expr>} change
+       * @returns {TraverseValue<Expr>}
+       */
+      _traverse_redo(options, change) {
+        let action;
+        let expr = this;
+        let prev;
+        do {
+          prev = expr;
+          const next = options.order === "LI" ? expr._traverse_descend(options, change) ?? change(expr) : change(expr) ?? expr._traverse_descend(options, change);
+          [expr, action] = unwrap(next);
+        } while (expr && action === control.redo);
+        if (!expr && prev !== this)
+          expr = prev;
+        return action ? action(expr) : expr;
+      }
+      /**
+       * @private
+       * @param {Object} options
+       * @param {(e:Expr) => TraverseValue<Expr>} change
+       * @returns {TraverseValue<Expr>}
+       */
+      _traverse_descend(options, change) {
+        return null;
       }
       /**
        * @desc Returns true if predicate() is true for any subterm of the expression, false otherwise.
@@ -179,18 +285,25 @@ var require_expr = __commonJS({
        * @experimental
        * @template T
        * @param {T} initial
-       * @param {(acc: T, expr: Expr) => ActionWrapper<T>} combine
+       * @param {(acc: T, expr: Expr) => TraverseValue<T>} combine
        * @returns {T}
        */
       fold(initial, combine) {
         const [value, _] = unwrap(this._fold(initial, combine));
         return value ?? initial;
       }
+      /**
+       * @template T
+       * @param {T} initial
+       * @param {(acc: T, expr: Expr) => TraverseValue<T>} combine
+       * @returns {TraverseValue<T>}
+       * @private
+       */
       _fold(initial, combine) {
         return combine(initial, this);
       }
       /**
-       * @desc rough estimate of the complexity of the term
+       * @desc rough estimate of the term's complexity
        * @return {number}
        */
       weight() {
@@ -209,52 +322,61 @@ var require_expr = __commonJS({
        *       Use toLambda() if you want to get a lambda term in any case.
        *
        * @param {{max?: number, maxArgs?: number}} options
-       * @return {{
-       *    normal: boolean,
-       *    steps: number,
-       *    expr?: Expr,
-       *    arity?: number,
-       *    proper?: boolean,
-       *    discard?: boolean,
-       *    duplicate?: boolean,
-       *    skip?: Set<number>,
-       *    dup?: Set<number>,
-       * }}
+       * @return {TermInfo}
        */
       infer(options = {}) {
-        const max = options.max ?? DEFAULTS.max;
-        const maxArgs = options.maxArgs ?? DEFAULTS.maxArgs;
-        const out = this._infer({ max, maxArgs, index: 0 });
-        return out;
+        return this._infer({
+          max: options.max ?? DEFAULTS.max,
+          maxArgs: options.maxArgs ?? DEFAULTS.maxArgs
+        }, 0);
       }
       /**
-       *
-       * @param {{max: number, maxArgs: number, index: number}} options
-       * @param {FreeVar[]} preArgs
-       * @param {number} steps
-       * @returns {{normal: boolean, steps: number}|{normal: boolean, steps: number}|{normal: boolean, steps: number, expr: Lambda|*, arity?: *, skip?: Set<any>, dup?: Set<any>, duplicate, discard, proper: boolean}|*|{normal: boolean, steps: number}}
+       * @desc Internal method for infer(), which performs the actual inference.
+       * @param {{max: number, maxArgs: number}} options
+       * @param {number} nargs - var index to avoid name clashes
+       * @returns {TermInfo}
        * @private
        */
-      _infer(options, preArgs = [], steps = 0) {
-        if (preArgs.length > options.maxArgs || steps > options.max)
-          return { normal: false, steps };
-        if (this.freeOnly()) {
-          return {
-            normal: true,
-            steps,
-            ...maybeLambda(preArgs, this)
-          };
+      _infer(options, nargs) {
+        const probe = [];
+        let steps = 0;
+        let expr = this;
+        main: for (let i = 0; i < options.maxArgs; i++) {
+          const next = expr.run({ max: options.max - steps });
+          steps += next.steps;
+          if (!next.final)
+            break;
+          if (firstVar(next.expr)) {
+            expr = next.expr;
+            if (!expr.any((e) => !(e instanceof FreeVar || e instanceof App)))
+              return maybeLambda(probe, expr, { steps });
+            const list = expr.unroll();
+            let discard = false;
+            let duplicate = false;
+            const acc = [];
+            for (let j = 1; j < list.length; j++) {
+              const sub = list[j]._infer(
+                { maxArgs: options.maxArgs - nargs, max: options.max - steps },
+                // limit recursion
+                nargs + i
+                // avoid variable name clashes
+              );
+              steps += sub.steps;
+              if (!sub.expr)
+                break main;
+              if (sub.discard)
+                discard = true;
+              if (sub.duplicate)
+                duplicate = true;
+              acc.push(sub.expr);
+            }
+            return maybeLambda(probe, list[0].apply(...acc), { discard, duplicate, steps });
+          }
+          const push = nthvar(nargs + i);
+          probe.push(push);
+          expr = next.expr.apply(push);
         }
-        const next = this.run({ max: (options.max - steps) / 3 });
-        steps += next.steps;
-        if (!next.final)
-          return { normal: false, steps };
-        if (next.steps !== 0)
-          return next.expr._infer(options, preArgs, steps);
-        if (this.unroll()[0] instanceof FreeVar)
-          return { normal: false, steps };
-        const push = nthvar(preArgs.length + options.index);
-        return this.apply(push)._infer(options, [...preArgs, push], steps);
+        return { normal: false, proper: false, steps };
       }
       /**
        * @desc Expand an expression into a list of terms
@@ -289,10 +411,10 @@ var require_expr = __commonJS({
        *   latin?: number,
        * }} options
        * @param {number} [maxWeight] - maximum allowed weight of terms in the sequence
-       * @return {IterableIterator<{expr: Expr, steps: number?, comment: string?}>}
+       * @return {IterableIterator<{expr: Expr, steps?: number, comment?: string}>}
        */
       *toLambda(options = {}) {
-        const expr = this.traverse((e) => {
+        let expr = this.traverse((e) => {
           if (e instanceof FreeVar || e instanceof App || e instanceof Lambda || e instanceof Alias)
             return null;
           const guess = e.infer({ max: options.max, maxArgs: options.maxArgs });
@@ -300,7 +422,25 @@ var require_expr = __commonJS({
             throw new Error("Failed to infer an equivalent  lambda term for " + e);
           return guess.expr;
         }) ?? this;
-        yield* simplifyLambda(expr, options);
+        const seen = /* @__PURE__ */ new Set();
+        let steps = 0;
+        while (expr) {
+          const next = expr.traverse({ order: "LI" }, (e) => {
+            if (seen.has(e))
+              return null;
+            if (e instanceof App && e.fun instanceof Lambda) {
+              const guess = e.infer({ max: options.max, maxArgs: options.maxArgs });
+              steps += guess.steps;
+              if (!guess.normal) {
+                seen.add(e);
+                return null;
+              }
+              return control.stop(guess.expr);
+            }
+          });
+          yield { expr, steps };
+          expr = next;
+        }
       }
       /**
        * @desc Rewrite the expression into S, K, and I combinators step by step.
@@ -313,28 +453,31 @@ var require_expr = __commonJS({
        * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
        */
       *toSKI(options = {}) {
+        let expr = this.traverse((e) => {
+          if (e instanceof FreeVar || e instanceof App || e instanceof Lambda || e instanceof Alias)
+            return null;
+          return e.infer().expr;
+        }) ?? this;
         let steps = 0;
-        let expr = this;
-        while (true) {
-          const opt = { max: options.max ?? 1, steps: 0 };
-          const next = expr._rski(opt);
-          const final = opt.steps === 0;
-          yield { expr, steps, final };
-          if (final)
-            break;
+        while (expr) {
+          const next = expr.traverse({ order: "LI" }, (e) => {
+            if (!(e instanceof Lambda) || e.impl instanceof Lambda)
+              return null;
+            if (e.impl === e.arg)
+              return control.stop(native.I);
+            if (!e.impl.any((t) => t === e.arg))
+              return control.stop(native.K.apply(e.impl));
+            if (!(e.impl instanceof App))
+              throw new Error("toSKI: assert failed: lambda body is of unexpected type " + e.impl.constructor.name);
+            if (e.impl.arg === e.arg && !e.impl.fun.any((t) => t === e.arg))
+              return control.stop(e.impl.fun);
+            return control.stop(native.S.apply(new Lambda(e.arg, e.impl.fun), new Lambda(e.arg, e.impl.arg)));
+          });
+          yield { expr, steps, final: !next };
+          steps++;
           expr = next;
-          steps += opt.steps;
         }
       }
-      /**
-       * @desc Internal method for toSKI, which performs one step of the conversion.
-       * @param {{max: number, steps: number}} options
-       * @returns {Expr}
-       * @private
-       */
-      _rski(options) {
-        return this;
-      }
       /**
        * Replace all instances of plug in the expression with value and return the resulting expression,
        * or null if no changes could be made.
@@ -382,7 +525,7 @@ var require_expr = __commonJS({
        * @desc Run uninterrupted sequence of step() applications
        *       until the expression is irreducible, or max number of steps is reached.
        *       Default number of steps = 1000.
-       * @param {{max: number?, steps: number?, throw: boolean?}|Expr} [opt]
+       * @param {{max?: number, steps?: number, throw?: boolean}|Expr} [opt]
        * @param {Expr} args
        * @return {{expr: Expr, steps: number, final: boolean}}
        */
@@ -411,7 +554,7 @@ var require_expr = __commonJS({
       /**
        * Execute step() while possible, yielding a brief description of events after each step.
        * Mnemonics: like run() but slower.
-       * @param {{max: number?}} options
+       * @param {{max?: number}} options
        * @return {IterableIterator<{final: boolean, expr: Expr, steps: number}>}
        */
       *walk(options = {}) {
@@ -474,19 +617,24 @@ var require_expr = __commonJS({
       }
       /**
        * @desc Assert expression equality. Can be used in tests.
-       * @param {Expr} expected
+       *
+       * `this` is the expected value and the argument is the actual one.
+       * Mnemonic: the expected value is always a combinator, the actual one may be anything.
+       *
+       * @param {Expr} actual
        * @param {string} comment
        */
-      expect(expected, comment = "") {
+      expect(actual, comment = "") {
         comment = comment ? comment + ": " : "";
-        if (!(expected instanceof _Expr))
-          throw new Error(comment + "attempt to expect a combinator to equal something else: " + expected);
-        const diff = this.diff(expected);
+        if (!(actual instanceof _Expr)) {
+          throw new Error(comment + "Expected a combinator but found " + (actual?.constructor?.name ?? typeof actual));
+        }
+        const diff = this.diff(actual);
         if (!diff)
           return;
         const poorMans = new Error(comment + diff);
-        poorMans.expected = expected + "";
-        poorMans.actual = this + "";
+        poorMans.expected = this.diag();
+        poorMans.actual = actual.diag();
         throw poorMans;
       }
       /**
@@ -586,6 +734,42 @@ var require_expr = __commonJS({
       _format(options, nargs) {
         throw new Error("No _format() method defined in class " + this.constructor.name);
       }
+      /**
+       * @desc Returns a string representation of the expression tree, with indentation to show structure.
+       *
+       *       Applications are flattened to avoid excessive nesting.
+       *       Variables include ids to distinguish different instances of the same variable name.
+       *
+       *       May be useful for debugging.
+       *
+       * @returns {string}
+       *
+       * @example
+       * > console.log(ski.parse('C 5 x (x->x x)').diag())
+       * App:
+       *   Native: C
+       *   Church: 5
+       *   FreeVar: x[53]
+       *   Lambda (x[54]):
+       *     App:
+       *       FreeVar: x[54]
+       *       FreeVar: x[54]
+       */
+      diag() {
+        const rec = (e, indent) => {
+          if (e instanceof App)
+            return [indent + "App:", ...e.unroll().flatMap((s) => rec(s, indent + "  "))];
+          if (e instanceof Lambda)
+            return [`${indent}Lambda (${e.arg}[${e.arg.id}]):`, ...rec(e.impl, indent + "  ")];
+          if (e instanceof Alias)
+            return [`${indent}Alias (${e.name}): \\`, ...rec(e.impl, indent)];
+          if (e instanceof FreeVar)
+            return [`${indent}FreeVar: ${e.name}[${e.id}]`];
+          return [`${indent}${e.constructor.name}: ${e}`];
+        };
+        const out = rec(this, "");
+        return out.join("\n");
+      }
       /**
        * @desc Convert the expression to a JSON-serializable format.
        * @returns {string}
@@ -605,72 +789,35 @@ var require_expr = __commonJS({
         super();
         this.arg = arg;
         this.fun = fun;
-        this.final = false;
-        this.arity = this.fun.arity > 0 ? this.fun.arity - 1 : 0;
       }
+      /** @property {boolean} [final] */
       weight() {
         return this.fun.weight() + this.arg.weight();
       }
-      _infer(options, preArgs = [], steps = 0) {
-        if (preArgs.length > options.maxArgs || steps > options.max)
-          return { normal: false, steps };
-        const proxy = super._infer(options, preArgs, steps);
-        if (proxy.normal)
-          return proxy;
-        steps = proxy.steps;
-        const [first, ...list] = this.unroll();
-        if (!(first instanceof FreeVar))
-          return { normal: false, steps };
-        let discard = false;
-        let duplicate = false;
-        const out = [];
-        for (const term of list) {
-          const guess = term._infer({
-            ...options,
-            maxArgs: options.maxArgs - preArgs.length,
-            max: options.max - steps,
-            index: preArgs.length + options.index
-          });
-          steps += guess.steps;
-          if (!guess.normal)
-            return { normal: false, steps };
-          out.push(guess.expr);
-          discard = discard || guess.discard;
-          duplicate = duplicate || guess.duplicate;
-        }
-        return {
-          normal: true,
-          steps,
-          ...maybeLambda(preArgs, first.apply(...out), {
-            discard,
-            duplicate
-          })
-        };
-      }
-      traverse(change) {
-        const replaced = change(this);
-        if (replaced instanceof Expr)
-          return replaced;
-        const fun = this.fun.traverse(change);
-        const arg = this.arg.traverse(change);
-        if (!fun && !arg)
-          return null;
-        return (fun ?? this.fun).apply(arg ?? this.arg);
+      _traverse_descend(options, change) {
+        const [fun, fAction] = unwrap(this.fun._traverse_redo(options, change));
+        if (fAction === control.stop)
+          return control.stop(fun ? fun.apply(this.arg) : null);
+        const [arg, aAction] = unwrap(this.arg._traverse_redo(options, change));
+        const final = fun || arg ? (fun ?? this.fun).apply(arg ?? this.arg) : null;
+        if (aAction === control.stop)
+          return control.stop(final);
+        return final;
       }
       any(predicate) {
         return predicate(this) || this.fun.any(predicate) || this.arg.any(predicate);
       }
       _fold(initial, combine) {
         const [value = initial, action = "descend"] = unwrap(combine(initial, this));
-        if (action === "prune")
+        if (action === control.prune)
           return value;
-        if (action === "stop")
+        if (action === control.stop)
           return control.stop(value);
         const [fValue = value, fAction = "descend"] = unwrap(this.fun._fold(value, combine));
-        if (fAction === "stop")
+        if (fAction === control.stop)
           return control.stop(fValue);
         const [aValue = fValue, aAction = "descend"] = unwrap(this.arg._fold(fValue, combine));
-        if (aAction === "stop")
+        if (aAction === control.stop)
           return control.stop(aValue);
         return aValue;
       }
@@ -714,15 +861,6 @@ var require_expr = __commonJS({
       unroll() {
         return [...this.fun.unroll(), this.arg];
       }
-      /**
-       * @desc Convert the expression to SKI combinatory logic
-       * @return {Expr}
-       */
-      _rski(options) {
-        if (options.steps >= options.max)
-          return this;
-        return this.fun._rski(options).apply(this.arg._rski(options));
-      }
       diff(other, swap = false) {
         if (!(other instanceof _App))
           return super.diff(other, swap);
@@ -784,6 +922,8 @@ var require_expr = __commonJS({
        * If a scope object is given, however, two variables with the same name and scope
        * are considered identical.
        *
+       * By convention, FreeVar.global is a constant denoting a global unbound variable.
+       *
        * @param {string} name - name of the variable
        * @param {any} scope - an object representing where the variable belongs to.
        */
@@ -814,6 +954,7 @@ var require_expr = __commonJS({
         return options.var[0] + name + options.var[1];
       }
     };
+    FreeVar.global = ["global"];
     var Native = class extends Named {
       /**
        * @desc A named term with a known rewriting rule.
@@ -829,29 +970,14 @@ var require_expr = __commonJS({
        *
        * @param {String} name
        * @param {Partial} impl
-       * @param {{note?: string, arity?: number, canonize?: boolean, apply?: function(Expr):(Expr|null) }} [opt]
+       * @param {{note?: string, arity?: number, canonize?: boolean }} [opt]
        */
       constructor(name, impl, opt = {}) {
         super(name);
         this.invoke = impl;
-        const guess = opt.canonize ?? true ? this.infer() : { normal: false };
-        this.arity = opt.arity || guess.arity || 1;
-        this.note = opt.note ?? guess.expr?.format({ terse: true, html: true, lambda: ["", " &mapsto; ", ""] });
-      }
-      _rski(options) {
-        if (this === native.I || this === native.K || this === native.S || options.steps >= options.max)
-          return this;
-        const canon = this.infer().expr;
-        if (!canon)
-          return this;
-        options.steps++;
-        return canon._rski(options);
+        this._setup({ canonize: true, ...opt });
       }
     };
-    var native = {};
-    function addNative(name, impl, opt) {
-      native[name] = new Native(name, impl, opt);
-    }
     var Lambda = class _Lambda extends Expr {
       /**
        * @desc Lambda abstraction of arg over impl.
@@ -892,35 +1018,25 @@ var require_expr = __commonJS({
       weight() {
         return this.impl.weight() + 1;
       }
-      _infer(options, preArgs = [], steps = 0) {
-        if (preArgs.length > options.maxArgs)
-          return { normal: false, steps };
-        const push = nthvar(preArgs.length + options.index);
-        return this.invoke(push)._infer(options, [...preArgs, push], steps + 1);
-      }
       invoke(arg) {
         return this.impl.subst(this.arg, arg) ?? this.impl;
       }
-      traverse(change) {
-        const replaced = change(this);
-        if (replaced instanceof Expr)
-          return replaced;
-        const impl = this.impl.traverse(change);
-        if (!impl)
-          return null;
-        return new _Lambda(this.arg, impl);
+      _traverse_descend(options, change) {
+        const [impl, iAction] = unwrap(this.impl._traverse_redo(options, change));
+        const final = impl ? new _Lambda(this.arg, impl) : null;
+        return iAction === control.stop ? control.stop(final) : final;
       }
       any(predicate) {
         return predicate(this) || this.impl.any(predicate);
       }
       _fold(initial, combine) {
         const [value = initial, action = "descend"] = unwrap(combine(initial, this));
-        if (action === "prune")
+        if (action === control.prune)
           return value;
-        if (action === "stop")
+        if (action === control.stop)
           return control.stop(value);
         const [iValue, iAction] = unwrap(this.impl._fold(value, combine));
-        if (iAction === "stop")
+        if (iAction === control.stop)
           return control.stop(iValue);
         return iValue ?? value;
       }
@@ -930,26 +1046,6 @@ var require_expr = __commonJS({
         const change = this.impl.subst(search, replace);
         return change ? new _Lambda(this.arg, change) : null;
       }
-      _rski(options) {
-        const impl = this.impl._rski(options);
-        if (options.steps >= options.max)
-          return new _Lambda(this.arg, impl);
-        options.steps++;
-        if (impl === this.arg)
-          return native.I;
-        if (!impl.any((e) => e === this.arg))
-          return native.K.apply(impl);
-        if (impl instanceof App) {
-          const { fun, arg } = impl;
-          if (arg === this.arg && !fun.any((e) => e === this.arg))
-            return fun._rski(options);
-          return native.S.apply(
-            new _Lambda(this.arg, fun)._rski(options),
-            new _Lambda(this.arg, arg)._rski(options)
-          );
-        }
-        throw new Error("Don't know how to convert to SKI" + this);
-      }
       diff(other, swap = false) {
         if (!(other instanceof _Lambda))
           return super.diff(other, swap);
@@ -966,25 +1062,24 @@ var require_expr = __commonJS({
         return true;
       }
     };
-    var Church = class _Church extends Native {
+    var Church = class _Church extends Expr {
       /**
        * @desc Church numeral representing non-negative integer n:
        *      n f x = f(f(...(f x)...)) with f applied n times.
        * @param {number} n
        */
       constructor(n) {
-        const p = Number.parseInt(n);
-        if (!(p >= 0))
+        n = Number.parseInt(n);
+        if (!(n >= 0))
           throw new Error("Church number must be a non-negative integer");
-        const name = "" + p;
-        const impl = (x) => (y) => {
+        super();
+        this.invoke = (x) => (y) => {
           let expr = y;
-          for (let i = p; i-- > 0; )
+          for (let i = n; i-- > 0; )
             expr = x.apply(expr);
           return expr;
         };
-        super(name, impl, { arity: 2, canonize: false, note: name });
-        this.n = p;
+        this.n = n;
         this.arity = 2;
       }
       diff(other, swap = false) {
@@ -997,6 +1092,9 @@ var require_expr = __commonJS({
       _unspaced(arg) {
         return false;
       }
+      _format(options, nargs) {
+        return nargs >= 2 ? options.redex[0] + this.n + options.redex[1] : this.n + "";
+      }
     };
     function waitn(expr, n) {
       return (arg) => n <= 1 ? expr.apply(arg) : waitn(expr.apply(arg), n - 1);
@@ -1016,39 +1114,43 @@ var require_expr = __commonJS({
        *
        * @param {String} name
        * @param {Expr} impl
-       * @param {{canonize: boolean?, max: number?, maxArgs: number?, note: string?, terminal: boolean?}} [options]
+       * @param {{canonize?: boolean, max?: number, maxArgs?: number, note?: string, terminal?: boolean}} [options]
        */
       constructor(name, impl, options = {}) {
         super(name);
         if (!(impl instanceof Expr))
           throw new Error("Attempt to create an alias for a non-expression: " + impl);
         this.impl = impl;
-        if (options.note)
-          this.note = options.note;
-        const guess = options.canonize ? impl.infer({ max: options.max, maxArgs: options.maxArgs }) : { normal: false };
-        this.arity = guess.proper && guess.arity || 0;
-        this.proper = guess.proper ?? false;
-        this.terminal = options.terminal ?? this.proper;
-        this.canonical = guess.expr;
-        this.invoke = waitn(impl, this.arity);
+        this._setup(options);
+        this.terminal = options.terminal ?? this.props?.proper;
+        this.invoke = waitn(impl, this.arity ?? 0);
       }
+      /**
+       * @property {boolean} [outdated] - whether the alias is outdated
+       *     and should be replaced with its definition when encountered.
+       * @property {boolean} [terminal] - whether the alias should behave like a standalone term
+       *     // TODO better name?
+       * @property {boolean} [proper] - whether the alias is a proper combinator (i.e. contains no free variables or constants)
+       * @property {number} [arity] - the number of arguments the alias waits for before expanding
+       * @property {Expr} [canonical] - equivalent lambda term.
+       */
       weight() {
         return this.terminal ? 1 : this.impl.weight();
       }
-      traverse(change) {
-        return change(this) ?? this.impl.traverse(change);
+      _traverse_descend(options, change) {
+        return this.impl._traverse_redo(options, change);
       }
       any(predicate) {
         return predicate(this) || this.impl.any(predicate);
       }
       _fold(initial, combine) {
-        const [value = initial, action = "descend"] = unwrap(combine(initial, this));
-        if (action === "prune")
+        const [value = initial, action] = unwrap(combine(initial, this));
+        if (action === control.prune)
           return value;
-        if (action === "stop")
+        if (action === control.stop)
           return control.stop(value);
         const [iValue, iAction] = unwrap(this.impl._fold(value, combine));
-        if (iAction === "stop")
+        if (iAction === control.stop)
           return control.stop(iValue);
         return iValue ?? value;
       }
@@ -1057,12 +1159,10 @@ var require_expr = __commonJS({
           return replace;
         return this.impl.subst(search, replace);
       }
-      _infer(options, preArgs = [], steps = 0) {
-        return this.impl._infer(options, preArgs, steps);
-      }
+      // DO NOT REMOVE TYPE or tsc chokes with
+      //       TS2527: The inferred type of 'Alias' references an inaccessible 'this' type.
       /**
-       *
-       * @return {{expr: Expr, steps: number}}
+       * @return {{expr: Expr, steps: number, changed: boolean}}
        */
       step() {
         if (this.arity > 0)
@@ -1074,9 +1174,6 @@ var require_expr = __commonJS({
           return null;
         return other.diff(this.impl, !swap);
       }
-      _rski(options) {
-        return this.impl._rski(options);
-      }
       _braced(first) {
         return this.outdated ? this.impl._braced(first) : false;
       }
@@ -1085,6 +1182,9 @@ var require_expr = __commonJS({
         return outdated ? this.impl._format(options, nargs) : super._format(options, nargs);
       }
     };
+    function addNative(name, impl, opt) {
+      native[name] = new Native(name, impl, opt);
+    }
     addNative("I", (x) => x);
     addNative("K", (x) => (_) => x);
     addNative("S", (x) => (y) => (z) => x.apply(z, y.apply(z)));
@@ -1098,6 +1198,11 @@ var require_expr = __commonJS({
         note: "Increase a Church numeral argument by 1, otherwise n => f => x => f(n f x)"
       }
     );
+    function firstVar(expr) {
+      while (expr instanceof App)
+        expr = expr.fun;
+      return expr instanceof FreeVar;
+    }
     function maybeLambda(args, expr, caps = {}) {
       const count = new Array(args.length).fill(0);
       let proper = true;
@@ -1121,8 +1226,10 @@ var require_expr = __commonJS({
           dup.add(i);
       }
       return {
+        normal: true,
+        steps: caps.steps,
         expr: args.length ? new Lambda(args, expr) : expr,
-        ...caps.synth ? {} : { arity: args.length },
+        arity: args.length,
         ...skip.size ? { skip } : {},
         ...dup.size ? { dup } : {},
         duplicate: !!dup.size || caps.duplicate || false,
@@ -1133,43 +1240,6 @@ var require_expr = __commonJS({
     function nthvar(n) {
       return new FreeVar("abcdefgh"[n] ?? "x" + n);
     }
-    function* simplifyLambda(expr, options = {}, state = { steps: 0 }) {
-      yield { expr, steps: state.steps, comment: "(self)" };
-      if (expr.freeOnly())
-        return;
-      let maxWeight = expr.weight();
-      if (expr instanceof Lambda) {
-        for (const term of simplifyLambda(expr.impl, options, state)) {
-          const candidate = new Lambda(expr.arg, term.expr);
-          if (candidate.weight() < maxWeight) {
-            maxWeight = candidate.weight();
-            yield { expr: candidate, steps: state.steps, comment: "(lambda)" + term.comment };
-          }
-        }
-      }
-      if (expr instanceof App) {
-        let { fun, arg } = expr;
-        for (const term of simplifyLambda(fun, options, state)) {
-          const candidate = term.expr.apply(arg);
-          if (candidate.weight() < maxWeight) {
-            maxWeight = candidate.weight();
-            fun = term.expr;
-            yield { expr: candidate, steps: state.steps, comment: "(fun)" + term.comment };
-          }
-        }
-        for (const term of simplifyLambda(arg, options, state)) {
-          const candidate = fun.apply(term.expr);
-          if (candidate.weight() < maxWeight) {
-            maxWeight = candidate.weight();
-            yield { expr: candidate, steps: state.steps, comment: "(arg)" + term.comment };
-          }
-        }
-      }
-      const canon = expr.infer({ max: options.max, maxArgs: options.maxArgs });
-      state.steps += canon.steps;
-      if (canon.expr && canon.expr.weight() < maxWeight)
-        yield { expr: canon.expr, steps: state.steps, comment: "(canonical)" };
-    }
     function toposort(list, env) {
       if (list instanceof Expr)
         list = [list];
@@ -1273,7 +1343,7 @@ var require_parser = __commonJS({
       "->",
       "\\+"
     );
-    var SKI2 = class _SKI {
+    var SKI2 = class {
       /**
        *
        * @param {{
@@ -1319,24 +1389,31 @@ var require_parser = __commonJS({
        *
        * @param {Alias|String} term
        * @param {String|Expr|function(Expr):Partial} [impl]
-       * @param {String} [note]
+       * @param {object|string} [options]
+       * @param {string} [options.note] - optional annotation for the term, default is auto-generated if this.annotate is true
+       * @param {boolean} [options.canonize] - whether to canonize the term's implementation, default is this.annotate
+       * @param {boolean} [options.fancy] - alternative HTML-friendly name for the term
+       * @param {number} [options.arity] - custom arity for the term, default is inferred from the implementation
        * @return {SKI} chainable
        */
-      add(term, impl, note) {
+      add(term, impl, options) {
         term = this._named(term, impl);
-        if (this.annotate && note === void 0) {
-          const guess = term.infer();
-          if (guess.expr)
-            note = guess.expr.format({ terse: true, html: true, lambda: ["", " &mapsto; ", ""] });
-        }
-        if (note !== void 0)
-          term.note = note;
+        if (typeof options === "string")
+          options = { note: options, canonize: false };
+        term._setup({ canonize: this.annotate, ...options });
         if (this.known[term.name])
           this.known[term.name].outdated = true;
         this.known[term.name] = term;
         this.allow.add(term.name);
         return this;
       }
+      /**
+       * @desc Internal helper for add() that creates an Alias or Native term from the given arguments.
+       * @param {Alias|string} term
+       * @param {string|Expr|function(Expr):Partial} impl
+       * @returns {Native|Alias}
+       * @private
+       */
       _named(term, impl) {
         if (term instanceof Alias)
           return new Alias(term.name, term.impl, { canonize: true });
@@ -1352,6 +1429,16 @@ var require_parser = __commonJS({
           return new Native(term, impl);
         throw new Error("add(): impl must be an Expr, a string, or a function with a signature Expr => ... => Expr");
       }
+      /**
+       * @desc Declare a new term if it is not known, otherwise just allow it.
+       *       Currently only used by quests.
+       *       Use with caution, this function may change its signature, behavior, or even be removed in the future.
+       *
+       * @experimental
+       * @param {string|Alias} name
+       * @param {string|Expr|function(Expr):Partial} impl
+       * @returns {SKI}
+       */
       maybeAdd(name, impl) {
         if (this.known[name])
           this.allow.add(name);
@@ -1363,7 +1450,7 @@ var require_parser = __commonJS({
        * @desc Declare and remove multiple terms at once
        *       term=impl adds term
        *       term= removes term
-       * @param {string[]]} list
+       * @param {string[]} list
        * @return {SKI} chainable
        */
       bulkAdd(list) {
@@ -1484,11 +1571,11 @@ var require_parser = __commonJS({
         return out;
       }
       /**
-       *
+       * @template T
        * @param {string} source
        * @param {Object} [options]
        * @param {{[keys: string]: Expr}} [options.env]
-       * @param {any} [options.scope]
+       * @param {T} [options.scope]
        * @param {boolean} [options.numbers]
        * @param {boolean} [options.lambdas]
        * @param {string} [options.allow]
@@ -1505,7 +1592,7 @@ var require_parser = __commonJS({
             expr.outdated = true;
           const def = item.match(/^([A-Z]|[a-z][a-z_0-9]*)\s*=(.*)$/s);
           if (def && def[2] === "")
-            expr = new FreeVar(def[1], options.scope ?? _SKI);
+            expr = new FreeVar(def[1], options.scope ?? FreeVar.global);
           else
             expr = this.parseLine(item, jar, options);
           if (def) {
@@ -1524,12 +1611,14 @@ var require_parser = __commonJS({
         return expr;
       }
       /**
-       *
+       * @desc Parse a single line of source code, without splitting it into declarations.
+       *       Internal, always use parse() instead.
+       * @template T
        * @param {String} source S(KI)I
        * @param {{[keys: string]: Expr}} env
        * @param {Object} [options]
        * @param {{[keys: string]: Expr}} [options.env] - unused, see 'env' argument
-       * @param {any} [options.scope]
+       * @param {T} [options.scope]
        * @param {boolean} [options.numbers]
        * @param {boolean} [options.lambdas]
        * @param {string} [options.allow]
@@ -1548,7 +1637,7 @@ var require_parser = __commonJS({
         const tokens = combChars.split(source);
         const empty = new Empty();
         const stack = [empty];
-        const context = options.scope || _SKI;
+        const context = options.scope || FreeVar.global;
         for (const c of tokens) {
           if (c === "(")
             stack.push(empty);
@@ -1593,12 +1682,12 @@ var require_parser = __commonJS({
         };
       }
     };
-    SKI2.vars = function(context = {}) {
+    SKI2.vars = function(scope = {}) {
       const cache = {};
       return new Proxy({}, {
         get: (target, name) => {
           if (!(name in cache))
-            cache[name] = new FreeVar(name, context);
+            cache[name] = new FreeVar(name, scope);
           return cache[name];
         }
       });
@@ -1620,40 +1709,23 @@ var require_quest = __commonJS({
     var { Expr, FreeVar, Alias, Lambda } = SKI2.classes;
     var Quest2 = class {
       /**
-         * @description A combinator problem with a set of test cases for the proposed solution.
-         * @param {{
-         *    input: InputSpec | InputSpec[],
-         *    cases: TestCase[],
-         *
-         *    // the rest is optional
-      
-         *    allow?: string,
-         *    numbers?: boolean,
-         *    env?: string[],
-         *    engine?: SKI,
-         *    engineFull?: SKI,
-         *
-         *    // metadata, also any fields not listed here will go to quest.meta.???
-         *    id?: string|number,
-         *    name?: string,
-         *    intro?: string|string[], // multiple strings will be concatenated with spaces
-         * }} options
-         *
-         * @example const quest = new Quest({
-         *    input: 'identity',
-         *    cases: [
-         *      ['identity x', 'x'],
-         *    ],
-         *    allow: 'SK',
-         *    intro: 'Find a combinator that behaves like the identity function.',
-         * });
-         * quest.check('S K K'); // { pass: true, details: [...], ... }
-         * quest.check('K S');   // { pass: false, details: [...], ... }
-         * quest.check('K x');   // fail! internal variable x is not equal to free variable x,
-         *                       //     despite having the same name.
-         * quest.check('I');     // fail! I not in the allowed list.
-         */
-      constructor(options = {}) {
+       * @description A combinator problem with a set of test cases for the proposed solution.
+       * @param {QuestSpec} options
+       * @example const quest = new Quest({
+       *    input: 'identity',
+       *    cases: [
+       *      ['identity x', 'x'],
+       *    ],
+       *    allow: 'SK',
+       *    intro: 'Find a combinator that behaves like the identity function.',
+       * });
+       * quest.check('S K K'); // { pass: true, details: [...], ... }
+       * quest.check('K S');   // { pass: false, details: [...], ... }
+       * quest.check('K x');   // fail! internal variable x is not equal to free variable x,
+       *                       //     despite having the same name.
+       * quest.check('I');     // fail! I not in the allowed list.
+       */
+      constructor(options) {
         const { input, cases, allow, numbers, lambdas, engine, engineFull, ...meta } = options;
         const env = options.env ?? options.vars;
         this.engine = engine ?? new SKI2();
@@ -1746,7 +1818,11 @@ var require_quest = __commonJS({
             numbers: spec.numbers ?? this.restrict.numbers,
             lambdas: spec.lambdas ?? this.restrict.lambdas
           });
-          weight += impl.weight();
+          const arsenal = { ...this.engine.getTerms(), ...jar };
+          weight += impl.fold(0, (a, e) => {
+            if (e instanceof SKI2.classes.Named && arsenal[e.name] === e)
+              return SKI2.control.prune(a + 1);
+          });
           const expr = impl instanceof FreeVar ? impl : new Alias(spec.fancy ?? spec.name, impl, { terminal: true, canonize: false });
           jar[spec.name] = expr;
           prepared.push(expr);
@@ -1779,6 +1855,62 @@ var require_quest = __commonJS({
           return { pass: false, details: [], exception: e, steps: 0, input };
         }
       }
+      verify(options) {
+        const findings = this.verifyMeta(options);
+        if (options.solutions) {
+          const solCheck = this.verifySolutions(options.solutions);
+          if (solCheck)
+            findings.solutions = solCheck;
+        }
+        if (options.seen) {
+          if (!this.id)
+            findings.seen = "No id in quest " + (this.name ?? "(unnamed)");
+          if (options.seen.has(this.id))
+            findings.seen = "Duplicate quest id " + this.id;
+          options.seen.add(this.id);
+        }
+        return Object.keys(findings).length ? findings : null;
+      }
+      /**
+       * @desc Verify that solutions that are expected to pass/fail do so.
+       * @param {SelfCheck|{[key: string]: SelfCheck}} dataset
+       * @return {{shouldPass: {input: string[], result: QuestResult}[], shouldFail: {input: string[], result: QuestResult}[]} | null}
+       */
+      verifySolutions(dataset) {
+        if (typeof dataset === "object" && !Array.isArray(dataset?.accepted) && !Array.isArray(dataset?.rejected)) {
+          if (!this.id || !dataset[this.id])
+            return null;
+        }
+        const { accepted = [], rejected = [] } = dataset[this.id] ?? dataset;
+        const ret = { shouldPass: [], shouldFail: [] };
+        for (const input of accepted) {
+          const result = this.check(...input);
+          if (!result.pass)
+            ret.shouldPass.push({ input, result });
+        }
+        for (const input of rejected) {
+          const result = this.check(...input);
+          if (result.pass)
+            ret.shouldFail.push({ input, result });
+        }
+        return ret.shouldFail.length + ret.shouldPass.length ? ret : null;
+      }
+      verifyMeta(options = {}) {
+        const findings = {};
+        for (const field of ["name", "intro"]) {
+          const found = checkHtml(this[field]);
+          if (found)
+            findings[field] = found;
+        }
+        if (options.date) {
+          const date = new Date(this.meta.created_at);
+          if (isNaN(date))
+            findings.date = "invalid date format: " + this.meta.created_at;
+          else if (date < /* @__PURE__ */ new Date("2024-07-15") || date > /* @__PURE__ */ new Date())
+            findings.date = "date out of range: " + this.meta.created_at;
+        }
+        return findings;
+      }
       /**
          *
          * @return {TestCase[]}
@@ -1819,10 +1951,10 @@ var require_quest = __commonJS({
       /**
        * @param {FreeVar[]} input
        * @param {{
-       *    max: number?,
-       *    note: string?,
-       *    env: {string: Expr}?,
-       *    engine: SKI?
+       *    max?: number,
+       *    note?: string,
+       *    env?: {string: Expr},
+       *    engine?: SKI
        * }} options
        * @param {[e1: string, e2: string]} terms
        */
@@ -1929,11 +2061,67 @@ var require_quest = __commonJS({
         return expr;
       }
     };
+    var Group = class {
+      constructor(options) {
+        this.name = options.name;
+        this.intro = list2str(options.intro);
+        this.id = options.id;
+        if (options.content)
+          this.content = options.content.map((c) => c instanceof Quest2 ? c : new Quest2(c));
+      }
+      verify(options) {
+        const findings = {};
+        const id = checkId(this.id, options.seen);
+        if (id)
+          findings[this.id] = id;
+        for (const field of ["name", "intro"]) {
+          const found = checkHtml(this[field]);
+          if (found)
+            findings[field] = found;
+        }
+        findings.content = this.content.map((q) => q.verify(options));
+        return findings;
+      }
+    };
     function list2str(str) {
       if (str === void 0 || typeof str === "string")
         return str;
       return Array.isArray(str) ? str.join(" ") : "" + str;
     }
+    function checkId(id, seen) {
+      if (id === void 0)
+        return "missing";
+      if (typeof id !== "string" && typeof id !== "number")
+        return "is a " + typeof id;
+      if (seen) {
+        if (seen.has(id))
+          return "duplicate id " + id;
+        seen.add(id);
+      }
+    }
+    function checkHtml(str) {
+      if (str === void 0)
+        return "missing";
+      if (typeof str !== "string")
+        return "not a string but " + typeof str;
+      const tagStack = [];
+      const tagRegex = /<\/?([a-z]+)(?:\s[^>]*)?>/gi;
+      let match;
+      while ((match = tagRegex.exec(str)) !== null) {
+        const [fullTag, tagName] = match;
+        if (fullTag.startsWith("</")) {
+          if (tagStack.length === 0 || tagStack.pop() !== tagName)
+            return `Unmatched closing tag: </${tagName}>`;
+        } else {
+          tagStack.push(tagName);
+        }
+      }
+      if (tagStack.length > 0)
+        return `Unclosed tags: ${tagStack.join(", ")}`;
+      return null;
+    }
+    Quest2.Group = Group;
+    Quest2.Case = Case;
     module2.exports = { Quest: Quest2 };
   }
 });
@@ -1943,6 +2131,7 @@ var require_extras = __commonJS({
   "src/extras.js"(exports2, module2) {
     "use strict";
     var { Expr, Alias, FreeVar } = require_expr();
+    var { Quest: Quest2 } = require_quest();
     function search(seed, options, predicate) {
       const {
         depth = 16,
@@ -2008,6 +2197,10 @@ var require_extras = __commonJS({
     function deepFormat(obj, options = {}) {
       if (obj instanceof Expr)
         return obj.format(options);
+      if (obj instanceof Quest2)
+        return "Quest(" + obj.name + ")";
+      if (obj instanceof Quest2.Case)
+        return "Quest.Case";
       if (Array.isArray(obj))
         return obj.map(deepFormat);
       if (typeof obj !== "object" || obj === null || obj.constructor !== Object)