fix(formula): register mixed double/int arithmetic overloads (#1928)

cel-js types a record field number as `double` and a bare integer literal as
`int`, with overloads only for matching pairs. An everyday formula like
`record.amount / 100` or `record.price * 2` therefore faulted at runtime
(`no such overload: dyn<double> / int`) and the engine silently returned null —
build-green, empty at runtime.

Register the missing `double <op> int` / `int <op> double` overloads for
`+ - * / %` (result computed as double, per CEL mixed-numeric promotion).
Pure int/int is untouched, so integer division (`7 / 2 == 3`) is preserved;
overloads fire only on a genuine double×int pair. Composes with the existing
string-field hydration retry (`"120000.00" + 1 == 120001`).

Reverts the `/ 100.0` float-literal workaround in example-crm's
`expected_revenue` back to plain `/ 100` now that it computes natively.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: os-zhuang

.changeset/cel-mixed-numeric-overloads.md

@@ -0,0 +1,17 @@
+---
+"@objectstack/formula": patch
+---
+
+fix(formula): register mixed `double <op> int` arithmetic overloads so number-field formulas compute
+
+cel-js types a record field number as `double` and a bare integer literal as
+`int`, and ships overloads only for matching numeric pairs. So an everyday
+formula like `record.amount / 100` or `record.price * 2` faulted at runtime
+(`no such overload: dyn<double> / int`); the engine caught the fault and the
+formula silently evaluated to `null` — passing build, empty at runtime (#1928).
+
+The CEL engine now registers the missing `double <op> int` / `int <op> double`
+overloads for `+ - * / %`, computing the result as a `double` (CEL's mixed-numeric
+promotion). Pure `int op int` is untouched, so integer division (`7 / 2 == 3`)
+keeps its semantics — the overloads fire only when the operands are genuinely a
+`double` and an `int`. Authors no longer need the `/ 100.0` float-literal workaround.

examples/app-crm/src/objects/opportunity.object.ts

@@ -45,11 +45,7 @@ export const Opportunity = ObjectSchema.create({
     }),
     expected_revenue: Field.formula({
       label: 'Expected Revenue',
-      // NOTE: the divisor is the float literal `100.0`, not `100`. cel-js has no
-      // `double <op> int` arithmetic overload, so `<currency/number field> / 100`
-      // faults at runtime and the formula silently evaluates to null. Using a
-      // float literal keeps both operands `double`. See objectstack-formula skill.
-      expression: cel`(record.amount == null ? 0.0 : record.amount) * (record.probability == null ? 0.0 : record.probability) / 100.0`,
+      expression: cel`(record.amount == null ? 0 : record.amount) * (record.probability == null ? 0 : record.probability) / 100`,
     }),
     close_date: Field.date({
       label: 'Close Date',

packages/formula/src/cel-engine.test.ts

@@ -164,6 +164,64 @@ describe('celEngine', () => {
     });
   });
 
+  // #1928 — cel-js ships no `double <op> int` arithmetic overload, so a field
+  // number (double) combined with a bare integer literal faulted `no such
+  // overload` and the formula silently evaluated to null. registerNumericCoercions
+  // closes the gap; these are the everyday formula shapes that were broken.
+  describe('mixed double/int arithmetic overloads (#1928)', () => {
+    it('divides a currency field by an int literal (expected_revenue shape)', () => {
+      const r = celEngine.evaluate(
+        cel('record.amount * record.probability / 100'),
+        { record: { amount: 120000, probability: 70 } },
+      );
+      expect(r).toEqual({ ok: true, value: 84000 });
+    });
+
+    it('divides a field by an int literal', () => {
+      const r = celEngine.evaluate(cel('record.amount / 100'), {
+        record: { amount: 120000 },
+      });
+      expect(r).toEqual({ ok: true, value: 1200 });
+    });
+
+    it('handles *, +, -, % between a field and an int literal', () => {
+      expect(celEngine.evaluate(cel('record.x * 2'), { record: { x: 5.5 } }))
+        .toEqual({ ok: true, value: 11 });
+      expect(celEngine.evaluate(cel('record.x + 1'), { record: { x: 2.5 } }))
+        .toEqual({ ok: true, value: 3.5 });
+      expect(celEngine.evaluate(cel('record.x - 100'), { record: { x: 250 } }))
+        .toEqual({ ok: true, value: 150 });
+      expect(celEngine.evaluate(cel('record.x % 7'), { record: { x: 20 } }))
+        .toEqual({ ok: true, value: 6 });
+    });
+
+    it('handles the int-literal on the left (int op double)', () => {
+      const r = celEngine.evaluate(cel('100 - record.x'), {
+        record: { x: 40 },
+      });
+      expect(r).toEqual({ ok: true, value: 60 });
+    });
+
+    it('leaves pure int/int arithmetic as integer division (7 / 2 == 3)', () => {
+      const r = celEngine.evaluate(cel('7 / 2'), {});
+      expect(r).toEqual({ ok: true, value: 3 });
+    });
+
+    it('still evaluates double/double field arithmetic', () => {
+      const r = celEngine.evaluate(cel('record.a / record.b'), {
+        record: { a: 10, b: 4 },
+      });
+      expect(r).toEqual({ ok: true, value: 2.5 });
+    });
+
+    it('composes with string-field hydration (currency string + int literal)', () => {
+      const r = celEngine.evaluate(cel('record.amount + 1'), {
+        record: { amount: '120000.00' },
+      });
+      expect(r).toEqual({ ok: true, value: 120001 });
+    });
+  });
+
   // ADR-0032 §1c — string-serialized date/datetime fields (#1530). Field.date
   // serializes to "YYYY-MM-DD" and Field.datetime to a full ISO string; cel-js
   // compares those raw strings against the google.protobuf.Timestamp returned by

packages/formula/src/cel-engine.ts

@@ -16,7 +16,7 @@
 import { Environment } from '@marcbachmann/cel-js';
 import type { Expression } from '@objectstack/spec';
 
-import { buildScope, registerStdLib } from './stdlib';
+import { buildScope, registerNumericCoercions, registerStdLib } from './stdlib';
 import type { DialectEngine, EvalContext, EvalResult } from './types';
 
 /**
@@ -38,7 +38,7 @@ function buildEnv(now: () => Date): Environment {
     enableOptionalTypes: true,
     limits: DEFAULT_LIMITS,
   });
-  return registerStdLib(env, now);
+  return registerNumericCoercions(registerStdLib(env, now));
 }
 
 /** Coerce cel-js's BigInt-flavored return into spec-friendly JS values. */

packages/formula/src/stdlib.ts

@@ -104,6 +104,38 @@ export function registerStdLib(
     );
 }
 
+/**
+ * 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;
+}
+
 /**
  * Build the variable scope for a single evaluation. Absent fields are simply
  * not bound — CEL macros (`has(record.foo)`) handle missing-key safely.