@sheetxl/primitives 0.8.0-beta.1 → 0.8.0-beta.3

package/types/src/IFormulaContext.d.ts

@@ -28,10 +28,10 @@ import { IRuntime } from './IRuntime';
  *
  * | Category | Key methods |
  * |---|---|
- * | Evaluation lifecycle | `markVolatile`, `getRow`, `getColumn`, `getEntireCoords` |
+ * | Evaluation lifecycle | `markVolatile`, `getRow`, `getColumn`, `getEntireCoords`, `getRandom` |
  * | Argument reflection | `getArgs` |
  * | Output hints | `formatResults` |
- * | Range construction | `createRange`, `filterHidden` |
+ * | Range construction | `createRange`, `flattenAreas`, `filterHidden` |
  * | Dynamic references | `getReference`, `getValueAt`, `getFormulaAt`, `getSpillAt` |
  * | Function lookup | `getFunction` |
  * | Dates | `getNow`, `toSerialDate`, `fromSerialDate`, `getDateParts`, `getSerialDate`, `parseAsDate`, `parseAsSerialDate`, `isValidDate` |
@@ -54,6 +54,25 @@ export interface IFormulaContext {
      * invoked per cell. Default is `null` (an empty range).
      */
     createRange<TS extends Scalar = Scalar>(rows?: number, columns?: number, values?: Scalar | Scalar[][] | ((value: TS, coords: IRange.CellCoords, range: IRange<TS>) => TS)): IRange;
+    /**
+     * One range over every cell of a `ReportType` slot's argument — the AREAS of a reference union
+     * folded into a single column, or the range returned unchanged.
+     *
+     * @param value The argument as it arrived: a range, or one range per area.
+     *
+     * @remarks
+     * A union `(A1:A5,B1:B2)` reaches a {@link IFunction.ParameterTypeJSON.reportType} slot as one
+     * `IRange` per area. Functions that answer over it do so because they walk MEMBERS and a union
+     * simply has more of them — `LARGE((DA1:DA5,DK1:DK2),2)` is the second largest of all seven
+     * cells. This is that walk, and it is a helper rather than a marshalling step on purpose: Excel
+     * flattens in exactly the same place, a shared reducer its bodies opt into, which is why the
+     * same union is flattened by `LARGE`, refused by `SUMPRODUCT` and answered `#REF!` by `ROWS`.
+     *
+     * The result is a single column in area order, row-major within each area. SHAPE IS NOT
+     * PRESERVED — a union has none. A body that needs an extent must ask
+     * {@link IFunctionArguments.getAreaCountAt} and answer for itself.
+     */
+    flattenAreas(value: IRange | IRange[]): IRange;
     /**
      * Returns coordinates as an address string.
      *
@@ -94,6 +113,20 @@ export interface IFormulaContext {
      * Returns the 0-based column of the cell being evaluated.
      */
     getColumn(): number;
+    /**
+     * Whether the call being evaluated is in Excel's VALUE mode, where a multi-cell reference at a
+     * slot that reads ONE value is implicitly intersected with the formula's cell (the `@` rule);
+     * `false` is ARRAY mode, where such a slot reads the reference's first cell.
+     *
+     * @remarks
+     * Only a body that accepts a whole reference at a single-value slot and reads it itself asks
+     * (`LINEST`'s `const`). The engine decides the mode from the formula around the call — a
+     * scalar-valued root, an aggregator or a lookup above it are value mode; a spilling root, an
+     * operator or lifting slot over an array-valued operand, a `LAMBDA` body and an array-entered
+     * block are array mode — and the mode is inherited through every call that does not set it.
+     * Outside a calculation this is `false`.
+     */
+    isImplicitIntersect(): boolean;
     /**
      * Resolves a range reference at runtime, returning an {@link IReferenceRange}.
      *
@@ -277,6 +310,7 @@ export interface IFormulaContext {
      *
      * @param criteria The criteria, exactly as the user wrote it — a comparison (`">10"`, `"<>x"`),
      * a wildcard pattern (`"a*"`), or a literal of any type.
+     * @param options How the criteria is matched. See {@link IFormulaContext.CriteriaOptions}.
      * @returns A predicate to test cell values with. Call it once per cell.
      *
      * @remarks
@@ -298,7 +332,7 @@ export interface IFormulaContext {
      * const count = range.reduce((total, value) => matches(value) ? total + 1 : total, 0);
      * ```
      */
-    createCriteria(criteria: Scalar): IFormulaContext.CriteriaEvaluator;
+    createCriteria(criteria: Scalar, options?: IFormulaContext.CriteriaOptions): IFormulaContext.CriteriaEvaluator;
     /**
      * Reads a typed literal in the workbook's language — the parse side of {@link toText}.
      *
@@ -386,6 +420,30 @@ export interface IFormulaContext {
      * ```
      */
     getNow(): number;
+    /**
+     * Returns a random number in `[0, 1)`, like `Math.random()`.
+     *
+     * @remarks
+     * Always draw through this, never `Math.random()`. The source is the runtime's, so a test or a
+     * replay can seed it, and the engine sees the draw: a draw is a PER-CELL read — two cells calling
+     * the same function in one pass differ — where `getNow` is one value for the whole pass, and the
+     * engine only shares an evaluation across the cells of a block when nothing per-cell was read.
+     * Pair it with `Volatile<T>` so the function draws again on the next pass.
+     *
+     * Under a seeded runtime ({@link IRuntime.getRandomSeed}) each draw is keyed by the cell, the
+     * pass and which draw it is within that cell, so a function that draws more than once gets
+     * distinct values and a cell gets the same ones however the pass was ordered. Take the draws
+     * where they are used rather than hoisting them, and the values follow the cells rather than
+     * the code path.
+     *
+     * @example
+     * ```typescript
+     * export function RAND(): Volatile<number> {
+     *   return FormulaContext.getRandom();
+     * }
+     * ```
+     */
+    getRandom(): number;
     /**
      * Returns `true` if the value is a usable date — either a `Date` or a number in the
      * workbook's serial date range.
@@ -447,14 +505,12 @@ export interface IFormulaContext {
      * Fields may fall outside their normal range and carry, which is what makes `DATE` and
      * `TIME` arithmetic work: month 13 is January of the next year, hour 50 is two days plus
      * two hours, and `getSerialDate(1900, 1, 0)` is serial 0. The `day` carries in SERIAL
-     * space, so it runs through the phantom `1900-02-29` — measured 25/25 by
-     * `probe-date-1900-day-overflow.ps1`.
+     * space, so it runs through the phantom `1900-02-29`.
      *
      * **This validates nothing, and that is deliberate — a caller MUST choose its own
      * policy.** No range check, no clamping, no bounds on any field, and no `DATE`-style
      * `0..1899 -> +1900` year offset. Those belong to `DATE`'s ARGUMENTS, not to the
-     * calendar, and the three things that prove it were measured together
-     * (`probe-date-arg-layer.ps1`, 2026-08-20):
+     * calendar, and three things prove it:
      *
      * * **The day policy is the caller's.** `DATE` and `DATEDIF`'s `md`/`yd` re-anchoring
      *   want the raw carry above — `DATEDIF("2020-01-31","2020-03-01","md")` is `-1`
@@ -523,6 +579,26 @@ export declare namespace IFormulaContext {
      * there.
      */
     type CriteriaEvaluator = (value: Scalar) => boolean;
+    /**
+     * How a criteria is matched — see {@link IFormulaContext.createCriteria}.
+     */
+    interface CriteriaOptions {
+        /**
+         * Where a TEXT criteria has to line up with the cell: `'whole'` (the default) for the whole
+         * cell, `'start'` for a prefix.
+         *
+         * @remarks
+         * The `D` functions' criteria table is the prefix form and the `*IF` family is not: the
+         * criterion `appl` takes the row whose value is `Apple` at `DSUM` and no row at all at
+         * `COUNTIF`, and the empty criterion — a prefix of everything — takes every TEXT cell at
+         * `DSUM` where `COUNTIF` takes only a cell that IS an empty string.
+         *
+         * It applies to a criteria that stays TEXT and to nothing else. An OPERATOR turns it off
+         * (`=appl` selects no row), and so does a criteria that reads as a number, a boolean or an
+         * error — `1` does not reach a cell holding `12`.
+         */
+        anchor?: 'whole' | 'start';
+    }
     /**
      * A serial date split into fields — see {@link IFormulaContext.getDateParts}.
      *

package/types/src/IFunction.d.ts

@@ -1,6 +1,6 @@
 import { Scalar } from './Scalar';
 import { ScalarType } from './ScalarType';
-import { CompatFeature } from './Compat';
+import { ValueKind } from './ValueKind';
 /**
  * A self-describing, type-safe, executable function.
  *
@@ -36,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.
      *
@@ -126,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.errors}
+         * @see {@link ParameterTypeJSON.acceptError}
          */
-        getErrorPolicy(): 'accept' | 'accept-ref' | null;
+        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.valueOrRange}
+         */
+        isValueOrRange(): boolean;
         /**
          * Indicates whether the parameter is required.
          */
@@ -182,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.
+         */
+        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.
          */
-        getEnums(): readonly string[];
+        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
@@ -197,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.
@@ -210,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,
@@ -238,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.
          *
@@ -253,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;
         /**
@@ -298,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.
@@ -395,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.
@@ -455,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}.
          */
-        enums?: string[];
+        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}.
+         */
+        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
@@ -486,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.
@@ -499,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.
@@ -510,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.
          *
@@ -587,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.
@@ -604,20 +913,6 @@ export declare namespace IFunction {
          * @defaultValue false
          */
         cancelable?: boolean;
-        /**
-         * Named engine behaviors this function opts into, from the `@compat` doc tag.
-         *
-         * @remarks
-         * Canonical spellings, deduplicated and in declaration order; a family alias the author wrote
-         * (`@compat atp`) has already been expanded to its atomic features. An unknown name never
-         * reaches here — the linter fails the build on one, deliberately: a compatibility rule that
-         * silently no-ops is the worst failure available, because the fixtures keep passing and the
-         * behavior is simply absent.
-         *
-         * @see {@link CompatFeatures}
-         * @see {@link CompatAliases}
-         */
-        compat?: CompatFeature[];
     }
 }
 //# sourceMappingURL=IFunction.d.ts.map