validate.ts

/**
 * Shared expression validator (ADR-0032 §Decision 1/5).
 *
 * One validator, used by every author surface — `objectstack build`,
 * `registerFlow`/metadata registration, and the agent-callable
 * `validate_expression` tool — so a malformed expression is caught the same
 * way everywhere, with a message written for **self-correction** (Decision 1d):
 * it states what is wrong AND the correct form.
 *
 * Field roles map to dialects (Decision 2):
 *   - `predicate`  → bare CEL returning bool (`record.rating >= 4`)
 *   - `value`      → bare CEL of any type   (`daysFromNow(3)`)
 *   - `template`   → text with `{{ path }}` holes (`Hot lead: {{ record.name }}`)
 *
 * The #1 author error (human or LLM) is wrapping a field reference in single
 * `{…}` braces inside a CEL field — `{x}` parses as a CEL map literal and fails.
 * This validator detects that specific mistake and returns the exact fix.
 */

import {
  compileCel,
  firstUndeclaredReference,
  firstDateTextVerdict,
  firstTypeMismatch,
  inferCelType,
  parseCelToAst,
  parseCelToAstWithReason,
  type CelAstNode,
  type FieldCelType,
} from './cel-engine';
import { templateEngine } from './template-engine';
import { findTraversalConflicts, readRootMembers, traversalsOf, type RootMemberRead } from './relationship-traversal';
import { REFERENCE_VALUE_TYPES } from '@objectstack/spec/data';
// #13594 — the one reader of cel-js's `found no matching overload for '…'`
// template. Both this module (which asks whether the name is ADVERTISED, to word
// a hint) and `firstUnknownFunctionCall` (which asks whether the environment
// REGISTERS it, to give the `@objectstack/lint` gate an existence verdict) must
// agree on WHICH token cel-js was talking about, so the extraction is shared and
// the pattern has one home.
import {
  callNameFromNoOverload,
  isReceiverRegistered,
  receiverCallNameFromNoOverload,
} from './unknown-function';
import { DEFAULT_TRAVERSAL_ROOT, type TraversalConflictKind } from './relationship-traversal';
import { optionLabelFieldOf, optionlessLabelSentence } from './stdlib';
import type {
  CelFieldRole,
  ExprValidationCode,
  ExpressionRefusal,
  ExpressionRefusalParams,
  ExpressionSourceKind,
} from './expression-refusal';
import type { CelLimitKey } from './cel-engine';

export type FieldRole = 'predicate' | 'value' | 'template';

/**
 * Loose input accepted by the validator: a bare string, or any object exposing
 * `dialect`/`source` (the Expression envelope, or a not-yet-narrowed value from
 * a `config.condition` / `edge.condition` field). Kept structural so call sites
 * need not pre-narrow to the strict {@link Expression} dialect union.
 */
export type ExprInput = string | { dialect?: string; source?: string } | null | undefined;

/** Optional schema context for field-existence checks (Decision 1b, v1). */
export interface ExprSchemaHint {
  /** Object the expression is authored against (for error text). */
  objectName?: string;
  /**
   * Known top-level field names, so each member read on `record` / `previous`
   * can be checked — in every spelling that names a member: `record.f`,
   * `record.?f`, `record['f']`, `record[?'f']`, and the same inside `has(…)`.
   * A computed key (`record[someVar]`) names no member before evaluation and
   * gets no verdict.
   */
  fields?: readonly string[];
  /**
   * The object's read attachments (`ObjectSchema.attachedOnRead`) — block name
   * → the leaf keys that block declares. A block is computed per caller and
   * attached to each served row, never stored, so it is not a field; this map
   * lets the field-existence pass judge the SECOND segment of
   * `record.<block>.<leaf>` (and `previous.…`, in every member spelling): a
   * leaf the block does not declare is refused under the same `unknown-field`
   * code, and the refusal names the leaves the block does declare.
   *
   * It only ADDS the second-segment judgement. Whether `record.<block>`
   * resolves at all is still {@link fields}' question, so a caller lists each
   * block name there too (`@objectstack/lint`'s field index does). Absent or
   * empty ⇒ only first segments are judged, exactly as before this key.
   */
  attachedOnRead?: Readonly<Record<string, readonly string[]>>;
  /**
   * #1928 tier 4 — field name → spec field type (`'text'`, `'currency'`,
   * `'boolean'`, `'date'`, …). Enables the advisory type-soundness check: a
   * text or boolean field used with an arithmetic/ordering operator against a
   * number faults at runtime and the expression silently evaluates to `null`,
   * so it is surfaced as a NON-blocking warning. Absent ⇒ the check is skipped.
   * Consulted at both scopes: `record.<field>` at a `'record'` site, the bare
   * `<field>` and its `record.<field>` / `previous.<field>` read at a
   * `'flattened'` one (#29959).
   */
  fieldTypes?: Readonly<Record<string, string>>;
  /**
   * Evaluation scope of the authoring site — determines whether a bare top-level
   * identifier is legal (#1928):
   *  - `'record'`    → the record is bound only as the `record` namespace, with
   *                    no field flattening (`Field.formula`, object validation
   *                    predicates). A bare `amount` resolves to nothing and the
   *                    expression silently evaluates to `null` / never fires, so
   *                    it MUST be written `record.amount`. We flag bare refs.
   *  - `'flattened'` → the record's own fields are spread to top-level alongside
   *                    flow variables (flow / automation conditions), so bare
   *                    `status` is correct and is NOT an error. Flow variables
   *                    are not schema-knowable, so a non-field bare identifier
   *                    can't be soundly told apart from a typo — but when one is
   *                    a near-miss of a known field we emit a non-blocking
   *                    did-you-mean *warning*. (Default.)
   */
  scope?: 'record' | 'flattened';
  /**
   * Binding roots THIS authoring surface mounts **beyond** the platform
   * baseline (`SCOPE_ROOTS`) — the surface naming the roots it binds, so the
   * validator keeps refusing every other one instead of standing down.
   *
   * ## What it is for
   *
   * `scope` answers "are the record's fields flattened here?". It cannot answer
   * "what else is mounted here?", and some surfaces mount something else. A
   * page component's `visibleWhen` is the worked case: `page.zod.ts`'s describe
   * states its contract-bound roots as `record`, `current_user` **and page
   * state as `page.<var>`**, and ends with the example `page.selectedProjectId
   * != ''`. `page` is not in the platform baseline and has no business being
   * there — a hook condition or a validation rule binds nothing of the sort —
   * so before this key the two faces of `scope` were the only choices, and
   * neither is correct for that surface:
   *
   *   - `'record'`    refuses `page.selectedProjectId != ''` — the spec's own
   *                   worked example — and prescribes `record.page`, which
   *                   names nothing on any layer;
   *   - `'flattened'` accepts it, and accepts a bare `status` with it, which is
   *                   the narrowing the surface wanted in the first place.
   *
   * Declaring `roots: ['page']` keeps the narrowing and stops the false
   * refusal: `page.selectedProjectId != ''` resolves, `status == 'done'` is
   * still the hard error it should be.
   *
   * ## Direction — this key only ADDS, and that is deliberate
   *
   * A root listed here is declared alongside the baseline, never instead of it:
   * passing `roots` can only turn a refusal into an acceptance, never the
   * reverse, so a caller that adopts it cannot silently lose a check it has
   * today. The opposite direction — a surface that binds a **closed** set and
   * must refuse a baseline root (`os`, `vars`) it never mounts — is NOT this
   * key's job and must not be bolted onto it: that surface says so with
   * `collectCelRootIdentifiers`, which reads the AST and is independent of any
   * declaration here. `SCOPE_ROOTS`'s own docblock is the authority on why
   * those are two mechanisms rather than one.
   *
   * ## Shape
   *
   * Plain declarative data — a list of names the caller already knows, not a
   * resolver callback the validator would have to invoke. `@objectstack/lint`'s
   * view/page gate already supplies exactly such a list to
   * {@link firstUndeclaredReference} (`VIEW_PAGE_EXTRA_ROOTS`); this key is the
   * same vocabulary reaching the shared validator, so a surface can declare its
   * roots without dropping out of `validateExpression` — and losing the compile
   * check, the braces hint, field existence, the role catalog and the
   * type-soundness pass with it.
   */
  roots?: readonly string[];
  /**
   * ADR-0068 D4 — the closed catalog of valid role names (built-in + declared).
   * When supplied, a role-membership predicate testing a role NOT in this set
   * (e.g. `'org_admni' in current_user.positions`) is flagged as an error. Closes
   * the AI-hallucination hole where a model invents a plausible-but-nonexistent
   * role that then silently never matches. Absent => role checks are skipped.
   */
  roleCatalog?: readonly string[];
  /**
   * [#18682] Opt IN to the relationship-traversal conflict checks.
   *
   * ⭐ Deliberately opt-in rather than derived from `fieldTypes`, because the
   * prescription these checks hand out is only TRUE where something hydrates.
   * `record.<reference field>.<field>` resolves the related record at exactly
   * one seam — the object validation rules (`script` / `cross_field`) evaluated
   * by ObjectQL's `checkPredicate` — and, since #24197, a formula field's
   * `expression` (role `value`), whose read path ObjectQL preloads one hop for.
   * Nothing hydrates at a field `requiredWhen` /
   * `readonlyWhen`, an option `visibleWhen`, an action's `visible` / `disabled`,
   * a sharing-rule (RLS) condition, a hook condition, or a flow node or edge
   * condition. Telling an author at one of those sites to
   * "write `record.account.id` instead" produces an expression that faults at
   * evaluation — and on the fail-OPEN seams among them, a faulting predicate
   * stops enforcing altogether. So the refusal would trade a working rule for a
   * dead one, at the seams the traversal capability never covered.
   *
   * Honoured for the `predicate` and `value` roles only; on `value` the
   * conflicts are worded for a formula (it reads null; there is no write to
   * refuse). Only a formula field's `expression` is a `value` site the engine
   * hydrates, so only that caller should set it on `value`.
   *
   * Set it only where the traversal is actually served. Absent ⇒ the checks do
   * not run, which is every caller's behaviour until it opts in.
   */
  traversalHydration?: boolean;
  /**
   * [#28659] The fields of {@link fields} that declare options once served —
   * the fields `label(record.<field>)` can answer on: inline `options`, or a
   * `picklist` the registry resolves onto the served field. Read an authored
   * field through `declaresOptionsOnceServed` (`stdlib.ts`), whose served-form
   * half is `declaresOptions`, the predicate the engine builds its label map
   * with, so this list and the evaluator agree.
   *
   * When supplied, every `label(record.<field>)` call naming a field that IS
   * declared ({@link fields}) but is not in this list is refused under
   * `label-field-no-options`: the evaluator faults on that call on every row,
   * so the formula reads null forever. A field {@link fields} does not declare
   * keeps its `unknown-field` refusal and gets no second one.
   *
   * Opt-in, like {@link traversalHydration}: absent ⇒ the check does not run,
   * because a caller that does not have the object's options in hand cannot
   * tell an optionless field from one it was not told about. Needs
   * {@link fields}; without it nothing is judged.
   */
  optionFields?: readonly string[];
  /**
   * [#29904, #29926] What the site's runtime does when this expression FAULTS,
   * as declared by the caller that knows the site — the validator cannot tell a
   * validation rule's `predicate` from a flow condition's. The tokens are the
   * null-guard verdict's `NullGuardOutcome` (`@objectstack/lint`), so one site
   * names one outcome to both verdicts.
   *
   * `'fail-closed'`: an expression that cannot be evaluated refuses the write
   * (or aborts the operation) it guards instead of being skipped — a
   * `severity: 'error'` object validation rule, a field `requiredWhen` /
   * `readonlyWhen`, an option `visibleWhen` on the write path, a hook
   * `condition`.
   *
   * `'run-fails'`: a record-triggered flow's start, edge or `decision` branch condition — the
   * engine's `evaluateCondition` throws on the fault (ADR-0032 §1c), so the
   * run fails there, while the record-change trigger isolates the write that
   * fired it: the write lands, the flow's work is not done.
   *
   * `'fail-open'`: an advisory (`severity: 'warning' | 'info'`) validation
   * rule — a rule that cannot be evaluated is skipped and logged, the write
   * proceeds, and the rule never gives its advisory (#24782).
   *
   * With any of the three, a `type-mismatch` (text or a boolean ordered /
   * arithmetic'd against a number) is an ERROR under that outcome's own code
   * and wording — the severity the nullable-comparison verdict already has at
   * the same sites. Absent at a `record`-scoped site: a fault reads as null (a
   * formula field), and `type-mismatch` stays the advisory warning whose
   * "evaluates to null" text is true there. Absent at a `'flattened'` (flow)
   * site: `type-mismatch-run-may-fail`, a warning saying the run fails where
   * the condition faults (#29959) — a flow condition never reads null.
   */
  faultOutcome?: ExprFaultOutcome;
  /**
   * [#29959] `'flattened'` scope only: the names the flow's run binds BEFORE it
   * flattens the record's fields — its declared variables and node ids
   * (`@objectstack/lint`'s `collectFlowVariableNames`), and the names the
   * engine binds over the flattening. `seedRunVariables` seeds those first and
   * the flattening skips a name already bound, so a bare read of one holds the
   * variable, not the field: the type-soundness check does not type it as the
   * field. `record.<name>` / `previous.<name>` still read the field and stay
   * typed. Absent ⇒ every bare field name is typed, exactly as before this key.
   */
  flowVariables?: readonly string[];
  /**
   * [#30025] `'flattened'` scope only: the flow's run can bind a name no static
   * reader sees — a node that hands out the live variable map or folds a
   * resume bag in (`script`, `connector_action`, `wait`, `subflow`, `map`, a
   * screen with no input contract; `@objectstack/lint`'s `flowCelRootScope`
   * over the flow's nodes, `provable: false`). A bare name
   * is then not proven to hold the field, so a bare-name `type-mismatch` takes
   * no declared {@link faultOutcome}: it is the `type-mismatch-run-may-fail`
   * warning. A `record.<name>` / `previous.<name>` read still reads the field
   * and keeps the outcome. Absent ⇒ every verdict is exactly as before this key.
   */
  bareNamesUnproven?: boolean;
}

/**
 * [#29926] What a site's runtime does once an expression there faults — see
 * {@link ExprSchemaHint.faultOutcome}.
 */
export type ExprFaultOutcome = 'fail-closed' | 'run-fails' | 'fail-open';

/**
 * One refusal (in `errors[]`) or advisory (in `warnings[]`).
 *
 * `code` and `params` say the same thing as `message`, for a consumer that
 * renders its own words: `code` is one of the closed set in
 * `expression-refusal.ts` and `params` are the values `message` interpolates.
 * `message` is the English sentence, unchanged.
 */
export type ExprValidationError = {
  /** Self-correcting message: what is wrong + the correct form. */
  message: string;
  /** The offending source, echoed for location. */
  source: string;
} & ExpressionRefusal<ExprValidationCode>;

/**
 * Build one {@link ExprValidationError}. The single place the correlation
 * between `code` and `params` is asserted; every call site is checked against
 * {@link ExpressionRefusalParams} for its own code.
 */
function refusal<Code extends ExprValidationCode>(
  code: Code,
  params: ExpressionRefusalParams[Code],
  source: string,
  message: string,
): ExprValidationError {
  return { source, message, code, params } as ExprValidationError;
}

/** A traversal conflict's kind → the refusal code it is reported under. */
const TRAVERSAL_CONFLICT_CODE: Readonly<Record<TraversalConflictKind, 'traversal-bare-and-traversed' | 'traversal-multi-hop'>> = {
  'bare-and-traversed': 'traversal-bare-and-traversed',
  'multi-hop': 'traversal-multi-hop',
};

export interface ExprValidationResult {
  ok: boolean;
  errors: ExprValidationError[];
  /**
   * Non-blocking advisories (#1928 tier 3): a likely-typo'd field reference in a
   * flattened flow condition. Never affects `ok` — callers surface these without
   * failing the build, since a bare identifier there may legitimately be a flow
   * variable.
   */
  warnings: ExprValidationError[];
}

/**
 * #1928 / #3306 — spec field type → the CEL type it is declared as for the
 * type-soundness check. Pinned to a concrete type ONLY where a specific misuse
 * always faults the runtime; numbers/currency/percent, selects (option values
 * may be numeric codes), lookups, media, JSON stay `dyn` because the runtime
 * rescues them. Any field type absent from this map is treated as `dyn`. Keeping
 * the map narrow is the source of the check's near-zero false-positive rate.
 */
const SPEC_TYPE_TO_CEL: Readonly<Record<string, FieldCelType>> = {
  // Free text — arithmetic / ordering against a number is (almost) always a bug.
  text: 'string', textarea: 'string', email: 'string', url: 'string',
  phone: 'string', markdown: 'string', html: 'string', richtext: 'string',
  // Booleans — arithmetic / ordering against a number ALWAYS faults at runtime.
  boolean: 'bool', toggle: 'bool',
  // Dates — ARITHMETIC against a number always nulls (`date − date + 1`, `date + n`,
  // #3306). Only arithmetic is flagged; ordering / equality / concatenation of a
  // date field are runtime-tolerated (see `firstTypeMismatch`).
  date: 'timestamp', datetime: 'timestamp',
};

/** Map an object's field-type hints onto the CEL types the soundness check uses. */
function toCelFieldTypes(fieldTypes: Readonly<Record<string, string>>): Record<string, FieldCelType> {
  const out: Record<string, FieldCelType> = {};
  for (const [name, specType] of Object.entries(fieldTypes)) {
    out[name] = SPEC_TYPE_TO_CEL[specType] ?? 'dyn';
  }
  return out;
}

/**
 * [#29926] The `type-mismatch` verdict at a site that declares its fault
 * outcome ({@link ExprSchemaHint.faultOutcome}): the code each outcome is
 * served under, and the clause that says what the runtime really does. Keyed
 * by the outcome, so a new outcome without its own code and wording does not
 * compile.
 */
const TYPE_MISMATCH_FAULT_ARMS: {
  readonly [O in ExprFaultOutcome]: {
    readonly code: 'type-mismatch-fail-closed' | 'type-mismatch-run-fails' | 'type-mismatch-fail-open';
    readonly clause: string;
  };
} = {
  'fail-closed': {
    code: 'type-mismatch-fail-closed',
    clause:
      'an expression that cannot be evaluated fails closed: the write (or the operation a hook guards) ' +
      'is refused, not skipped.',
  },
  'run-fails': {
    code: 'type-mismatch-run-fails',
    clause:
      'a flow condition that cannot be evaluated fails the run: the flow stops at this condition, the ' +
      'write that fired it still lands, and the work the flow exists to do is not done.',
  },
  'fail-open': {
    code: 'type-mismatch-fail-open',
    clause:
      'the rule is advisory, so a rule that cannot be evaluated is skipped, not refused: the write ' +
      'proceeds, the rule is never applied (its advisory never fires), and the only trace is a log line ' +
      'saying it could not be evaluated.',
  },
};

/**
 * #1928 / #3306 — a type-soundness verdict for an expression, or `null` when
 * sound. Two categories, with different severities:
 *  - `date-arith` (**error**): arithmetic on a date field against a number
 *    (`date − date + 1`, `today() + 30`) — always nulls at runtime and never
 *    recovers, so it blocks the build.
 *  - `type-mismatch` (**warning**): a text/boolean field used with an
 *    arithmetic/ordering operator against a number — nulls unless the text value
 *    happens to be numeric, so it stays advisory. An **error** where the caller
 *    declares the site's fault outcome (`faultOutcome`, #29904 / #29926):
 *    there the fault is not a null but a refused write, a failed flow run or a
 *    rule that never applies, each under its own code
 *    ({@link TYPE_MISMATCH_FAULT_ARMS}). In a flattened (flow) condition with
 *    no declared outcome it is `type-mismatch-run-may-fail`, still a warning,
 *    worded for the failed run a fault there is (#29959); a flattened
 *    condition's `record.<field>` / `previous.<field>` read is judged as its
 *    bare name is.
 *  - `date-text-arithmetic` / `date-duration-value` (**error**, #28944): what
 *    the Timestamp typing passes, re-checked with a date field declared as the
 *    text the runtime holds — see {@link dateTextIssue}.
 * `scope` selects `record.<field>` vs bare field binding, shaping the message.
 */
function typeSoundnessIssue(
  source: string,
  fieldTypes: Readonly<Record<string, string>>,
  scope: 'record' | 'flattened',
  role: 'predicate' | 'value',
  faultOutcome: ExprSchemaHint['faultOutcome'],
  flowVariables?: readonly string[],
  bareNamesUnproven?: boolean,
): { issue: ExprValidationError; severity: 'error' | 'warning' } | null {
  const celFieldTypes = toCelFieldTypes(fieldTypes);
  // [#29959] A bare name a flow variable holds is not the field (see
  // `ExprSchemaHint.flowVariables`), for every bare-name verdict here.
  const shadowed = scope === 'flattened' && flowVariables && flowVariables.length > 0
    ? new Set(flowVariables)
    : undefined;
  let mismatch = firstTypeMismatch(source, celFieldTypes, scope, shadowed);
  // [#30025] Where the run can bind a bare name no reader sees
  // (`ExprSchemaHint.bareNamesUnproven`), a bare-name mismatch is not proven to
  // be the field's, so it takes no declared outcome. A `record.<field>` /
  // `previous.<field>` mismatch in the same source still does: with every bare
  // name left `dyn`, only the record-root pass can answer, and its answer wins.
  let outcome = faultOutcome;
  if (
    mismatch && scope === 'flattened' && bareNamesUnproven && faultOutcome !== undefined
    && mismatch.category === 'type-mismatch' && mismatch.root === undefined
  ) {
    const rootRead = firstTypeMismatch(source, celFieldTypes, scope, new Set(Object.keys(celFieldTypes)));
    if (rootRead && rootRead.root !== undefined) mismatch = rootRead;
    else outcome = undefined;
  }
  if (!mismatch) {
    const bareCelTypes = shadowed
      ? Object.fromEntries(Object.entries(celFieldTypes).filter(([name]) => !shadowed.has(name)))
      : celFieldTypes;
    return dateTextIssue(source, bareCelTypes, scope, role);
  }
  const reference = mismatch.field
    ? (mismatch.root !== undefined
      ? `${mismatch.root}.${mismatch.field}`
      : scope === 'record' ? `record.${mismatch.field}` : mismatch.field)
    : undefined;
  const ref = reference !== undefined ? `\`${reference}\`` : null;
  if (mismatch.category === 'date-arith') {
    const subject = ref ? `${ref} is a date` : 'a date field';
    return {
      severity: 'error',
      issue: refusal(
        'date-arithmetic',
        { operands: mismatch.operands, ...(reference !== undefined ? { reference } : {}) },
        source,
        `date arithmetic \`${mismatch.operands}\` — ${subject}, and CEL can't do arithmetic on ` +
          `dates: this faults at runtime, so the field silently evaluates to null. Use ` +
          `\`daysBetween(a, b)\` for the span in whole days, and \`daysFromNow(n)\` / ` +
          `\`addDays(d, n)\` / \`addMonths(d, n)\` to shift a date.`,
      ),
    };
  }
  const heldKind: 'boolean' | 'text' = mismatch.celType === 'bool' ? 'boolean' : 'text';
  const held = heldKind === 'boolean' ? 'a boolean' : 'text';
  const subject = ref ? `${ref} holds ${held}` : `${held === 'a boolean' ? 'a boolean' : 'a text'} field`;
  const params = {
    operands: mismatch.operands,
    operator: mismatch.operator,
    held: heldKind,
    ...(reference !== undefined ? { reference } : {}),
  };
  // [#29904] Measured on the evaluator: `record.name > 5` faults on `"abc"`
  // and on null, and the ADR-0032 §1c rescue answers only numeric text
  // (`"7"`). `size()` answers text; `double()` / `int()` validate clean but
  // fault on text that is not a number — so the hint says so.
  const operand = reference ?? (heldKind === 'boolean' ? 'the field' : 'the text');
  const convert = heldKind === 'boolean'
    ? 'Compare a boolean with `true` / `false`, or use a number field.'
    : `Compare like with like: use a number field, compare text with text, or convert ` +
      `explicitly — \`size(${operand})\` for its length, \`double(${operand})\` for its value ` +
      `(which itself faults on text that is not a number).`;
  const faults =
    `type mismatch \`${mismatch.operands}\` — ${subject} but is used with \`${mismatch.operator}\` ` +
    `against a number. CEL has no such operation, so wherever the value is not numeric text ` +
    `(an empty value included) the expression faults`;
  if (outcome !== undefined) {
    // [#29926] One code per outcome: a code names ONE message template
    // (`expression-refusal.ts`), and the three outcomes are three sentences.
    const arm = TYPE_MISMATCH_FAULT_ARMS[outcome];
    return {
      severity: 'error',
      issue: refusal(arm.code, params, source, `${faults}, and here ${arm.clause} ${convert}`),
    };
  }
  if (scope === 'flattened') {
    // [#29959] A flattened condition is a flow's, and the engine's
    // `evaluateCondition` throws on a fault (ADR-0032 §1c) on every flow: it
    // never reads null. The caller declared no outcome because what the run
    // binds under the name is not proven to be the field's value there — a
    // flow whose entrance hands over an API request body, an action's partial
    // record, a parent's record or nothing; a node's inert `condition` — so
    // the mismatch stays a warning, worded for the run without naming the
    // flow's kind (the engine's registration log serves it on every flow).
    return {
      severity: 'warning',
      issue: refusal(
        'type-mismatch-run-may-fail',
        params,
        source,
        `${faults}, and a flow condition that faults when it is evaluated fails the run: the flow stops ` +
          `at this condition and the work it exists to do is not done (it does not read null). Whether ` +
          `${ref ?? 'the field'} holds ${held} there depends on what the run binds, which this check cannot ` +
          `prove here, so this is a warning, not a refusal. ${convert}`,
      ),
    };
  }
  return {
    severity: 'warning',
    issue: refusal(
      'type-mismatch',
      {
        operands: mismatch.operands,
        operator: mismatch.operator,
        held: heldKind,
        ...(reference !== undefined ? { reference } : {}),
      },
      source,
      `type mismatch \`${mismatch.operands}\` — ${subject} but is used with \`${mismatch.operator}\` ` +
        `against a number. This faults at runtime, so the expression silently evaluates to null ` +
        `(unless the value happens to be numeric). Use a number field, or drop the arithmetic/comparison.`,
    ),
  };
}

/**
 * #28944 — the date shapes the Timestamp typing of {@link firstTypeMismatch}
 * passes and the runtime cannot answer, judged by {@link firstDateTextVerdict}
 * with every `date`/`datetime` field declared as the text the runtime holds:
 *  - `date-text-arithmetic`: arithmetic on that text the evaluator faults on —
 *    `record.end_date - record.start_date` (either field kind), `record.d -
 *    duration('24h')` — so the expression reads null. Any role.
 *  - `date-duration-value`: a formula (`value` role) that computes a
 *    `google.protobuf.Duration` — `today() - record.start_date` — which a field
 *    serialises as `{}`. A predicate that COMPARES a duration
 *    (`today() - record.d > duration('72h')`) evaluates, and is not touched.
 * Runs only when there is something to find: a date field to retype, or a
 * `value` whose computed type is the question.
 */
function dateTextIssue(
  source: string,
  celFieldTypes: Readonly<Record<string, FieldCelType>>,
  scope: 'record' | 'flattened',
  role: 'predicate' | 'value',
): { issue: ExprValidationError; severity: 'error' | 'warning' } | null {
  if (role !== 'value' && !Object.values(celFieldTypes).includes('timestamp')) return null;
  const verdict = firstDateTextVerdict(source, celFieldTypes, scope);
  if (!verdict) return null;
  const reference = verdict.field
    ? (scope === 'record' ? `record.${verdict.field}` : verdict.field)
    : undefined;
  const ref = reference !== undefined ? `\`${reference}\`` : null;
  const shift = `\`daysFromNow(n)\` / \`addDays(d, n)\` / \`addMonths(d, n)\` to shift a date.`;
  if (verdict.kind === 'fault') {
    const subject = ref ? `${ref} is a date field` : 'a date field is an operand';
    return {
      severity: 'error',
      issue: refusal(
        'date-text-arithmetic',
        { operands: verdict.operands, ...(reference !== undefined ? { reference } : {}) },
        source,
        `date arithmetic \`${verdict.operands}\` — ${subject}, and the runtime holds a date field as ` +
          `its text (\`YYYY-MM-DD\`, or an ISO-8601 instant for a date-time), which CEL can't do ` +
          `arithmetic on: this faults at runtime, so the field silently evaluates to null. Use ` +
          `\`daysBetween(a, b)\` for the span in whole days, and ${shift}`,
      ),
    };
  }
  if (role !== 'value' || verdict.type !== 'google.protobuf.Duration') return null;
  return {
    severity: 'error',
    issue: refusal(
      'date-duration-value',
      reference !== undefined ? { reference } : {},
      source,
      `date arithmetic — this computes a \`google.protobuf.Duration\`${ref ? ` from ${ref}` : ''}, and a ` +
        `field can't hold a duration: it reads \`{}\` at runtime. Use \`daysBetween(a, b)\` for the ` +
        `span in whole days, and ${shift}`,
    ),
  };
}

/** A bare `{x}` that is NOT part of a `{{x}}` mustache hole. */
const SINGLE_BRACE_RE = /(?:^|[^{])\{\s*([A-Za-z_$][\w.$]*)\s*\}(?!\})/;
/** The roots whose members the field-existence pass judges against `schema.fields`. */
const FIELD_EXISTENCE_ROOTS = ['record', 'previous'] as const;

/** The dialect a field role expects (Decision 2). */
export function expectedDialect(role: FieldRole): 'cel' | 'template' {
  return role === 'template' ? 'template' : 'cel';
}

/** `array` / `object` / `number` — never called with a string or nullish. */
function nonStringSourceKind(value: unknown): ExpressionSourceKind {
  if (Array.isArray(value)) return 'array';
  return typeof value as ExpressionSourceKind;
}

/** `an array` / `an object` / `a number` — the kind as the message renders it. */
function describeNonStringSource(kind: ExpressionSourceKind): string {
  if (kind === 'array') return 'an array';
  if (kind === 'object') return 'an object';
  return `a ${kind}`;
}

/**
 * Normalize the three authorable spellings — bare text, an envelope, absent —
 * into the dialect and the source text the checks below read.
 *
 * `nonStringSource` is the fourth population, which is not authorable at all: an
 * envelope whose `source` is present but is NOT a string. `ExprInput` declares
 * `source?: string`, so this cannot arrive through a typed call — but every
 * production call site casts, because the value comes out of METADATA, where the
 * declaration is a claim and not a guarantee. Read unguarded it reached
 * `source.trim()` and threw a bare `TypeError: source.trim is not a function`
 * out of a validator whose whole contract is that it never throws: callers that
 * exist to collect LOCATED findings (`AutomationEngine.validateFlowExpressions`,
 * `@objectstack/lint`'s stack walk) were bypassed entirely, so `registerFlow`
 * died on an internal message naming neither the flow nor the node, and
 * `objectstack validate` died naming neither the hook nor the sharing rule.
 *
 * The refusal is reported HERE, once, at the entry every predicate/value slot in
 * the platform shares — never by each caller wrapping the call in a try/catch,
 * which is the tolerant-consumer shape Prime Directive #12 forbids.
 *
 * ⚠️ Only a PRESENT non-string qualifies. `null` / `undefined` / a missing
 * `source` still normalize to `''` and still read as "not authored" (`ok: true`),
 * unchanged — including the `{ ast }` envelope, which carries no `source` at all
 * and whose admission is `ExpressionSchema`'s rule, not this function's.
 */
function toSource(input: ExprInput): { dialect?: string; source: string; nonStringSource?: ExpressionSourceKind } {
  if (input == null) return { source: '' };
  if (typeof input === 'string') return { source: input };
  const raw = (input as { source?: unknown }).source;
  if (raw == null) return { dialect: input.dialect, source: '' };
  if (typeof raw !== 'string') {
    return { dialect: input.dialect, source: '', nonStringSource: nonStringSourceKind(raw) };
  }
  return { dialect: input.dialect, source: raw };
}

/**
 * The refusal text for a non-string envelope `source`, shared by the message
 * every role composes. Deliberately NOT exported: the published surface of
 * `@objectstack/formula` does not move for this fix — the refusal travels the
 * `errors[]` channel that already exists, so no consumer needs a new symbol to
 * read it.
 */
const NON_STRING_SOURCE_REFUSAL =
  'an expression envelope carries its expression as a string `source`';

function bracesHint(source: string): { text: string; ref: string } | null {
  const m = SINGLE_BRACE_RE.exec(source);
  if (!m) return null;
  const ref = m[1];
  return {
    ref,
    text:
      `it looks like a \`{${ref}}\` template brace was used inside a CEL expression — ` +
      `\`{…}\` parses as a CEL map literal and fails. Write the bare reference instead, e.g. \`${ref}\`.`,
  };
}

/**
 * The prescription for a **bounds** refusal — an expression that is perfectly
 * good CEL and merely too big for the platform's parse budget (#7073).
 *
 * Until #7073 every `celEngine.compile` refusal got the same dialect trailer
 * ("`predicate`s are bare CEL (e.g. `record.rating >= 4`)"), byte for byte,
 * including this class. That sentence is actively wrong here: the source is
 * already bare CEL, so an author who obeys the last sentence they were given —
 * an LLM author above all — rewrites the dialect, learns nothing, and comes
 * back with the same 80-clause conjunction. The front half of the message
 * (cel-js's own `Exceeded maxAstNodes (256)`) was right all along; only the
 * prescription lied.
 *
 * The class comes from `celEngine.compile`'s own `kind: 'bounds'`; WHICH bound
 * and its value come from {@link parseCelToAstWithReason}, the same
 * reason-carrying entrance `@objectstack/lint`'s RLS gate reads (#6778 /
 * PR #6831 — the consumer-side instance of this same defect family). Called
 * WITHOUT `admitOverLimit`, so it takes neither the unbounded parse nor the
 * overrun measurement: this path needs only the bound's NAME, and a refusal
 * must not pay to re-parse a source it has just judged too large.
 *
 * ### Why the remedies are generic
 *
 * `validateExpression` is ADR-0032's shared validator: one message serves all
 * ~10 expression slots (flow/automation conditions, `Field.formula`, validation
 * rules, `visibleWhen`, `sharingRules[].condition`, the `validate_expression`
 * tool …). Their COMBINATION semantics differ, so PR #6831's RLS-specific
 * sentence ("splitting the top-level `&&` widens the grant") is not portable —
 * it is true for a security predicate and false, or merely meaningless, for a
 * formula value. Shrinking and denormalising are safe everywhere; splitting is
 * offered only with the caveat that the site decides what splitting means.
 */
function boundsHint(source: string): { text: string; limit?: CelLimitKey; limitValue?: number } | null {
  const parsed = parseCelToAstWithReason(source);
  // `celEngine.compile` said `bounds`, and both verdicts are graded by the same
  // `classifyCelFault`, so this holds — but a narrowing that ever stopped
  // holding must degrade to the old trailer, never to a wrong bound name.
  if (parsed.ok || parsed.kind !== 'bounds') return null;
  const { limit, limitValue } = parsed.overrun;
  const known = limit && limitValue != null ? { limit, limitValue } : null;
  const bound = known
    ? `the \`${known.limit}\` budget (limit ${known.limitValue})`
    : "one of the platform's parse budgets";
  return {
    ...(known ?? {}),
    text:
      `this is valid CEL that exceeds ${bound} — a SIZE fault, not a dialect mistake, so ` +
      `re-spelling the expression will not fix it. Shrink it (fewer clauses, shallower nesting, ` +
      `fewer list elements), or precompute the heavy part into a stored field and reference that ` +
      `field instead. Splitting it into several expressions changes how they combine at this ` +
      `authoring site, so check that site's semantics before doing that.`,
  };
}

/**
 * The nearest advertised callable to `name`, or `undefined` when nothing is
 * close enough that a suggestion beats silence.
 *
 * Deliberately STRICTER than {@link nearestName}'s shared budget, and that
 * difference is the entire reason this function exists rather than a call to
 * the shared one. `nearest` spends `max(2, floor(name.length / 3))` edits —
 * right for a field name checked against the handful of fields on one object,
 * measurably wrong against this catalog: `nearestName('can', CEL_STDLIB_FUNCTIONS)`
 * answers `'min'`. Two edits on a three-character name, jumping from a
 * permission verb to a numeric function — a confident suggestion across an
 * unrelated namespace, which is worse than silence. An author who takes it (an
 * LLM author above all, following the last sentence it was handed) writes
 * `min(object, verb)` and is further from working than before it asked.
 *
 * The budget here is proportional rather than floored: at most one edit per
 * three characters of the LONGER name, so at least two thirds of a suggestion
 * must already be typed. That keeps the case that makes suggesting worthwhile
 * (`isBlnk` → `isBlank`, one edit in seven) and refuses the measured hazard
 * (`can` → `min`, two edits in three). Both are pinned in `validate.test.ts`;
 * a change to this budget that loses either is a regression, not a tuning.
 *
 * The distance metric stays the module's one {@link levenshtein} — only the
 * acceptance budget is class-specific, which is what the hazard is about.
 */
function nearestCallable(name: string): string | undefined {
  let best: string | undefined;
  let bestDistance = Infinity;
  for (const candidate of CEL_STDLIB_FUNCTIONS) {
    const distance = levenshtein(name, candidate);
    if (distance > Math.floor(Math.max(name.length, candidate.length) / 3)) continue;
    if (distance >= bestDistance) continue;
    bestDistance = distance;
    best = candidate;
  }
  return best;
}

/**
 * The prescription for the **unknown-name** arm of a `type` refusal — an
 * expression that is perfectly good CEL and merely calls something by a name
 * that resolves to nothing in this position.
 *
 * The second leg of the repair {@link boundsHint} made for the `bounds` class
 * (#7073). Until this hint, every unknown-function refusal ended with the same
 * dialect trailer ("`predicate`s are bare CEL (e.g. `record.rating >= 4`)"),
 * and that sentence is actively wrong here for exactly the reason it was wrong
 * for `bounds`: the source already IS bare CEL and parses fine. An author who
 * obeys the last sentence they were given rewrites the dialect, learns nothing,
 * and comes back with the same unresolvable name. The front half (cel-js's own
 * `found no matching overload for '…'`) was right all along and is kept
 * verbatim; only the prescription lied.
 *
 * ### Why the name must be checked against the advertised catalog first
 *
 * cel-js emits ONE message shape for two different faults: a name that resolves
 * to nothing (`upperr(record.name)`) and a real function handed arguments no
 * overload accepts (`upper(1, 2)` → `found no matching overload for
 * 'upper(int, int)'`). Telling the second author that `upper` "is not a
 * callable name" would be a fresh false statement in place of a merely useless
 * one, so an advertised name falls through to the existing trailer untouched.
 *
 * ### Why the wording is "not a callable name HERE"
 *
 * {@link CEL_STDLIB_FUNCTIONS} is a curated bare-callable subset, not an oracle
 * for existence — 33 further names cel-js registers are callable only on a
 * receiver (`record.name.split(',')` works; bare `split(…)` faults here and
 * lands in this arm). So the message may say the name cannot be called in this
 * position, and may point at what IS advertised, but must not claim the name
 * does not exist. For the same reason it names no size: what the catalog
 * contains is being adjudicated separately, and a message asserting a count
 * would be falsified by that ruling.
 */
function unknownFunctionHint(celMessage: string): { text: string; name: string; suggestion?: string } | null {
  const name = callNameFromNoOverload(celMessage);
  if (!name || CEL_STDLIB_FUNCTIONS.includes(name)) return null;
  const suggestion = nearestCallable(name);
  return {
    name,
    ...(suggestion ? { suggestion } : {}),
    text:
      `\`${name}\` is not a callable name here — a NAME fault, not a dialect mistake, so ` +
      `re-spelling the expression will not fix it.` +
      (suggestion ? ` Did you mean \`${suggestion}\`?` : '') +
      ` The callable names this platform advertises for authoring are the \`functions\` list ` +
      `\`introspectScope\` returns (\`CEL_STDLIB_FUNCTIONS\`) — pick one of those, or precompute ` +
      `the value in a stored field and reference that field instead.`,
  };
}

/**
 * A plain dotted identifier chain written immediately left of `.name(` in
 * `source`, or `undefined` when the receiver is anything else.
 *
 * cel-js's message names the receiver's TYPE (`dyn.upper()`), never the
 * author's expression, so the only place the real receiver exists is the source
 * — and only the plain-chain shape can be lifted out of it safely. Anything
 * else (`record.tags[0].upper()`, `(a + b).upper()`, `'lit'.upper()`) returns
 * `undefined` so the caller prints a shape instead of a spelling: a
 * prescription that cannot be DERIVED must not be invented, or the repair
 * repeats the defect it fixes one level up.
 *
 * `name` reaches here having matched `[A-Za-z_$][\w$]*` AND been found in
 * {@link CEL_STDLIB_FUNCTIONS}, so it carries no regex metacharacter.
 *
 * Deliberately whitespace-intolerant around the dots: `record . name . upper()`
 * is legal CEL that nobody writes, and admitting it costs a quantifier that
 * backtracks (the ReDoS concern the role scanners below document). It falls
 * through to the generic sentence, which is correct, just less specific.
 */
function receiverChainInSource(source: string, name: string): string | undefined {
  const call = new RegExp(`[.]${name}\\s*\\(`).exec(source);
  if (!call) return undefined;
  const before = source.slice(0, call.index);
  const chain = /[A-Za-z_$][\w$]*(?:[.][A-Za-z_$][\w$]*)*$/.exec(before);
  if (!chain) return undefined;
  // The chain must START the receiver. A character that continues an expression
  // leftwards means the real receiver is larger than what matched — e.g.
  // `record.tags[0].name.upper()`, where the chain is `name` and the receiver
  // is not.
  if (chain.index > 0 && /[\w$.)\]'"]/.test(before[chain.index - 1])) return undefined;
  return chain[0];
}

/**
 * The prescription for the **receiver-call** arm of a `type` refusal — a
 * bare-callable stdlib function written as a method, `record.name.upper()`
 * (#14203).
 *
 * The third leg of the repair {@link boundsHint} (#7073) and
 * {@link unknownFunctionHint} (#13821) made for their own classes, and the one
 * neither could cover: the name is right, so the unknown-name arm stays silent
 * by design (calling `upper` "not a callable name" would be a fresh false
 * statement), and the fault is not size, so the bounds arm never sees it. What
 * was left was the dialect trailer — "`predicate`s are bare CEL" — handed to an
 * author whose source already IS bare CEL and parses fine. Advice that cannot
 * succeed, for the third time in the same shape.
 *
 * It is a high-frequency AI-author mistake rather than an exotic one: method
 * call syntax is what almost every other language uses for string operations,
 * so a generator that knows `upper` exists reaches for `record.name.upper()`
 * before `upper(record.name)`. And the correct spelling is derivable from the
 * fault itself, which is what makes a prescription honest here.
 *
 * ### The two keys, and why one of them is not enough
 *
 * **Membership of {@link CEL_STDLIB_FUNCTIONS}**, never the call shape alone.
 * The 33 receiver-only names cel-js registers (`split`, `map`,
 * `getFullYear`) are correct ONLY after a dot — `record.name.split(',')`
 * type-checks and never reaches here at all, and telling anyone to write
 * `split(record.name, ',')` would break working authoring.
 *
 * **Plus the environment's own record of the receiver form.** Seven advertised
 * names hold definitions of BOTH kinds — `contains`, `endsWith`, `matches`,
 * `size`, `startsWith`, `string`, `trim` — so catalog membership by itself
 * would answer `record.name.contains()` (a real receiver call with the wrong
 * arity) with "write `contains(record.name)`", which faults just as hard. That
 * class keeps the existing trailer: its fault is the ARGUMENTS, and grading
 * those is the blind spot #13594 deliberately keeps blind.
 */
function receiverCallHint(celMessage: string, source: string): { text: string; name: string; receiver?: string } | null {
  const name = receiverCallNameFromNoOverload(celMessage);
  if (!name || !CEL_STDLIB_FUNCTIONS.includes(name)) return null;
  if (isReceiverRegistered(name)) return null;
  const receiver = receiverChainInSource(source, name);
  return {
    name,
    ...(receiver ? { receiver } : {}),
    text:
      `\`${name}\` is callable bare, not as a method — a CALL-SHAPE fault, not a dialect ` +
      `mistake, so re-spelling the expression will not fix it. ` +
      (receiver
        ? `Write \`${name}(${receiver})\` instead.`
        : `Write \`${name}(…)\` with the receiver as its first argument instead.`) +
      ` The callable names this platform advertises for authoring (the \`functions\` list ` +
      `\`introspectScope\` returns, \`CEL_STDLIB_FUNCTIONS\`) take their subject as an ` +
      `argument; only cel-js's own receiver methods (\`record.name.split(',')\`) are written ` +
      `after a dot.`,
  };
}

/**
 * [#28659] Every `label(record.<field>)` call in `source` whose field is
 * declared but declares no options — one `label-field-no-options` refusal per
 * such field, worded as the evaluator's fault on the same call
 * (`optionlessLabelSentence`), so the door says at author time what the log
 * line would say on every row.
 *
 * The field a call names is read through `optionLabelFieldOf`, the reader the
 * `label` macro itself uses, so a call shape the macro refuses at the type
 * check (a computed argument, `record.?kind`) names no field here and is left
 * to that refusal. Runs only when the caller supplied
 * {@link ExprSchemaHint.optionFields} and {@link ExprSchemaHint.fields}; a
 * field outside `fields` is `checkFieldExistence`'s to refuse.
 */
function checkOptionLabelTargets(
  ast: () => CelAstNode | null,
  source: string,
  schema: ExprSchemaHint | undefined,
  errors: ExprValidationError[],
): void {
  if (!schema?.optionFields || !schema.fields || schema.fields.length === 0) return;
  // A source that never spells the call cannot hold one (CEL has no comments),
  // so the common formula pays one scan and no tree walk.
  if (!/\blabel\s*\(/.test(source)) return;
  const tree = ast();
  if (tree == null) return;
  const declared = new Set(schema.fields);
  const withOptions = new Set(schema.optionFields);
  const seen = new Set<string>();
  const visited = new Set<object>();
  const walk = (node: unknown): void => {
    if (!node || typeof node !== 'object' || visited.has(node)) return;
    visited.add(node);
    if (Array.isArray(node)) {
      for (const child of node) walk(child);
      return;
    }
    const { op, args } = node as { op?: unknown; args?: unknown };
    if (op === 'call' && Array.isArray(args) && args[0] === 'label' && Array.isArray(args[1]) && args[1].length === 1) {
      const field = optionLabelFieldOf(args[1][0] as { op: string; args: unknown } | undefined);
      if (field !== undefined && declared.has(field) && !withOptions.has(field) && !seen.has(field)) {
        seen.add(field);
        errors.push(refusal('label-field-no-options', { field }, source, optionlessLabelSentence(field)));
      }
    }
    for (const value of Object.values(node as Record<string, unknown>)) walk(value);
  };
  walk(tree);
}

/**
 * Every member `source` reads on `record` / `previous`, judged against
 * `schema.fields` — one `unknown-field` refusal per undeclared name.
 *
 * The members come from `readRootMembers`, the AST member reader the
 * relationship-traversal analysis is built on, so every spelling that names a
 * member is judged once and the same way: `record.f`, `record.?f`,
 * `record['f']`, `record[?'f']`, and any of them inside `has(…)`. A reader that
 * saw only the dot spelling let a typo written any other way reach the
 * evaluator with no authoring verdict, to fault there on every row instead.
 * A computed key (`record[someVar]`) names no member before evaluation, so it
 * gets no verdict here.
 *
 * `ast` is null only for a source the canonical front end will not parse; the
 * caller reaches this after `celEngine.compile` accepted the source, which owns
 * that verdict, so there is nothing to judge.
 */
function checkFieldExistence(
  ast: () => CelAstNode | null,
  source: string,
  schema: ExprSchemaHint | undefined,
  errors: ExprValidationError[],
): void {
  if (!schema?.fields || schema.fields.length === 0) return;
  const tree = ast();
  if (tree == null) return;
  const known = new Set(schema.fields);
  const seen = new Set<string>();
  const blocks = schema.attachedOnRead;
  const seenLeaves = new Set<string>();
  for (const read of readRootMembers(tree, FIELD_EXISTENCE_ROOTS)) {
    const field = read.field;
    if (known.has(field)) {
      // [#22211 ruling A] A head that names a declared read attachment has a
      // closed second segment: judge it against the block's declared leaves.
      // Own-key test, so an inherited name (`constructor`) is never a block.
      if (blocks && Object.prototype.hasOwnProperty.call(blocks, field)) {
        checkAttachedLeaf(source, schema.objectName, field, blocks[field], read, seenLeaves, errors);
      }
      continue;
    }
    if (seen.has(field)) continue;
    seen.add(field);
    const suggestion = nearest(field, schema.fields);
    errors.push(refusal(
      'unknown-field',
      {
        field,
        ...(schema.objectName ? { objectName: schema.objectName } : {}),
        ...(suggestion ? { suggestion } : {}),
      },
      source,
      `unknown field \`${field}\`${schema.objectName ? ` on \`${schema.objectName}\`` : ''}` +
        (suggestion ? ` — did you mean \`${suggestion}\`?` : ''),
    ));
  }
}

/**
 * [#22211 ruling A] The second segment of `record.<block>.<leaf>` when
 * `<block>` is a declared read attachment (`ExprSchemaHint.attachedOnRead`).
 *
 * The same `unknown-field` refusal as a first segment, with `field` naming the
 * dotted path as written, so a consumer rendering only the first-segment params
 * still says something true. The one addition is an optional clause naming the
 * leaves the block declares — the remedy — carried as `block` + `leaves`,
 * present together exactly when the message carries that clause.
 *
 * The leaf is judged in every spelling that names a member, exactly like the
 * block itself: `record.viewer.can_act`, `record.viewer.?can_act`,
 * `record.viewer['can_act']`, `record['viewer'][?'can_act']`, inside `has(…)`
 * or not. Unjudged, deliberately (each a missed catch, never a false refusal):
 * a computed key (`record.viewer[k]`), a method call on the block, which reads
 * the block's value rather than a member of it, and any segment past the
 * second — a leaf is a scalar, so a third segment is not this declaration's
 * question.
 */
function checkAttachedLeaf(
  source: string,
  objectName: string | undefined,
  block: string,
  leaves: unknown,
  read: RootMemberRead,
  seenLeaves: Set<string>,
  errors: ExprValidationError[],
): void {
  if (!Array.isArray(leaves)) return;
  const leaf = read.leaf;
  if (leaf === undefined) return;
  if (leaves.includes(leaf)) return;
  const field = `${block}.${leaf}`;
  if (seenLeaves.has(field)) return;
  seenLeaves.add(field);
  const declared = leaves.filter((l): l is string => typeof l === 'string');
  const nearLeaf = nearest(leaf, declared);
  const suggestion = nearLeaf ? `${block}.${nearLeaf}` : undefined;
  errors.push(refusal(
    'unknown-field',
    {
      field,
      ...(objectName ? { objectName } : {}),
      ...(suggestion ? { suggestion } : {}),
      ...(declared.length > 0 ? { block, leaves: declared } : {}),
    },
    source,
    `unknown field \`${field}\`${objectName ? ` on \`${objectName}\`` : ''}` +
      (declared.length > 0
        ? ` (the read attachment \`${block}\` declares ${declared.map((l) => `\`${l}\``).join(', ')})`
        : '') +
      (suggestion ? ` — did you mean \`${suggestion}\`?` : ''),
  ));
}

/**
 * Is `name` written as a NAMESPACE in `source` — `name.x`, `name?.x`,
 * `name['x']`, `name.fn(…)` — rather than as a bare value (`name == 'x'`)?
 *
 * The distinction is what lets a refusal speak about roots at all: an author
 * who wrote `pge.selectedProjectId` is treating `pge` as a namespace, and a
 * bare value reference (`stat == 'done'`) is not that, whatever it is named.
 */
function isNamespaceUse(name: string, source: string): boolean {
  // `name` reaches here from cel-js's `Unknown variable: X` capture, so it is
  // `[A-Za-z_$][\w$]*` — `$` is the only regex metacharacter it can carry.
  const escaped = name.replace(/\$/g, '\\$');
  return new RegExp(`(?<![\\w$.])${escaped}\\s*(?:\\?\\.|\\.|\\[)`).test(source);
}

/**
 * A ROOT-oriented refusal for a namespace reference that is one typo away from
 * a root this surface declared (`pge.selectedProjectId` where the surface binds
 * `page`) — or `null`, which leaves the generic bare-reference message and its
 * `record.<name>` prescription exactly as they were.
 *
 * Three guards keep this from ever prescribing the wrong fix, and each one is
 * load-bearing:
 *
 *  - **No declared roots ⇒ null.** Every call site that does not pass
 *    `schema.roots` — which is all of them until one opts in — gets the message
 *    it got before, byte for byte. The message change rides entirely inside the
 *    new opt-in.
 *  - **A known field ⇒ null.** `record.<name>` is the right fix for a bare
 *    field, JSON member access included (`address.city` → `record.address.city`),
 *    and a field named in `schema.fields` is exactly that case.
 *  - **Not a near-miss of a declared root ⇒ null.** Without a field catalog a
 *    namespace reference is genuinely ambiguous — a record field written bare,
 *    or a root that does not exist — and prescribing either one would be a
 *    guess. A name within the shared edit-distance threshold of a root the
 *    surface *does* mount is the one shape that is not ambiguous, so it is the
 *    only one that gets a second prescription. ⛔ Never widen this to emit both
 *    prescriptions at once: two findings pointing opposite ways is the shape
 *    the author cannot act on.
 */
function mistypedRootRefusal(
  bare: string,
  source: string,
  surfaceRoots: readonly string[],
  fields: readonly string[] | undefined,
): ExprValidationError | null {
  if (surfaceRoots.length === 0) return null;
  if (fields?.includes(bare)) return null;
  if (!isNamespaceUse(bare, source)) return null;
  const suggestion = nearest(bare, surfaceRoots);
  if (!suggestion) return null;
  return refusal(
    'unbound-root',
    { name: bare, roots: [...surfaceRoots], suggestion },
    source,
    `unbound root \`${bare}\` — beyond the record this authoring surface binds ` +
      `\`${surfaceRoots.join('`, `')}\`, and \`${bare}\` is none of them, so \`${bare}.…\` ` +
      `resolves to nothing and the expression silently evaluates to null. ` +
      `Did you mean \`${suggestion}\`?`,
  );
}

/** Cheap edit-distance suggestion for typo'd field names. */
/**
 * The closest candidate to `name`, or `undefined` when nothing is close enough
 * to be worth suggesting.
 *
 * The public face of the same edit-distance heuristic this module already uses
 * for unknown field refs and unknown roles, exported so other "did you mean?"
 * diagnostics reuse one threshold instead of each inventing their own — an
 * author (increasingly an agent) should not get a suggestion here and silence
 * there for the same class of typo.
 */
export function nearestName(name: string, candidates: readonly string[]): string | undefined {
  return nearest(name, candidates);
}

function nearest(name: string, candidates: readonly string[]): string | undefined {
  let best: string | undefined;
  let bestD = Infinity;
  for (const c of candidates) {
    const d = levenshtein(name, c);
    if (d < bestD) { bestD = d; best = c; }
  }
  return bestD <= Math.max(2, Math.floor(name.length / 3)) ? best : undefined;
}

function levenshtein(a: string, b: string): number {
  const m = a.length, n = b.length;
  const dp = Array.from({ length: m + 1 }, (_, i) => i);
  for (let j = 1; j <= n; j++) {
    let prev = dp[0];
    dp[0] = j;
    for (let i = 1; i <= m; i++) {
      const tmp = dp[i];
      dp[i] = Math.min(dp[i] + 1, dp[i - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
      prev = tmp;
    }
  }
  return dp[m];
}

// ADR-0068 D4 — position-membership predicate heads: a position NAME literal
// used in a membership test against a user subject's `.positions`
// (ADR-0090 D3 rename). Matched names are validated against the closed catalog.
const ROLE_IN_RE = /(['"])([a-z0-9_]+)\1\s+in\s+(?:current_user|user|ctx\.user)\.positions\b/g;
const ROLE_CONTAINS_RE = /(?:current_user|user|ctx\.user)\.positions\s*\.\s*contains\(\s*(['"])([a-z0-9_]+)\1\s*\)/g;
// Bounded quantifiers ({0,N}, not * / *?) keep this linear: a CEL `exists`
// body is tiny in practice, and unbounded greedy/lazy scanners here backtrack
// polynomially (O(n^2)) on adversarial input like repeated `user.positions.exists(`
// (ADR-0068 D4 ReDoS hardening). The pre-`==` class excludes `=` so the bounded
// run stops cleanly before the operator without a lazy quantifier.
const ROLE_EXISTS_RE = /(?:current_user|user|ctx\.user)\.positions\s*\.\s*exists\s*\([^,)]{0,64},[^)=]{0,128}==\s*(['"])([a-z0-9_]+)\1/g;
const ROLE_EQ_RE = /(?:current_user|user|ctx\.user)\.position\s*==\s*(['"])([a-z0-9_]+)\1/g;

/**
 * Flag role-membership predicates referencing a role outside the closed catalog
 * (ADR-0068 D4 — anti-hallucination). No-op when no `roleCatalog` is supplied.
 */
function checkRoleCatalog(
  source: string,
  schema: ExprSchemaHint | undefined,
  errors: ExprValidationError[],
): void {
  const catalog = schema?.roleCatalog;
  if (!catalog || catalog.length === 0) return;
  const known = new Set(catalog);
  const seen = new Set<string>();
  for (const re of [ROLE_IN_RE, ROLE_CONTAINS_RE, ROLE_EXISTS_RE, ROLE_EQ_RE]) {
    re.lastIndex = 0;
    let m: RegExpExecArray | null;
    while ((m = re.exec(source)) !== null) {
      const name = m[2];
      if (known.has(name) || seen.has(name)) continue;
      seen.add(name);
      const suggestion = nearest(name, catalog);
      errors.push(refusal(
        'unknown-role',
        { name, ...(suggestion ? { suggestion } : {}), catalog: [...catalog] },
        source,
        `unknown role \`${name}\` — not a defined role` +
          (suggestion ? `; did you mean \`${suggestion}\`?` : '.') +
          ` Valid roles: ${catalog.join(', ')}.`,
      ));
    }
  }
}

/**
 * Validate one expression for a given field role. Never throws — returns a
 * structured result. Call sites decide whether to throw (build/registration)
 * or report (agent tool).
 *
 * "Never throws" is the contract, and it now holds for the one input that used
 * to break it: an envelope whose `source` is not a string is refused through
 * `errors[]` like any other malformed expression, so the caller's located
 * reporting survives to the author. See {@link toSource}.
 */
export function validateExpression(
  role: FieldRole,
  input: ExprInput,
  schema?: ExprSchemaHint,
): ExprValidationResult {
  const { dialect, source, nonStringSource } = toSource(input);
  const errors: ExprValidationError[] = [];
  const warnings: ExprValidationError[] = [];
  if (nonStringSource !== undefined) {
    // Attributed to the empty string, deliberately: the value that would be the
    // location IS the value being refused, so echoing it would put a non-string
    // into a `source: string` slot every caller renders.
    errors.push(refusal(
      'envelope-source-not-text',
      { role, found: nonStringSource },
      '',
      `invalid ${role} envelope: ${NON_STRING_SOURCE_REFUSAL} — found ${describeNonStringSource(nonStringSource)}. ` +
        `Write the expression as bare text (e.g. ${role === 'template' ? '`Hi {{ record.name }}`' : '`record.rating >= 4`'}), ` +
        `or as an envelope whose \`source\` is that text ` +
        `(e.g. \`{ dialect: '${expectedDialect(role)}', source: '…' }\`).`,
    ));
    return { ok: false, errors, warnings };
  }
  if (!source.trim()) return { ok: true, errors, warnings };

  if (role === 'template') {
    // Templates must be the `template` dialect (or untyped string). Reject a
    // CEL envelope mistakenly placed in a text field.
    if (dialect && dialect !== 'template') {
      errors.push(refusal(
        'template-dialect-mismatch',
        { dialect },
        source,
        `expected a text template but got a \`${dialect}\` expression.`,
      ));
      return { ok: false, errors, warnings };
    }
    const compiled = templateEngine.compile(source);
    if (!compiled.ok) {
      errors.push(refusal(
        'invalid-template',
        { detail: compiled.error.message },
        source,
        `invalid template: ${compiled.error.message} (holes use \`{{ path }}\`).`,
      ));
    }
    // A single `{x}` in a template is the legacy/deprecated form (ADR-0032 §3).
    const hint = SINGLE_BRACE_RE.test(source) ? bracesHintForTemplate(source) : null;
    if (hint) errors.push(refusal('template-single-brace', { ref: hint.ref }, source, hint.text));
    return { ok: errors.length === 0, errors, warnings };
  }

  // predicate | value → CEL
  if (dialect && dialect !== 'cel') {
    errors.push(refusal(
      'cel-dialect-mismatch',
      { dialect },
      source,
      `expected a CEL expression but got a \`${dialect}\` dialect.`,
    ));
    return { ok: false, errors, warnings };
  }
  // `compileCel` is `celEngine.compile` with the fault's cel-js code kept
  // beside the verdict (#27904), for the `invalid-cel` params below.
  const { result: compiled, celCode } = compileCel(source);
  // One parse through the canonical front end, shared by the two passes that
  // read members — field existence and the relationship-traversal arm — and
  // taken only when one of them runs.
  let parsedAst: CelAstNode | null | undefined;
  const ast = (): CelAstNode | null => (parsedAst === undefined ? (parsedAst = parseCelToAst(source)) : parsedAst);
  if (!compiled.ok) {
    // #7073 — a bounds refusal gets the SIZE prescription, never the dialect
    // trailer: the source is already bare CEL, so "write bare CEL" is advice
    // that cannot succeed. #13821 routes the `type` class the same way for the
    // same reason, one class per arm. Both are checked before the braces hint
    // because the class is certain (it comes from the engine's own verdict)
    // while the braces hint is a heuristic.
    //
    // The `type` class carries TWO prescriptions, and they are disjoint by
    // construction rather than by ordering: #14203's receiver-call arm fires
    // only when the name IS advertised, #13821's unknown-name arm only when it
    // is not. Neither speaks for a fault it cannot name.
    //
    // A `type` fault that names no unresolvable call — an operator or ternary
    // mismatch (`1 + 'a'`, `no such overload: int + string`), or a real function
    // handed wrong arguments (`upper(1, 2)`, `record.name.contains()`) — gets
    // null from both and keeps the existing trailer.
    //
    // Each arm is its own refusal code, so the one that wrote the prescription
    // is the one that names the code — the message and the code cannot
    // disagree about which fault this was.
    const celRole: CelFieldRole = role;
    const detail = compiled.error.message;
    const lead = `invalid CEL ${role}: ${detail}`;
    const bounds = compiled.error.kind === 'bounds' ? boundsHint(source) : null;
    const method = !bounds && compiled.error.kind === 'type' ? receiverCallHint(detail, source) : null;
    const unknownFn = !bounds && !method && compiled.error.kind === 'type' ? unknownFunctionHint(detail) : null;
    const braces = !bounds && !method && !unknownFn ? bracesHint(source) : null;
    if (bounds) {
      const { text, ...budget } = bounds;
      errors.push(refusal('cel-too-large', { role: celRole, detail, ...budget }, source, `${lead} — ${text}`));
    } else if (method) {
      const { text, ...call } = method;
      errors.push(refusal('cel-method-call', { role: celRole, detail, ...call }, source, `${lead} — ${text}`));
    } else if (unknownFn) {
      const { text, ...call } = unknownFn;
      errors.push(refusal('cel-unknown-function', { role: celRole, detail, ...call }, source, `${lead} — ${text}`));
    } else if (braces) {
      errors.push(refusal('cel-template-brace', { role: celRole, detail, ref: braces.ref }, source, `${lead} — ${braces.text}`));
    } else {
      // #27904 — the engine's own fault code and the range it points at, when
      // it reported them, beside the unchanged sentence: an editor keys its own
      // words to `celCode` and puts its caret at `pos`. Absent when unknown.
      const { pos } = compiled.error;
      errors.push(refusal(
        'invalid-cel',
        { role: celRole, detail, ...(celCode ? { celCode } : {}), ...(pos ? { pos } : {}) },
        source,
        `${lead} — ${role}s are bare CEL (e.g. \`record.rating >= 4\`).`,
      ));
    }
  } else {
    checkFieldExistence(ast, source, schema, errors);
    checkOptionLabelTargets(ast, source, schema, errors);
    checkRoleCatalog(source, schema, errors);
    if (schema?.scope === 'record') {
      // In a `record`-scoped site a bare top-level identifier is a silent bug —
      // it must be `record.<field>` (#1928). Hard error.
      //
      // `schema.roots` are declared alongside the platform baseline, so a root
      // this surface really does mount is not read as a bare field: that is the
      // whole of the accept-side change, and an absent/empty `roots` reproduces
      // the previous call byte for byte.
      const surfaceRoots = schema.roots ?? [];
      const bare = firstUndeclaredReference(source, surfaceRoots);
      if (bare) {
        errors.push(
          mistypedRootRefusal(bare, source, surfaceRoots, schema.fields) ??
            refusal(
              'bare-reference',
              { name: bare },
              source,
              `bare reference \`${bare}\` — a formula/validation expression binds the record as the ` +
                `\`record\` namespace, not at top level, so \`${bare}\` resolves to nothing and the ` +
                `expression silently evaluates to null. Write \`record.${bare}\`.`,
            ),
        );
      } else if (schema.fieldTypes) {
        // #1928 / #3306 — with per-field types in hand, flag a type-unsound
        // operator use that faults at runtime and silently nulls: a text/boolean
        // field arithmetic'd/ordered against a number (advisory warning — a
        // numeric text value can succeed — or an error where the site fails
        // closed, #29904), or date-field arithmetic (hard error —
        // always nulls). Only runs when there is no bare-ref error (the typed
        // check needs the canonical `record.<field>` form).
        const r = typeSoundnessIssue(source, schema.fieldTypes, 'record', role, schema.faultOutcome);
        if (r) (r.severity === 'error' ? errors : warnings).push(r.issue);
      }
    } else if (schema?.fields && schema.fields.length > 0) {
      // Flattened flow/automation condition: the record's fields ARE bound at
      // top-level, so a bare ref is normally correct. But a *non-field* bare
      // identifier is either a flow variable or a typo. When it is a near-miss
      // of a known field, warn (did-you-mean) WITHOUT failing the build —
      // a genuine flow variable won't be edit-distance-close to a field. (#1928)
      // `roots` joins the declared set here for the same reason it does in the
      // `record` arm: a root the surface mounts is not a typo'd field, and
      // suggesting one for it would be a did-you-mean nobody can act on.
      const unknown = firstUndeclaredReference(source, [...schema.fields, ...(schema.roots ?? [])]);
      if (unknown) {
        const suggestion = nearest(unknown, schema.fields);
        if (suggestion) {
          warnings.push(refusal(
            'field-near-miss',
            {
              name: unknown,
              suggestion,
              ...(schema.objectName != null ? { objectName: schema.objectName } : {}),
            },
            source,
            `\`${unknown}\` is not a field of \`${schema.objectName ?? 'the trigger object'}\` — ` +
              `did you mean \`${suggestion}\`? (flow conditions reference fields bare, e.g. \`${suggestion} == …\`). ` +
              `If \`${unknown}\` is a flow variable this is safe to ignore.`,
          ));
        }
      }
      // #1928 / #3306 — the same type-soundness check, for bare-field conditions:
      // a text/boolean field compared/arithmetic'd against a number (advisory), or
      // date-field arithmetic (error). Flow variables stay `dyn` (never flagged);
      // equality/ordering of a date is runtime-safe (never flagged).
      if (schema.fieldTypes) {
        const r = typeSoundnessIssue(source, schema.fieldTypes, 'flattened', role, schema.faultOutcome, schema.flowVariables,
          schema.bareNamesUnproven);
        if (r) (r.severity === 'error' ? errors : warnings).push(r.issue);
      }
    }
  }
  // [#18682] Relationship traversal: refuse the shapes that cannot be served
  // as written — but ONLY where they are served. Three conditions, all
  // required: the caller opted in (`traversalHydration`, see its docblock for
  // why this is not derived from `fieldTypes`), the slot is a PREDICATE or a
  // formula `value` (the two seams that hydrate), and `fieldTypes` is present to tell a
  // REFERENCE field from an object-valued one — `record.address.city` traverses
  // today and must keep traversing.
  //
  // ⛔ This arm is the AUTHOR-side half only. ADR-0124: a client-side direction
  // is never the whole answer, and no runtime package imports this one, so the
  // same conflict is refused independently by ObjectQL's `checkPredicate`.
  // Metadata authored through Studio, written straight to `sys_metadata` or
  // produced by an agent never reaches this check.
  //
  // [#24197] A formula `value` is the second seam that serves one hop: the
  // engine's formula read path preloads it before computing the field. Its
  // caller opts in exactly as a validation condition's does, and the conflicts
  // are worded for a field that reads null rather than a write that is refused.
  if (schema?.fieldTypes && schema.traversalHydration === true && (role === 'predicate' || role === 'value')) {
    const tree = ast();
    const analysis = tree ? traversalsOf(readRootMembers(tree, [DEFAULT_TRAVERSAL_ROOT])) : null;
    if (analysis) {
      const conflicts = findTraversalConflicts(
        analysis,
        (field) => REFERENCE_VALUE_TYPES.has(schema.fieldTypes![field] ?? ''),
        DEFAULT_TRAVERSAL_ROOT,
        role === 'value' ? 'formula' : 'predicate',
      );
      for (const conflict of conflicts) {
        errors.push(refusal(
          TRAVERSAL_CONFLICT_CODE[conflict.kind],
          { root: DEFAULT_TRAVERSAL_ROOT, field: conflict.field },
          source,
          conflict.message,
        ));
      }
    }
  }
  return { ok: errors.length === 0, errors, warnings };
}

function bracesHintForTemplate(source: string): { text: string; ref: string } {
  const m = SINGLE_BRACE_RE.exec(source);
  const ref = m?.[1] ?? 'field';
  return { ref, text: `single-brace \`{${ref}}\` is not a valid template hole — use double braces: \`{{ ${ref} }}\`.` };
}

/**
 * Introspect what an author (esp. an agent) may use in a field (Decision 1e):
 * the expected dialect, the in-scope field references, and the callable
 * functions. Feeds the authoring context so the model does not guess.
 *
 * A surface that declares `schema.roots` gets those roots ADVERTISED here as
 * well as accepted by {@link validateExpression}. The two faces are fed from
 * one declaration on purpose: a root the validator accepts but this list never
 * names is a spelling the author has no way to discover, and a second hand-kept
 * list is how the two drift apart.
 */
export function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
  dialect: 'cel' | 'template';
  fields: string[];
  roots: string[];
  roles: string[];
  functions: string[];
} {
  return {
    dialect: expectedDialect(role),
    fields: [...(schema?.fields ?? [])],
    roots: [...new Set([
      'record', 'previous', 'input', 'os', 'current_user', 'user', 'vars',
      ...(schema?.roots ?? []),
    ])],
    roles: [...(schema?.roleCatalog ?? [])],
    functions: CEL_STDLIB_FUNCTIONS,
  };
}

/**
 * Coarse value categories a `value`/formula expression can compute. `'unknown'`
 * means cel-js could not prove a concrete type — either a `dyn` result (an
 * ambiguous expression over untyped operands) or one that does not type-check.
 */
export type InferredValueType = 'number' | 'text' | 'boolean' | 'date' | 'unknown';

/** Map a cel-js type-checker type name onto an ObjectStack field value category. */
function celTypeToValueType(celType: string | null): InferredValueType {
  switch (celType) {
    case 'int':
    case 'uint':
    case 'double':
      return 'number';
    case 'string':
      return 'text';
    case 'bool':
      return 'boolean';
    case 'google.protobuf.Timestamp':
      return 'date';
    default:
      // `dyn`, `google.protobuf.Duration`, list/map, null, or un-type-checkable.
      return 'unknown';
  }
}

/**
 * Infer the coarse value type a `value`/formula expression computes — `'number'`,
 * `'text'`, `'boolean'`, `'date'`, or `'unknown'` when cel-js cannot prove a
 * concrete type. `schema.fields` (the host object's field names) are declared so
 * a bare `<field>` reference resolves the same as `record.<field>`.
 *
 * The motivating use is measure-eligibility: a dataset derives a SUM measure for
 * a `formula` field ONLY when this returns `'number'`, so an ambiguous or
 * non-numeric formula never yields an incoherent measure. Conservative by
 * construction — see {@link inferCelType}.
 */
export function inferExpressionType(input: ExprInput, schema?: ExprSchemaHint): InferredValueType {
  const { source, nonStringSource } = toSource(input);
  // The second consumer of the shared entry, and it crashed identically. There
  // is no `errors[]` here to route a refusal through, and this function is
  // conservative by construction: a source it cannot read is a type it cannot
  // prove, which is exactly what `'unknown'` already means.
  if (nonStringSource !== undefined) return 'unknown';
  if (!source.trim()) return 'unknown';
  return celTypeToValueType(inferCelType(source, schema?.fields));
}

/**
 * Public catalog of CEL functions available in expressions — what `introspectScope`
 * advertises to authors (incl. AI). Every entry MUST actually resolve at runtime:
 * either registered in `registerStdLib` or a verified cel-js built-in. Drifting this
 * list ahead of the runtime tells the author to call functions that fault (#1928).
 *
 * ## This is a CURATED SUBSET of what the environment resolves — by construction
 *
 * The evaluation `Environment` resolves **77** distinct function names. This list
 * carries 38 of them, and the 39-name gap is NOT staleness. Measured decomposition
 * (`cel-stdlib-drift.test.ts` re-measures all four numbers on every run):
 *
 *   77 registered names
 *    = 42 callable BARE, as `fn(x)`            -> the only shape this list may carry
 *    + 35 callable only on a RECEIVER, `x.fn()` -> structurally ineligible
 *                                                 (cel-js's 33, plus our `can`
 *                                                 and `hasCapability`)
 *
 *   42 bare-callable
 *    = 30 added by `registerStdLib`   -> ALL advertised (one per registration site)
 *    +  8 cel-js built-ins            -> advertised: has size int string bool double
 *                                        timestamp duration
 *    +  4 cel-js built-ins WITHHELD   -> bytes dyn type uint
 *
 * **Bare-callability is the membership rule, and it is load-bearing.** Every
 * consumer spends an entry as a bare call: objectui's Studio predicate editor
 * inserts a suggestion verbatim as `` `name(` `` (`CelPredicateField.tsx`), and the
 * runtime drift guard in `cel-engine.test.ts` probes each entry with a bare-call
 * expression. So the 33 receiver-only names cel-js registers (`s.split(',')`,
 * `list.map(...)`, `ts.getFullYear()`, `opt.orValue(...)`) can never appear here:
 * flattening them into this list would autocomplete `split(` into an author's
 * predicate, which faults `no matching overload`. Widening this list to "every
 * registered name" is therefore not the safe direction — it is a broken one.
 *
 * The 4 withheld bare-callables are CEL's remaining type-conversion/introspection
 * primitives. They resolve today; they are withheld as an authoring decision (no
 * measured demand, and `dyn`/`uint`/`bytes` mostly widen the ways an AI author can
 * emit something unusable), not because they are unavailable. That withholding is
 * a declared ledger in the drift pin, so adding one is a deliberate edit and a new
 * cel-js built-in cannot arrive unnoticed.
 *
 * ⛔ This list is NOT an oracle for rejecting unknown functions. A gate that
 * rejects what is absent here would reject 39 names that resolve and evaluate
 * today. The unknown-function verdict belongs to the engine's own `check()`
 * (ruling on #13594); `@objectstack/lint` uses that and never reads this list.
 */
export const CEL_STDLIB_FUNCTIONS: string[] = [
  // Dates (registered stdlib)
  'now', 'today', 'daysFromNow', 'daysAgo', 'daysBetween', 'addDays', 'addMonths', 'date', 'datetime',
  'isoDate', 'isoDatetime',
  // Numbers (registered stdlib)
  'abs', 'round', 'floor', 'ceil', 'min', 'max',
  // Strings (registered stdlib)
  'upper', 'lower', 'trim', 'contains', 'startsWith', 'endsWith', 'matches', 'joinNonEmpty',
  // Collections / null-ish (registered stdlib)
  'isBlank', 'isEmpty', 'coalesce', 'len',
  // Options (registered stdlib) — `label(record.<field>)`, a select value's label
  'label',
  // cel-js built-ins (verified to resolve)
  'size', 'has', 'int', 'string', 'bool', 'double', 'timestamp', 'duration',
];