@objectstack/formula 10.2.0 → 11.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/formula",
-  "version": "10.2.0",
+  "version": "11.0.0",
   "license": "Apache-2.0",
   "description": "ObjectStack canonical expression engine — CEL (cel-js) + ObjectStack stdlib + dialect registry",
   "main": "dist/index.js",
@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "@marcbachmann/cel-js": "^7.6.1",
-    "@objectstack/spec": "10.2.0"
+    "@objectstack/spec": "11.0.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3",

package/src/cel-engine.ts

@@ -126,6 +126,42 @@ export function firstUndeclaredReference(
   return null;
 }
 
+/**
+ * The result type cel-js's type-checker infers for a `value`/`predicate`
+ * expression — its raw CEL type name (`'int'`, `'double'`, `'string'`, `'bool'`,
+ * `'google.protobuf.Timestamp'`, `'dyn'`, …) — or `null` when the expression does
+ * not type-check. Reuses the SAME record-scoped, stdlib-registered env as
+ * {@link firstUndeclaredReference}: namespace roots (`record`, `previous`, …) are
+ * declared `map` and `knownFields` are declared `dyn`, so both `record.<field>`
+ * and bare `<field>` references resolve while every stdlib call carries its
+ * declared return type.
+ *
+ * Deliberately conservative. A member access (`record.amount`) or a bare field is
+ * `dyn`, and an operator over two `dyn` operands stays `dyn` (cel-js cannot prove
+ * it numeric), so `record.a + record.b` — which could be string concatenation —
+ * infers `dyn`, not a number. A typed literal or a stdlib return DOES pin the
+ * type, so the common computed-number formulas resolve concretely:
+ * `daysBetween(start_date, end_date) + 1` → `int`, `amount * 0.1` → `double`. A
+ * caller keying off a concrete numeric type therefore never mis-classifies an
+ * ambiguous formula.
+ */
+export function inferCelType(source: string, knownFields: readonly string[] = []): string | null {
+  if (typeof source !== 'string' || !source.trim()) return null;
+  try {
+    const env = knownFields.length === 0
+      ? (recordScopeEnv ??= buildScopedEnv([]))
+      : buildScopedEnv(knownFields);
+    const result = env.parse(source).check?.() as
+      | { valid?: boolean; type?: unknown }
+      | undefined;
+    if (!result || result.valid === false) return null;
+    return typeof result.type === 'string' ? result.type : null;
+  } catch {
+    // Parse/other faults mean we cannot prove a type — the conservative `null`.
+    return null;
+  }
+}
+
 /** @deprecated use {@link firstUndeclaredReference} with no fields. */
 export function detectBareReference(source: string): string | null {
   return firstUndeclaredReference(source);

package/src/index.ts

@@ -24,7 +24,7 @@ export type { CelFilterCompileResult, CelFilterCompileOptions, CelFilterFailReas
 export { matchesFilterCondition } from './matches-filter';
 // ADR-0032 — shared validator + introspection (one validator for build,
 // registration, and the agent-callable validate_expression tool).
-export { validateExpression, introspectScope, expectedDialect, CEL_STDLIB_FUNCTIONS } from './validate';
-export type { FieldRole, ExprSchemaHint, ExprValidationError, ExprValidationResult } from './validate';
+export { validateExpression, introspectScope, expectedDialect, inferExpressionType, CEL_STDLIB_FUNCTIONS } from './validate';
+export type { FieldRole, ExprInput, ExprSchemaHint, ExprValidationError, ExprValidationResult, InferredValueType } from './validate';
 export type { SeedValue, SeedPrimitive } from './seed-eval';
 export type { DialectEngine, EvalContext, EvalResult, EvalError } from './types';

package/src/stdlib.ts

@@ -14,6 +14,7 @@
 import type { Environment } from '@marcbachmann/cel-js';
 
 import type { EvalContext } from './types';
+import { createEvalUser, type EvalUser } from '@objectstack/spec';
 
 /**
  * Calendar-day parts (y/m/d) of an instant *as seen in a timezone*
@@ -266,6 +267,34 @@ export function registerNumericCoercions(env: Environment): Environment {
   return env;
 }
 
+/**
+ * Normalize the loosely-typed EvalContext user into the canonical EvalUser
+ * (ADR-0068). `roles` is preferred; a legacy singular `role` is folded in so
+ * existing call sites keep working.
+ */
+function toEvalUser(u: NonNullable<EvalContext['user']>): EvalUser {
+  const legacyRole = typeof u.role === 'string' && u.role ? [u.role] : [];
+  const roles = Array.isArray(u.roles) ? (u.roles as string[]) : [];
+  const canonical = createEvalUser({
+    id: u.id,
+    name: typeof u.name === 'string' ? u.name : undefined,
+    email: typeof u.email === 'string' ? u.email : undefined,
+    roles: [...roles, ...legacyRole],
+    organizationId:
+      typeof u.organizationId === 'string' || u.organizationId === null
+        ? (u.organizationId as string | null)
+        : undefined,
+  });
+  // Back-compat: keep the DEPRECATED singular `role` readable so existing
+  // predicates (`os.user.role`, `current_user.role`) keep resolving during the
+  // ADR-0068 migration window. `roles[]` is the canonical surface; the footgun
+  // ADR-0068 removes is the server-side OVERWRITE of `role`, not read access.
+  if (typeof u.role === 'string' && u.role) {
+    (canonical as EvalUser & { role?: string }).role = u.role;
+  }
+  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.
@@ -279,7 +308,19 @@ export function buildScope(ctx: EvalContext): Record<string, unknown> {
 
   // Namespaced data — written as `os.user.id`, `os.env`, etc. in CEL.
   const os: Record<string, unknown> = {};
-  if (ctx.user !== undefined) os.user = ctx.user;
+  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;

package/src/types.ts

@@ -30,9 +30,22 @@ export interface EvalContext {
    * Defaults to `UTC` when unset. Calendar-day `date` rendering stays tz-naive.
    */
   timezone?: string;
-  /** Current authenticated subject (hook / action / view contexts). */
+  /**
+   * Current authenticated subject (hook / action / view contexts).
+   *
+   * ADR-0068: the canonical user contract is {@link EvalUser} from
+   * `@objectstack/spec`, surfaced to predicates as `current_user` (aliases
+   * `user`, `ctx.user`). `roles: string[]` is the only canonical role field;
+   * the singular `role` is deprecated (its "overwritten to 'admin' on
+   * promotion" behavior is the footgun ADR-0068 eliminates).
+   */
   user?: {
     id: string;
+    /** CANONICAL (ADR-0068). Scope-resolved role names assigned to the user. */
+    roles?: string[];
+    /** Active organization ID (null = platform / unscoped). */
+    organizationId?: string | null;
+    /** @deprecated ADR-0068 — use {@link roles}. Retained for back-compat only. */
     role?: string;
     email?: string;
     [key: string]: unknown;

package/src/validate.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { validateExpression, introspectScope, expectedDialect } from './validate';
+import { validateExpression, introspectScope, expectedDialect, inferExpressionType } from './validate';
 
 describe('validateExpression (ADR-0032)', () => {
   describe('predicates (CEL)', () => {
@@ -165,3 +165,45 @@ describe('validateExpression (ADR-0032)', () => {
     });
   });
 });
+
+describe('inferExpressionType — coarse value-type of a formula', () => {
+  // The host object's fields, so a bare `<field>` reference resolves the same as
+  // `record.<field>` (a stored formula may be written either way).
+  const fields = ['start_date', 'end_date', 'amount', 'rate', 'first', 'last', 'name', 'items'];
+
+  it('infers number for a computed-number formula (the leave_days repro)', () => {
+    // daysBetween(...): int, int + 1 → int → number. The exact case a "total
+    // leave days" dashboard card needs a SUM measure derived for.
+    expect(inferExpressionType('daysBetween(start_date, end_date) + 1', { fields })).toBe('number');
+    expect(inferExpressionType('daysBetween(record.start_date, record.end_date) + 1')).toBe('number');
+    expect(inferExpressionType('amount * 0.1', { fields })).toBe('number'); // dyn * double → double
+    expect(inferExpressionType('round(amount)', { fields })).toBe('number');
+    expect(inferExpressionType('len(items)', { fields })).toBe('number');
+  });
+
+  it('accepts the canonical Expression envelope as input', () => {
+    expect(inferExpressionType({ dialect: 'cel', source: 'amount * 0.1' }, { fields })).toBe('number');
+  });
+
+  it('infers text / boolean / date for non-numeric formulas', () => {
+    expect(inferExpressionType('upper(name)', { fields })).toBe('text');
+    expect(inferExpressionType('rate >= 0.5', { fields })).toBe('boolean');
+    expect(inferExpressionType('today()')).toBe('date');
+  });
+
+  it('is conservative — an ambiguous (dyn) result is unknown, never number', () => {
+    // `first + last` could be string concatenation OR numeric addition; with two
+    // untyped operands cel-js yields `dyn`, so we must NOT call it a number (else
+    // a dataset would SUM a text formula). This is the safety property.
+    expect(inferExpressionType('first + last', { fields })).toBe('unknown');
+    expect(inferExpressionType('amount + rate', { fields })).toBe('unknown');
+  });
+
+  it('returns unknown for empty, absent, or un-type-checkable expressions', () => {
+    expect(inferExpressionType('')).toBe('unknown');
+    expect(inferExpressionType(null)).toBe('unknown');
+    expect(inferExpressionType(undefined)).toBe('unknown');
+    expect(inferExpressionType('no_such_fn(amount)', { fields })).toBe('unknown'); // no overload
+    expect(inferExpressionType('undeclared_field + 1')).toBe('unknown'); // bare ref, no fields given
+  });
+});

package/src/validate.ts

@@ -17,7 +17,7 @@
  * This validator detects that specific mistake and returns the exact fix.
  */
 
-import { celEngine, firstUndeclaredReference } from './cel-engine';
+import { celEngine, firstUndeclaredReference, inferCelType } from './cel-engine';
 import { templateEngine } from './template-engine';
 
 export type FieldRole = 'predicate' | 'value' | 'template';
@@ -53,6 +53,14 @@ export interface ExprSchemaHint {
    *                    did-you-mean *warning*. (Default.)
    */
   scope?: 'record' | 'flattened';
+  /**
+   * 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.roles`) 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[];
 }
 
 export interface ExprValidationError {
@@ -146,6 +154,51 @@ function levenshtein(a: string, b: string): number {
   return dp[m];
 }
 
+// ADR-0068 D4 — role-membership predicate heads: a role NAME literal used in a
+// membership test against a user subject's `.roles` (or the deprecated singular
+// `.role`). Matched names are validated against the closed role catalog.
+const ROLE_IN_RE = /(['"])([a-z0-9_]+)\1\s+in\s+(?:current_user|user|ctx\.user)\.roles\b/g;
+const ROLE_CONTAINS_RE = /(?:current_user|user|ctx\.user)\.roles\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.roles.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)\.roles\s*\.\s*exists\s*\([^,)]{0,64},[^)=]{0,128}==\s*(['"])([a-z0-9_]+)\1/g;
+const ROLE_EQ_RE = /(?:current_user|user|ctx\.user)\.role\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({
+        source,
+        message:
+          `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)
@@ -194,6 +247,7 @@ export function validateExpression(
     });
   } else {
     checkFieldExistence(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.
@@ -246,16 +300,61 @@ 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: ['record', 'previous', 'input', 'os', 'vars'],
+    roots: ['record', 'previous', 'input', 'os', 'current_user', 'user', 'vars'],
+    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 } = toSource(input);
+  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: