stdlib.ts

/**
 * ObjectStack standard CEL function library.
 *
 * Registered into an `Environment` by the CEL engine. All functions are pure
 * given a pinned `now` and the pinned data this module is handed — that determinism is what makes `objectstack build` artifacts
 * byte-stable across runs. ⛔ Nothing registered here may be handed a resolver,
 * a lazy getter or any other callback into the host: a function that reaches
 * outside its arguments and the data pinned at registration makes the same
 * source evaluate to different values on two runs of the same build.
 *
 * Function naming intentionally avoids the `os.` prefix because cel-js binds
 * dotted names to receiver types. Instead, the `os` namespace in CEL holds
 * *data* (`os.user`, `os.org`, `os.env`) supplied by the caller's
 * {@link EvalContext}. The two RECEIVER-form functions this library registers —
 * `current_user.can(object, verb)` and `current_user.hasCapability(name)` — use
 * that same binding rather than fighting it: see
 * {@link registerPermissionPredicate} and {@link registerCapabilityPredicate}.
 * The one MACRO it registers, `label(record.<field>)`, reads the field's name
 * off its argument's AST: see {@link bindOptionLabel}.
 */

import type { Environment } from '@marcbachmann/cel-js';

import type { EvalContext, EvalOptionLabels, EvalPermissions, EvalSystemPermissions } from './types';
import { createEvalUser, type EvalUser } from '@objectstack/spec';
// The verb vocabulary lives on the SECURITY subpath, where the permission
// contract it is seeded from lives — not on the root barrel, which exports a
// curated authoring surface and no domain tables.
import {
  objectPermissionGrants,
  resolveObjectPermissionVerb,
  OBJECT_PERMISSION_VERB_NAMES,
} from '@objectstack/spec/security';

/**
 * Calendar-day parts (y/m/d) of an instant *as seen in a timezone*
 * (ADR-0053 Phase 2). Uses `Intl.DateTimeFormat` so DST transitions are
 * handled correctly — never hand-rolled offset math. An unknown zone throws,
 * which the caller treats as a fall-through to UTC.
 */
function partsInTz(d: Date, tz: string): { y: number; m: number; day: number } {
  const parts = new Intl.DateTimeFormat('en-US', {
    timeZone: tz, year: 'numeric', month: '2-digit', day: '2-digit',
  }).formatToParts(d);
  const get = (t: string) => Number(parts.find((p) => p.type === t)?.value);
  return { y: get('year'), m: get('month'), day: get('day') };
}

/**
 * The calendar day of an instant *in a reference timezone*, expressed as a
 * UTC-midnight `Date` (ADR-0053 Phase 2, decision D1). This is the one
 * representation consistent with how `Field.date` strings hydrate (UTC
 * midnight), how the SQL driver normalizes date filters, and how Phase 1
 * stores dates — so `record.date == today()` compares cleanly. Falls back to
 * the UTC calendar day for `UTC` or an invalid zone.
 */
function calendarDayUtc(d: Date, tz: string): Date {
  if (tz && tz !== 'UTC') {
    try {
      const { y, m, day } = partsInTz(d, tz);
      return new Date(Date.UTC(y, m - 1, day));
    } catch {
      // unknown zone → fall through to UTC
    }
  }
  return startOfDayUtc(d);
}

/** Truncate a Date to start-of-day in UTC. */
function startOfDayUtc(d: Date): Date {
  const out = new Date(d.getTime());
  out.setUTCHours(0, 0, 0, 0);
  return out;
}

/** Coerce a CEL value (Date | ISO string | epoch number) to a Date. */
function toDate(v: unknown): Date {
  if (v instanceof Date) return v;
  if (typeof v === 'number' || typeof v === 'bigint') return new Date(Number(v));
  return new Date(String(v));
}

/** One UTC day in milliseconds. */
const MS_PER_DAY = 86_400_000;

/**
 * The range cel-js's own `timestamp()` accepts, 0001-01-01T00:00:00Z through
 * 9999-12-31T23:59:59.999Z. Inside it `toISOString()` has one fixed shape,
 * `YYYY-MM-DDTHH:mm:ss.sssZ`; outside it the year expands (`+010000-…`).
 */
const MIN_TIMESTAMP_MS = -62_135_596_800_000;
const MAX_TIMESTAMP_MS = 253_402_300_799_999;

/**
 * The ISO text of a timestamp: `toISOString()`, the UTC calendar, three-digit
 * milliseconds and a `Z`. These are the bytes the retired flow template
 * dialect wrote for `{NOW()}`, and their first ten characters are what it
 * wrote for `{TODAY()}` (the 17.x `resolveToken`, deleted in #19939).
 *
 * An invalid or out-of-range instant is refused rather than rendered. The
 * refusal is a throw, which the engine reports as a runtime error.
 */
function isoTimestampText(fn: string, d: Date): string {
  const ms = d.getTime();
  if (!(ms >= MIN_TIMESTAMP_MS && ms <= MAX_TIMESTAMP_MS)) {
    throw new Error(
      `${fn}(t): \`t\` is not a renderable timestamp (${Number.isNaN(ms) ? 'an invalid date' : 'outside 0001-01-01 … 9999-12-31'}). ` +
      `Pass a valid timestamp, e.g. ${fn}(${fn === 'isoDate' ? 'today()' : 'now()'}), or ISO text through date(…).`,
    );
  }
  return d.toISOString();
}

/** Add `n` days to a Date in UTC; returns a new Date. */
function addDaysUtc(d: Date, n: number): Date {
  const out = new Date(d.getTime());
  out.setUTCDate(out.getUTCDate() + n);
  return out;
}

/**
 * Add `n` calendar months to a Date in UTC; returns a new Date. Clamps the day
 * to the target month's last day so `addMonths(date('2026-01-31'), 1)` yields
 * Feb 28, never an overflow into March — matching how authors expect a
 * "next service date = last + N months" rule to behave.
 */
function addMonthsUtc(d: Date, n: number): Date {
  const out = new Date(d.getTime());
  const day = out.getUTCDate();
  out.setUTCDate(1); // avoid roll-over while shifting the month
  out.setUTCMonth(out.getUTCMonth() + n);
  const lastDay = new Date(Date.UTC(out.getUTCFullYear(), out.getUTCMonth() + 1, 0)).getUTCDate();
  out.setUTCDate(Math.min(day, lastDay));
  return out;
}

/**
 * What `current_user.can(object, verb)` is answered from: the acting subject
 * this evaluation bound, and that subject's effective object permissions.
 *
 * Both halves are DATA, pinned for the one evaluation they answer. `subject` is the
 * very object {@link buildScope} mounted under `current_user` (and its `user` /
 * `ctx.user` / `os.user` aliases), carried here so the binding can tell a call
 * ON the acting subject from a call on something else that happens to sit to
 * the left of a dot.
 */
export interface PermissionBinding {
  /**
   * The canonical `EvalUser` this evaluation bound, or `undefined` when the
   * evaluation carries no user at all (a parse-time environment, a system
   * write). Compared by IDENTITY, never by shape.
   */
  readonly subject: unknown;
  /** The subject's effective object permissions, or `undefined` when none were passed. */
  readonly permissions: EvalPermissions | undefined;
  /**
   * The subject's held system capabilities — the `systemPermissions` list of
   * the published `/auth/me/permissions` response — or `undefined` when none
   * were passed. Read by `current_user.hasCapability(name)` and nothing else.
   */
  readonly systemPermissions?: EvalSystemPermissions | undefined;
}

/**
 * Register `can` — the permission predicate — as a RECEIVER method, so the one
 * authored spelling is `current_user.can(object, verb)`.
 *
 * ## Receiver-only, deliberately
 *
 * cel-js binds dotted names to receiver types, and a bare `can(object, verb)`
 * is NOT registered: it keeps faulting (`found no matching overload for
 * 'can(dyn, dyn)'`), which is the right answer — a bare call names no subject,
 * and a permission question with no subject has no meaning. The name exists in
 * the environment either way, so the publish gate's function-existence verdict
 * (`firstUnknownFunctionCall`) reads a bare call as a call-FORM fault rather
 * than an existence one, exactly as it already does for `split`.
 *
 * ## Every refusal is LOUD — there is no quiet answer
 *
 * The binding throws, and the engine reports the throw as
 * `{ ok: false, error: { kind: 'runtime' } }`, for each of:
 *
 *  - **no permission data in the context.** ⛔ Never `true` (fail-open: an
 *    action shown to someone who cannot use it, and worse, a section of data
 *    revealed), ⛔ never a silent `false` (fail-shut: every gated element
 *    disappears for everyone, indistinguishable from a correct denial, and the
 *    author is told nothing). A context that was never given the data cannot
 *    tell "denied" from "nobody passed it", so it says so.
 *  - **a receiver that is not the acting subject.** `record.can(…)` reads as a
 *    question about the record and would silently be answered about the user.
 *  - **a verb outside the vocabulary.** `current_user.can('crm_lead', 'approve')`
 *    is an author asking about a capability this platform does not model; the
 *    refusal names the whole accepted vocabulary.
 *  - **a non-string object or verb.**
 *
 * The ONE quiet answer is a real one: an object the effective map does not
 * mention is an object with no grant, and answers `false` — the same answer an
 * all-`false` entry gives, because they mean the same thing.
 */
export function registerPermissionPredicate(
  env: Environment,
  binding: PermissionBinding | undefined,
): Environment {
  return bindPermissionPredicate(env, () => binding);
}

/**
 * {@link registerPermissionPredicate}, answered from whatever binding `read`
 * returns at the moment of the call rather than from one fixed at registration.
 */
function bindPermissionPredicate(
  env: Environment,
  read: () => PermissionBinding | undefined,
): Environment {
  return env.registerFunction(
    'dyn.can(dyn, dyn): bool',
    (receiver: unknown, object: unknown, verb: unknown): boolean => {
      const binding = read();
      if (typeof object !== 'string' || object.length === 0) {
        throw new Error(
          'can(object, verb): `object` must be an object NAME (a non-empty string), e.g. ' +
          "current_user.can('crm_lead', 'edit').",
        );
      }
      if (typeof verb !== 'string' || verb.length === 0) {
        throw new Error(
          'can(object, verb): `verb` must be one of ' +
          `${OBJECT_PERMISSION_VERB_NAMES.join(', ')} (a non-empty string).`,
        );
      }
      const target = resolveObjectPermissionVerb(verb);
      if (!target) {
        throw new Error(
          `can(object, verb): \`${verb}\` is not a permission verb. The accepted verbs are ` +
          `${OBJECT_PERMISSION_VERB_NAMES.join(', ')}. A capability outside that list is not ` +
          'modelled as an object permission, so no answer about it would mean anything. To ask ' +
          "whether the subject holds a system capability, write current_user.hasCapability('<name>').",
        );
      }
      if (binding?.subject === undefined || receiver !== binding.subject) {
        throw new Error(
          'can(object, verb) answers about the ACTING SUBJECT and must be called on it: write ' +
          "current_user.can('<object>', '<verb>') (the `user` / `ctx.user` / `os.user` aliases " +
          'are the same object and work too). Calling it on anything else would answer a ' +
          'question about the current user while reading as a question about the receiver.',
        );
      }
      if (binding.permissions === undefined) {
        throw new Error(
          `can('${object}', '${verb}') cannot be answered: this evaluation context carries no ` +
          'permission data. Pass `permissions` on the EvalContext — the `objects` map of the ' +
          'published /auth/me/permissions response, object name -> EffectiveObjectPermission. ' +
          'Refusing loudly is deliberate: answering `true` would show what the subject may not ' +
          'have, and answering `false` would hide it from everyone with no way to tell that ' +
          'apart from a real denial.',
        );
      }
      const entry = Object.prototype.hasOwnProperty.call(binding.permissions, object)
        ? binding.permissions[object]
        : undefined;
      return objectPermissionGrants(entry, target);
    },
  );
}

/**
 * Register `hasCapability` — the capability predicate — as a RECEIVER method,
 * so the one authored spelling is `current_user.hasCapability(name)`.
 *
 * It asks the question the action gate asks (ADR-0066 D4): does the acting
 * subject hold this system capability? The answer is read from the subject's
 * held capabilities — the `systemPermissions` list `/auth/me/permissions`
 * publishes, the same list an action's `requiredPermissions` is checked
 * against — so a page node gated with it and an action gated on the same name
 * agree for every viewer. That is what makes the action's declaration the one
 * source of truth: a page predicate names the capability the action declares,
 * never a proxy for it (`can('<object>', 'edit')` is a different question and
 * answers differently for a subject who holds one and not the other).
 *
 * `visible` hides and `requiredPermissions` refuses (ADR-0066 D4): a predicate
 * written with this function decides what is SHOWN, and the server stays the
 * authority on what may be DONE.
 *
 * A name is just a string. ⛔ There is no registry lookup: a name no action
 * declares is answered like any other — `true` when the subject holds it,
 * `false` when it does not — because the list is the subject's, not the
 * platform's catalog.
 *
 * Receiver-only and LOUD on exactly the terms `can` is (see
 * {@link registerPermissionPredicate}): a bare call faults as a call-FORM
 * fault, a receiver that is not the acting subject throws, a non-string or
 * empty name throws, and a context carrying no capability list THROWS — ⛔
 * never `true` (fail-open), ⛔ never a silent `false` (every gated node gone,
 * indistinguishable from a real denial). An EMPTY list is a real answer and
 * evaluates to `false`.
 */
export function registerCapabilityPredicate(
  env: Environment,
  binding: PermissionBinding | undefined,
): Environment {
  return bindCapabilityPredicate(env, () => binding);
}

/**
 * {@link registerCapabilityPredicate}, answered from whatever binding `read`
 * returns at the moment of the call rather than from one fixed at registration.
 */
function bindCapabilityPredicate(
  env: Environment,
  read: () => PermissionBinding | undefined,
): Environment {
  return env.registerFunction(
    'dyn.hasCapability(dyn): bool',
    (receiver: unknown, name: unknown): boolean => {
      const binding = read();
      if (typeof name !== 'string' || name.length === 0) {
        throw new Error(
          'hasCapability(name): `name` must be a system capability NAME (a non-empty string), ' +
          "e.g. current_user.hasCapability('manage_users').",
        );
      }
      if (binding?.subject === undefined || receiver !== binding.subject) {
        throw new Error(
          'hasCapability(name) answers about the ACTING SUBJECT and must be called on it: write ' +
          "current_user.hasCapability('<name>') (the `user` / `ctx.user` / `os.user` aliases are " +
          'the same object and work too). Calling it on anything else would answer a question ' +
          'about the current user while reading as a question about the receiver.',
        );
      }
      const held = binding.systemPermissions;
      if (held === undefined) {
        throw new Error(
          `hasCapability('${name}') cannot be answered: this evaluation context carries no ` +
          'capability list. Pass `systemPermissions` on the EvalContext — the `systemPermissions` ' +
          'list of the published /auth/me/permissions response. Refusing loudly is deliberate: ' +
          'answering `true` would show what the subject may not have, and answering `false` would ' +
          'hide it from everyone with no way to tell that apart from a real denial.',
        );
      }
      if (!Array.isArray(held) || held.some((entry) => typeof entry !== 'string')) {
        throw new Error(
          `hasCapability('${name}') cannot be answered: the context's \`systemPermissions\` is not ` +
          'a list of capability names. Pass the `systemPermissions` array of the published ' +
          '/auth/me/permissions response unchanged.',
        );
      }
      return held.includes(name);
    },
  );
}

/** The slice of a cel-js AST node `label()` reads: its operator and operands. */
interface CelMacroNode {
  readonly op: string;
  readonly args: unknown;
}

/** The slice of cel-js's type checker a macro's `typeCheck` calls. */
interface CelMacroChecker {
  check(node: CelMacroNode, ctx: unknown): unknown;
  getType(name: string): unknown;
  createError(code: string, message: string, node: CelMacroNode): Error;
}

/** The slice of cel-js's evaluator a macro's `evaluate` calls. */
interface CelMacroEvaluator {
  run(node: CelMacroNode, ctx: unknown): unknown;
}

/**
 * The refusal for an argument that is not a field read straight off `record`.
 * Shared by the type check (publish time) and the evaluation (an unchecked run).
 */
const LABEL_ARGUMENT_REFUSAL =
  'label() takes a field of this record, read directly: label(record.<field>), e.g. ' +
  "'v' + string(record.version_no) + ' · ' + label(record.kind). The field's name is what " +
  'picks its options, so a computed value, a related record\'s field or an optional read ' +
  '(record.?kind) has no options to look up.';

/**
 * The field `label()`'s argument names — `kind` for `label(record.kind)` — or
 * `undefined` when the argument is any other shape.
 */
function optionLabelFieldOf(node: CelMacroNode | undefined): string | undefined {
  if (!node || node.op !== '.' || !Array.isArray(node.args)) return undefined;
  const [receiver, field] = node.args as [CelMacroNode | undefined, unknown];
  if (!receiver || receiver.op !== 'id' || receiver.args !== 'record') return undefined;
  return typeof field === 'string' && field.length > 0 ? field : undefined;
}

/**
 * The label a reader reads for `value` of `field`, from the pinned map.
 *
 * `null` / absent is `''`, so a name composes cleanly over an empty select
 * (`trim()` answers `''` for the same reason). A value no option declares reads
 * as itself — the select control shows such a value the same way. Everything
 * else that cannot be answered THROWS, which the engine reports as
 * `{ ok: false, kind: 'runtime' }`.
 */
function optionLabelOf(field: string, value: unknown, labels: EvalOptionLabels | undefined): string {
  if (labels === undefined) {
    throw new Error(
      `label(record.${field}) cannot be answered: this evaluation context carries no option ` +
      'labels. A formula field read through the data engine carries them; pass `optionLabels` ' +
      'on the EvalContext — field -> stored value -> label, resolved in the reader\'s locale. ' +
      'Refusing is deliberate: the stored value instead of its label is the wrong answer this ' +
      'function exists to remove.',
    );
  }
  // The field's options first, so a field that declares none faults on EVERY
  // row, not only on the rows where it happens to hold a value.
  const options = Object.prototype.hasOwnProperty.call(labels, field) ? labels[field] : undefined;
  if (options === undefined) {
    throw new Error(
      `label(record.${field}): \`${field}\` declares no options, so it has no option label. ` +
      'label() reads a select field\'s option label; read any other field directly ' +
      `(record.${field}).`,
    );
  }
  if (value === null || value === undefined) return '';
  if (typeof value === 'object') {
    throw new Error(
      `label(record.${field}) renders ONE option value, and \`${field}\` holds ` +
      `${Array.isArray(value) ? 'a list of values' : 'an object'} on this record.`,
    );
  }
  const stored = String(value);
  const shown = Object.prototype.hasOwnProperty.call(options, stored) ? options[stored] : undefined;
  return typeof shown === 'string' && shown.length > 0 ? shown : stored;
}

/**
 * Register `label` — the option-label function — as a MACRO, so the authored
 * spelling is `label(record.<field>)` and the function knows WHICH field it
 * reads. A select field's stored value (`clean`) is the same string in every
 * locale; its label (`Clean`, `清稿`) is not. A record name composed in a
 * formula (`'v' + string(record.version_no) + ' · ' + label(record.kind)`)
 * renders in the reader's locale through it.
 *
 * ## Why a macro
 *
 * A plain function receives the VALUE and nothing else, and a value does not
 * say whose options it belongs to: two select fields may both store `open`.
 * cel-js hands a macro its argument's AST, as it does `has(record.foo)`, so
 * the field's name is read off the source, once, at parse. Any other argument
 * shape is refused at the type check, which `compile()` and the publish gate
 * run, so a wrong spelling never reaches a stored formula.
 *
 * ## Data, never a translator
 *
 * The labels are the {@link EvalOptionLabels} map the caller pinned for this
 * evaluation (`EvalContext.optionLabels`). Translating is the caller's job,
 * done before evaluation through the same path the object's metadata is
 * served by, so the stdlib stays pure under the module header's rule. The
 * map is read through `read` at the moment of the call, as the permission
 * binding is, so the shared evaluation environment answers each evaluation
 * from its own map.
 */
function bindOptionLabel(env: Environment, read: () => EvalOptionLabels | undefined): Environment {
  return env.registerFunction('label(ast): string', ({ args }: { args: CelMacroNode[] }) => {
    const field = optionLabelFieldOf(args[0]);
    return {
      args,
      async: false,
      typeCheck(checker: CelMacroChecker, _macro: unknown, ctx: unknown) {
        if (field === undefined) throw checker.createError('invalid_macro_argument', LABEL_ARGUMENT_REFUSAL, args[0]);
        checker.check(args[0], ctx);
        return checker.getType('string');
      },
      evaluate(ev: CelMacroEvaluator, _macro: unknown, ctx: unknown) {
        if (field === undefined) throw new Error(LABEL_ARGUMENT_REFUSAL);
        return optionLabelOf(field, ev.run(args[0], ctx), read());
      },
    };
  });
}

/**
 * Register the ObjectStack standard library into a CEL environment.
 *
 * The `now` resolver is closed over so each call uses the pinned
 * `EvalContext.now` (or wall-clock fallback); `permissionBinding` is pinned the
 * same way and for the same reason — see {@link PermissionBinding} — and so is
 * `optionLabels` ({@link bindOptionLabel}).
 * Implementations are kept tiny and dependency-free — they're the contract
 * surface for AI authors and must stay legible.
 *
 * `can`, `hasCapability` and `label` are registered UNCONDITIONALLY, binding or not:
 * whether a name exists in this environment is a fact about the platform, not
 * about one call site's data. A conditional registration would make the publish gate's answer depend
 * on which context happened to build the environment, so an authored predicate
 * could pass the gate and be unknown at runtime — the very split this binding
 * exists to close.
 */
export function registerStdLib(
  env: Environment,
  now: () => Date,
  timezone = 'UTC',
  permissionBinding?: PermissionBinding,
  optionLabels?: EvalOptionLabels,
): Environment {
  const pinned: StdLibBinding = { now, timezone, permissionBinding, optionLabels };
  return registerBoundStdLib(env, () => pinned);
}

/**
 * Everything a stdlib function reads that is not one of its arguments: the
 * clock, the reference timezone, the permission binding and the option labels.
 *
 * Package-internal (NOT re-exported from `index.ts`).
 */
export interface StdLibBinding {
  readonly now: () => Date;
  readonly timezone: string;
  readonly permissionBinding: PermissionBinding | undefined;
  readonly optionLabels?: EvalOptionLabels | undefined;
}

/**
 * {@link registerStdLib}, with every function reading its {@link StdLibBinding}
 * through `read` at the moment it is CALLED rather than from values fixed when
 * it was registered.
 *
 * This is what lets the engine build the stdlib once and reuse that
 * environment for every evaluation: it points `read` at a per-evaluation slot
 * and sets the slot around each `evaluate` (see `celEngine.evaluate`).
 * {@link registerStdLib} is this function with a `read` that always answers
 * the same pinned values, so both register the same names with the same
 * implementations.
 *
 * Package-internal (NOT re-exported from `index.ts`).
 */
export function registerBoundStdLib(env: Environment, read: () => StdLibBinding): Environment {
  bindPermissionPredicate(env, () => read().permissionBinding);
  bindCapabilityPredicate(env, () => read().permissionBinding);
  bindOptionLabel(env, () => read().optionLabels);
  const now = (): Date => read().now();
  const today = (): Date => {
    const binding = read();
    return calendarDayUtc(binding.now(), binding.timezone);
  };
  // `today()` / `daysFromNow()` / `daysAgo()` are calendar-day functions: they
  // resolve to the reference-tz calendar day expressed as a UTC-midnight Date
  // (ADR-0053 Phase 2 D1), never an instant carrying wall-clock time. For a
  // genuine sub-day offset use `now() + duration("Nh")`.
  return env
    .registerFunction('now(): google.protobuf.Timestamp', () => now())
    .registerFunction(
      'today(): google.protobuf.Timestamp',
      () => today(),
    )
    .registerFunction(
      'daysFromNow(int): google.protobuf.Timestamp',
      (n: bigint | number) => addDaysUtc(today(), Number(n)),
    )
    .registerFunction(
      'daysAgo(int): google.protobuf.Timestamp',
      (n: bigint | number) => addDaysUtc(today(), -Number(n)),
    )
    // Returns true when `value` is null, undefined, empty string, or empty list.
    // Matches the intent of legacy `ISBLANK()` while staying CEL-idiomatic.
    .registerFunction(
      'isBlank(dyn): bool',
      (value: unknown) => {
        if (value === null || value === undefined) return true;
        if (typeof value === 'string') return value.length === 0;
        if (Array.isArray(value)) return value.length === 0;
        return false;
      },
    )
    // Returns `value` when not null/undefined, otherwise the `fallback`.
    // Use this to safely concatenate optional string fields:
    //   coalesce(record.salutation, '') + ' ' + coalesce(record.first_name, '')
    .registerFunction(
      'coalesce(dyn, dyn): dyn',
      (value: unknown, fallback: unknown) =>
        (value === null || value === undefined) ? fallback : value,
    )
    // Trim leading/trailing ASCII whitespace from a string. Returns '' for
    // null/undefined so it composes cleanly with `coalesce`.
    .registerFunction(
      'trim(dyn): string',
      (value: unknown) => {
        if (value === null || value === undefined) return '';
        return String(value).trim();
      },
    )
    // Join a list of values with `sep`, dropping null/undefined/empty entries
    // first. Designed for display-name formulas like:
    //   joinNonEmpty([record.salutation, record.first_name, record.last_name], ' ')
    // which produces 'Alice Martinez' (no leading/trailing/internal extra
    // spaces) when `salutation` is null.
    .registerFunction(
      'joinNonEmpty(list, string): string',
      (list: unknown, sep: unknown) => {
        const arr = Array.isArray(list) ? list : [];
        const separator = typeof sep === 'string' ? sep : ' ';
        const parts: string[] = [];
        for (const item of arr) {
          if (item === null || item === undefined) continue;
          const s = String(item).trim();
          if (s.length > 0) parts.push(s);
        }
        return parts.join(separator);
      },
    )
    // ── Dates ────────────────────────────────────────────────────────────
    // Whole days from `a` to `b` (negative if `b` is before `a`). The common
    // shape is `daysBetween(today(), record.due)` for "days remaining". Args are
    // coerced (Date | ISO string | epoch) so a `Field.date` that arrives as a
    // string still works without the caller hydrating it.
    .registerFunction(
      'daysBetween(dyn, dyn): int',
      (a: unknown, b: unknown) =>
        BigInt(Math.round((toDate(b).getTime() - toDate(a).getTime()) / MS_PER_DAY)),
    )
    // Shift an arbitrary date by a (possibly negative) number of days/months.
    // Unlike `daysFromNow`, these operate on a *given* date — the shape behind
    // "next service date = last service + cycle". Args are coerced (Date | ISO
    // string | epoch) so a `Field.date` arriving as a string works directly.
    // `addMonths` clamps to the target month's last day (Jan 31 +1mo → Feb 28).
    // `n` is typed `dyn` (not `int`): a record number field arrives as cel-js
    // `double`, so an `int` overload would fault `no such overload` (#1928).
    // We coerce defensively with `Number(...)`.
    .registerFunction(
      'addDays(dyn, dyn): google.protobuf.Timestamp',
      (d: unknown, n: unknown) => addDaysUtc(toDate(d), Math.trunc(Number(n))),
    )
    .registerFunction(
      'addMonths(dyn, dyn): google.protobuf.Timestamp',
      (d: unknown, n: unknown) => addMonthsUtc(toDate(d), Math.trunc(Number(n))),
    )
    // Parse an ISO date / date-time string to a Timestamp. `date` and `datetime`
    // are aliases — both accept either form (the field's own type decides the
    // intent); kept distinct because authors reach for whichever reads clearer.
    .registerFunction('date(dyn): google.protobuf.Timestamp', (s: unknown) => toDate(s))
    .registerFunction('datetime(dyn): google.protobuf.Timestamp', (s: unknown) => toDate(s))
    // The string form of a timestamp, the reverse of `date` / `datetime`:
    // `isoDate(t)` is `YYYY-MM-DD` and `isoDatetime(t)` is
    // `YYYY-MM-DDTHH:mm:ss.sssZ`, both on the UTC calendar. They write the
    // bytes the retired flow template dialect wrote for `{TODAY()}` and `{NOW()}`.
    // `isoDate(today())` is the reference-timezone day, because `today()` is
    // that day at UTC midnight (ADR-0053 D1).
    //
    // Two named functions, not a `string(timestamp)` overload. A `string()`
    // overload answers one shape for one type, so it cannot spell the date
    // shape. CEL also defines `string(timestamp)` as RFC 3339 text that drops
    // zero fractions, so matching the template's `.000` would make `string()`
    // a dialect. That name stays refused for a timestamp, which a test pins.
    //
    // The parameter is a timestamp, never `dyn`. Text, a number or `null` is
    // refused: at build when the argument's type is known, at run otherwise.
    // Coercing like `toDate` would parse non-ISO text in the host's local
    // zone and could render a different day.
    .registerFunction(
      'isoDate(google.protobuf.Timestamp): string',
      (d: Date) => isoTimestampText('isoDate', d).slice(0, 10),
    )
    .registerFunction(
      'isoDatetime(google.protobuf.Timestamp): string',
      (d: Date) => isoTimestampText('isoDatetime', d),
    )
    // ── Numbers ──────────────────────────────────────────────────────────
    .registerFunction('abs(dyn): double', (x: unknown) => Math.abs(Number(x)))
    .registerFunction('round(dyn): int', (x: unknown) => BigInt(Math.round(Number(x))))
    // `floor`/`ceil` round toward −∞ / +∞ (NOT toward zero like integer division),
    // so `floor(-1.2) == -2`, `ceil(-1.2) == -1`. Registered because they are
    // universally-expected math primitives that authors (and LLMs) reach for by
    // reflex — omitting them makes `floor(...)` fault and the formula silently
    // null (#3306). Return `int` to match `round`, coercing the arg with
    // `Number(...)` (a record number arrives as cel-js `double`).
    .registerFunction('floor(dyn): int', (x: unknown) => BigInt(Math.floor(Number(x))))
    .registerFunction('ceil(dyn): int', (x: unknown) => BigInt(Math.ceil(Number(x))))
    // min/max return the smaller/larger operand verbatim (type preserved) rather
    // than a coerced copy, so `min(record.a, record.b)` keeps int-ness when both
    // are ints. Comparison is numeric.
    .registerFunction('min(dyn, dyn): dyn', (a: unknown, b: unknown) => (Number(a) <= Number(b) ? a : b))
    .registerFunction('max(dyn, dyn): dyn', (a: unknown, b: unknown) => (Number(a) >= Number(b) ? a : b))
    // ── Strings ──────────────────────────────────────────────────────────
    // Free-function forms of the common string ops. CEL also exposes some as
    // receiver methods (`s.contains(x)`), but the authoring catalog advertises
    // the bare-call form, so register it to match what authors are told to use.
    .registerFunction('upper(dyn): string', (s: unknown) => String(s ?? '').toUpperCase())
    .registerFunction('lower(dyn): string', (s: unknown) => String(s ?? '').toLowerCase())
    .registerFunction('contains(dyn, dyn): bool', (s: unknown, sub: unknown) => String(s ?? '').includes(String(sub ?? '')))
    .registerFunction('startsWith(dyn, dyn): bool', (s: unknown, p: unknown) => String(s ?? '').startsWith(String(p ?? '')))
    .registerFunction('endsWith(dyn, dyn): bool', (s: unknown, p: unknown) => String(s ?? '').endsWith(String(p ?? '')))
    .registerFunction('matches(dyn, dyn): bool', (s: unknown, re: unknown) => new RegExp(String(re ?? '')).test(String(s ?? '')))
    // ── Collections ──────────────────────────────────────────────────────
    // `len` mirrors CEL's built-in `size()` for strings/lists/maps; `isEmpty` is
    // the inverse-of-non-empty companion to `isBlank` (true for null, '', []).
    .registerFunction('len(dyn): int', (v: unknown) => BigInt(lengthOf(v)))
    .registerFunction(
      'isEmpty(dyn): bool',
      (v: unknown) => v === null || v === undefined || lengthOf(v) === 0,
    );
}

/** Length of a string / list / map (0 for scalars and null). */
function lengthOf(v: unknown): number {
  if (v === null || v === undefined) return 0;
  if (typeof v === 'string' || Array.isArray(v)) return v.length;
  if (typeof v === 'object') return Object.keys(v as Record<string, unknown>).length;
  return 0;
}

/**
 * Register mixed `double <op> int` / `int <op> double` arithmetic overloads.
 *
 * cel-js types a record field number as `double` and a bare integer literal as
 * `int`, and ships overloads only for matching pairs (`double op double`,
 * `int op int`). So a formula as ordinary as `record.amount / 100` or
 * `record.price * 2` faults at runtime (`no such overload: dyn<double> / int`);
 * the engine catches the fault and the formula silently evaluates to `null`
 * (#1928). Authors then have to know the cel-js quirk and write `/ 100.0`.
 *
 * We close the gap by registering the missing mixed overloads. The result is
 * always computed as a JS `double`, matching CEL's promotion rule for mixed
 * numeric arithmetic. Pure `int op int` is untouched, so integer division
 * (`7 / 2 == 3`) keeps its semantics — these overloads only fire when the two
 * operands are genuinely a `double` and an `int`.
 */
export function registerNumericCoercions(env: Environment): Environment {
  const ops: Record<string, (a: number, b: number) => number> = {
    '+': (a, b) => a + b,
    '-': (a, b) => a - b,
    '*': (a, b) => a * b,
    '/': (a, b) => a / b,
    '%': (a, b) => a % b,
  };
  for (const [op, fn] of Object.entries(ops)) {
    const impl = (a: unknown, b: unknown) => fn(Number(a), Number(b));
    env.registerOperator(`double ${op} int`, impl);
    env.registerOperator(`int ${op} double`, impl);
  }
  return env;
}

/**
 * Normalize the loosely-typed EvalContext user into the canonical EvalUser
 * (ADR-0068, renamed by ADR-0090 D3): `positions` is the one canonical
 * membership array. One-step rename — no legacy `roles`/`role` aliases parse.
 */
function toEvalUser(u: NonNullable<EvalContext['user']>): EvalUser {
  const positions = Array.isArray(u.positions) ? (u.positions as string[]) : [];
  const canonical = createEvalUser({
    id: u.id,
    name: typeof u.name === 'string' ? u.name : undefined,
    email: typeof u.email === 'string' ? u.email : undefined,
    positions,
    organizationId:
      typeof u.organizationId === 'string' || u.organizationId === null
        ? (u.organizationId as string | null)
        : undefined,
  });
  return canonical;
}

/**
 * Build the variable scope for a single evaluation. Absent fields are simply
 * not bound — CEL macros (`has(record.foo)`) handle missing-key safely.
 */
export function buildScope(ctx: EvalContext): Record<string, unknown> {
  const scope: Record<string, unknown> = {};

  if (ctx.record !== undefined) scope.record = ctx.record;
  if (ctx.previous !== undefined) scope.previous = ctx.previous;
  if (ctx.input !== undefined) scope.input = ctx.input;

  // Namespaced data — written as `os.user.id`, `os.env`, etc. in CEL.
  const os: Record<string, unknown> = {};
  if (ctx.user !== undefined) {
    // ADR-0068: one canonical EvalUser under every alias (`current_user`,
    // `user`, `ctx.user`, `os.user`) — the SAME object, so a predicate
    // evaluates identically wherever it is authored.
    const currentUser = toEvalUser(ctx.user);
    scope.current_user = currentUser;
    scope.user = currentUser;
    scope.ctx = {
      ...(typeof scope.ctx === 'object' && scope.ctx !== null ? scope.ctx : {}),
      user: currentUser,
    };
    os.user = currentUser;
  }
  if (ctx.org !== undefined) os.org = ctx.org;
  if (ctx.env !== undefined) os.env = ctx.env;
  if (Object.keys(os).length > 0) scope.os = os;

  if (ctx.extra !== undefined) Object.assign(scope, ctx.extra);

  return scope;
}