@sheetxl/primitives 0.7.28-beta.4 → 0.8.0-beta.2

package/types/src/IFunction.d.ts

@@ -1,5 +1,6 @@
 import { Scalar } from './Scalar';
 import { ScalarType } from './ScalarType';
+import { ValueKind } from './ValueKind';
 /**
  * A self-describing, type-safe, executable function.
  *
@@ -35,6 +36,16 @@ export interface IFunction {
      * Indicates whether the function is a built-in function.
      */
     isBuiltIn(): boolean;
+    /**
+     * Indicates whether the function is a defined name whose body is `LAMBDA(…)`.
+     *
+     * @remarks
+     * A named lambda is reachable by name like any other function, so signature help and function
+     * lookups can describe it: its parameters are the lambda's, and its summary is the name's
+     * comment, or the name's formula when it has no comment. A formula calls it through the NAME,
+     * never through {@link execute}, which answers `#CALC!`.
+     */
+    isLambda(): boolean;
     /**
      * Returns the execution environment this function belongs to.
      *
@@ -125,17 +136,47 @@ export declare namespace IFunction {
          */
         getName(): string;
         /**
-         * The DECLARED error policy, or `null` when the parameter relies on the default.
+         * True when a BARE error at this parameter — an error instead of a value or a range, `NA()`,
+         * `#NAME?`, a union where one rectangle is needed — is delivered to the body RAW rather than
+         * propagated: the `AcceptError<T>` marker. A rule, not a type — the engine's auto-reject is
+         * off at this slot, and the body narrows with `FormulaError.isError` if it cares.
          *
          * @remarks
-         * `null` is the common case and it is not "no policy": the default is REJECT in every position
-         * — scalar, lifted, flattened and range alike — so `null` means reject. There is deliberately
-         * no `'reject'` value to declare it with; a `RejectError<T>` marker existed, said exactly what
-         * `null` already says, and was removed rather than left as a second spelling.
+         * The default, and the common case, is that the error propagates with its identity and the
+         * body never runs. The marker never looks INSIDE a container: an error member of a range
+         * reaches the body either way and is the body's to judge (`IRange.firstError`).
+         *
+         * @see {@link ParameterTypeJSON.acceptError}
+         */
+        isAcceptError(): boolean;
+        /**
+         * True when a multi-cell REFERENCE at this scalar parameter is `#VALUE!` rather than a
+         * broadcast — the `NoLift<T>` marker.
+         *
+         * @see {@link ParameterTypeJSON.noLift}
+         */
+        isNoLift(): boolean;
+        /**
+         * True when the members reaching this repeating scalar parameter are coerced rather than
+         * filtered — the `NoFilter<T>` marker.
+         *
+         * @see {@link ParameterTypeJSON.noFilter}
+         */
+        isNoFilter(): boolean;
+        /**
+         * True when the argument at this parameter may reach the body UNEVALUATED, as an `ILazy`
+         * handle — the `Lazy<T>` marker.
+         *
+         * @see {@link ParameterTypeJSON.lazy}
+         */
+        isLazy(): boolean;
+        /**
+         * True when the parameter takes EITHER a value or a range, decided per argument by its kind —
+         * an `IRange | Scalar` union.
          *
-         * @see {@link ParameterTypeJSON.errors}
+         * @see {@link ParameterTypeJSON.valueOrRange}
          */
-        getErrorPolicy(): 'accept' | 'accept-ref' | null;
+        isValueOrRange(): boolean;
         /**
          * Indicates whether the parameter is required.
          */
@@ -181,11 +222,60 @@ export declare namespace IFunction {
          */
         isRest(): boolean;
         /**
-         * Indicates that the parameter is limited to a list of specific values.
-         * If the input value is a `string` it will be passed as a case-insensitive version.
-         * If the input value is a `number` it will be passed as a value against the offset.
+         * The enum the parameter is limited to, or `null` when it takes any value of its type.
+         *
+         * @remarks
+         * Declared by typing the parameter as a TypeScript `enum`, as an alias paired with a same-name
+         * `as const` object, or as a union of number or string literals (`0 | 1`).
+         *
+         * @see {@link IEnum}
+         */
+        getEnum(): IFunction.IEnum | null;
+    }
+    /**
+     * One member of an {@link IEnum}.
+     */
+    interface IEnumMember {
+        /**
+         * The declared member name (`End`). For a union of bare literals, which names nothing, this is
+         * the value as text.
          */
-        getEnums(): readonly string[];
+        getName(): string;
+        /**
+         * The value a formula passes. Typed, and never localized.
+         */
+        getValue(): number | string;
+        /**
+         * Whether the member is declared but not offered, from the member's `@deprecated` tag.
+         *
+         * @remarks
+         * A deprecated member stays in the set, so a formula that passes it is not refused and the
+         * function decides what it answers. It is left out of the argument dropdown and the values
+         * a warning lists. A string is the tag's label (`Excel desktop only`).
+         */
+        isDeprecated(): boolean | string;
+    }
+    /**
+     * A closed set of values a parameter accepts.
+     *
+     * @remarks
+     * All members are numbers or all are strings; the two never mix. The set is free-form: it does
+     * not have to be contiguous or start at zero (`-1 | 0 | 1`).
+     */
+    interface IEnum {
+        /**
+         * The declared type name (`PaymentType`), unique within the module that declares it. For a
+         * union of bare literals it is the values joined by `|`.
+         */
+        getId(): string;
+        /**
+         * Whether the members are numbers or strings.
+         */
+        getScalarType(): typeof ScalarType.Number | typeof ScalarType.String;
+        /**
+         * The members, in declaration order.
+         */
+        getMembers(): readonly IFunction.IEnumMember[];
     }
     /**
      * Describes the runtime return behavior of a function, including modifiers like
@@ -196,6 +286,14 @@ export declare namespace IFunction {
      * If none are specified, The value will be returned with no special behavior.
      */
     interface IReturnType extends IValueType {
+        /**
+         * The declared {@link ValueKind} of the result — the declared override where one exists, else
+         * the kind the type spellings imply — or `null` when the result's kind follows the value
+         * itself (`'*'`, an untyped return).
+         *
+         * @see {@link ReturnTypeJSON.kind}
+         */
+        getKind(): ValueKind | null;
         /**
          * Indicates the return value is a Promise or Promise-like (i.e., async).
          * The system will mark the result as pending and re-trigger evaluation once resolved.
@@ -209,6 +307,17 @@ export declare namespace IFunction {
          * @defaultValue `false`
          */
         isStreaming(): boolean;
+        /**
+         * True when the result can change with nothing dirty, so a cell naming this function
+         * recalculates on every pass — the `Volatile<T>` marker.
+         *
+         * @remarks
+         * STATIC, and read from the formula text at compile time: it is true of the call whether or
+         * not the call runs, which is what a lazy argument (and Excel) requires.
+         *
+         * @see {@link ReturnTypeJSON.volatile}
+         */
+        isVolatile(): boolean;
     }
     /**
      * The type-system metadata the engine reads to coerce arguments, apply broadcasting,
@@ -237,6 +346,17 @@ export declare namespace IFunction {
          * If not specified, the function is assumed to be volatile (its output might change even if its inputs haven't).
          */
         getParameters(): readonly IParameterType[];
+        /**
+         * The largest number of arguments a call to this function may carry.
+         *
+         * @remarks
+         * Only meaningful for a VARIADIC function; a fixed parameter list is already its own maximum.
+         * The number is the whole CALL's argument count, prefix and optional suffix included, and it
+         * is refused where Excel refuses it — at entry, before evaluation.
+         *
+         * @see {@link Repeating}
+         */
+        getMaxArguments(): number;
         /**
          * Metadata describing the type and dimensionality of the return value.
          *
@@ -252,7 +372,11 @@ export declare namespace IFunction {
      */
     interface IDescriptor {
         /**
-         * A overwritten name for the function.
+         * The canonical name of the function, matching {@link IDeclaration.getName}.
+         *
+         * @remarks
+         * A descriptor may override the name; when it does not, this is the name of the function
+         * in code. Use {@link getNameLocal} for display.
          */
         getName(): string;
         /**
@@ -297,6 +421,31 @@ export declare namespace IFunction {
             example?: string;
             defaultValue?: Scalar;
         }>>;
+        /**
+         * Describe each enum the function's parameters are limited to.
+         *
+         * @remarks
+         * The keys are enum ids (see {@link IEnum.getId}), and within one the member names (see
+         * {@link IEnumMember.getName}). Every enum a parameter declares has an entry and every member
+         * has one within it, so a caller can read a label without checking: `nameLocal` falls back to
+         * the declared name. Values are never localized — they are on the declaration.
+         */
+        getEnums(): Readonly<Record<string, IFunction.IEnumDescription>>;
+    }
+    /**
+     * The copy for one enum: what it is, and what each member means.
+     */
+    interface IEnumDescription {
+        /** The enum's name in the user's language, or its declared name. */
+        readonly nameLocal: string;
+        /** What the enum controls. */
+        readonly summary?: string;
+        /** By member name. */
+        readonly members: Readonly<Record<string, {
+            /** The member's name in the user's language, or its declared name. */
+            readonly nameLocal: string;
+            readonly description?: string;
+        }>>;
     }
     /**
      * Describes the type characteristics of a function parameter or return value.
@@ -394,7 +543,8 @@ export declare namespace IFunction {
          * @remarks
          * Descriptive rather than applied: an absent argument is never pushed, so the initializer
          * supplies the value itself. It is recorded so help text, tooltips and completions can say
-         * "defaults to 3" without reading the source.
+         * "defaults to 3" without reading the source. The exception is a {@link lazy} slot, which has
+         * no initializer to run — `Lazy<T, V>` declares the default here and the engine applies it.
          *
          * Present for a literal initializer only. One computed from another argument
          * (`numberS2: number = numberS`) has no value to record and leaves this undefined.
@@ -454,28 +604,126 @@ export declare namespace IFunction {
          */
         repeating?: ParameterTypeJSON[];
         /**
-         * The DECLARED error policy, generated from the `AcceptError<T>` / `AcceptRefError<T>`
-         * parameter markers.
+         * A BARE error at this parameter — an error instead of a value or a range — is delivered to
+         * the body RAW rather than propagated: the engine's auto-reject is off at this slot, and the
+         * body narrows if it cares. Generated from the `AcceptError<T>` marker. A failed COERCION to
+         * the declared type is delivered the same way, as the `#VALUE!` it would have raised, so a
+         * body that rethrows what it receives answers exactly as the engine would have — and one that
+         * reads its arguments in its own order can (`IFS(TRUE,1,"x",2)` is 1: the pair is never
+         * reached).
+         *
+         * @remarks
+         * OMITTED is the default (ErrorPolicy.ts): the error propagates with its identity (a scalar
+         * argument), becomes an error member of the output (a lifted member), or short-circuits on the
+         * first error in argument order (a flattened list) — the body never runs. A
+         * `FormulaError.Known`-typed parameter receives without the marker, because the type declares
+         * it. On a TYPED range (`IRange<number>`) the marker also lets error members ride through the
+         * typed read raw — COUNT's profile. Errors INSIDE a range are otherwise never the marker's
+         * business: a valid range is handed over whole.
+         */
+        acceptError?: boolean;
+        /**
+         * The argument's subtree may be handed over UNEVALUATED, as an `ILazy` handle the body either
+         * returns unread or forces with `getValue()`. Generated from the `Lazy<T>` marker.
+         *
+         * @remarks
+         * A declaration, not a request: the engine defers where it can and DECLINES where it cannot
+         * (an absent argument, an async subtree, a lift that needs every arm), handing over a handle
+         * that is already full. Either way the body sees a handle and nothing else, which is why the
+         * marker is a contract rather than something inferred from what the body happens to read.
+         *
+         * Only a RESULT position carries it — `IF`'s branches, `CHOOSE`'s arms, `IFERROR`'s fallback.
+         * A condition, an index or a case value is eager, so `AND(FALSE,A1)` still reads `A1` and is
+         * still a circular reference.
          *
-         * - `'accept'`: the body receives `FormulaError` values raw.
-         * - `'accept-ref'`: per argument SHAPE — reject for a direct/computed argument, accept for a
-         *   reference-shaped one. Resolved to one of the two before any coercion runs, so nothing
-         *   downstream sees this value.
+         * {@link defaultValue} is APPLIED at a lazy slot rather than merely recorded: the parameter
+         * cannot carry an initializer of its own (`= false` does not typecheck against a handle), so
+         * `Lazy<T, V>` declares it and the engine supplies it for an absent argument.
          *
-         * OMITTED is the default and the default is REJECT (ErrorPolicy.ts): never call the body — the
-         * error propagates with its identity (scalar argument), becomes an error member of the output
-         * (lifted member), or short-circuits on the first error in row-major order (range/array
-         * member). Only a `FormulaError.Known`-typed parameter receives without a marker, because the
-         * type declares it. There is no `'reject'` value: it would say what omitting this says.
+         * @see {@link Lazy}
          */
-        errors?: 'accept' | 'accept-ref';
+        lazy?: boolean;
         /**
-         * Indicates whether the function requires the address of the calling cell as an input.
-         * Cannot be combined with `stream`.
+         * A multi-cell REFERENCE at this scalar parameter is `#VALUE!` rather than a broadcast.
+         * Generated from the `NoLift<T>` marker.
          *
-         * @defaultValue `false`
+         * @remarks
+         * Per parameter, because Excel is: `NETWORKDAYS.INTL` refuses a reference at its date slots
+         * and lifts one at `weekend`. An ARRAY at the slot still lifts, a one-cell reference is an
+         * ordinary argument, and a repeating slot absorbs a container as members, so the marker only
+         * ever applies to a non-repeating scalar parameter.
+         */
+        noLift?: boolean;
+        /**
+         * The members reaching this repeating scalar parameter are COERCED rather than filtered, and
+         * one that cannot be coerced is `#VALUE!` for the whole call. Generated from the `NoFilter<T>`
+         * marker.
+         *
+         * @remarks
+         * Numeric text parses, a blank inside a multi-cell range reads 0, and a boolean or
+         * non-numeric text member refuses — Excel's Analysis-ToolPak reading of a repeating slot,
+         * where the native family skips all three (`GCD({6,"8",12})` is 2 where `SUM` would answer
+         * over 6 and 12 alone). Only a repeating slot has members, so the marker applies nowhere
+         * else; a non-repeating scalar's counterpart is {@link noLift}.
+         */
+        noFilter?: boolean;
+        /**
+         * The declared type is ADVISORY: the engine delivers it when it can and hands the body the
+         * raw argument when it cannot, instead of answering `#VALUE!` at the slot. Generated from the
+         * `ReportType<T>` marker.
+         *
+         * @remarks
+         * The type still reaches the function help, the wizard and the linter — it is what the slot
+         * means to a caller. It stops being a gate, so the BODY owns every answer the engine would
+         * otherwise have given: a union reaches it as `IRange[]`, a value or an error reaches it as
+         * itself. See {@link IFunctionArguments.getKindAt} and
+         * {@link IFunctionArguments.getAreaCountAt} for the discriminators.
+         */
+        reportType?: boolean;
+        /**
+         * The parameter takes EITHER a value or a range — declared as a two-member union of a bare
+         * range type and a scalar type (`IRange | Scalar`, `IReferenceRange | number`) — and the
+         * marshaller picks the arm by the ARGUMENT's kind: a value, a bare error or a one-cell
+         * reference is the scalar arm (dereferenced, coerced to {@link scalar}, its fault raised in
+         * argument order like any scalar slot's); a multi-cell reference, an array or a reference
+         * union is the range arm, handed over whole. The slot never lifts.
+         *
+         * @remarks
+         * Excel reads a one-cell argument at some array slots as THE ARGUMENT rather than as a
+         * one-cell container: `SORT(<#N/A cell>,1,1,<#DIV/0! cell>)` is `#N/A` where
+         * `TAKE(<#N/A cell>,<#DIV/0! cell>)` is `#DIV/0!`. The engine's default
+         * for a range slot is TAKE's; this flag is SORT's. {@link scalar} and {@link range} each carry
+         * their arm, a pair that without this flag reads as a TYPED range (`IRange<number>`).
+         */
+        valueOrRange?: boolean;
+        /**
+         * The closed set of values the parameter accepts. Generated from a parameter typed as a
+         * TypeScript `enum`, as an alias paired with a same-name `as const` object, or as a union of
+         * number or string literals. {@link scalar} carries the members' type.
+         *
+         * @remarks
+         * Parameters that share a declared enum share one `EnumJSON`, by {@link EnumJSON.id}.
          */
-        enums?: string[];
+        enum?: EnumJSON;
+    }
+    /**
+     * The JSON form of an {@link IEnum}.
+     */
+    interface EnumJSON {
+        /**
+         * The declared type name, unique within the declaring module. A union of bare literals has no
+         * name, so its id is the values joined by `|`.
+         */
+        id: string;
+        /**
+         * Whether the members are numbers or strings. The two never mix.
+         */
+        type: typeof ScalarType.Number | typeof ScalarType.String;
+        /**
+         * The members, in declaration order. A union of bare literals names nothing, so each name is
+         * the value as text.
+         */
+        members: [name: string, value: number | string, deprecated?: string | true][];
     }
     /**
      * Describes the runtime return behavior of a function, including modifiers like
@@ -485,6 +733,24 @@ export declare namespace IFunction {
      * If none are specified, The value will be returned with no special behavior.
      */
     interface ReturnTypeJSON extends ValueTypeJSON {
+        /**
+         * The declared {@link ValueKind} of the result, where the inherited type spellings cannot say
+         * it. Generated from the `@returnKind` marker.
+         *
+         * @remarks
+         * A return type is a pair — is the call a REFERENCE, and what is its value kind. Both halves
+         * usually derive from the type spellings: {@link ValueTypeJSON.range} `'p'` (an
+         * `IReferenceRange` return, which a function whose value paths are casts may also use —
+         * `XLOOKUP`, `TAKE`) is `Reference`; `'r'`/`'m'` is `Array`; a concrete
+         * {@link ValueTypeJSON.scalar} is that scalar kind; `'*'` or an untyped return follows the
+         * value itself. This field overrides the derivation for the one spelling that loses it — a
+         * union like `number[] | number[][]` (`ROW`) collapses to `'*'`, yet the function's one-cell
+         * answer is a SCALAR (`TYPE(ROW(A1))` is 1 where `TYPE(TRANSPOSE({5}))` is 64).
+         *
+         * The engine applies the kind at the call exit: a one-cell range result whose declared kind
+         * is a scalar is its member value downstream.
+         */
+        kind?: ValueKind;
         /**
          * Indicates the return value is a Promise or Promise-like (i.e., async).
          * The system will mark the result as pending and re-trigger evaluation once resolved.
@@ -498,6 +764,20 @@ export declare namespace IFunction {
          * @defaultValue `false`
          */
         stream?: boolean;
+        /**
+         * The result can change with nothing dirty — a cell naming this function recalculates on
+         * every pass. Generated from the `Volatile<T>` marker.
+         *
+         * @remarks
+         * Collected at COMPILE time from the formula text (`CompiledFormula.hasVolatile`), because
+         * that is where Excel decides it: `=IF(TRUE,1,RAND())` recalculates on every idle pass though
+         * no branch selects the arm, and with lazy arguments the call never happens for the engine to
+         * observe. Sits beside {@link async} and {@link stream} because all three are about WHEN a
+         * result arrives rather than what it is.
+         *
+         * @see {@link Volatile}
+         */
+        volatile?: boolean;
     }
     /**
      * Contains metadata about a function declaration, including its name, return type, parameters, and additional documentation.
@@ -509,6 +789,20 @@ export declare namespace IFunction {
         returnType?: ReturnTypeJSON;
         /** @inheritdoc IFunction.IDeclaration.getParameters */
         parameters?: ParameterTypeJSON[];
+        /**
+         * The largest number of arguments a call may carry, from `Repeating<T, Max>` on the variadic
+         * parameter. Omitted at the default of 255.
+         *
+         * @remarks
+         * Excel keeps one such number per NAME and compares it against the whole call's argument
+         * count in its front end, so a call past it is refused AT ENTRY rather than answered — which
+         * is why the cap lives on the declaration and not in a body. It is not derivable from the
+         * shape: `STDEV` takes 255 arguments and `STDEV.S`, the same function under its dotted name,
+         * takes 254.
+         *
+         * @defaultValue 255
+         */
+        maxArguments?: number;
         /**
          * Describes the execution context required by the function.
          *
@@ -586,6 +880,22 @@ export declare namespace IFunction {
             example?: string;
             defaultValue?: Scalar;
         }>;
+        /**
+         * Describe each enum the function's parameters are limited to, by enum id.
+         */
+        enums?: Record<string, EnumDescriptorJSON>;
+    }
+    /**
+     * The JSON form of an {@link IEnumDescription}. Every field is optional: an enum with no doc
+     * comments has nothing to say, and a language pack may translate any part of one.
+     */
+    interface EnumDescriptorJSON {
+        nameLocal?: string;
+        summary?: string;
+        members?: Record<string, {
+            nameLocal?: string;
+            description?: string;
+        }>;
     }
     /**
      * Contains extended metadata about a function that is not be directly inferable from the code itself.

package/types/src/IFunctionArguments.d.ts

@@ -0,0 +1,192 @@
+import { Scalar } from './Scalar';
+import { ValueKind } from './ValueKind';
+import { IRange } from './IRange';
+import { Lambda } from './Lambda';
+/**
+ * The current call's arguments, as the body sees them — argument **reflection**.
+ *
+ * @remarks
+ * A declaration answers "what does this parameter mean?", and the marshaller coerces every
+ * argument to it. That is right for the overwhelming majority of parameters. What it cannot answer
+ * is anything about *this particular call*:
+ *
+ * - What did the caller write there — a value, a cell, an array, nothing at all?
+ * - What was the value BEFORE the parameter's type coerced it?
+ * - Was that empty slot an omission, or a blank cell the caller pointed at?
+ *
+ * Excel has behaviors that turn on exactly those questions, and they cluster at the
+ * parameters Excel declares `any` — where there is nothing to express as a type, because Excel
+ * declined to express one. `CUMIPMT` refuses a boolean at every slot while `FV` coerces one at
+ * every slot; the difference is not the values, it is that `CUMIPMT`'s slots are `any` and its
+ * body decides.
+ *
+ * It is REFLECTION and nothing else — two questions, and no third:
+ *
+ * | question | answers |
+ * | --- | --- |
+ * | *what was supplied* | {@link getLength}, {@link getKindAt} |
+ * | *what it is* | {@link getRawAt}, {@link getKindAt} |
+ *
+ * Coercion is deliberately absent. A body that wants a number calls
+ * {@link IFormulaContext.parseAsNumber} on the value this hands it — that already takes a value,
+ * already propagates an incoming error with its identity, and already answers `#VALUE!` for a
+ * boolean, which IS the rule an `any` slot needs. There is no coercion an index can do that a
+ * value cannot.
+ *
+ * Obtained from `FormulaContext.getArgs()`, and valid ONLY while the body that asked for it is
+ * running. A body must not retain it across an `await`, a callback, or a nested evaluation — the
+ * views are pooled by dispatch depth, so the one at your depth is handed to the next call at that
+ * depth.
+ *
+ * ```typescript
+ * export function CUMIPMT(rate: Scalar, nper: Scalar): number {
+ *   const args = FormulaContext.getArgs();
+ *   if (args.getKindAt(0) === ValueKind.Omitted) return FormulaError.BuiltIn.NA; // `CUMIPMT(,120,…)`
+ *   const asNumber = FormulaContext.parseAsNumber(args.getRawAt(0) as Scalar);  // TRUE is #VALUE!
+ *   // …
+ * }
+ * ```
+ *
+ * @see {@link IFormulaContext.getArgs}
+ */
+export interface IFunctionArguments {
+    /**
+     * How many PARAMETERS the caller supplied.
+     *
+     * @remarks
+     * Indexing throughout matches the BODY's own signature, never the raw call positions
+     * (see {@link getRawAt}). `index >= getLength()` is an ABSENT argument — one the caller never
+     * wrote, whose own JS initializer supplied the value. That is a different thing from an OMITTED
+     * one; see {@link isOmittedAt}.
+     */
+    getLength(): number;
+    /**
+     * This invocation's value at `index`, uncoerced.
+     *
+     * @param index The PARAMETER index — the position in the body's own signature.
+     *
+     * @remarks
+     * A `Scalar` means the argument IS a value; an {@link IRange} means a container whose members
+     * the body reads itself (a reference materializes on demand); a {@link Lambda} means a callable.
+     *
+     * At a REPEATING parameter (`Repeating<T>`, or a rest parameter) this is the ARRAY of that
+     * group's values — one entry per argument the caller wrote — and {@link getRepeatingArgsAt} is the
+     * per-argument view of the same thing. Indexing by parameter rather than by call position is
+     * what lets a body ask its questions in the vocabulary it declared:
+     *
+     * ```typescript
+     * // IFS(condition: Repeating<[logicalTest: boolean, logicalTrue: AcceptError<any>]>)
+     * args.getRawAt(0);                       // [test1, value1, test2, value2, …]
+     * args.getRepeatingArgsAt(0).getRawAt(0);     // test1
+     * ```
+     *
+     * **Under a lift** the call broadcasts and the body runs once per output cell; this reports the
+     * value for THIS invocation — the member at the current broadcast position for a lifted argument,
+     * the whole argument for one that is not lifting. That is what every identified caller wants: a
+     * body checking for a boolean must see the member, not the array around it.
+     *
+     * One boundary is worth knowing: under a lift at a parameter that declares a CONCRETE scalar
+     * type, the member has already been converted by that declaration, so the raw and coerced answers
+     * coincide there. At the `Scalar` slots this interface exists for, nothing coerces and the value
+     * is the member exactly as the caller's range holds it.
+     *
+     * A reference UNION (`(A1:A3,C1:C3)`) is an array too — one `IReferenceRange` per area — which
+     * is how a body whose slot took the areas apart can still tell one argument's union from two
+     * arguments (`SUMPRODUCT` refuses the first and accepts the second).
+     */
+    getRawAt(index: number): IFunctionArguments.RawArg | IFunctionArguments.RawArg[];
+    /**
+     * A nested view over one REPEATING parameter's arguments, so a body can ask the same questions
+     * one level down — `getRepeatingArgsAt(0).isOmittedAt(1)`.
+     *
+     * @param index The PARAMETER index of the repeating group (or rest parameter).
+     *
+     * @remarks
+     * The nested view is FLAT over the group's arguments: a period-2 group repeated three times reads
+     * as six, in call order. That is where "which one was omitted" has an answer at all — the group
+     * as a whole cannot be omitted, only one of its arguments can.
+     *
+     * At a non-repeating parameter this returns an EMPTY view (`getLength()` of 0) rather than
+     * throwing, so a body that folds over its groups needs no special case.
+     */
+    getRepeatingArgsAt(index: number): IFunctionArguments;
+    /**
+     * The KIND of the argument at `index` — the total discriminator over {@link getRawAt}'s value.
+     *
+     * @param index The PARAMETER index — the position in the body's own signature.
+     *
+     * @remarks
+     * Every raw argument is exactly one of a closed set of kinds ({@link ValueKind}), and this
+     * answers without materializing anything — a reference stays coords underneath. The scalar
+     * kinds ARE `ScalarType` values, so `getKindAt(i) === ScalarType.Boolean` reads naturally.
+     *
+     * Under a lift this reports THIS invocation's value, like {@link getRawAt} — except the
+     * {@link ValueKind.Omitted} answer, which is a fact about the CALL (the caller wrote an empty
+     * comma) and does not change per broadcast position. At a REPEATING parameter it answers for
+     * the group's FIRST argument; per-argument kinds are one level down —
+     * `getRepeatingArgsAt(i).getKindAt(j)`.
+     *
+     * There are THREE argument positions:
+     *
+     * | form | position | answer |
+     * | --- | --- | --- |
+     * | `CUMIPMT(0.01,120,100000,13,24)` | never wrote a 6th | `Omitted` here — the POSITION fact is {@link getLength} (`index >= getLength()`), not a kind |
+     * | `CUMIPMT(,120,100000,13,24,0)` | the empty comma | {@link ValueKind.Omitted} |
+     * | `CUMIPMT(…,E1)`, E1 blank | a blank CELL | {@link ValueKind.Reference} — blankness is the cell's value, not the argument |
+     *
+     * The kind is the argument's own and it survives what it passes through:
+     * `VLOOKUP(10,10,1,TRUE)` is `#N/A` where `VLOOKUP(10,{10},1,TRUE)` is 10 — scalar vs 1x1
+     * array; `TYPE(IF(TRUE,10))` is 1 where `TYPE(IF(TRUE,{10}))` is 64 — a selector carries the
+     * kind through in both directions.
+     */
+    getKindAt(index: number): ValueKind;
+    /**
+     * True when the argument at `index` is DIRECT — Excel's "typed into the list of arguments":
+     * the evaluated value IS a value, not a container or a callable.
+     *
+     * @param index The PARAMETER index — the position in the body's own signature.
+     *
+     * @remarks
+     * The derived predicate over {@link getKindAt}: true exactly when the kind is one of the
+     * `ScalarType` members. A blank (`ScalarType.Null`) IS a value and is direct; an omitted
+     * argument, a reference, an array and a callable are not. Directness is what the
+     * direct-vs-member coercion rules key on (`SUM(1,TRUE)` is 2 where `SUM({1,TRUE})` is 1), so
+     * a body speaking that vocabulary can ask in it.
+     */
+    isDirectAt(index: number): boolean;
+    /**
+     * How many AREAS the argument at `index` covers — 1 for an ordinary reference, more for a
+     * union (`(A1:A5,B1:B2)`), and 0 for anything that is not a reference at all.
+     *
+     * @param index The PARAMETER index — the position in the body's own signature.
+     *
+     * @remarks
+     * {@link getKindAt} deliberately cannot answer this: a union IS a reference and reports
+     * {@link ValueKind.Reference}, the same as `A1:A5`. This is the question a body asks when the
+     * union is the thing it must decide about, and the three possible answers all come from asking
+     * it — flatten every area, refuse, or `#REF!`.
+     *
+     * Only a {@link IFunction.ParameterTypeJSON.reportType} slot can see a union at all; at every
+     * other slot the marshaller has already answered `#VALUE!`.
+     */
+    getAreaCountAt(index: number): number;
+}
+/**
+ * {@inheritDoc IFunctionArguments}
+ *
+ * @see
+ * ### **Interface**
+ *
+ * {@link IFunctionArguments}
+ */
+export declare namespace IFunctionArguments {
+    /**
+     * One argument as the caller wrote it — a value, a container, a callable, or nothing.
+     *
+     * @remarks
+     * `undefined` is an OMITTED or ABSENT argument; `null` is a blank, which is a value. A reference
+     * union is delivered as `RawArg[]` — one reference per area (see {@link IFunctionArguments.getRawAt}).
+     */
+    type RawArg = Scalar | IRange | Lambda | undefined;
+}
+//# sourceMappingURL=IFunctionArguments.d.ts.map