@elaraai/east 1.0.83 → 1.0.85

package/dist/src/query/jq/check.js

@@ -0,0 +1,2261 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The jq checker: types a program against the East type of its input, and
+ * gives the program and its types, which every surface translates, or the
+ * problems that stop it (`devdocs/QUERY.md` §2–§13). It only checks: it
+ * rewrites nothing.
+ *
+ * @packageDocumentation
+ */
+import { variant } from "../../containers/variant.js";
+import { ArrayType, BooleanType, DateTimeType, DictType, FloatType, IntegerType, NeverType, NullType, StringType, StructType, VariantType, isImmutableType, isTypeEqual, printType, } from "../../types.js";
+import { BUILTINS } from "./catalog.js";
+import { isoDateTime, jsonString, literalValue } from "./literals.js";
+import { MESSAGES, closest, edit, report } from "./messages.js";
+import { parseJq } from "./parse.js";
+import { ERROR, MANY, MAYBE, ONE, SOME, ZERO, also, canBeNull, casesOf, describeType, descendTypes, either, membersOf, nullablePayload, JQ_TYPE_NAMES, narrowTypes, orNull, piped, refine, typed, unify, unifyShape, union, unwrap, wireMultiplicity, } from "./shapes.js";
+import { childPath, jqChildren } from "./spans.js";
+/** What a node that never runs gives. */
+const DEAD = { shape: typed(NeverType), mult: { lo: 1, hi: 0 } };
+/** The input of a node that never runs: no value reaches it. */
+const NOTHING = { shape: typed(NeverType), mult: ONE };
+/** The binary operators by kind. */
+const ARITHMETIC = new Set(["+", "-", "*", "/", "%"]);
+const COMPARISON = new Set(["==", "!=", "<", "<=", ">", ">="]);
+/** Numbers: Integer and Float. */
+function isNumber(type) {
+    return type.type === "Integer" || type.type === "Float";
+}
+/** `.`, as a path node. */
+const IDENTITY = variant("identity", null);
+/** What an update's path is made of, for the diagnostic that refuses another. */
+const UPDATE_PATHS = "an update's path is made of field reads, indexes, slices, .[], select, the type selectors, empty, .., recurse and |";
+/**
+ * The type selectors an update's path may hold, each a `select` of a type
+ * test: `(.. | numbers) |= . * 2`.
+ *
+ * @internal
+ */
+export const UPDATE_SELECTORS = new Set([
+    "arrays", "objects", "iterables", "booleans", "numbers", "strings", "nulls", "values", "scalars", "normals", "finites",
+]);
+/**
+ * The path `recurse(f)` walks in an update: field reads, then `.[]`, as
+ * `.children[]`.
+ *
+ * @param node - `f`
+ * @returns the names of the fields read before the `.[]`, or `undefined` for
+ *   another path
+ *
+ * @internal
+ */
+export function walkSteps(node) {
+    if (node.type !== "iterate")
+        return undefined;
+    const fields = [];
+    let target = node.value.target;
+    while (target.type === "field" && !target.value.optional) {
+        fields.unshift(target.value.name);
+        target = target.value.target;
+    }
+    return target.type === "identity" ? { fields } : undefined;
+}
+/** Whether values of type `b` are values of type `a`: equal types, or `a` recursive with `b` its node. */
+function sameType(a, b) {
+    return isTypeEqual(a, b) || (a.type === "Recursive" && isTypeEqual(a.node, b));
+}
+/** A rebuilt value's type: the original, recursive wrapper and all, when what was rebuilt is its node. */
+function rewrap(original, rebuilt) {
+    return original.type === "Recursive" && isTypeEqual(original.node, rebuilt) ? original : rebuilt;
+}
+/**
+ * A shape with each option that may be null opened: `null`, and its value,
+ * as members of their own. In a lenient place jq raises for a `null` a
+ * builtin cannot take and computes with a value, so each is checked apart.
+ *
+ * @returns the opened shape, or `undefined` when no member is such an option
+ */
+function openOptions(shape) {
+    if (shape.kind === "error")
+        return undefined;
+    let opened = false;
+    const members = [];
+    for (const member of membersOf(shape)) {
+        const payload = nullablePayload(unwrap(member.shape.type));
+        if (payload === undefined || member.shape.facts?.kind === "present") {
+            members.push(member);
+            continue;
+        }
+        opened = true;
+        members.push({ shape: typed(NullType), case: member.case }, { shape: typed(payload), case: member.case });
+    }
+    return opened ? union(members) : undefined;
+}
+/** Checks one program. */
+class Checker {
+    text;
+    spans;
+    options;
+    input;
+    diagnostics = [];
+    records = new Map();
+    /** The nodes checked, by path. */
+    nodes = new Map();
+    /** What is in scope at each node checked, by instance and path. */
+    scopes = new Map();
+    /** Each node's input when it was checked, by instance and path. */
+    inputs = new Map();
+    /** How many instances {@link Checker.retype} has made. */
+    retypes = 0;
+    /** The cases each update's `.value` step updates, by instance, path and variant type. */
+    updatedCases = new Map();
+    /** The builtin calls checked with their input's options opened, by instance and path: whether each raises for null. */
+    opened = new Map();
+    /** How many type errors a lenient place has let by, to run as errors. */
+    refused = 0;
+    reads = [];
+    /** Defs being instantiated, by instance signature: their output so far, for recursion. */
+    active = new Map();
+    /** The root's field names, with `root`. */
+    rootNames;
+    constructor(text, spans, options, input) {
+        this.text = text;
+        this.spans = spans;
+        this.options = options;
+        this.input = input;
+        const t = unwrap(input);
+        this.rootNames = options.root === true && t.type === "Struct" ? Object.keys(t.fields) : [];
+    }
+    // ─── Recording and reporting ───────────────────────────────────────────
+    range(path) {
+        return this.spans.get(path);
+    }
+    record(path, env, result) {
+        this.records.set(`${env.instance}|${path}`, result);
+        return result;
+    }
+    /** Reports a problem and gives the error shape. */
+    fail(range, code, message, options = {}) {
+        this.diagnostics.push(report(this.text, code, range, message, options));
+        return { shape: ERROR, mult: ONE };
+    }
+    /** A type error jq raises at run time: reported, or in a lenient place no output. */
+    mismatch(env, range, code, message, options = {}) {
+        if (env.lenient) {
+            this.refused += 1;
+            return { shape: typed(NeverType), mult: ZERO };
+        }
+        return this.fail(range, code, message, options);
+    }
+    warn(range, code, message, fixes = []) {
+        this.diagnostics.push(report(this.text, code, range, message, { fixes, warning: true }));
+    }
+    /** The text of a node, as written. */
+    source(path) {
+        const r = this.range(path);
+        return r === undefined ? "" : this.text.slice(r.from, r.to);
+    }
+    /** The range of a field read's `.name` (or `."name"`), without its target. */
+    accessorRange(node, path) {
+        const whole = this.range(path);
+        const target = this.range(childPath(path, "field.target"));
+        if (whole === undefined || target === undefined)
+            return whole;
+        const from = node.value.target.type === "identity" ? target.from : target.to;
+        return { from, to: node.value.optional ? whole.to - 1 : whole.to };
+    }
+    // ─── The walk ──────────────────────────────────────────────────────────
+    check(node, path, input, env) {
+        this.nodes.set(path, node);
+        this.scopes.set(`${env.instance}|${path}`, env);
+        this.inputs.set(`${env.instance}|${path}`, input.shape);
+        // A node whose input has no values never runs (a branch narrowing rules
+        // out, the elements of `[]`): it gives nothing, and `lo: 1, hi: 0` is the
+        // identity of `either`, so a dead branch leaves its `if`'s bounds alone.
+        if (input.shape.kind === "type" && input.shape.type.type === "Never")
+            return this.record(path, env, DEAD);
+        return this.record(path, env, this.checkNode(node, path, input, env));
+    }
+    checkNode(node, path, input, env) {
+        const at = (step) => childPath(path, step);
+        switch (node.type) {
+            case "identity":
+                return { shape: input.shape, mult: ONE, access: [], stream: input.stream };
+            case "descend":
+                return this.descend(input, path, env);
+            case "literal":
+                return { shape: typed(this.literal(node.value).type), mult: ONE };
+            case "variable":
+                return this.variable(node.value, path, env);
+            case "break":
+                if (!env.labels.has(node.value))
+                    return this.fail(this.range(path), "unknown_function", MESSAGES.unknownLabel(node.value));
+                return { shape: typed(NeverType), mult: ZERO };
+            case "field":
+                return this.field(node, path, input, env);
+            case "index":
+                return this.index(node, path, input, env);
+            case "slice":
+                return this.slice(node, path, input, env);
+            case "iterate":
+                return this.iterate(node, path, input, env);
+            case "pipe": {
+                const left = this.check(node.value.left, at("pipe.left"), input, env);
+                const right = this.check(node.value.right, at("pipe.right"), left, env);
+                return this.compose(left, right);
+            }
+            case "comma": {
+                const left = this.check(node.value.left, at("comma.left"), input, env);
+                const right = this.check(node.value.right, at("comma.right"), input, env);
+                return { shape: union([...membersOf(left.shape), ...membersOf(right.shape)]), mult: also(left.mult, right.mult) };
+            }
+            case "alternative":
+                return this.alternative(node, path, input, env);
+            case "negate": {
+                const operand = this.check(node.value, at("negate"), input, env);
+                return this.mapMembers(operand, member => {
+                    const t = unwrap(member.type);
+                    if (isNumber(t))
+                        return { shape: typed(t), mult: ONE };
+                    // In a lenient place, an option is null, which raises, or a number, negated.
+                    const payload = nullablePayload(t);
+                    if (env.lenient && payload !== undefined && isNumber(unwrap(payload)))
+                        return { shape: typed(unwrap(payload)), mult: MAYBE };
+                    return this.mismatch(env, this.range(path), "type_mismatch", MESSAGES.negate(describeType(member.type)));
+                });
+            }
+            case "binary":
+                return this.binary(node, path, input, env);
+            case "array": {
+                if (node.value.type === "none")
+                    return { shape: typed(ArrayType(NeverType)), mult: ONE };
+                const body = this.check(node.value.value, at("array.some"), input, env);
+                const element = this.collect(body, this.range(path), at("array.some"));
+                if (element === undefined)
+                    return { shape: ERROR, mult: ONE };
+                const facts = body.shape.kind === "type" && body.shape.facts !== undefined ? { kind: "elements", element: body.shape.facts } : undefined;
+                return { shape: typed(ArrayType(element), facts), mult: ONE };
+            }
+            case "object":
+                return this.object(node, path, input, env);
+            case "string": {
+                let mult = ONE;
+                node.value.forEach((part, i) => {
+                    if (part.type === "interpolate")
+                        mult = piped(mult, this.check(part.value, at(`string[${i}].interpolate`), input, env).mult);
+                });
+                return { shape: typed(StringType), mult };
+            }
+            case "format":
+                return this.format(node, path, input, env);
+            case "if":
+                return this.conditional(node, path, input, env);
+            case "try":
+                return this.tryCatch(node, path, input, env);
+            case "reduce":
+            case "foreach":
+                return this.fold(node, path, input, env);
+            case "bind":
+                return this.bind(node, path, input, env);
+            case "label": {
+                const labels = new Set(env.labels);
+                labels.add(node.value.name);
+                const body = this.check(node.value.body, at("label.body"), input, { ...env, labels });
+                // A break stops the stream wherever it runs, so outputs the body would give after it may not come.
+                return { shape: body.shape, mult: breaksTo(node.value.body, node.value.name) ? { lo: 0, hi: body.mult.hi } : body.mult };
+            }
+            case "def": {
+                const defs = new Map(env.defs);
+                const params = node.value.params;
+                const key = `${node.value.name}/${params.length}`;
+                let closure;
+                const binding = { kind: "def", node, path, env: () => closure };
+                defs.set(key, binding);
+                closure = { ...env, defs };
+                return this.check(node.value.rest, at("def.rest"), input, closure);
+            }
+            case "call":
+                return this.call(node, path, input, env);
+            case "update":
+                return this.update(node, path, input, env);
+        }
+    }
+    /** `a | b`: `b` runs on each output of `a`. */
+    compose(left, right) {
+        const prefix = left.access;
+        return {
+            shape: right.shape,
+            mult: piped(left.mult, right.mult),
+            access: prefix !== undefined && right.access !== undefined ? [...prefix, ...right.access] : undefined,
+            caseOf: prefix !== undefined && right.caseOf !== undefined ? { ...right.caseOf, path: [...prefix, ...right.caseOf.path] } : undefined,
+            proves: prefix !== undefined && right.proves !== undefined ? right.proves.map(p => ({ ...p, path: [...prefix, ...p.path] })) : undefined,
+            typeOf: prefix !== undefined && right.typeOf !== undefined ? [...prefix, ...right.typeOf] : undefined,
+            partial: right.partial,
+            stream: right.stream,
+        };
+    }
+    /** Applies a typing to each member of a result's shape, and unions the outcomes. */
+    mapMembers(input, each) {
+        if (input.shape.kind === "error")
+            return { shape: ERROR, mult: input.mult };
+        const members = [];
+        let mult;
+        let error = false;
+        for (const member of membersOf(input.shape)) {
+            const out = each(member.shape, member.case);
+            if (out.shape.kind === "error")
+                error = true;
+            else
+                for (const m of membersOf(out.shape))
+                    members.push({ shape: m.shape, case: m.case ?? member.case });
+            mult = mult === undefined ? out.mult : either(mult, out.mult);
+        }
+        if (error)
+            return { shape: ERROR, mult: mult ?? ONE };
+        return { shape: union(members), mult: mult ?? ZERO };
+    }
+    /**
+     * The one type a stream's outputs share, or a reported `ambiguous_output`.
+     *
+     * @param result - the stream
+     * @param range - where to report a problem
+     * @param at - the path of the node that gives the stream, when it is one:
+     *   outputs that are fields read side by side (`.id, .customer_id`) get the
+     *   suggestion to put them in an object
+     */
+    collect(result, range, at) {
+        if (result.shape.kind === "error")
+            return undefined;
+        const type = unifyShape(result.shape);
+        if (type !== undefined)
+            return type;
+        let acc = NeverType;
+        for (const member of membersOf(result.shape)) {
+            const next = unify(acc, member.shape.type);
+            if (next === undefined) {
+                const message = MESSAGES.noCommonType(describeType(acc), describeType(member.shape.type));
+                const outputs = at === undefined ? undefined : this.lastStage(at);
+                const names = outputs === undefined ? undefined : fieldsSideBySide(outputs.node);
+                const where = outputs === undefined ? undefined : this.range(outputs.path);
+                if (names === undefined || where === undefined) {
+                    this.fail(range, "ambiguous_output", message);
+                }
+                else {
+                    const suggestion = `{${names.join(", ")}}`;
+                    this.fail(where, "ambiguous_output", message, { suggestions: [suggestion], fixes: [edit(`Use ${suggestion}`, where.from, where.to, suggestion)] });
+                }
+                return undefined;
+            }
+            acc = next;
+        }
+        return acc;
+    }
+    /** The node that gives a node's outputs: the last segment of its pipes, through `as` bodies. */
+    lastStage(path) {
+        let node = this.nodes.get(path);
+        let at = path;
+        while (node !== undefined) {
+            if (node.type === "pipe") {
+                at = childPath(at, "pipe.right");
+                node = node.value.right;
+                continue;
+            }
+            if (node.type === "bind") {
+                at = childPath(at, "bind.body");
+                node = node.value.body;
+                continue;
+            }
+            return { node, path: at };
+        }
+        return undefined;
+    }
+    // ─── Leaves ────────────────────────────────────────────────────────────
+    /** A literal's value and type, as the program writes it. */
+    literal(value) {
+        return literalValue(value);
+    }
+    variable(name, path, env) {
+        if (name === "__loc__")
+            return { shape: typed(StructType({ file: StringType, line: IntegerType })), mult: ONE };
+        if (name === "ENV" || name === "__prog_args")
+            return this.fail(this.range(path), "unsupported", MESSAGES.excluded(`$${name}`));
+        const bound = env.vars.get(name);
+        if (bound === undefined)
+            return this.fail(this.range(path), "unknown_function", MESSAGES.unknownVariable(name));
+        return { shape: bound.shape, mult: ONE, caseOf: undefined };
+    }
+    /** `..`: the value and every value nested in it, depth first. */
+    descend(input, path, env) {
+        if (this.refuseRoot(input, path, env))
+            return { shape: ERROR, mult: ONE };
+        if (input.shape.kind === "error")
+            return { shape: ERROR, mult: SOME };
+        const types = descendTypes(membersOf(input.shape).map(member => member.shape.type));
+        return { shape: union(types.map(type => ({ shape: typed(type), case: undefined }))), mult: SOME };
+    }
+    // ─── Paths ─────────────────────────────────────────────────────────────
+    field(node, path, input, env) {
+        const { name, optional, target } = node.value;
+        const base = this.check(target, childPath(path, "field.target"), input, env);
+        const range = this.accessorRange(node, path);
+        const lenient = optional ? { ...env, lenient: true } : env;
+        const read = this.readField(base, name, range, lenient, optional, path);
+        const composed = this.compose(base, { ...read, mult: read.mult });
+        return {
+            ...composed,
+            access: base.access !== undefined && read.access !== undefined ? [...base.access, ...read.access] : undefined,
+            caseOf: read.caseOf !== undefined && base.access !== undefined ? { ...read.caseOf, path: base.access } : undefined,
+            partial: read.partial,
+            stream: base.stream,
+        };
+    }
+    /** `.name` on each member of a shape. */
+    readField(base, name, range, env, optional, path) {
+        if (base.shape.kind === "error")
+            return { shape: ERROR, mult: ONE };
+        const isRoot = base.shape.kind === "type" && this.isRootShape(base.shape);
+        const all = membersOf(base.shape);
+        // The payloads of an un-narrowed variant: a case whose payload lacks the
+        // field gives null, as jq's `.value.f` does, unless no case has it.
+        const payloads = all.some(m => m.case !== undefined);
+        const withField = all.filter(m => m.case !== undefined && name in this.fieldsOf(m.shape.type));
+        if (payloads && withField.length === 0 && !optional && !env.lenient) {
+            const names = [...new Set(all.flatMap(m => Object.keys(this.fieldsOf(m.shape.type))))];
+            const suggestions = closest(name, names).map(n => `.${n}`);
+            const fixes = suggestions.length > 0 && range !== undefined ? [edit(`Use ${suggestions[0]}`, range.from, range.to, suggestions[0])] : [];
+            return this.fail(range, "unknown_field", MESSAGES.unknownPayloadField(`.${name}`, suggestions[0]), { suggestions, fixes });
+        }
+        const members = [];
+        let mult;
+        let caseOf;
+        let missing = false;
+        let error = false;
+        for (const member of all) {
+            const payload = unwrap(nullablePayload(unwrap(member.shape.type)) ?? member.shape.type).type;
+            const lacks = member.case !== undefined && (payload === "Struct" || payload === "Null") && !(name in this.fieldsOf(member.shape.type));
+            const out = this.fieldOfType(member.shape, name, range, env, optional || lacks, isRoot, path);
+            if (out.caseOf !== undefined)
+                caseOf = out.caseOf;
+            if (out.shape.kind === "error") {
+                error = true;
+                continue;
+            }
+            if (lacks)
+                missing = true;
+            for (const m of membersOf(out.shape))
+                members.push(m);
+            mult = mult === undefined ? out.mult : either(mult, out.mult);
+        }
+        if (error)
+            return { shape: ERROR, mult: ONE };
+        const partial = missing && withField.length === 1 ? { caseName: withField[0].case, leaf: name, at: path } : undefined;
+        // A field of the payloads is one field to jq: its values share a type when they can.
+        const merged = payloads ? unifyShape(union(members)) : undefined;
+        const shape = merged !== undefined ? typed(merged) : union(members);
+        return { shape, mult: mult ?? ONE, access: [name], caseOf, partial };
+    }
+    /** The fields jq sees on a type: a struct's, through an option. */
+    fieldsOf(type) {
+        const t = unwrap(nullablePayload(unwrap(type)) ?? type);
+        return t.type === "Struct" ? t.fields : {};
+    }
+    isRootShape(shape) {
+        return this.options.root === true && shape.type === this.input;
+    }
+    fieldOfType(member, name, range, env, optional, isRoot, path) {
+        const type = member.type;
+        const t = unwrap(type);
+        if (t.type === "Null")
+            return { shape: typed(NullType), mult: ONE };
+        const payload = nullablePayload(t);
+        if (payload !== undefined) {
+            const inner = this.fieldOfType(typed(payload, member.facts?.kind === "present" ? member.facts.payload : undefined), name, range, env, optional, false, path);
+            if (inner.shape.kind === "error" || member.facts?.kind === "present")
+                return inner;
+            // `.type` of an optional variant still tests its case: a true test proves the value is there.
+            const wrapped = this.mapMembers(inner, m => {
+                const t2 = orNull(m.type);
+                if (t2 === undefined)
+                    return this.mismatch(env, range, "ambiguous_output", MESSAGES.noCommonType(describeType(m.type), "Null"));
+                return { shape: typed(t2, m.facts), mult: ONE };
+            });
+            return { ...wrapped, caseOf: inner.caseOf };
+        }
+        switch (t.type) {
+            case "Struct": {
+                const fields = t.fields;
+                if (name in fields) {
+                    if (isRoot && !this.reads.includes(name))
+                        this.reads.push(name);
+                    const facts = member.facts?.kind === "fields" ? member.facts.fields.get(name) : undefined;
+                    return { shape: typed(fields[name], facts), mult: ONE };
+                }
+                if (optional || env.lenient)
+                    return { shape: typed(NullType), mult: ONE };
+                const suggestions = closest(name, Object.keys(fields)).map(s => `.${s}`);
+                const fixes = suggestions.length > 0 && range !== undefined ? [edit(`Use ${suggestions[0]}`, range.from, range.to, suggestions[0])] : [];
+                const message = isRoot ? MESSAGES.unknownDataset(`.${name}`, suggestions[0]) : MESSAGES.unknownField(`.${name}`, describeType(type), suggestions[0]);
+                return this.fail(range, "unknown_field", message, { suggestions, fixes });
+            }
+            case "Dict": {
+                if (unwrap(t.key).type !== "String") {
+                    return this.mismatch(env, range, "type_mismatch", MESSAGES.keyType(`.${name}`, describeType(t.key), jsonString(name), "String"));
+                }
+                const value = orNull(t.value);
+                if (value === undefined)
+                    return this.mismatch(env, range, "ambiguous_output", MESSAGES.noCommonType(describeType(t.value), "Null"));
+                return { shape: typed(value), mult: ONE };
+            }
+            case "Variant": {
+                const cases = casesOf(t, member.facts);
+                if (name === "type")
+                    return { shape: typed(StringType), mult: ONE, caseOf: { path: [], variant: t, cases } };
+                if (name === "value") {
+                    const payloadFacts = member.facts?.kind === "cases" ? member.facts.payload : undefined;
+                    const all = t.cases;
+                    return {
+                        shape: union(cases.map(c => ({ shape: typed(all[c], cases.length === 1 ? payloadFacts : undefined), case: c }))),
+                        mult: cases.length === 0 ? ZERO : ONE,
+                    };
+                }
+                if (optional || env.lenient)
+                    return { shape: typed(NullType), mult: ONE };
+                return this.fail(range, "unknown_field", MESSAGES.unknownVariantField(`.${name}`, this.source(childPath(path, "field.target")) || "."), {
+                    suggestions: [".type", ".value"],
+                });
+            }
+            default:
+                if (optional)
+                    return { shape: typed(NeverType), mult: ZERO };
+                return this.mismatch(env, range, "type_mismatch", MESSAGES.notAField(`.${name}`, describeType(type)));
+        }
+    }
+    index(node, path, input, env) {
+        const { index, optional, target } = node.value;
+        const base = this.check(target, childPath(path, "index.target"), input, env);
+        const keyPath = childPath(path, "index.index");
+        const key = this.check(index, keyPath, input, env);
+        const range = this.range(path);
+        const lenient = optional ? { ...env, lenient: true } : env;
+        // A literal string on a struct reads a field.
+        if (index.type === "literal") {
+            const literal = this.literal(index.value);
+            if (literal.type.type === "String" && membersOf(base.shape).every(m => unwrap(m.shape.type).type !== "Dict")) {
+                const read = this.readField(base, literal.value, range, lenient, optional, path);
+                return { ...this.compose(base, read), access: base.access !== undefined ? [...base.access, literal.value] : undefined, stream: base.stream };
+            }
+        }
+        if (key.shape.kind === "error")
+            return { shape: ERROR, mult: ONE };
+        const keyType = this.collect(key, this.range(keyPath));
+        if (keyType === undefined)
+            return { shape: ERROR, mult: ONE };
+        const form = `${this.source(childPath(path, "index.target")) || "."}[…]`;
+        const out = this.mapMembers(base, member => {
+            const t = unwrap(member.type);
+            if (t.type === "Null")
+                return { shape: typed(NullType), mult: ONE };
+            const payload = nullablePayload(t);
+            const container = payload !== undefined ? unwrap(payload) : t;
+            const element = (() => {
+                switch (container.type) {
+                    case "Array":
+                    case "Set": return { key: IntegerType, value: (container.type === "Array" ? container.value : container.key), facts: member.facts?.kind === "elements" ? member.facts.element : undefined };
+                    case "Vector": return { key: IntegerType, value: container.element, facts: undefined };
+                    case "Matrix": return { key: IntegerType, value: ArrayType(container.element), facts: undefined };
+                    case "Dict": return { key: container.key, value: container.value, facts: member.facts?.kind === "values" ? member.facts.value : undefined };
+                    default: return undefined;
+                }
+            })();
+            if (element === undefined) {
+                if (container.type === "Struct")
+                    return this.mismatch(lenient, this.range(keyPath), "type_mismatch", MESSAGES.structKey(form));
+                if (optional)
+                    return { shape: typed(NeverType), mult: ZERO };
+                return this.mismatch(lenient, range, "not_indexable", MESSAGES.notIndexable(this.source(childPath(path, "index.target")) || ".", describeType(member.type)));
+            }
+            if (!this.keyFits(keyType, element.key, index, keyPath, env)) {
+                return this.mismatch(lenient, this.range(keyPath), "type_mismatch", MESSAGES.keyType(form, describeType(element.key), this.source(keyPath), describeType(keyType)));
+            }
+            const value = orNull(element.value);
+            if (value === undefined)
+                return this.mismatch(lenient, range, "ambiguous_output", MESSAGES.noCommonType(describeType(element.value), "Null"));
+            return { shape: typed(value, element.facts), mult: ONE };
+        });
+        return { shape: out.shape, mult: piped(key.mult, piped(base.mult, out.mult)) };
+    }
+    /** Whether a key of `given` type indexes by `wanted`, reading a literal as its operand's type. */
+    keyFits(given, wanted, node, path, env) {
+        const w = unwrap(wanted);
+        if (isTypeEqual(given, w))
+            return true;
+        if (node.type === "literal")
+            return this.coerceLiteral(node, path, w, env) !== undefined;
+        return false;
+    }
+    /**
+     * A literal used where `wanted` is: an Integer where a Float is, an ISO
+     * string where a DateTime is, a string that is not an ISO-8601 date
+     * reported. The program keeps the literal as written (`devdocs/QUERY.md`
+     * §7). An Integer needs nothing more: its translation widens it wherever
+     * it meets a Float. A string read as a DateTime is recorded as one in this
+     * instance, and its translation gives the DateTime it writes.
+     *
+     * @returns the type the literal is read as, or `undefined` when it does
+     *   not fit
+     */
+    coerceLiteral(node, path, wanted, env) {
+        const literal = this.literal(node.value);
+        if (isTypeEqual(literal.type, wanted))
+            return wanted;
+        if (wanted.type === "Float" && literal.type.type === "Integer")
+            return FloatType;
+        if (wanted.type === "DateTime" && literal.type.type === "String") {
+            if (isoDateTime(literal.value) === undefined) {
+                this.fail(this.range(path), "type_mismatch", MESSAGES.isoDate(this.source(path)));
+                return undefined;
+            }
+            this.records.set(`${env.instance}|${path}`, { shape: typed(DateTimeType), mult: ONE });
+            return DateTimeType;
+        }
+        return undefined;
+    }
+    /**
+     * An array literal of literals (`["2026-01-01", "2026-02-01"]`) used where
+     * an array of `wanted` is: each element read as {@link coerceLiteral} reads
+     * it, and what checking the array recorded retyped to match.
+     *
+     * @returns the array's new type, or `undefined` when it is not such an
+     *   array, or an element does not fit
+     */
+    coerceArrayLiteral(node, path, wanted, env) {
+        if (node.type !== "array" || node.value.type !== "some")
+            return undefined;
+        const literals = [];
+        const commas = [];
+        const collect = (n, at) => {
+            if (n.type === "literal") {
+                literals.push({ node: n, path: at });
+                return true;
+            }
+            if (n.type !== "comma")
+                return false;
+            commas.push(at);
+            return collect(n.value.left, childPath(at, "comma.left")) && collect(n.value.right, childPath(at, "comma.right"));
+        };
+        if (!collect(node.value.value, childPath(path, "array.some")))
+            return undefined;
+        for (const literal of literals)
+            if (this.coerceLiteral(literal.node, literal.path, wanted, env) === undefined)
+                return undefined;
+        const retype = (at, type) => {
+            const key = `${env.instance}|${at}`;
+            const r = this.records.get(key);
+            if (r !== undefined)
+                this.records.set(key, { ...r, shape: typed(type) });
+        };
+        for (const at of [...commas, ...literals.map(l => l.path)])
+            retype(at, wanted);
+        retype(path, ArrayType(wanted));
+        return ArrayType(wanted);
+    }
+    slice(node, path, input, env) {
+        const { from, optional, target, to } = node.value;
+        const base = this.check(target, childPath(path, "slice.target"), input, env);
+        let mult = base.mult;
+        for (const [bound, step] of [[from, "slice.from.some"], [to, "slice.to.some"]]) {
+            if (bound.type !== "some")
+                continue;
+            const boundPath = childPath(path, step);
+            const r = this.check(bound.value, boundPath, input, env);
+            mult = piped(mult, r.mult);
+            const t = this.collect(r, this.range(boundPath));
+            if (t !== undefined && !this.keyFits(t, IntegerType, bound.value, boundPath, env) && !canBeNull(t)) {
+                this.mismatch(env, this.range(boundPath), "type_mismatch", MESSAGES.sliceBound(describeType(t)));
+            }
+        }
+        const lenient = optional ? { ...env, lenient: true } : env;
+        const out = this.mapMembers(base, member => {
+            const u = unwrap(member.type);
+            // `null` slices to null, as jq slices it: an option's value is sliced, and its null stays null.
+            const payload = nullablePayload(u);
+            const present = member.facts?.kind === "present";
+            const t = payload === undefined ? u : unwrap(payload);
+            const facts = payload === undefined ? member.facts : member.facts?.kind === "present" ? member.facts.payload : undefined;
+            const sliced = (type, f) => {
+                if (payload === undefined || present)
+                    return { shape: typed(type, f), mult: ONE };
+                const option = orNull(type);
+                return option === undefined ? this.mismatch(lenient, this.range(path), "ambiguous_output", MESSAGES.noCommonType(describeType(type), "Null")) : { shape: typed(option), mult: ONE };
+            };
+            switch (t.type) {
+                case "Null": return { shape: typed(NullType), mult: ONE };
+                case "Array":
+                case "String":
+                case "Vector": return sliced(t, facts);
+                case "Set": return sliced(ArrayType(t.key));
+                default:
+                    if (optional)
+                        return { shape: typed(NeverType), mult: ZERO };
+                    return this.mismatch(lenient, this.range(path), "not_indexable", MESSAGES.notIndexable(this.source(childPath(path, "slice.target")) || ".", describeType(member.type)));
+            }
+        });
+        return { shape: out.shape, mult: piped(mult, out.mult) };
+    }
+    iterate(node, path, input, env) {
+        const { optional, target } = node.value;
+        const base = this.check(target, childPath(path, "iterate.target"), input, env);
+        if (this.refuseRoot(base, path, env))
+            return { shape: ERROR, mult: ONE };
+        const form = `${this.source(childPath(path, "iterate.target")) === "." ? "." : this.source(childPath(path, "iterate.target"))}[]`;
+        const out = this.mapMembers(base, member => this.elementsOf(member, optional, optional ? { ...env, lenient: true } : env, form, this.range(path)));
+        return { shape: out.shape, mult: piped(base.mult, out.mult), stream: path };
+    }
+    /** The elements `.[]` gives on one member. */
+    elementsOf(member, optional, env, form, range) {
+        const t = unwrap(member.type);
+        const payload = nullablePayload(t);
+        if (payload !== undefined) {
+            // Null raises; in a lenient place that gives no output, and a value's elements are given.
+            if (!optional && !env.lenient && member.facts?.kind !== "present") {
+                const fixes = range === undefined ? [] : [edit(`Use ${form}?`, range.to, range.to, "?")];
+                return this.mismatch(env, range, "not_iterable", MESSAGES.notIterableNull(form, describeType(member.type)), { fixes });
+            }
+            const inner = this.elementsOf(typed(payload, member.facts?.kind === "present" ? member.facts.payload : undefined), optional, env, form, range);
+            return { shape: inner.shape, mult: { lo: 0, hi: inner.mult.hi } };
+        }
+        switch (t.type) {
+            case "Array": return { shape: typed(t.value, member.facts?.kind === "elements" ? member.facts.element : undefined), mult: MANY };
+            case "Set": return { shape: typed(t.key), mult: MANY };
+            case "Vector": return { shape: typed(t.element), mult: MANY };
+            case "Matrix": return { shape: typed(ArrayType(t.element)), mult: MANY };
+            case "Dict": return { shape: typed(t.value, member.facts?.kind === "values" ? member.facts.value : undefined), mult: MANY };
+            case "Struct": {
+                const fields = t.fields;
+                const facts = member.facts?.kind === "fields" ? member.facts.fields : undefined;
+                return {
+                    shape: union(Object.entries(fields).map(([name, f]) => ({ shape: typed(f, facts?.get(name)), case: undefined }))),
+                    mult: Object.keys(fields).length === 0 ? ZERO : SOME,
+                };
+            }
+            default:
+                if (optional)
+                    return { shape: typed(NeverType), mult: ZERO };
+                return this.mismatch(env, range, "not_iterable", MESSAGES.notIterable(form, describeType(member.type)));
+        }
+    }
+    /** With `root`, a filter that would read every dataset of the root is refused. */
+    refuseRoot(input, path, _env) {
+        if (this.options.root !== true || input.shape.kind !== "type" || !this.isRootShape(input.shape))
+            return false;
+        this.fail(this.range(path), "unsupported", MESSAGES.wholeRoot(this.rootNames));
+        return true;
+    }
+    /**
+     * "Narrow first": a payload field only one case has, read where its value
+     * is needed. The fix inserts `select(.F.type == "case") | ` before the read,
+     * so only rows of that case reach it.
+     */
+    narrowFirst(env, range, type, partial) {
+        // The read is `<base>.F.value.leaf`, where <base> is `.` or the node the field reads start from.
+        const leaf = this.nodes.get(partial.at);
+        const step = (node, path) => node?.type === "field" || node?.type === "index" ? { node: node.value.target, path: childPath(path, `${node.type}.target`) } : undefined;
+        const value = step(leaf, partial.at);
+        const variant = value === undefined ? undefined : step(value.node, value.path);
+        if (variant === undefined)
+            return this.mismatch(env, range, "type_mismatch", MESSAGES.input(this.source(partial.at), "a value", describeType(type)));
+        let base = variant;
+        while (base.node.type === "field" || base.node.type === "index")
+            base = step(base.node, base.path);
+        const chain = this.range(partial.at);
+        const start = base.node.type === "identity" ? chain.from : this.range(base.path).to;
+        const variantText = this.text.slice(start, this.range(variant.path).to);
+        const leafText = this.text.slice(start, chain.to);
+        const select = `select(${variantText}.type == ${jsonString(partial.caseName)})`;
+        const message = MESSAGES.narrowFirst(leafText, describeType(type), partial.caseName, variantText, partial.leaf);
+        const label = "Narrow first";
+        let fix;
+        if (base.node.type === "identity") {
+            fix = isPipePosition(partial.at)
+                ? edit(label, chain.from, chain.from, `${select} | `)
+                : { edits: [{ insert: `(${select} | `, length: 0n, offset: BigInt(chain.from) }, { insert: ")", length: 0n, offset: BigInt(chain.to) }], label };
+        }
+        else {
+            const inner = ` | ${select} | ${leafText}`;
+            fix = isPipePosition(partial.at)
+                ? edit(label, start, chain.to, inner)
+                : { edits: [{ insert: "(", length: 0n, offset: BigInt(chain.from) }, { insert: `${inner})`, length: BigInt(chain.to - start), offset: BigInt(start) }], label };
+        }
+        return this.mismatch(env, range, "type_mismatch", message, { fixes: [fix] });
+    }
+    /**
+     * An array builtin run on each element of a stream. The fix collects the
+     * stream, from the segment of the call's pipe chain that makes it to the
+     * segment before the call: `a | [b[] | c] | sort_by(…)`.
+     */
+    arrayOnElement(env, callPath, name, stream, type) {
+        const streamText = this.source(stream);
+        // The segments before the call in its pipe chain, first to last.
+        const segments = [];
+        let base = callPath;
+        while (base === "pipe.right" || base.endsWith(".pipe.right")) {
+            base = base === "pipe.right" ? "" : base.slice(0, -".pipe.right".length);
+            segments.unshift(childPath(base, "pipe.left"));
+        }
+        const first = segments.find(segment => stream === segment || stream.startsWith(`${segment}.`));
+        const from = first === undefined ? undefined : this.range(first);
+        const to = segments.length === 0 ? undefined : this.range(segments[segments.length - 1]);
+        if (from === undefined || to === undefined) {
+            return this.mismatch(env, this.range(callPath), "array_builtin_on_element", MESSAGES.arrayOnElement(name, streamText, describeType(type), `[${streamText}]`));
+        }
+        const collected = `[${this.text.slice(from.from, to.to)}]`;
+        const fix = {
+            edits: [{ insert: "[", length: 0n, offset: BigInt(from.from) }, { insert: "]", length: 0n, offset: BigInt(to.to) }],
+            label: `Collect ${streamText} first`,
+        };
+        return this.mismatch(env, this.range(callPath), "array_builtin_on_element", MESSAGES.arrayOnElement(name, streamText, describeType(type), collected), { fixes: [fix] });
+    }
+    // ─── Operators ─────────────────────────────────────────────────────────
+    alternative(node, path, input, env) {
+        const left = this.check(node.value.left, childPath(path, "alternative.left"), input, env);
+        const right = this.check(node.value.right, childPath(path, "alternative.right"), input, env);
+        if (left.shape.kind === "error" || right.shape.kind === "error")
+            return { shape: ERROR, mult: ONE };
+        const kept = [];
+        let alwaysTruthy = true;
+        for (const member of membersOf(left.shape)) {
+            const t = unwrap(member.shape.type);
+            if (t.type === "Null") {
+                alwaysTruthy = false;
+                continue;
+            }
+            const payload = nullablePayload(t);
+            if (payload !== undefined) {
+                alwaysTruthy = false;
+                kept.push({ shape: typed(payload), case: member.case });
+                continue;
+            }
+            if (t.type === "Boolean")
+                alwaysTruthy = false;
+            kept.push(member);
+        }
+        const shape = union([...kept, ...membersOf(right.shape)]);
+        const lo = right.mult.lo === 1 || (alwaysTruthy && left.mult.lo === 1) ? 1 : 0;
+        return { shape, mult: { lo, hi: Math.max(left.mult.hi, right.mult.hi) } };
+    }
+    binary(node, path, input, env) {
+        const { op } = node.value;
+        const leftPath = childPath(path, "binary.left");
+        const rightPath = childPath(path, "binary.right");
+        if (op === "and" || op === "or") {
+            const left = this.check(node.value.left, leftPath, input, env);
+            // The right side of `and` runs only when the left is true, so it sees the left's facts.
+            const rightInput = op === "and" && left.proves !== undefined ? this.narrow(input, left.proves) : input;
+            const right = this.check(node.value.right, rightPath, rightInput, env);
+            if (left.shape.kind === "error" || right.shape.kind === "error")
+                return { shape: ERROR, mult: ONE };
+            const proves = op === "and" ? [...(left.proves ?? []), ...(right.proves ?? [])] : undefined;
+            return { shape: typed(BooleanType), mult: piped(left.mult, right.mult), proves: proves?.length ? proves : undefined };
+        }
+        const left = this.check(node.value.left, leftPath, input, env);
+        const right = this.check(node.value.right, rightPath, input, env);
+        if (left.shape.kind === "error" || right.shape.kind === "error")
+            return { shape: ERROR, mult: piped(left.mult, right.mult) };
+        const mult = piped(left.mult, right.mult);
+        if (COMPARISON.has(op))
+            return { ...this.comparison(op, node, path, left, right, env), mult };
+        if (ARITHMETIC.has(op)) {
+            const out = this.arithmetic(op, left, right, { leftPath, rightPath, range: this.range(path) }, env);
+            return { shape: out.shape, mult: piped(mult, out.mult), partial: out.partial };
+        }
+        throw new Error(`checkJq: ${jsonString(op)} is not a jq binary operator`);
+    }
+    comparison(op, node, path, left, right, env) {
+        const leftPath = childPath(path, "binary.left");
+        const rightPath = childPath(path, "binary.right");
+        // `type == "number"`: a type test, which narrows.
+        for (const [typeSide, otherNode, otherPath] of [[left, node.value.right, rightPath], [right, node.value.left, leftPath]]) {
+            if (typeSide.typeOf === undefined || otherNode.type !== "literal" || (op !== "==" && op !== "!="))
+                continue;
+            const literal = this.literal(otherNode.value);
+            if (literal.type.type !== "String")
+                continue;
+            const name = literal.value;
+            if (!JQ_TYPE_NAMES.includes(name)) {
+                const suggestions = closest(name, JQ_TYPE_NAMES).map(c => jsonString(c));
+                const range = this.range(otherPath);
+                const fixes = suggestions.length > 0 && range !== undefined ? [edit(`Use ${suggestions[0]}`, range.from, range.to, suggestions[0])] : [];
+                return this.fail(range, "unknown_case", MESSAGES.unknownType(jsonString(name), JQ_TYPE_NAMES, suggestions[0]), { suggestions, fixes });
+            }
+            const types = op === "==" ? [name] : JQ_TYPE_NAMES.filter(n => n !== name);
+            return { shape: typed(BooleanType), mult: ONE, proves: [{ kind: "type", path: typeSide.typeOf, types }] };
+        }
+        // `.F.type == "case"`: a case test, which narrows.
+        for (const [caseSide, casePath, otherNode, otherPath] of [[left, leftPath, node.value.right, rightPath], [right, rightPath, node.value.left, leftPath]]) {
+            if (caseSide.caseOf === undefined || otherNode.type !== "literal")
+                continue;
+            const literal = this.literal(otherNode.value);
+            if (literal.type.type !== "String")
+                continue;
+            const name = literal.value;
+            const variantType = unwrap(caseSide.caseOf.variant);
+            const allCases = variantType.type === "Variant" ? Object.keys(variantType.cases) : [];
+            if (!allCases.includes(name)) {
+                const suggestions = closest(name, allCases).map(c => jsonString(c));
+                const range = this.range(otherPath);
+                const fixes = suggestions.length > 0 && range !== undefined ? [edit(`Use ${suggestions[0]}`, range.from, range.to, suggestions[0])] : [];
+                const variantPath = this.source(casePath).replace(/\s*\.\s*type$/, "");
+                return this.fail(range, "unknown_case", MESSAGES.unknownCase(variantPath, jsonString(name), allCases, suggestions[0]), { suggestions, fixes });
+            }
+            if (op === "==" || op === "!=") {
+                const cases = op === "==" ? [name] : caseSide.caseOf.cases.filter(c => c !== name);
+                return { shape: typed(BooleanType), mult: ONE, proves: [{ kind: "case", path: caseSide.caseOf.path, cases }] };
+            }
+        }
+        const lt = this.collect(left, this.range(leftPath));
+        const rt = this.collect(right, this.range(rightPath));
+        if (lt === undefined || rt === undefined)
+            return { shape: ERROR, mult: ONE };
+        if (lt.type === "Never" || rt.type === "Never")
+            return { shape: typed(BooleanType), mult: ONE };
+        // A whole variant compared with a string.
+        for (const [side, sidePath, other] of [[lt, leftPath, rt], [rt, rightPath, lt]]) {
+            const s = unwrap(nullablePayload(unwrap(side)) ?? side);
+            if (s.type === "Variant" && nullablePayload(s) === undefined && unwrap(other).type === "String") {
+                const text = this.source(sidePath);
+                const range = this.range(sidePath);
+                const fixes = range !== undefined ? [edit("Use .type", range.to, range.to, ".type")] : [];
+                return this.fail(range, "type_mismatch", MESSAGES.wholeVariant(text, describeType(side)), { fixes });
+            }
+        }
+        const reported = this.diagnostics.length;
+        const fits = this.comparable(lt, rt, node, path, env);
+        // A literal that failed to parse as the other side's type has said so.
+        if (this.diagnostics.length > reported)
+            return { shape: ERROR, mult: ONE };
+        if (fits) {
+            // An Integer never equals a Float with a fraction.
+            if ((op === "==" || op === "!=") && unwrap(nullablePayload(unwrap(lt)) ?? lt).type === "Integer" && node.value.right.type === "literal") {
+                const literal = this.literal(node.value.right.value);
+                if (literal.type.type === "Float" && !Number.isInteger(literal.value)) {
+                    return this.fail(this.range(path), "type_mismatch", MESSAGES.neverEqual(op));
+                }
+            }
+            return { shape: typed(BooleanType), mult: ONE };
+        }
+        return this.mismatch(env, this.range(path), "type_mismatch", MESSAGES.compares(op, describeType(lt), describeType(rt)));
+    }
+    /** Whether two types compare: equal, numbers, a value and its option, or a literal read as the other's type. */
+    comparable(a, b, node, path, env) {
+        const ua = unwrap(a);
+        const ub = unwrap(b);
+        if (isTypeEqual(ua, ub))
+            return true;
+        // Numbers compare: the translation widens an Integer it compares with a Float.
+        if (isNumber(ua) && isNumber(ub))
+            return true;
+        if (ua.type === "Null" && canBeNull(ub))
+            return true;
+        if (ub.type === "Null" && canBeNull(ua))
+            return true;
+        const pa = nullablePayload(ua);
+        const pb = nullablePayload(ub);
+        if (pa !== undefined || pb !== undefined)
+            return this.comparable(pa ?? ua, pb ?? ub, node, path, env);
+        if (ua.type === "DateTime" && node.value.right.type === "literal")
+            return this.coerceLiteral(node.value.right, childPath(path, "binary.right"), DateTimeType, env) !== undefined;
+        if (ub.type === "DateTime" && node.value.left.type === "literal")
+            return this.coerceLiteral(node.value.left, childPath(path, "binary.left"), DateTimeType, env) !== undefined;
+        return unify(ua, ub) !== undefined && ua.type === ub.type;
+    }
+    arithmetic(op, left, right, operands, env) {
+        const { leftPath, rightPath } = operands;
+        const lt = this.collect(left, this.range(leftPath));
+        const rt = this.collect(right, this.range(rightPath));
+        if (lt === undefined || rt === undefined)
+            return { shape: ERROR, mult: ONE };
+        // An operand with no value (a recursion not yet known, `empty`) gives none.
+        if (lt.type === "Never" || rt.type === "Never")
+            return { shape: typed(NeverType), mult: ONE };
+        const fail = () => this.mismatch(env, operands.range, "type_mismatch", MESSAGES.arithmetic(op, describeType(lt), describeType(rt)));
+        let a = unwrap(lt);
+        let b = unwrap(rt);
+        // `null` is the identity for `+`.
+        if (op === "+") {
+            if (a.type === "Null")
+                return { shape: typed(b), mult: ONE };
+            if (b.type === "Null")
+                return { shape: typed(a), mult: ONE };
+            const pa = nullablePayload(a);
+            const pb = nullablePayload(b);
+            if (pa !== undefined && pb !== undefined) {
+                const inner = this.arithmetic(op, { shape: typed(pa), mult: ONE }, { shape: typed(pb), mult: ONE }, operands, env);
+                const t = inner.shape.kind === "type" ? orNull(inner.shape.type) : undefined;
+                return t === undefined ? inner : { shape: typed(t), mult: ONE };
+            }
+            if (pa !== undefined)
+                a = unwrap(pa);
+            if (pb !== undefined)
+                b = unwrap(pb);
+        }
+        else if (nullablePayload(a) !== undefined || nullablePayload(b) !== undefined) {
+            if (!env.lenient)
+                return fail();
+            // In a lenient place, an option is null, which raises, or its value, combined as a value is.
+            const pa = nullablePayload(a);
+            const pb = nullablePayload(b);
+            const inner = this.arithmetic(op, { shape: typed(pa ?? a), mult: ONE }, { shape: typed(pb ?? b), mult: ONE }, operands, env);
+            return inner.shape.kind === "error" ? inner : { ...inner, mult: { lo: 0, hi: inner.mult.hi } };
+        }
+        if (isNumber(a) && isNumber(b)) {
+            if (op === "/")
+                return { shape: typed(FloatType), mult: ONE };
+            // jq's remainder of the numbers truncated to integers: a Float operand, which can be NaN, gives a Float.
+            if (op === "%")
+                return { shape: typed(a.type === "Integer" && b.type === "Integer" ? IntegerType : FloatType), mult: ONE };
+            // An Integer with a Float is a Float: the translation widens the Integer.
+            return { shape: typed(a.type === "Float" || b.type === "Float" ? FloatType : IntegerType), mult: ONE };
+        }
+        switch (op) {
+            case "+":
+                if (a.type === "String" && b.type === "String")
+                    return { shape: typed(StringType), mult: ONE };
+                if (a.type === "Array" && b.type === "Array") {
+                    const element = unify(a.value, b.value);
+                    return element === undefined ? fail() : { shape: typed(ArrayType(element)), mult: ONE };
+                }
+                if (a.type === "Struct" && b.type === "Struct")
+                    return { shape: this.mergeStructs(left, right, false, operands.range), mult: ONE };
+                if (a.type === "Dict" && b.type === "Dict") {
+                    const merged = unify(a, b);
+                    return merged === undefined ? fail() : { shape: typed(merged), mult: ONE };
+                }
+                if ((a.type === "Struct" && Object.keys(a.fields).length === 0 && b.type === "Dict") || (b.type === "Struct" && Object.keys(b.fields).length === 0 && a.type === "Dict")) {
+                    return { shape: typed(a.type === "Dict" ? a : b), mult: ONE };
+                }
+                return fail();
+            case "-":
+                if (a.type === "Array" && b.type === "Array" && unify(a.value, b.value) !== undefined)
+                    return { shape: typed(a), mult: ONE };
+                return fail();
+            case "*":
+                if (a.type === "Struct" && b.type === "Struct")
+                    return { shape: this.mergeStructs(left, right, true, operands.range), mult: ONE };
+                // Dicts merge deeply, as jq merges objects: a key both hold has their values merged when both are objects.
+                if (a.type === "Dict" && b.type === "Dict") {
+                    const merged = unify(a, b);
+                    return merged === undefined ? fail() : { shape: typed(merged), mult: ONE };
+                }
+                if ((a.type === "Struct" && Object.keys(a.fields).length === 0 && b.type === "Dict") || (b.type === "Struct" && Object.keys(b.fields).length === 0 && a.type === "Dict")) {
+                    return { shape: typed(a.type === "Dict" ? a : b), mult: ONE };
+                }
+                // A string repeated, the count a number on either side: a negative count gives null.
+                if ((a.type === "String" && isNumber(b)) || (isNumber(a) && b.type === "String"))
+                    return { shape: typed(orNull(StringType)), mult: ONE };
+                return fail();
+            case "/":
+                if (a.type === "String" && b.type === "String")
+                    return { shape: typed(ArrayType(StringType)), mult: ONE };
+                return fail();
+            default:
+                return fail();
+        }
+    }
+    /**
+     * `a + b` or `a * b` on structs: the fields of `a`, then the new fields of
+     * `b`; `b`'s value wins, and `*` merges fields that are structs, or dicts,
+     * in both deeply.
+     */
+    mergeStructs(left, right, deep, range) {
+        let problem = false;
+        const merge = (a, b, aFacts, bFacts) => {
+            const ua = unwrap(a);
+            const ub = unwrap(b);
+            const af = ua.type === "Struct" ? ua.fields : {};
+            const bf = ub.type === "Struct" ? ub.fields : {};
+            const fields = {};
+            const facts = new Map();
+            const aKnown = aFacts?.kind === "fields" ? aFacts.fields : undefined;
+            const bKnown = bFacts?.kind === "fields" ? bFacts.fields : undefined;
+            for (const [name, t] of Object.entries(af)) {
+                fields[name] = t;
+                const f = aKnown?.get(name);
+                if (f !== undefined)
+                    facts.set(name, f);
+            }
+            for (const [name, t] of Object.entries(bf)) {
+                if (deep && name in af && unwrap(af[name]).type === "Struct" && unwrap(t).type === "Struct") {
+                    const inner = merge(af[name], t, aKnown?.get(name), bKnown?.get(name));
+                    fields[name] = inner.type;
+                    if (inner.facts !== undefined)
+                        facts.set(name, inner.facts);
+                    else
+                        facts.delete(name);
+                }
+                else if (deep && name in af && unwrap(af[name]).type === "Dict" && unwrap(t).type === "Dict") {
+                    // Two dicts merge into one holding both's keys: their types must unify.
+                    const inner = unify(unwrap(af[name]), unwrap(t));
+                    if (inner === undefined) {
+                        if (!problem)
+                            this.fail(range, "type_mismatch", MESSAGES.arithmetic("*", describeType(af[name]), describeType(t)));
+                        problem = true;
+                    }
+                    fields[name] = inner ?? t;
+                    facts.delete(name);
+                }
+                else {
+                    fields[name] = t;
+                    const f = bKnown?.get(name);
+                    if (f !== undefined)
+                        facts.set(name, f);
+                    else
+                        facts.delete(name);
+                }
+            }
+            return { type: StructType(fields), facts: facts.size > 0 ? { kind: "fields", fields: facts } : undefined };
+        };
+        const l = left.shape;
+        const r = right.shape;
+        const merged = merge(l.type, r.type, l.facts, r.facts);
+        return problem ? ERROR : typed(merged.type, merged.facts);
+    }
+    // ─── Construction ──────────────────────────────────────────────────────
+    object(node, path, input, env) {
+        // Names build a struct and computed keys a dict (§13.6): an object has one kind of key.
+        const computedKeys = node.value.filter(entry => entry.key.type === "computed").length;
+        if (computedKeys > 0 && computedKeys < node.value.length)
+            return this.fail(this.range(path), "type_mismatch", MESSAGES.mixedKeys());
+        let mult = ONE;
+        const literal = [];
+        const computed = [];
+        let error = false;
+        node.value.forEach((entry, i) => {
+            const valuePath = childPath(path, `object[${i}].value.some`);
+            const key = entry.key;
+            let name;
+            let value;
+            if (key.type === "name")
+                name = key.value;
+            else if (key.type === "variable") {
+                name = key.value;
+                if (entry.value.type === "none")
+                    value = this.variable(key.value, path, env);
+            }
+            else {
+                const keyPath = childPath(path, `object[${i}].key.computed`);
+                const k = this.check(key.value, keyPath, input, env);
+                // `{"\(f)"}` holds the input's value at the key, `.[key]`.
+                const v = entry.value.type === "some"
+                    ? this.check(entry.value.value, valuePath, input, env)
+                    : this.entryAt(input, k, keyPath, env);
+                mult = piped(mult, piped(k.mult, v.mult));
+                if (k.shape.kind === "error" || v.shape.kind === "error")
+                    error = true;
+                computed.push({ key: k, value: v, keyPath });
+                return;
+            }
+            if (value === undefined) {
+                value = entry.value.type === "some"
+                    ? this.check(entry.value.value, valuePath, input, env)
+                    : this.readField(input, name, this.range(path), env, false, path);
+            }
+            if (value.shape.kind === "error")
+                error = true;
+            mult = piped(mult, value.mult);
+            const earlier = literal.findIndex(l => l.name === name);
+            if (earlier !== -1) {
+                this.warn(this.range(path), "duplicate_key", MESSAGES.duplicateKey(jsonString(name)));
+                literal[earlier] = { name, result: value };
+            }
+            else {
+                literal.push({ name, result: value });
+            }
+        });
+        if (error)
+            return { shape: ERROR, mult };
+        if (computed.length > 0) {
+            let keyType = NeverType;
+            let valueType = NeverType;
+            for (const c of computed) {
+                const k = this.collect(c.key, this.range(c.keyPath));
+                const v = this.collect(c.value, this.range(path));
+                if (k === undefined || v === undefined)
+                    return { shape: ERROR, mult };
+                const nk = unify(keyType, k);
+                const nv = unify(valueType, v);
+                if (nk === undefined)
+                    return this.fail(this.range(c.keyPath), "ambiguous_output", MESSAGES.noCommonType(describeType(keyType), describeType(k)));
+                if (nv === undefined)
+                    return this.fail(this.range(path), "ambiguous_output", MESSAGES.noCommonType(describeType(valueType), describeType(v)));
+                keyType = nk;
+                valueType = nv;
+            }
+            if (!isImmutableType(keyType))
+                return this.fail(this.range(computed[0].keyPath), "type_mismatch", MESSAGES.mutableKey(this.source(computed[0].keyPath), describeType(keyType)));
+            return { shape: typed(DictType(keyType, valueType)), mult };
+        }
+        const fields = {};
+        const facts = new Map();
+        for (const l of literal) {
+            const t = this.collect(l.result, this.range(path));
+            if (t === undefined)
+                return { shape: ERROR, mult };
+            fields[l.name] = t;
+            if (l.result.shape.kind === "type" && l.result.shape.facts !== undefined)
+                facts.set(l.name, l.result.shape.facts);
+        }
+        return { shape: typed(StructType(fields), facts.size > 0 ? { kind: "fields", fields: facts } : undefined), mult };
+    }
+    /**
+     * The value at a computed key of the input, as `.[key]` reads it: a dict's
+     * value at the key, or null where it has none; `null`'s is null. A struct's
+     * field needs its name written (§4).
+     */
+    entryAt(input, key, keyPath, env) {
+        if (key.shape.kind === "error")
+            return { shape: ERROR, mult: ONE };
+        const keyType = this.collect(key, this.range(keyPath));
+        if (keyType === undefined)
+            return { shape: ERROR, mult: ONE };
+        const range = this.range(keyPath);
+        return this.mapMembers(input, member => {
+            const u = unwrap(member.type);
+            if (u.type === "Null")
+                return { shape: typed(NullType), mult: ONE };
+            const t = unwrap(nullablePayload(u) ?? u);
+            if (t.type === "Dict") {
+                if (!isTypeEqual(unwrap(keyType), unwrap(t.key))) {
+                    return this.mismatch(env, range, "type_mismatch", MESSAGES.keyType(`{${this.source(keyPath)}}`, describeType(t.key), this.source(keyPath), describeType(keyType)));
+                }
+                const value = orNull(t.value);
+                if (value === undefined)
+                    return this.mismatch(env, range, "ambiguous_output", MESSAGES.noCommonType(describeType(t.value), "Null"));
+                return { shape: typed(value), mult: ONE };
+            }
+            if (t.type === "Struct")
+                return this.mismatch(env, range, "type_mismatch", MESSAGES.structKey(`{${this.source(keyPath)}}`));
+            return this.mismatch(env, range, "not_indexable", MESSAGES.notIndexable(".", describeType(member.type)));
+        });
+    }
+    format(node, path, input, env) {
+        const { name, string } = node.value;
+        const builtin = BUILTINS.get(`@${name}`);
+        if (builtin === undefined) {
+            const suggestions = closest(`@${name}`, [...BUILTINS.keys()].filter(k => k.startsWith("@")));
+            return this.fail(this.range(path), "unknown_function", MESSAGES.unknownFunction(`@${name}`, 0, suggestions[0]), { suggestions });
+        }
+        const status = this.availability(builtin, `@${name}`, path);
+        if (status !== undefined)
+            return status;
+        if (string.type === "some") {
+            let mult = ONE;
+            const inner = string.value;
+            if (inner.type === "string") {
+                inner.value.forEach((part, i) => {
+                    if (part.type === "interpolate") {
+                        const partPath = childPath(childPath(path, "format.string.some"), `string[${i}].interpolate`);
+                        const r = this.check(part.value, partPath, input, env);
+                        mult = piped(mult, r.mult);
+                        // Each interpolated value is formatted, so it must be one the format takes.
+                        if (r.shape.kind !== "error")
+                            builtin.typing(this.context(builtin, `@${name}`, partPath, r, env, [], []));
+                    }
+                });
+            }
+            this.record(childPath(path, "format.string.some"), env, { shape: typed(StringType), mult });
+            return { shape: typed(StringType), mult };
+        }
+        return builtin.typing(this.context(builtin, `@${name}`, path, input, env, [], []));
+    }
+    // ─── Control ───────────────────────────────────────────────────────────
+    /** Adds facts to a result's shape. */
+    narrow(input, proves) {
+        let shape = input.shape;
+        for (const proof of proves) {
+            if (proof.kind === "case")
+                shape = refine(shape, proof.path, proof.cases);
+            else if (proof.path.length === 0)
+                shape = narrowTypes(shape, proof.types);
+        }
+        return { ...input, shape };
+    }
+    conditional(node, path, input, env) {
+        const { branches, otherwise } = node.value;
+        const members = [];
+        let mult;
+        let error = false;
+        let rest = input;
+        let condMult = ONE;
+        branches.forEach((branch, i) => {
+            const condition = this.check(branch.condition, childPath(path, `if.branches[${i}].condition`), rest, env);
+            // A condition after one that is always true never runs.
+            if (rest !== NOTHING)
+                condMult = piped(condMult, condition.mult);
+            // A literal condition decides the branch, as the translation does: the branch it rules out never runs.
+            const truth = this.truthOf(branch.condition);
+            const thenInput = truth === false ? NOTHING : condition.proves !== undefined ? this.narrow(rest, condition.proves) : rest;
+            const result = this.check(branch.then, childPath(path, `if.branches[${i}].then`), thenInput, env);
+            if (condition.shape.kind === "error" || result.shape.kind === "error")
+                error = true;
+            members.push(...membersOf(result.shape));
+            mult = mult === undefined ? result.mult : either(mult, result.mult);
+            // The next branch runs when this condition is false.
+            if (condition.proves !== undefined && condition.proves.length === 1) {
+                const proof = condition.proves[0];
+                if (proof.kind === "case") {
+                    const variantShape = this.shapeAt(rest.shape, proof.path);
+                    if (variantShape !== undefined) {
+                        const others = casesOf(variantShape.type, variantShape.facts).filter(c => !proof.cases.includes(c));
+                        rest = this.narrow(rest, [{ kind: "case", path: proof.path, cases: others }]);
+                    }
+                }
+                else {
+                    rest = this.narrow(rest, [{ kind: "type", path: proof.path, types: JQ_TYPE_NAMES.filter(name => !proof.types.includes(name)) }]);
+                }
+            }
+            if (truth === true)
+                rest = NOTHING;
+        });
+        const other = otherwise.type === "some"
+            ? this.check(otherwise.value, childPath(path, "if.otherwise.some"), rest, env)
+            : rest === NOTHING ? DEAD : { shape: rest.shape, mult: ONE };
+        if (other.shape.kind === "error" || error)
+            return { shape: ERROR, mult: ONE };
+        members.push(...membersOf(other.shape));
+        return { shape: union(members), mult: piped(condMult, either(mult ?? ONE, other.mult)) };
+    }
+    /** A literal's truth to jq: `false` and `null` are false, any other literal true; `undefined` for any other node. */
+    truthOf(node) {
+        if (node.type !== "literal")
+            return undefined;
+        const { type, value } = this.literal(node.value);
+        if (type.type === "Boolean")
+            return value;
+        return type.type !== "Null";
+    }
+    /** The shape at a field path, for narrowing's else branch. */
+    shapeAt(shape, path) {
+        if (shape.kind !== "type")
+            return undefined;
+        let current = shape;
+        for (const name of path) {
+            const t = unwrap(current.type);
+            if (t.type !== "Struct")
+                return undefined;
+            const fields = t.fields;
+            if (!(name in fields))
+                return undefined;
+            current = typed(fields[name], current.facts?.kind === "fields" ? current.facts.fields.get(name) : undefined);
+        }
+        return current;
+    }
+    tryCatch(node, path, input, env) {
+        const body = this.check(node.value.body, childPath(path, "try.body"), input, { ...env, lenient: true });
+        if (node.value.catch.type === "none")
+            return { shape: body.shape, mult: { lo: 0, hi: body.mult.hi } };
+        // Error values are strings: `error(v)` raises `v`'s East text (§13.14).
+        const handler = this.check(node.value.catch.value, childPath(path, "try.catch.some"), { shape: typed(StringType), mult: ONE }, env);
+        if (body.shape.kind === "error" || handler.shape.kind === "error")
+            return { shape: ERROR, mult: ONE };
+        return { shape: union([...membersOf(body.shape), ...membersOf(handler.shape)]), mult: { lo: 0, hi: Math.max(body.mult.hi, handler.mult.hi) } };
+    }
+    fold(node, path, input, env) {
+        const kind = node.type;
+        const source = this.check(node.value.source, childPath(path, `${kind}.source`), input, env);
+        const init = this.check(node.value.init, childPath(path, `${kind}.init`), input, env);
+        if (source.shape.kind === "error" || init.shape.kind === "error")
+            return { shape: ERROR, mult: ONE };
+        const element = this.collect(source, this.range(childPath(path, `${kind}.source`)));
+        let acc = this.collect(init, this.range(childPath(path, `${kind}.init`)));
+        if (element === undefined || acc === undefined)
+            return { shape: ERROR, mult: ONE };
+        const bound = this.destructure(node.value.pattern, childPath(path, `${kind}.pattern`), { shape: typed(element), mult: ONE }, env);
+        if (bound === undefined)
+            return { shape: ERROR, mult: ONE };
+        const inner = { ...env, vars: new Map([...env.vars, ...bound]) };
+        let update;
+        const first = acc;
+        for (let round = 0; round < 8; round++) {
+            const errors = this.diagnostics.length;
+            update = this.check(node.value.update, childPath(path, `${kind}.update`), { shape: typed(acc), mult: ONE }, inner);
+            if (update.shape.kind === "error")
+                return { shape: ERROR, mult: ONE };
+            const next = this.collect(update, this.range(childPath(path, `${kind}.update`)));
+            if (next === undefined)
+                return { shape: ERROR, mult: ONE };
+            const merged = unify(acc, next);
+            if (merged === undefined) {
+                return this.fail(this.range(path), "cannot_infer", MESSAGES.accumulator(kind, describeType(first), describeType(next)));
+            }
+            if (isTypeEqual(merged, acc))
+                break;
+            // A round that changed the accumulator's type is checked again; drop its problems.
+            this.diagnostics.length = errors;
+            acc = merged;
+            if (round === 7)
+                return this.fail(this.range(path), "cannot_infer", MESSAGES.accumulator(kind, describeType(first), describeType(merged)));
+        }
+        // The accumulator's settled type, for the translator.
+        this.record(`${path}#acc`, env, { shape: typed(acc), mult: ONE });
+        if (kind === "reduce")
+            return { shape: typed(acc), mult: ONE };
+        const extract = node.value.extract;
+        if (extract.type === "none")
+            return { shape: typed(acc), mult: MANY };
+        const out = this.check(extract.value, childPath(path, "foreach.extract.some"), { shape: typed(acc), mult: ONE }, inner);
+        return { shape: out.shape, mult: MANY };
+    }
+    bind(node, path, input, env) {
+        const source = this.check(node.value.source, childPath(path, "bind.source"), input, env);
+        if (source.shape.kind === "error")
+            return { shape: ERROR, mult: ONE };
+        const alternatives = node.value.patterns;
+        const bindings = [];
+        alternatives.forEach((pattern, i) => {
+            const errors = this.diagnostics.length;
+            const bound = this.destructure(pattern, childPath(path, `bind.patterns[${i}]`), source, env);
+            // With ?//, a pattern that cannot match is skipped at run time.
+            if (bound === undefined && alternatives.length > 1 && i < alternatives.length - 1)
+                this.diagnostics.length = errors;
+            if (bound !== undefined)
+                bindings.push(bound);
+        });
+        if (bindings.length === 0)
+            return { shape: ERROR, mult: ONE };
+        const names = new Set(bindings.flatMap(b => [...b.keys()]));
+        const vars = new Map(env.vars);
+        for (const name of names) {
+            let type = NeverType;
+            let facts;
+            for (const b of bindings) {
+                const r = b.get(name);
+                const t = r === undefined ? NullType : (r.shape.kind === "type" ? r.shape.type : unifyShape(r.shape) ?? NeverType);
+                type = unify(type, t) ?? type;
+                if (bindings.length === 1 && r?.shape.kind === "type")
+                    facts = r.shape.facts;
+            }
+            vars.set(name, { shape: typed(type, facts), mult: ONE });
+        }
+        const body = this.check(node.value.body, childPath(path, "bind.body"), input, { ...env, vars });
+        return { shape: body.shape, mult: piped(source.mult, body.mult), stream: body.stream };
+    }
+    /** The variables a pattern binds from a source, or `undefined` after a reported problem. */
+    destructure(pattern, path, source, env) {
+        const out = new Map();
+        const visit = (p, at, value) => {
+            if (value.shape.kind === "error")
+                return false;
+            switch (p.type) {
+                case "variable":
+                    out.set(p.value, value);
+                    return true;
+                case "array": {
+                    return p.value.every((item, i) => {
+                        const element = this.mapMembers(value, member => {
+                            const t = unwrap(member.type);
+                            const container = t.type === "Array" ? t.value : t.type === "Vector" ? t.element : undefined;
+                            if (container === undefined) {
+                                if (t.type === "Null")
+                                    return { shape: typed(NullType), mult: ONE };
+                                return this.fail(this.range(at), "type_mismatch", MESSAGES.input("an array pattern", "an array", describeType(member.type)));
+                            }
+                            const e = orNull(container);
+                            return e === undefined ? this.fail(this.range(at), "ambiguous_output", MESSAGES.noCommonType(describeType(container), "Null")) : { shape: typed(e), mult: ONE };
+                        });
+                        return visit(item, childPath(at, `array[${i}]`), element);
+                    });
+                }
+                case "object": {
+                    return p.value.every((entry, i) => {
+                        const read = this.readField(value, entry.key, this.range(at), env, false, at);
+                        if (read.shape.kind === "error")
+                            return false;
+                        if (entry.value.type === "none") {
+                            out.set(entry.key, read);
+                            return true;
+                        }
+                        return visit(entry.value.value, childPath(at, `object[${i}].value.some`), read);
+                    });
+                }
+            }
+        };
+        return visit(pattern, path, { shape: source.shape, mult: ONE }) ? out : undefined;
+    }
+    // ─── Calls ─────────────────────────────────────────────────────────────
+    call(node, path, input, env) {
+        const { args, name } = node.value;
+        const binding = env.defs.get(`${name}/${args.length}`);
+        if (binding !== undefined) {
+            if (binding.kind === "param") {
+                const instance = `${env.instance}>${path}`;
+                return this.check(binding.arg, binding.path, input, { ...binding.env, instance, lenient: env.lenient });
+            }
+            return this.callDef(binding, node, path, input, env);
+        }
+        const builtin = BUILTINS.get(name);
+        // A builtin a query may not use says so, whatever it is given.
+        if (builtin !== undefined && builtin.status !== "supported" && builtin.status !== "tooling")
+            return this.availability(builtin, name, path);
+        if (builtin === undefined || !builtin.arities.includes(args.length)) {
+            const defined = [...env.defs.keys()].filter(k => k.startsWith(`${name}/`)).map(k => Number(k.slice(name.length + 1)));
+            const arities = builtin?.arities ?? defined;
+            if (arities.length > 0)
+                return this.fail(this.range(path), "arity", MESSAGES.arity(name, [...arities].sort(), args.length));
+            const candidates = [...new Set([...[...env.defs.keys()].map(k => k.split("/")[0]), ...[...BUILTINS.keys()].filter(k => !k.startsWith("@"))])];
+            const suggestions = closest(name, candidates);
+            return this.fail(this.range(path), "unknown_function", MESSAGES.unknownFunction(name, args.length, suggestions[0]), { suggestions });
+        }
+        const unavailable = this.availability(builtin, name, path);
+        if (unavailable !== undefined)
+            return unavailable;
+        const argPaths = args.map((_, i) => childPath(path, `call.args[${i}]`));
+        // In a lenient place, an option is null or its value, each checked apart: jq
+        // raises for a null the builtin cannot take, and computes with a value.
+        const opened = env.lenient ? openOptions(input.shape) : undefined;
+        if (opened !== undefined) {
+            // Whether the builtin takes null, from its typing on null alone; what that reports is reported again below.
+            const reported = this.diagnostics.length;
+            const refused = this.refused;
+            builtin.typing(this.context(builtin, name, path, { ...input, shape: typed(NullType), partial: undefined }, env, args, argPaths));
+            this.diagnostics.length = reported;
+            this.opened.set(`${env.instance}|${path}`, { nullRaises: this.refused > refused });
+        }
+        const given = opened === undefined ? input : { ...input, shape: opened, partial: undefined };
+        return builtin.typing(this.context(builtin, name, path, given, env, args, argPaths));
+    }
+    /** A builtin a query may not call: its diagnostic. */
+    availability(builtin, name, path) {
+        switch (builtin.status) {
+            case "supported": return undefined;
+            case "excluded": return this.fail(this.range(path), "unsupported", MESSAGES.excluded(name));
+            case "unavailable": return this.fail(this.range(path), "unsupported", MESSAGES.unavailable(name, builtin.reason ?? ""));
+            case "not_yet": return this.fail(this.range(path), "unsupported", MESSAGES.notYet(name));
+            case "tooling": return this.options.tooling === true ? undefined : this.fail(this.range(path), "unsupported", MESSAGES.tooling(name));
+        }
+    }
+    callDef(binding, node, path, input, env) {
+        const def = binding.node.value;
+        const closure = binding.env();
+        const vars = new Map(closure.vars);
+        const defs = new Map(closure.defs);
+        let mult = ONE;
+        const signature = [binding.path, input.shape.kind === "type" ? printType(input.shape.type) : "?"];
+        let filters = false;
+        def.params.forEach((param, i) => {
+            const argPath = childPath(path, `call.args[${i}]`);
+            if (param.startsWith("$")) {
+                const value = this.check(node.value.args[i], argPath, input, env);
+                mult = piped(mult, value.mult);
+                const t = this.collect(value, this.range(argPath));
+                const shape = t === undefined ? ERROR : typed(t);
+                vars.set(param.slice(1), { shape, mult: ONE });
+                defs.set(`${param.slice(1)}/0`, { kind: "param", arg: variant("variable", param.slice(1)), path: argPath, env: { ...closure, vars } });
+                signature.push(t === undefined ? "?" : printType(t));
+            }
+            else {
+                filters = true;
+                defs.set(`${param}/0`, { kind: "param", arg: node.value.args[i], path: argPath, env });
+            }
+        });
+        const key = signature.join("|");
+        const active = this.active.get(key);
+        if (active !== undefined) {
+            // A recursive call: its output so far.
+            if (active.filters)
+                return this.fail(this.range(path), "unsupported", MESSAGES.recursiveFilter(def.name));
+            active.recursed = true;
+            return active.result;
+        }
+        const instance = `${env.instance}>${path}`;
+        const bodyEnv = { vars, defs, labels: closure.labels, instance, lenient: env.lenient };
+        // The recursion's outputs so far: none known yet, as `lo: 1, hi: 0` (the
+        // identity of `either`), so the fixpoint can find a lower bound of one.
+        const state = { result: { shape: typed(NeverType), mult: { lo: 1, hi: 0 } }, recursed: false, filters };
+        this.active.set(key, state);
+        try {
+            for (let round = 0; round < 8; round++) {
+                const errors = this.diagnostics.length;
+                state.recursed = false;
+                const result = this.check(def.body, childPath(binding.path, "def.body"), input, bodyEnv);
+                if (result.shape.kind === "error" || !state.recursed)
+                    return { ...result, mult: piped(mult, result.mult) };
+                const before = unifyShape(state.result.shape);
+                const after = unifyShape(result.shape);
+                const merged = before === undefined || after === undefined ? undefined : unify(before, after);
+                if (merged === undefined)
+                    return this.fail(this.range(path), "cannot_infer", MESSAGES.recursion(def.name));
+                const next = { lo: state.result.mult.lo === 1 && result.mult.lo === 1 ? 1 : 0, hi: Math.max(state.result.mult.hi, result.mult.hi) };
+                if (isTypeEqual(merged, before) && next.lo === state.result.mult.lo && next.hi === state.result.mult.hi) {
+                    return { shape: result.shape, mult: piped(mult, result.mult) };
+                }
+                // A round that changed what the recursion gives is checked again; drop its problems.
+                this.diagnostics.length = errors;
+                state.result = { shape: typed(merged), mult: next };
+            }
+            return this.fail(this.range(path), "cannot_infer", MESSAGES.recursion(def.name));
+        }
+        finally {
+            this.active.delete(key);
+        }
+    }
+    /** The context a builtin types a call in. */
+    context(builtin, name, path, input, env, args, argPaths) {
+        return {
+            name,
+            path,
+            input,
+            args,
+            argPaths,
+            range: this.range(path),
+            argRange: (i) => this.range(argPaths[i]),
+            arg: (i, argInput) => this.check(args[i], argPaths[i], argInput ?? { ...input, access: undefined, stream: undefined }, env),
+            literal: (i) => {
+                const arg = args[i];
+                return arg?.type === "literal" ? this.literal(arg.value) : undefined;
+            },
+            literalOf: (node) => this.literal(node.value),
+            coerceArg: (i, wanted) => {
+                const arg = args[i];
+                return arg?.type === "literal" ? this.coerceLiteral(arg, argPaths[i], unwrap(wanted), env) : undefined;
+            },
+            coerceArgElements: (i, wanted) => {
+                const arg = args[i];
+                return arg === undefined ? undefined : this.coerceArrayLiteral(arg, argPaths[i], unwrap(wanted), env);
+            },
+            problems: () => this.diagnostics.length,
+            fail: (code, message, options) => this.fail(options?.arg !== undefined ? this.range(argPaths[options.arg]) : this.range(path), code, message, options),
+            mismatch: (code, message, arg, fixes) => this.mismatch(env, arg !== undefined ? this.range(argPaths[arg]) : this.range(path), code, message, { fixes: fixes ?? [] }),
+            skipNulls: () => {
+                const range = this.range(path);
+                return range !== undefined && isPipePosition(path) ? edit("Skip nulls", range.from, range.from, "values | ") : undefined;
+            },
+            warn: (code, message, fixes) => this.warn(this.range(path), code, message, fixes),
+            source: (i) => i === undefined ? this.source(path) : this.source(argPaths[i]),
+            collect: (result, arg) => this.collect(result, arg !== undefined ? this.range(argPaths[arg]) : this.range(path)),
+            refuseRoot: () => this.refuseRoot(input, path, env),
+            narrow: (result, proves) => this.narrow(result, proves),
+            narrowFirst: (type) => this.narrowFirst(env, this.range(path), type, input.partial),
+            onElement: (type) => this.arrayOnElement(env, path, name, input.stream, type),
+            text: this.text,
+            rangeAt: (at) => this.range(at),
+            resultAt: (at) => this.records.get(`${env.instance}|${at}`),
+            builtin,
+        };
+    }
+    // ─── Assignment ────────────────────────────────────────────────────────
+    update(node, path, input, env) {
+        const { op } = node.value;
+        const pathPath = childPath(path, "update.path");
+        const valuePath = childPath(path, "update.value");
+        if (input.shape.kind === "error")
+            return { shape: ERROR, mult: ONE };
+        // An update gives the whole value it updates, which a root never is.
+        if (this.refuseRoot(input, path, env))
+            return { shape: ERROR, mult: ONE };
+        // The value of `=` and of the arithmetic updates is evaluated on `.`.
+        let value;
+        if (op !== "|=") {
+            value = this.check(node.value.value, valuePath, input, env);
+            if (value.shape.kind === "error")
+                return { shape: ERROR, mult: ONE };
+        }
+        // Each position's new value, and how many it has: `|=` keeps its update's
+        // first output, and one with none deletes the position.
+        const at = (current) => {
+            if (op === "|=") {
+                const r = this.check(node.value.value, valuePath, current, env);
+                return { shape: r.shape, mult: { lo: r.mult.lo, hi: r.mult.hi === 0 ? 0 : 1 } };
+            }
+            if (op === "=")
+                return { shape: value.shape, mult: ONE };
+            const operator = op.slice(0, -1);
+            if (operator === "//") {
+                if (current.shape.kind === "type" && !canBeNull(unwrap(current.shape.type)) && unwrap(current.shape.type).type !== "Boolean") {
+                    this.warn(this.range(pathPath), "never_missing", MESSAGES.neverMissing(this.source(pathPath), describeType(current.shape.type)));
+                }
+                const kept = this.mapMembers(current, m => {
+                    const t = unwrap(m.type);
+                    const payload = nullablePayload(t);
+                    if (t.type === "Null")
+                        return { shape: typed(NeverType), mult: ZERO };
+                    return { shape: typed(payload ?? m.type), mult: ONE };
+                });
+                return { shape: union([...membersOf(kept.shape), ...membersOf(value.shape)]), mult: ONE };
+            }
+            return this.arithmetic(operator, current, value, { leftPath: pathPath, rightPath: valuePath, range: this.range(path) }, env);
+        };
+        const assigned = this.assign(input.shape, node.value.path, pathPath, at, env);
+        if (assigned === undefined)
+            return { shape: ERROR, mult: ONE };
+        const shape = this.wholeShape(assigned, path);
+        return { shape, mult: shape.kind === "error" || value === undefined ? ONE : value.mult };
+    }
+    /** `.` after an update: `null` where the update deleted it, as jq gives it. */
+    wholeShape(assigned, path) {
+        if (assigned.mult.hi === 0)
+            return typed(NullType);
+        if (assigned.mult.lo === 1)
+            return assigned.shape;
+        const type = unifyShape(assigned.shape);
+        const option = type === undefined ? undefined : orNull(type);
+        if (option === undefined)
+            return this.fail(this.range(path), "ambiguous_output", MESSAGES.noCommonType(describeType(type ?? NeverType), "Null")).shape;
+        return typed(option);
+    }
+    /**
+     * The shape of `.` after assigning at the positions a path expression
+     * names, each position's new value given by `at`.
+     *
+     * @returns the new shape, with its multiplicity: less than one where the
+     *   update deletes `.` itself; or `undefined` after a reported problem
+     */
+    assign(shape, pathNode, path, at, env) {
+        if (shape.kind === "error")
+            return undefined;
+        const members = [];
+        let mult;
+        for (const member of membersOf(shape)) {
+            const next = this.assignMember(member.shape, pathNode, path, at, env);
+            if (next === undefined)
+                return undefined;
+            members.push({ shape: next.shape, case: member.case });
+            mult = mult === undefined ? next.mult : either(mult, next.mult);
+        }
+        return { shape: union(members), mult: mult ?? ONE };
+    }
+    assignMember(shape, pathNode, path, at, env) {
+        const range = this.range(path);
+        switch (pathNode.type) {
+            case "identity": {
+                const r = at({ shape, mult: ONE });
+                const t = this.collect(r, range);
+                return t === undefined ? undefined : { shape: typed(t), mult: r.mult };
+            }
+            case "pipe": {
+                const { left, right } = pathNode.value;
+                return this.assignMember(shape, left, childPath(path, "pipe.left"), current => this.assign(current.shape, right, childPath(path, "pipe.right"), at, env) ?? { shape: ERROR, mult: ONE }, env);
+            }
+            case "field":
+            case "index":
+            case "iterate":
+            case "slice": {
+                // An index's key and a slice's bounds are taken on the step's own input, as jq takes them.
+                const keys = this.stepKeys(pathNode, path, shape, env);
+                if (keys === undefined)
+                    return undefined;
+                return this.assignMember(shape, pathNode.value.target, childPath(path, `${pathNode.type}.target`), current => {
+                    const inner = this.assignStep(current, pathNode, path, at, env, keys);
+                    return inner === undefined ? { shape: ERROR, mult: ONE } : { shape: inner, mult: ONE };
+                }, env);
+            }
+            case "descend":
+                return this.assignWalk(shape, undefined, path, at, env);
+            case "call": {
+                const { args, name } = pathNode.value;
+                if (name === "select" && args.length === 1) {
+                    const condition = this.check(args[0], childPath(path, "call.args[0]"), { shape, mult: ONE }, env);
+                    if (condition.shape.kind === "error")
+                        return undefined;
+                    const kept = condition.proves !== undefined ? this.narrow({ shape, mult: ONE }, condition.proves) : { shape, mult: ONE };
+                    return this.selected(shape, { shape: kept.shape, mult: { lo: 0, hi: condition.mult.hi === 0 ? 0 : 1 } }, at, path);
+                }
+                if (UPDATE_SELECTORS.has(name) && args.length === 0) {
+                    const builtin = BUILTINS.get(name);
+                    return this.selected(shape, builtin.typing(this.context(builtin, name, path, { shape, mult: ONE }, env, [], [])), at, path);
+                }
+                if (name === "empty" && args.length === 0)
+                    return { shape, mult: ONE };
+                if (name === "recurse" && args.length <= 1) {
+                    return this.assignWalk(shape, args.length === 1 ? { node: args[0], path: childPath(path, "call.args[0]") } : undefined, path, at, env);
+                }
+                this.fail(range, "unsupported", MESSAGES.unavailable(`assigning to ${name}(…)`, UPDATE_PATHS));
+                return undefined;
+            }
+            default:
+                this.fail(range, "unsupported", MESSAGES.unavailable(`assigning to ${this.source(path)}`, UPDATE_PATHS));
+                return undefined;
+        }
+    }
+    /**
+     * An update of a value where a filter keeps it (`select(f)`, `numbers`):
+     * the value as the filter keeps it is updated; where it is not kept, it
+     * stays.
+     *
+     * @param shape - the value
+     * @param kept - what the filter gives on it, narrowed
+     */
+    selected(shape, kept, at, path) {
+        if (kept.shape.kind === "error")
+            return undefined;
+        if (kept.mult.hi === 0 || (kept.shape.kind === "type" && kept.shape.type.type === "Never"))
+            return { shape, mult: ONE };
+        const replaced = at({ shape: kept.shape, mult: ONE });
+        const t = this.collect(replaced, this.range(path));
+        if (t === undefined)
+            return undefined;
+        const merged = sameType(shape.type, t) ? shape.type : unify(shape.type, t);
+        if (merged === undefined) {
+            this.fail(this.range(path), "ambiguous_output", MESSAGES.noCommonType(describeType(shape.type), describeType(t)));
+            return undefined;
+        }
+        // Kept every time, it has the update's values; else it keeps its own where it is not kept.
+        const mult = kept.mult.lo === 1 ? replaced.mult : { lo: replaced.mult.lo, hi: 1 };
+        return { shape: typed(merged), mult };
+    }
+    /**
+     * An index's key type, checked on the step's own input, or a slice's bounds:
+     * each gives one value.
+     *
+     * @returns the key's type (none for a field, `.[]` or a slice), or
+     *   `undefined` after a reported problem
+     */
+    stepKeys(step, path, input, env) {
+        const one = (node, at) => {
+            const r = this.check(node, at, { shape: input, mult: ONE }, env);
+            if (r.shape.kind === "error")
+                return undefined;
+            if (r.mult.lo !== 1 || r.mult.hi !== 1) {
+                this.fail(this.range(at), "unsupported", MESSAGES.updateKey(this.source(at)));
+                return undefined;
+            }
+            return this.collect(r, this.range(at));
+        };
+        if (step.type === "index") {
+            if (step.value.index.type === "literal" && this.literal(step.value.index.value).type.type === "String")
+                return { key: StringType };
+            const key = one(step.value.index, childPath(path, "index.index"));
+            return key === undefined ? undefined : { key };
+        }
+        if (step.type === "slice") {
+            for (const [bound, s] of [[step.value.from, "slice.from.some"], [step.value.to, "slice.to.some"]]) {
+                if (bound.type !== "some")
+                    continue;
+                const at = childPath(path, s);
+                const t = one(bound.value, at);
+                if (t === undefined)
+                    return undefined;
+                if (!this.keyFits(t, IntegerType, bound.value, at, env) && !canBeNull(unwrap(t))) {
+                    this.fail(this.range(at), "type_mismatch", MESSAGES.sliceBound(describeType(t)));
+                    return undefined;
+                }
+            }
+        }
+        return { key: undefined };
+    }
+    /**
+     * One step of an update's path on a value: `.name`, `.[k]`, `.[a:b]` or
+     * `.[]`. A step with `?` names no position on a value it cannot take.
+     */
+    assignStep(current, step, path, at, env, keys) {
+        const failed = { shape: ERROR, mult: ONE };
+        const assigned = this.assign(current.shape, IDENTITY, path, whole => {
+            const member = whole.shape;
+            const t = unwrap(member.type);
+            const unchanged = { shape: member, mult: ONE };
+            const done = (type) => ({ shape: typed(rewrap(member.type, type)), mult: ONE });
+            // A position's new value, and how many it has.
+            const replace = (old, facts) => {
+                const r = at({ shape: typed(old, facts), mult: ONE });
+                const type = this.collect(r, this.range(path));
+                return type === undefined ? undefined : { type, mult: r.mult };
+            };
+            const optional = step.value.optional;
+            const literalName = step.type === "index" && step.value.index.type === "literal" && t.type !== "Dict" ? this.literal(step.value.index.value) : undefined;
+            const name = step.type === "field" ? step.value.name : literalName?.type.type === "String" ? literalName.value : undefined;
+            if (name !== undefined) {
+                const payload = nullablePayload(t);
+                if (payload !== undefined) {
+                    // An option: `null` is updated as null is, and a value as it is; the two must share a type.
+                    const present = member.facts?.kind === "present" ? member.facts.payload : undefined;
+                    const whenNull = this.assignStep({ shape: typed(NullType), mult: ONE }, step, path, at, env, keys);
+                    const whenSome = this.assignStep({ shape: typed(payload, present), mult: ONE }, step, path, at, env, keys);
+                    const a = whenNull === undefined ? undefined : unifyShape(whenNull);
+                    const b = whenSome === undefined ? undefined : unifyShape(whenSome);
+                    if (a === undefined || b === undefined)
+                        return failed;
+                    const merged = unify(a, b);
+                    if (merged === undefined)
+                        return this.fail(this.range(path), "ambiguous_output", MESSAGES.noCommonType(describeType(a), describeType(b)));
+                    return done(merged);
+                }
+                if (t.type === "Struct") {
+                    const fields = { ...t.fields };
+                    const facts = member.facts?.kind === "fields" ? member.facts.fields.get(name) : undefined;
+                    const next = replace(name in fields ? fields[name] : NullType, facts);
+                    if (next === undefined)
+                        return failed;
+                    // An update that never gives a value deletes the field, as jq deletes the key.
+                    if (next.mult.hi === 0)
+                        delete fields[name];
+                    else
+                        fields[name] = next.type;
+                    return done(StructType(fields));
+                }
+                if (t.type === "Null") {
+                    const next = replace(NullType, undefined);
+                    if (next === undefined)
+                        return failed;
+                    return next.mult.hi === 0 ? unchanged : done(StructType({ [name]: next.type }));
+                }
+                if (t.type === "Dict" && unwrap(t.key).type === "String") {
+                    const old = orNull(t.value) ?? t.value;
+                    const next = replace(old, undefined);
+                    if (next === undefined)
+                        return failed;
+                    const merged = unify(t.value, next.type);
+                    if (merged === undefined)
+                        return this.fail(this.range(path), "ambiguous_output", MESSAGES.noCommonType(describeType(t.value), describeType(next.type)));
+                    return done(DictType(t.key, merged));
+                }
+                // A variant's payload, in each case it can hold here; its case's name is its type, not a value to update.
+                if (t.type === "Variant" && nullablePayload(t) === undefined && (name === "value" || name === "type")) {
+                    if (name === "type")
+                        return this.fail(this.range(path), "unsupported", MESSAGES.unavailable(`assigning to ${this.source(path)}`, "a variant's case is its type; build the new value instead"));
+                    const cases = casesOf(t, member.facts);
+                    const payloads = { ...t.cases };
+                    const facts = member.facts?.kind === "cases" && cases.length === 1 ? member.facts.payload : undefined;
+                    for (const c of cases) {
+                        const next = replace(payloads[c], facts);
+                        if (next === undefined)
+                            return failed;
+                        // A payload cannot be deleted: with no value, it keeps its type, and the update raises there.
+                        if (next.mult.hi !== 0)
+                            payloads[c] = next.type;
+                    }
+                    this.updatedCases.set(`${env.instance}|${path}|${printType(t)}`, cases);
+                    return done(VariantType(payloads));
+                }
+                if (optional)
+                    return unchanged;
+                return this.mismatch(env, this.range(path), "type_mismatch", MESSAGES.notAField(`.${name}`, describeType(member.type)));
+            }
+            if (step.type === "index") {
+                const keyPath = childPath(path, "index.index");
+                const keyType = keys.key;
+                if (t.type === "Array") {
+                    if (!this.keyFits(keyType, IntegerType, step.value.index, keyPath, env)) {
+                        return this.mismatch(env, this.range(keyPath), "type_mismatch", MESSAGES.keyType(".[…]", "Integer", this.source(keyPath), describeType(keyType)));
+                    }
+                    // The element itself: an index past the end is an error, where jq pads with nulls (§13.23).
+                    const next = replace(t.value, member.facts?.kind === "elements" ? member.facts.element : undefined);
+                    if (next === undefined)
+                        return failed;
+                    const merged = unify(t.value, next.type);
+                    if (merged === undefined)
+                        return this.fail(this.range(path), "ambiguous_output", MESSAGES.noCommonType(describeType(t.value), describeType(next.type)));
+                    return done(ArrayType(merged));
+                }
+                if (t.type === "Dict" || (t.type === "Struct" && Object.keys(t.fields).length === 0) || t.type === "Null") {
+                    const dictKey = t.type === "Dict" ? t.key : keyType;
+                    const dictValue = t.type === "Dict" ? t.value : NeverType;
+                    if (!this.keyFits(keyType, dictKey, step.value.index, keyPath, env)) {
+                        return this.mismatch(env, this.range(keyPath), "type_mismatch", MESSAGES.keyType(".[…]", describeType(dictKey), this.source(keyPath), describeType(keyType)));
+                    }
+                    if (!isImmutableType(dictKey))
+                        return this.fail(this.range(keyPath), "type_mismatch", MESSAGES.mutableKey(this.source(keyPath), describeType(dictKey)));
+                    const next = replace(dictValue.type === "Never" ? NullType : (orNull(dictValue) ?? dictValue), undefined);
+                    if (next === undefined)
+                        return failed;
+                    const merged = unify(dictValue, next.type);
+                    if (merged === undefined)
+                        return this.fail(this.range(path), "ambiguous_output", MESSAGES.noCommonType(describeType(dictValue), describeType(next.type)));
+                    return done(DictType(dictKey, merged));
+                }
+                if (optional)
+                    return unchanged;
+                return this.mismatch(env, this.range(path), "not_indexable", MESSAGES.notIndexable(this.source(childPath(path, "index.target")) || ".", describeType(member.type)));
+            }
+            if (step.type === "slice") {
+                // The slice's new value is an array, spliced in its place; none deletes the slice.
+                if (t.type === "Array" || t.type === "Null") {
+                    const next = t.type === "Array" ? replace(t, member.facts) : replace(NullType, undefined);
+                    if (next === undefined)
+                        return failed;
+                    if (next.mult.hi === 0)
+                        return unchanged;
+                    const given = unwrap(next.type);
+                    if (given.type !== "Array")
+                        return this.mismatch(env, this.range(path), "type_mismatch", MESSAGES.sliceUpdate(this.source(path), describeType(next.type)));
+                    // `null`'s slice is null, so the array the update gives is the value, or null where it gives none.
+                    if (t.type === "Null")
+                        return done(next.mult.lo === 1 ? next.type : orNull(next.type));
+                    const merged = unify(t.value, given.value);
+                    if (merged === undefined)
+                        return this.fail(this.range(path), "ambiguous_output", MESSAGES.noCommonType(describeType(t), describeType(next.type)));
+                    return done(ArrayType(merged));
+                }
+                if (optional)
+                    return unchanged;
+                if (t.type === "String")
+                    return this.mismatch(env, this.range(path), "type_mismatch", MESSAGES.stringSlice(this.source(path)));
+                return this.mismatch(env, this.range(path), "not_indexable", MESSAGES.notIndexable(this.source(childPath(path, "slice.target")) || ".", describeType(member.type)));
+            }
+            // `.[]`: every element; an element with no value is deleted.
+            switch (t.type) {
+                case "Array": {
+                    const next = replace(t.value, member.facts?.kind === "elements" ? member.facts.element : undefined);
+                    return next === undefined ? failed : done(ArrayType(next.type));
+                }
+                case "Dict": {
+                    const next = replace(t.value, member.facts?.kind === "values" ? member.facts.value : undefined);
+                    return next === undefined ? failed : done(DictType(t.key, next.type));
+                }
+                case "Struct": {
+                    const facts = member.facts?.kind === "fields" ? member.facts.fields : undefined;
+                    const fields = {};
+                    for (const [name, f] of Object.entries(t.fields)) {
+                        const next = replace(f, facts?.get(name));
+                        if (next === undefined)
+                            return failed;
+                        if (next.mult.hi !== 0)
+                            fields[name] = next.type;
+                    }
+                    return done(StructType(fields));
+                }
+                default:
+                    if (optional)
+                        return unchanged;
+                    return this.mismatch(env, this.range(path), "not_iterable", MESSAGES.notIterable(".[]", describeType(member.type)));
+            }
+        }, env);
+        return assigned?.shape;
+    }
+    /**
+     * `..`, `recurse` or `recurse(.a[])` in an update's path: every value the
+     * walk visits is a position, and the update must give each back with its
+     * own type.
+     */
+    assignWalk(shape, child, path, at, env) {
+        const range = this.range(path);
+        const steps = child === undefined ? undefined : walkSteps(child.node);
+        if (child !== undefined && steps === undefined) {
+            this.fail(range, "unsupported", MESSAGES.unavailable(`assigning through recurse(${this.source(child.path)})`, "an update's recurse walks .[], or field reads then .[], as recurse(.children[])"));
+            return undefined;
+        }
+        // The kinds of position the walk visits.
+        const kinds = [];
+        let problem = false;
+        const visit = (t) => {
+            if (problem || kinds.some(k => isTypeEqual(k, t)))
+                return;
+            kinds.push(t);
+            const inner = child === undefined ? this.walkKinds(t, path) : this.stepKinds(t, child, env);
+            if (inner === undefined) {
+                problem = true;
+                return;
+            }
+            inner.forEach(visit);
+        };
+        visit(shape.type);
+        if (problem)
+            return undefined;
+        let root = ONE;
+        for (const kind of kinds) {
+            const r = at({ shape: typed(kind), mult: ONE });
+            if (r.shape.kind === "error")
+                return undefined;
+            const t = this.collect(r, range);
+            if (t === undefined)
+                return undefined;
+            if (t.type !== "Never" && !sameType(kind, t)) {
+                this.fail(range, "type_mismatch", MESSAGES.walkUpdate(this.source(path), describeType(kind), describeType(t)));
+                return undefined;
+            }
+            if (kind === kinds[0])
+                root = r.mult;
+        }
+        return { shape: typed(shape.type), mult: root };
+    }
+    /**
+     * The kinds of position `..` finds directly inside a value in an update:
+     * the elements of an array or set, a dict's values, a struct's fields, an
+     * option's value's positions, and a variant's payloads (its case's name is
+     * not a position). A Vector or Matrix is refused.
+     */
+    walkKinds(type, path) {
+        const u = unwrap(type);
+        const payload = nullablePayload(u);
+        const t = payload === undefined ? u : unwrap(payload);
+        switch (t.type) {
+            case "Array": return [t.value];
+            case "Set": return [t.key];
+            case "Dict": return [t.value];
+            case "Struct": return Object.values(t.fields);
+            case "Variant": return Object.values(t.cases);
+            case "Vector":
+            case "Matrix":
+                this.fail(this.range(path), "unsupported", MESSAGES.unavailable(`assigning through ${this.source(path)}`, `it would walk ${describeType(t)}, whose elements an update does not rebuild`));
+                return undefined;
+            default: return [];
+        }
+    }
+    /** The kinds of position `recurse(f)` finds from a value: `f`'s outputs on it, checked as a read. */
+    stepKinds(type, child, env) {
+        const r = this.check(child.node, child.path, { shape: typed(type), mult: ONE }, env);
+        if (r.shape.kind === "error")
+            return undefined;
+        return membersOf(r.shape).map(m => m.shape.type);
+    }
+    /** Checks a node again on another input, in a new instance; see {@link CheckJqResult.retype}. */
+    retype(path, instance, input) {
+        const env = this.scopes.get(`${instance}|${path}`);
+        const node = this.nodes.get(path);
+        if (env === undefined || node === undefined)
+            return null;
+        this.retypes += 1;
+        const next = `${instance}~${this.retypes}`;
+        const reported = this.diagnostics.length;
+        const result = this.check(node, path, { shape: typed(input), mult: ONE }, { ...env, instance: next });
+        const failed = result.shape.kind === "error" || this.diagnostics.slice(reported).some(d => d.severity.type === "error");
+        // The program was checked already; what this finds is the translator's to act on, not the author's.
+        this.diagnostics.length = reported;
+        return failed ? null : next;
+    }
+}
+/** The field names of outputs that are field reads side by side, `.a, .b`: what `{a, b}` would hold. */
+function fieldsSideBySide(node) {
+    if (node.type === "comma") {
+        const left = fieldsSideBySide(node.value.left);
+        const right = fieldsSideBySide(node.value.right);
+        return left === undefined || right === undefined ? undefined : [...left, ...right];
+    }
+    if (node.type === "field" && node.value.target.type === "identity" && !node.value.optional && /^[A-Za-z_][A-Za-z0-9_]*$/.test(node.value.name)) {
+        return [node.value.name];
+    }
+    return undefined;
+}
+/** The steps that lead to a node where a pipe can start without parentheses. */
+const PIPE_POSITION = /(^|\.)(pipe\.(left|right)|call\.args\[\d+\]|array\.some|bind\.body|label\.body|def\.(body|rest)|if\.branches\[\d+\]\.(condition|then)|if\.otherwise\.some|object\[\d+\]\.value\.some|reduce\.update|foreach\.update|foreach\.extract\.some|try\.catch\.some)$/;
+/** Whether a node at a path can have `f | ` put before it without parentheses. */
+function isPipePosition(path) {
+    return path === "" || PIPE_POSITION.test(path);
+}
+/** A node's record in an instance; with none given, outside every def, or else the first instance checked. */
+function anyInstance(records, path, instance) {
+    if (instance !== undefined)
+        return records.get(`${instance}|${path}`);
+    const outside = records.get(`|${path}`);
+    if (outside !== undefined)
+        return outside;
+    for (const [key, value] of records)
+        if (key.endsWith(`|${path}`) && key.slice(0, -path.length - 1).startsWith(">"))
+            return value;
+    return undefined;
+}
+/** Whether a `break $name` for a label is in a node, outside any label of the same name inside it. */
+function breaksTo(node, name) {
+    if (node.type === "break")
+        return node.value === name;
+    if (node.type === "label" && node.value.name === name)
+        return false;
+    return jqChildren(node).some(child => child.node !== undefined && breaksTo(child.node, name));
+}
+/** The top-level pipeline's stages: its segments, through the bodies of the `as` that lead it. */
+function spine(node, path) {
+    if (node.type === "pipe")
+        return [{ node: node.value.left, path: childPath(path, "pipe.left") }, ...spine(node.value.right, childPath(path, "pipe.right"))];
+    if (node.type === "bind")
+        return spine(node.value.body, childPath(path, "bind.body"));
+    return [{ node, path }];
+}
+/**
+ * Checks a jq program against the East type of its input.
+ *
+ * @param program - the program's text, or what {@link parseJq} made of it
+ * @param input - the type the program runs on
+ * @param options - `root` for an e3 root, `tooling` for the tooling-only builtins
+ * @returns the program as written when there is no error, the type it was
+ *   checked against, the element type and multiplicity, the root fields
+ *   read, the stages, every node's type, and the diagnostics
+ *
+ * @remarks
+ * The checker types every node over East types as `devdocs/QUERY.md` says: it
+ * narrows variants through `select` and `if`, infers `reduce` and `foreach`
+ * accumulators and recursive `def`s by fixpoint, and reads a literal as the
+ * type it is used as (an Integer where a Float is, an ISO-8601 string where a
+ * DateTime is), reporting a string that is not a date or a `strftime` format
+ * East has no token for. It rewrites nothing: the translator gives each value
+ * from the types it reads (#1138). A problem is a diagnostic with its span,
+ * one sentence, suggestions and fixes; lints are warnings. `program` is
+ * present exactly when no diagnostic is an error, and with `inputType`,
+ * `elementType` and `multiplicity` it is what every reader of the query —
+ * the translator, the split planner, a host — works from.
+ *
+ * @example
+ * ```ts
+ * const Order = StructType({ id: IntegerType, total: FloatType });
+ * const checked = checkJq(".orders | map(.total) | add", StructType({ orders: ArrayType(Order) }));
+ * checked.elementType;    // FloatType
+ * checked.multiplicity;   // "one"
+ *
+ * checkJq(".orders[0].totl", StructType({ orders: ArrayType(Order) })).diagnostics[0]!.message;
+ * // "unknown_field: .totl is not a field of Struct{id: Integer, total: Float}. Did you mean .total?"
+ * ```
+ */
+export function checkJq(program, input, options = {}) {
+    const parsed = typeof program === "string" ? parseJq(program) : program;
+    const empty = (diagnostics) => ({
+        program: null, inputType: input, elementType: null, multiplicity: null, reads: [], stages: [], typeAt: () => null, diagnostics,
+        resultAt: () => null, scopeAt: () => null, source: { text: parsed.text, spans: parsed.spans, root: options.root === true },
+        inputAt: () => null, retype: () => null, updatedCases: () => null, opened: () => null,
+    });
+    if (parsed.program.type === "none")
+        return empty(parsed.diagnostics);
+    const root = parsed.program.value;
+    const checker = new Checker(parsed.text, parsed.spans, options, input);
+    const env = { vars: new Map(), defs: new Map(), labels: new Set(), instance: "", lenient: false };
+    const start = { shape: typed(input), mult: ONE };
+    const result = checker.check(root, "", start, env);
+    if (options.root === true && result.shape.kind === "type" && checker.isRootShape(result.shape)) {
+        checker.refuseRoot(result, "", env);
+    }
+    const elementType = result.shape.kind === "error" ? undefined : checker.collect(result, parsed.spans.get(""), "");
+    const multiplicity = wireMultiplicity(result.mult);
+    // The stages of the top-level pipeline.
+    const stages = [];
+    let cumulative = ONE;
+    for (const stage of spine(root, "")) {
+        const record = checker.records.get(`|${stage.path}`);
+        const range = parsed.spans.get(stage.path);
+        if (record === undefined || range === undefined)
+            break;
+        cumulative = piped(cumulative, record.mult);
+        const type = unifyShape(record.shape);
+        if (type === undefined)
+            break;
+        stages.push({ path: stage.path, from: range.from, to: range.to, type, multiplicity: wireMultiplicity(cumulative) });
+    }
+    const errors = checker.diagnostics.some(d => d.severity.type === "error");
+    const typeAt = (path, instance = "") => {
+        const record = checker.records.get(`${instance}|${path}`);
+        if (record === undefined)
+            return null;
+        const type = unifyShape(record.shape);
+        return type === undefined ? null : { type, multiplicity: wireMultiplicity(record.mult) };
+    };
+    const checks = !errors && elementType !== undefined;
+    return {
+        program: checks ? root : null,
+        inputType: input,
+        elementType: checks ? elementType : null,
+        multiplicity: checks ? multiplicity : null,
+        reads: checker.reads,
+        stages,
+        typeAt,
+        diagnostics: checker.diagnostics,
+        resultAt: (path, instance) => anyInstance(checker.records, path, instance) ?? null,
+        scopeAt: (path, instance) => {
+            const env = anyInstance(checker.scopes, path, instance);
+            return env === undefined ? null : { vars: env.vars, defs: [...env.defs.keys()] };
+        },
+        source: { text: parsed.text, spans: parsed.spans, root: options.root === true },
+        inputAt: (path, instance) => checker.inputs.get(`${instance}|${path}`) ?? null,
+        retype: (path, instance, input) => checker.retype(path, instance, input),
+        updatedCases: (path, instance, variant) => checker.updatedCases.get(`${instance}|${path}|${printType(variant)}`) ?? null,
+        opened: (path, instance) => checker.opened.get(`${instance}|${path}`) ?? null,
+    };
+}
+//# sourceMappingURL=check.js.map