@tabnas/expr 0.5.18 → 0.5.20

package/dist/expr.js

@@ -1,10 +1,16 @@
 "use strict";
 /* Copyright (c) 2021-2025 Richard Rodger, MIT License */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.translate = exports.testing = exports.Expr = exports.VERSION = void 0;
+exports.translate = exports.testing = exports.FoldError = exports.Expr = exports.VERSION = void 0;
 exports.evaluation = evaluation;
 exports.simplify = simplify;
 exports.parseSimplified = parseSimplified;
+exports.fold = fold;
+exports.recordPositions = recordPositions;
+exports.opify = opify;
+exports.isOp = isOp;
+exports.keyOpOf = keyOpOf;
+exports.makeKeyMap = makeKeyMap;
 // This algorithm is based on Pratt parsing, and draws heavily from
 // the explanation written by Aleksey Kladov here:
 // https://matklad.github.io/2020/04/13/simple-but-powerful-pratt-parsing.html
@@ -69,6 +75,7 @@ let Expr = function Expr(tn, options) {
     const suffixTM = makeOpMap(token, fixed, optop, 'suffix');
     const infixTM = makeOpMap(token, fixed, optop, 'infix');
     const ternaryTM = makeOpMap(token, fixed, optop, 'ternary');
+    const keyTM = makeKeyMap(optop);
     const parenOTM = makeParenMap(token, fixed, optop);
     const parenCTM = omap(parenOTM, ([_, pdef]) => [
         undefined,
@@ -94,6 +101,45 @@ let Expr = function Expr(tn, options) {
             },
         },
     });
+    // Deferred mode: fold the finished root on the last pass of the parse.
+    // The engine's post-process rule event fires after every pass in every
+    // grammar; the last pass is a depth-0 close whose alternate neither
+    // pushes, replaces nor failed (a rule with no close alternates reports
+    // none), outside any probe and not synthesised by recovery. A parse
+    // that fails is therefore never folded: the engine reports the failing
+    // pass with `alt.err` set, from a handler that swallows subscriber
+    // errors. The start rule's own after-close is not that event: a grammar
+    // may replace its start rule (yaml's `stream` does on a directive or a
+    // document marker), and `parse` returns the original root rule's node,
+    // which is what is written here.
+    if (options.fold) {
+        const foldOptions = options.fold;
+        const deferred = {
+            ...foldOptions,
+            op: optop,
+            positions: true === foldOptions.positions ? recordPositions(tn) : foldOptions.positions,
+        };
+        tn.sub({
+            ruleDone: (r, ctx, done) => {
+                if (0 !== r.d || 'c' !== done.state || done.probe || done.forced)
+                    return;
+                const alt = done.alt;
+                if (null != alt && (alt.p || alt.r || alt.err))
+                    return;
+                // A token the last close backtracked over is still in the
+                // lookahead buffer, and the engine's trailing-content check fails
+                // the parse on it once the rule loop ends: such a parse is not
+                // folded, so a fold error cannot stand in for the syntax error.
+                // Under recovery the parse returns its value all the same.
+                const t0 = ctx.t0;
+                if (!ctx.cfg.parse.recover.enabled && null != t0 &&
+                    ctx.NOTOKEN.tin !== t0.tin && ZZ !== t0.tin)
+                    return;
+                const root = ctx.root();
+                root.node = foldTree(root.node, deferred, keyTM);
+            },
+        });
+    }
     // Append 'expr' to the g (group tag) of every alt added below. Mirrors
     // the jsonic grammar(...) setting {rule:{alt:{g:'expr'}}}, applied
     // manually because the plugin uses jsonic.rule() (not jsonic.grammar()).
@@ -1116,6 +1162,8 @@ function makeOpMap(token, fixed, op, anyfix) {
                 active: false,
                 required: false,
             },
+            key: false,
+            dynamic: false,
             token: {},
             OP_MARK,
         });
@@ -1180,6 +1228,8 @@ function makeParenMap(token, fixed, optop) {
                 tkn: '',
                 tin: -1,
                 terms: 1,
+                key: false,
+                dynamic: false,
                 token: {},
                 OP_MARK,
             };
@@ -1187,6 +1237,568 @@ function makeParenMap(token, fixed, optop) {
         return a;
     }, {});
 }
+// Key operators, by the member name that marks a site. A key operator
+// carries no token, no tin and no binding power; `terms` is 2 (the
+// member's value, then the sibling map). The table is a Map in the order
+// a map that owns two of the members is resolved by: static operators
+// before dynamic ones, then member names in code-point order. Neither
+// declaration order nor object key order is used: a Go option table has
+// no declaration order, and a JavaScript object lists integer-like names
+// first. Two operators on one member name are refused.
+function makeKeyMap(optop) {
+    const found = [];
+    const owner = new Map();
+    for (const [name, kdef] of entries(optop)) {
+        if (!kdef || !kdef.key)
+            continue;
+        const src = 'string' === typeof kdef.src ? kdef.src : (kdef.src || [])[0];
+        if ('string' !== typeof src || '' === src) {
+            throw new FoldError('fold_key', 'key operator ' + shown(name) + ' names no member');
+        }
+        const prior = owner.get(src);
+        if (undefined !== prior) {
+            throw new FoldError('fold_key', 'key operators ' + shown(prior) + ' and ' + shown(name) + ' both name the member ' + shown(src));
+        }
+        owner.set(src, name);
+        found.push({
+            name: name + (name.endsWith('-key') ? '' : '-key'),
+            src,
+            left: Number.MIN_SAFE_INTEGER,
+            right: Number.MAX_SAFE_INTEGER,
+            use: kdef.use || {},
+            prefix: false,
+            suffix: false,
+            infix: false,
+            ternary: false,
+            paren: false,
+            terms: 2,
+            tkn: '',
+            tin: -1,
+            osrc: '',
+            csrc: '',
+            otkn: '',
+            otin: -1,
+            ctkn: '',
+            ctin: -1,
+            preval: { active: false, required: false },
+            key: true,
+            dynamic: !!kdef.dynamic,
+            token: {},
+            OP_MARK,
+        });
+    }
+    found.sort((a, b) => a.dynamic === b.dynamic ? byCodePoint(a.src, b.src) : a.dynamic ? 1 : -1);
+    return new Map(found.map((op) => [op.src, op]));
+}
+// Compare two strings by Unicode code point, which is the order Go and
+// Rust compare strings in; JavaScript's own `<` compares UTF-16 code
+// units, which differs above U+FFFF.
+function byCodePoint(a, b) {
+    const x = Array.from(a);
+    const y = Array.from(b);
+    for (let i = 0; i < x.length && i < y.length; i++) {
+        const d = x[i].codePointAt(0) - y[i].codePointAt(0);
+        if (0 !== d)
+            return d;
+    }
+    return x.length - y.length;
+}
+// A plain record: an object whose prototype is `null` (the engine's
+// maps) or `Object.prototype` (`JSON.parse`, a literal). Anything else, a
+// Map, a Date, a class instance, a boxed value, is a leaf to a fold and
+// to `evaluation`: passed through by identity, never rebuilt, since a
+// rebuilt copy would carry the prototype without the internal state.
+function isRecord(v) {
+    if (null == v || 'object' !== typeof v || Array.isArray(v))
+        return false;
+    const proto = Object.getPrototypeOf(v);
+    return null === proto || Object.prototype === proto;
+}
+// The key operator a map is an occurrence of, by shape: the first, in the
+// table's order, whose member the map owns. Undefined for anything else.
+function keyOpOf(keys, node) {
+    if (!isRecord(node))
+        return undefined;
+    for (const op of keys.values()) {
+        if (Object.prototype.hasOwnProperty.call(node, op.src))
+            return op;
+    }
+    return undefined;
+}
+// RFC 6901: a pointer from path segments.
+function pointer(path) {
+    let out = '';
+    for (const seg of path) {
+        out += '/' + String(seg).replace(/~/g, '~0').replace(/\//g, '~1');
+    }
+    return out;
+}
+// An RFC 6901 array index: `0`, or digits with no leading zero, given as
+// a string, or a non-negative integer; -1 for anything else, `-` and
+// out-of-range indices included.
+const INDEX = /^(0|[1-9][0-9]*)$/;
+function arrayIndex(seg, length) {
+    const i = 'number' === typeof seg
+        ? (Number.isInteger(seg) ? seg : -1)
+        : (INDEX.test(seg) ? Number(seg) : -1);
+    return 0 <= i && i < length ? i : -1;
+}
+// One step of a path: an index into a list, or an own member of a plain
+// record. NOTHING when the step names nothing.
+const NOTHING = Symbol('nothing');
+function step(node, seg) {
+    if (Array.isArray(node)) {
+        const i = arrayIndex(seg, node.length);
+        return i < 0 ? NOTHING : node[i];
+    }
+    if (isRecord(node) && Object.prototype.hasOwnProperty.call(node, seg))
+        return node[seg];
+    return NOTHING;
+}
+// A new container of the same prototype as `like` (the engine builds
+// null-prototype objects), with members DEFINED rather than assigned so a
+// member named `__proto__` stays data.
+function newRecord(like) {
+    return Object.create(Object.getPrototypeOf(like));
+}
+function define(o, k, v) {
+    Object.defineProperty(o, k, { value: v, enumerable: true, writable: true, configurable: true });
+}
+// The fold's own errors. `code` is what a fixture pins: `fold_cycle` (a
+// cycle under `cycle: 'error'`), `fold_depth` (nesting and reference hops
+// past `maxDepth`, or the stack ran out first), `fold_inherit` (an
+// `inherit` that returned no bag, or folded its own subtree), `fold_key`
+// (an operator table with two key operators on one member name, or one
+// on none) and `fold_option` (`positions: true` outside deferred mode).
+// The document key and the pointers are fields; the message quotes them
+// JSON-escaped and cut short, since member names are document content.
+class FoldError extends Error {
+    constructor(code, message, fields) {
+        super('expr fold: ' + message);
+        this.name = 'FoldError';
+        this.code = code;
+        if (fields)
+            Object.assign(this, fields);
+    }
+}
+exports.FoldError = FoldError;
+// A key or pointer for a message: JSON-escaped, so a newline or an escape
+// sequence in a member name stays visible, and at most about 80
+// characters long.
+function shown(s) {
+    const q = JSON.stringify(s);
+    return q.length <= 80 ? q : q.slice(0, 76) + '..."';
+}
+// Record the opening token of every container a parse builds, by the
+// container's identity, and return the lookup `fold` takes as
+// `positions`. It subscribes to the engine's post-process rule event on
+// the instance, so it works in any grammar; the table is weak, so a
+// parsed tree's entries go with the tree.
+function recordPositions(tn) {
+    const tokens = new WeakMap();
+    tn.sub({
+        ruleDone: (r, _ctx, done) => {
+            if ('o' !== done.state)
+                return;
+            const node = r.node;
+            if (null != node && 'object' === typeof node && !tokens.has(node) && r.o0) {
+                tokens.set(node, r.o0);
+            }
+        },
+    });
+    return (node) => tokens.get(node);
+}
+class PNode {
+    constructor(doc, parent, seg, raw) {
+        this.doc = doc;
+        this.parent = parent;
+        this.seg = seg;
+        this.raw = raw;
+        this.kids = undefined;
+        // 0 not yet folded, 1 being folded (on the active stack), 2 folded.
+        this.state = 0;
+        this.value = undefined;
+        // How the walk entered it: 0 from its parent, 1 through a reference.
+        this.via = 0;
+        this.k = undefined;
+        this.kBusy = false;
+        // Its resolution met a cycle, so the resolver was told `cycle: true`.
+        this.cut = false;
+        // A member of a loop of references with no container in it, or a
+        // reference into one: there is nothing to resolve it to.
+        this.loop = false;
+        // The key operator this map is an occurrence of, decided once (shape,
+        // then the host's `recognise`): undefined until decided, null for none.
+        this.site = undefined;
+        this.parts = undefined;
+        this.plainDone = false;
+        this.plainValue = undefined;
+        this.ptr = undefined;
+    }
+}
+// Fold a finished tree: walk it, reduce every key-operator site
+// bottom-up through `opts.evaluate`, and return a NEW tree; the input is
+// never changed (though a value a resolver returns, `site.node` among
+// them, is placed in the output as it is). Values flow up through
+// `evaluate`; context flows down through `inherit`, computed per path
+// from each map's own ancestors and kept. One result per location, so
+// every site naming one target shares one folded value. Every container
+// being folded is on an active stack: a site whose target is on it
+// closes a cycle, which the resolver is told about (or which throws).
+// Dynamic key operators are reported and folded as plain maps. Token
+// operator arrays met in the walk are reduced through the same
+// `evaluate` when `tokens` is on.
+function fold(root, opts) {
+    return foldTree(root, opts, makeKeyMap(opts.op || {}));
+}
+function foldTree(root, opts, keys) {
+    if (true === opts.positions) {
+        throw new FoldError('fold_option', 'positions: true records tokens during a parse, so it works in the deferred mode only;'
+            + ' pass a lookup, such as recordPositions(tn), to fold');
+    }
+    const tokens = false !== opts.tokens;
+    const inherit = opts.inherit;
+    const recognise = opts.recognise;
+    const lookup = 'function' === typeof opts.positions ? opts.positions : undefined;
+    const maxDepth = null == opts.maxDepth ? 1000 : opts.maxDepth;
+    const base = opts.k || {};
+    const report = { cycles: [], unresolved: [], dynamic: [] };
+    const noted = new Set();
+    const stack = [];
+    const docs = new Map();
+    const makeDoc = (key, raw) => {
+        const doc = { key, root: raw };
+        doc.top = new PNode(doc, undefined, '', raw);
+        docs.set(key, doc);
+        return doc;
+    };
+    // Another document, by key, loaded once; undefined when it cannot be had.
+    const docOf = (from, key) => {
+        if (undefined === key || key === from.doc.key)
+            return from.doc;
+        let doc = docs.get(key);
+        if (undefined === doc) {
+            const raw = undefined === opts.load ? undefined : opts.load(key, siteOf(from));
+            doc = undefined === raw ? null : makeDoc(key, raw);
+            docs.set(key, doc);
+        }
+        return null === doc ? undefined : doc;
+    };
+    const kid = (pn, seg, raw) => {
+        const name = String(seg);
+        let kids = pn.kids;
+        if (undefined === kids)
+            kids = pn.kids = new Map();
+        let node = kids.get(name);
+        if (undefined === node) {
+            node = new PNode(pn.doc, pn, seg, raw);
+            kids.set(name, node);
+        }
+        return node;
+    };
+    const ptrOf = (pn) => {
+        if (undefined !== pn.ptr)
+            return pn.ptr;
+        const chain = [];
+        let p = pn;
+        while (undefined !== p && undefined === p.ptr) {
+            chain.push(p);
+            p = p.parent;
+        }
+        let s = undefined === p ? '' : p.ptr;
+        for (let i = chain.length - 1; 0 <= i; i--) {
+            const c = chain[i];
+            s = undefined === c.parent ? '' : s + '/' + String(c.seg).replace(/~/g, '~0').replace(/\//g, '~1');
+            c.ptr = s;
+        }
+        return s;
+    };
+    const pathOf = (pn) => {
+        const path = [];
+        for (let p = pn; undefined !== p && undefined !== p.parent; p = p.parent) {
+            path.push(p.seg);
+        }
+        return path.reverse();
+    };
+    const note = (list, row) => {
+        const id = JSON.stringify([list, row.doc, row.at, row.targetDoc, row.target, row.src]);
+        if (noted.has(id))
+            return;
+        noted.add(id);
+        report[list].push(row);
+    };
+    // The bag at a map: the `inherit` calls of its ancestors and of the map
+    // itself, from the root down, each kept, worked out without recursion.
+    const kOf = (pn) => {
+        if (undefined === inherit)
+            return base;
+        if (undefined !== pn.k)
+            return pn.k;
+        const chain = [];
+        let p = pn;
+        while (undefined !== p && undefined === p.k) {
+            if (p.kBusy) {
+                throw new FoldError('fold_inherit', 'inherit folded its own subtree at ' + shown(ptrOf(p)), { doc: p.doc.key, at: ptrOf(p) });
+            }
+            chain.push(p);
+            p = p.parent;
+        }
+        let k = undefined === p ? base : p.k;
+        for (let i = chain.length - 1; 0 <= i; i--) {
+            const c = chain[i];
+            if (isRecord(c.raw)) {
+                c.kBusy = true;
+                let next;
+                try {
+                    next = inherit(siteOf(c, k), c.raw, k);
+                }
+                finally {
+                    c.kBusy = false;
+                }
+                if (null == next || 'object' !== typeof next) {
+                    throw new FoldError('fold_inherit', 'inherit returned no bag at ' + shown(ptrOf(c)), { doc: c.doc.key, at: ptrOf(c) });
+                }
+                k = next;
+            }
+            c.k = k;
+        }
+        return k;
+    };
+    const siteOf = (pn, parentK) => {
+        let path;
+        const node = pn.raw;
+        return {
+            root: pn.doc.root,
+            doc: pn.doc.key,
+            get path() {
+                return undefined === path ? (path = pathOf(pn)) : path;
+            },
+            node,
+            get k() {
+                return undefined === parentK ? kOf(pn) : parentK;
+            },
+            token: undefined !== lookup && null != node && 'object' === typeof node ? lookup(node) : undefined,
+            at: (target, doc) => at(pn, target, doc),
+            locate: (target, doc) => locate(pn, target, doc),
+            plain: () => plainOf(pn),
+        };
+    };
+    const locate = (from, target, key) => {
+        const doc = docOf(from, key);
+        if (undefined === doc)
+            return { found: false };
+        let node = doc.root;
+        for (const seg of target) {
+            node = step(node, seg);
+            if (NOTHING === node)
+                return { found: false };
+        }
+        return { found: true, value: node };
+    };
+    const miss = (from, targetDoc, target) => {
+        note('unresolved', { doc: from.doc.key, at: ptrOf(from), targetDoc, target: pointer(target) });
+        return { found: false, cycle: false };
+    };
+    // A cycle: `from` named `target` while `target` was still being folded
+    // (a back edge), or `target` is in a loop of references. Every member of
+    // a loop made only of references is a cycle, and so is every reference
+    // into one, since none of them has anything to resolve to. A cycle that
+    // passes through a container is cut once, at the site whose target was
+    // being folded; a later reference to that site gets its folded value.
+    const cycleTo = (from, target) => {
+        const row = { doc: from.doc.key, at: ptrOf(from), targetDoc: target.doc.key, target: ptrOf(target) };
+        if ('error' === opts.cycle) {
+            throw new FoldError('fold_cycle', 'cycle at ' + shown(row.at) + ' to ' + shown(row.target), row);
+        }
+        note('cycles', row);
+        from.cut = true;
+        if (1 === target.state) {
+            const i = stack.lastIndexOf(target);
+            let refs = 0 <= i;
+            for (let j = i + 1; refs && j < stack.length; j++)
+                refs = 1 === stack[j].via;
+            if (refs) {
+                for (let j = i; j < stack.length; j++)
+                    stack[j].loop = true;
+                from.loop = true;
+            }
+        }
+        else if (target.loop) {
+            from.loop = true;
+        }
+        return { found: true, cycle: true };
+    };
+    // The folded value at `target` in a document, for the site at `from`.
+    // Raw members are followed from the root; a key-operator map met on the
+    // way is folded (through the memo) and the remaining segments read its
+    // folded value, so a reference to a reference resolves. A target still
+    // being folded is a cycle, and so is a path that must pass through a
+    // site that was cut.
+    const at = (from, target, key) => {
+        const targetDoc = undefined === key ? from.doc.key : key;
+        const doc = docOf(from, key);
+        if (undefined === doc)
+            return miss(from, targetDoc, target);
+        let pn = doc.top;
+        let node = doc.root;
+        for (let i = 0; i < target.length; i++) {
+            const v = step(node, target[i]);
+            if (NOTHING === v)
+                return miss(from, targetDoc, target);
+            if (i === target.length - 1 && !Array.isArray(v) && !isRecord(v)) {
+                return { found: true, cycle: false, value: v };
+            }
+            pn = kid(pn, Array.isArray(node) ? arrayIndex(target[i], node.length) : String(target[i]), v);
+            node = v;
+            // Only a static site changes what lies below it; any other map,
+            // a dynamic one or one `recognise` refused, folds member by member,
+            // so the raw path below it names the same location.
+            const op = i < target.length - 1 && isRecord(node) ? siteOpOf(pn) : null;
+            if (null !== op && !op.dynamic) {
+                if (1 === pn.state || pn.loop)
+                    return cycleTo(from, pn);
+                let folded = walk(pn, 1);
+                if (pn.loop || pn.cut)
+                    return cycleTo(from, pn);
+                for (i++; i < target.length; i++) {
+                    folded = step(folded, target[i]);
+                    if (NOTHING === folded)
+                        return miss(from, targetDoc, target);
+                }
+                return { found: true, cycle: false, value: folded };
+            }
+        }
+        if (1 === pn.state)
+            return cycleTo(from, pn);
+        const value = walk(pn, 1);
+        if (pn.loop)
+            return cycleTo(from, pn);
+        return { found: true, cycle: false, value };
+    };
+    // The key operator a map is an occurrence of here, if any: its shape,
+    // then the host's `recognise`, decided once per location.
+    const siteOpOf = (pn) => {
+        if (undefined !== pn.site)
+            return pn.site;
+        let op = keyOpOf(keys, pn.raw) ?? null;
+        pn.site = op;
+        if (null !== op && undefined !== recognise && !recognise(siteOf(pn), op))
+            op = pn.site = null;
+        return op;
+    };
+    // A member's folded value: a container through the memo, anything else
+    // as it is.
+    const member = (pn, seg, child) => Array.isArray(child) || isRecord(child) ? walk(kid(pn, seg, child), 0) : child;
+    // A map folded as a plain map, members in its own order.
+    const plainOf = (pn) => {
+        if (pn.plainDone)
+            return pn.plainValue;
+        const node = pn.raw;
+        if (!isRecord(node))
+            return walk(pn, 0);
+        const parts = pn.parts;
+        const out = newRecord(node);
+        for (const name of Object.keys(node)) {
+            define(out, name, undefined === parts ? member(pn, name, node[name])
+                : name === parts.op.src ? parts.value : parts.siblings[name]);
+        }
+        pn.plainDone = true;
+        pn.plainValue = out;
+        return out;
+    };
+    const walk = (pn, via) => {
+        if (2 === pn.state)
+            return pn.value;
+        const node = pn.raw;
+        const list = Array.isArray(node);
+        if (!list && (!isRecord(node) || OP_MARK === node.OP_MARK))
+            return node;
+        if (1 === pn.state)
+            return node;
+        if (maxDepth <= stack.length) {
+            throw new FoldError('fold_depth', 'nesting and references deeper than ' + maxDepth + ' at ' + shown(ptrOf(pn)), { doc: pn.doc.key, at: ptrOf(pn) });
+        }
+        pn.state = 1;
+        pn.via = via;
+        stack.push(pn);
+        let out;
+        try {
+            if (list && isOp(node)) {
+                // Each term is folded at its own path first, so a key-operator
+                // site inside a token expression resolves, and a nested
+                // expression is kept by path. With `tokens` off the operator
+                // node is rebuilt around its own head, so it stays an operator.
+                const terms = [];
+                for (let i = 1; i < node.length; i++)
+                    terms.push(member(pn, i, node[i]));
+                out = tokens ? opts.evaluate(siteOf(pn), node[0], terms) : [node[0], ...terms];
+            }
+            else if (list) {
+                // Members are walked inline, not through `member`, so a level of
+                // nesting costs one stack frame.
+                out = [];
+                for (let i = 0; i < node.length; i++) {
+                    const c = node[i];
+                    out.push(Array.isArray(c) || isRecord(c) ? walk(kid(pn, i, c), 0) : c);
+                }
+            }
+            else {
+                const op = siteOpOf(pn);
+                if (null === op || op.dynamic) {
+                    if (null !== op)
+                        note('dynamic', { doc: pn.doc.key, at: ptrOf(pn), src: op.src });
+                    if (pn.plainDone) {
+                        out = pn.plainValue;
+                    }
+                    else {
+                        out = newRecord(node);
+                        for (const name of Object.keys(node)) {
+                            const c = node[name];
+                            define(out, name, Array.isArray(c) || isRecord(c) ? walk(kid(pn, name, c), 0) : c);
+                        }
+                        pn.plainDone = true;
+                        pn.plainValue = out;
+                    }
+                }
+                else {
+                    const siblings = newRecord(node);
+                    let value;
+                    for (const name of Object.keys(node)) {
+                        const v = member(pn, name, node[name]);
+                        if (name === op.src)
+                            value = v;
+                        else
+                            define(siblings, name, v);
+                    }
+                    pn.parts = { op, value, siblings };
+                    const site = siteOf(pn);
+                    out = opts.evaluate(site, { ...op, token: site.token || op.token }, [value, siblings]);
+                }
+            }
+        }
+        finally {
+            stack.pop();
+            pn.state = 0;
+        }
+        pn.state = 2;
+        pn.value = out;
+        return out;
+    };
+    const main = makeDoc(null == opts.doc ? '' : opts.doc, root);
+    let out;
+    try {
+        out = walk(main.top, 0);
+    }
+    catch (err) {
+        if (err instanceof RangeError && /call stack/i.test(String(err.message))) {
+            throw new FoldError('fold_depth', 'the stack ran out before maxDepth (' + maxDepth + ') was reached; lower maxDepth', { doc: main.key });
+        }
+        throw err;
+    }
+    if (opts.report)
+        opts.report(report);
+    return out;
+}
 // Default operator precedence — the "binding power" scale.
 //
 // Binding powers are compared only by ORDER, never by magnitude (every
@@ -1330,13 +1942,13 @@ function prattify(expr, op, whence) {
 // member's position in the list. Weak, so an entry lasts only as long as
 // the value itself.
 const EVALUATED = new WeakSet();
-function evaluation(rule, ctx, expr, evaluate) {
+function evaluation(rule, ctx, expr, evaluate, opts) {
     let out = expr ?? null;
     if (null == expr || EVALUATED.has(expr)) {
         return out;
     }
     if (isOp(expr)) {
-        out = evaluate(rule, ctx, expr[0], expr.slice(1).map((term) => evaluation(rule, ctx, term, evaluate)));
+        out = evaluate(rule, ctx, expr[0], expr.slice(1).map((term) => evaluation(rule, ctx, term, evaluate, opts)));
     }
     // An implicit list — `f(1+2, 3+4)`, `1+2, 3+4` — is a plain array, not
     // an op-array, so the branch above does not reach its members. Reduce
@@ -1347,9 +1959,22 @@ function evaluation(rule, ctx, expr, evaluate) {
     // the expr rule's close hook does that itself — mutating its own tree
     // is the parser's business, not this function's.
     else if (Array.isArray(expr)) {
-        out = expr.map((term) => evaluation(rule, ctx, term, evaluate));
+        out = expr.map((term) => evaluation(rule, ctx, term, evaluate, opts));
+    }
+    // A plain object is passed through unchanged by default, as the
+    // reference documents; with `objects` on it is reduced member by member
+    // into a NEW object of the same prototype, which is what the eager
+    // `evaluate` option already does for an expression inside a map.
+    else if (opts && opts.objects && isRecord(expr)) {
+        const o = newRecord(expr);
+        for (const k of Object.keys(expr))
+            define(o, k, evaluation(rule, ctx, expr[k], evaluate, opts));
+        out = o;
     }
-    if (null != out && 'object' === typeof out) {
+    // Only a value this fold PRODUCED is marked: a node passed through
+    // unchanged (a plain object, by default) is not, so a later fold with
+    // `objects` on still reaches the operators inside it.
+    if (null != out && 'object' === typeof out && out !== expr) {
         EVALUATED.add(out);
     }
     // console.log('EXPR-EVAL', expr, '->', out)
@@ -1412,15 +2037,24 @@ function simplify(value) {
 function parseSimplified(tn, src, meta) {
     return simplify(tn.parse(src, meta));
 }
+// Mark a hand-built operator description as this plugin's, so `isOp` and
+// `evaluation` recognise a node headed by it. A sibling plugin that builds
+// operator nodes needs this; `simplify` needs it not, reading any
+// `src`-headed array. Fills nothing else: pass a complete description.
+function opify(op) {
+    ;
+    op.OP_MARK = OP_MARK;
+    return op;
+}
 const testing = {
     prattify,
-    opify: (x) => ((x.OP_MARK = OP_MARK), x),
+    opify,
 };
 exports.testing = testing;
 // VERSION is this package's version. It MUST equal package.json "version":
 // the release orchestrator rewrites both, and the version test fails the
 // build if they drift. Mirrors `const VERSION` in go/expr.go.
-const VERSION = '0.5.18';
+const VERSION = '0.5.20';
 exports.VERSION = VERSION;
 // The translation parts a host composes a translation from (admin ADR-27):
 // the manifest and the alchemy sources, generated by ../embed-translate.js.