@objectstack/formula 4.0.4

package/dist/index.mjs

@@ -0,0 +1,300 @@
+// src/cel-engine.ts
+import { Environment } from "@marcbachmann/cel-js";
+
+// src/stdlib.ts
+function startOfDayUtc(d) {
+  const out = new Date(d.getTime());
+  out.setUTCHours(0, 0, 0, 0);
+  return out;
+}
+function addDaysUtc(d, n) {
+  const out = new Date(d.getTime());
+  out.setUTCDate(out.getUTCDate() + n);
+  return out;
+}
+function registerStdLib(env, now) {
+  return env.registerFunction("now(): google.protobuf.Timestamp", () => now()).registerFunction(
+    "today(): google.protobuf.Timestamp",
+    () => startOfDayUtc(now())
+  ).registerFunction(
+    "daysFromNow(int): google.protobuf.Timestamp",
+    (n) => addDaysUtc(now(), Number(n))
+  ).registerFunction(
+    "daysAgo(int): google.protobuf.Timestamp",
+    (n) => addDaysUtc(now(), -Number(n))
+  );
+}
+function buildScope(ctx) {
+  const scope = {};
+  if (ctx.record !== void 0) scope.record = ctx.record;
+  if (ctx.previous !== void 0) scope.previous = ctx.previous;
+  if (ctx.input !== void 0) scope.input = ctx.input;
+  const os = {};
+  if (ctx.user !== void 0) os.user = ctx.user;
+  if (ctx.org !== void 0) os.org = ctx.org;
+  if (ctx.env !== void 0) os.env = ctx.env;
+  if (Object.keys(os).length > 0) scope.os = os;
+  if (ctx.extra !== void 0) Object.assign(scope, ctx.extra);
+  return scope;
+}
+
+// src/cel-engine.ts
+var DEFAULT_LIMITS = {
+  maxAstNodes: 256,
+  maxDepth: 32,
+  maxListElements: 64,
+  maxMapEntries: 64,
+  maxCallArguments: 16
+};
+function buildEnv(now) {
+  const env = new Environment({
+    unlistedVariablesAreDyn: true,
+    enableOptionalTypes: true,
+    limits: DEFAULT_LIMITS
+  });
+  return registerStdLib(env, now);
+}
+function coerce(value) {
+  if (typeof value === "bigint") {
+    if (value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) {
+      return Number(value);
+    }
+    return value.toString();
+  }
+  if (Array.isArray(value)) return value.map(coerce);
+  if (value && typeof value === "object" && !(value instanceof Date)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = coerce(v);
+    return out;
+  }
+  return value;
+}
+function classifyError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  let kind = "runtime";
+  if (/Exceeded max/i.test(message)) kind = "bounds";
+  else if (/parse|unexpected|syntax/i.test(message)) kind = "parse";
+  else if (/type|unknown variable|undeclared/i.test(message)) kind = "type";
+  return { ok: false, error: { kind, message } };
+}
+var celEngine = {
+  dialect: "cel",
+  compile(source) {
+    try {
+      const env = buildEnv(() => /* @__PURE__ */ new Date(0));
+      const compiled = env.parse(source);
+      const checkErrors = compiled.check?.();
+      if (checkErrors && Array.isArray(checkErrors) && checkErrors.length > 0) {
+        return {
+          ok: false,
+          error: { kind: "type", message: checkErrors.join("; ") }
+        };
+      }
+      return { ok: true, value: compiled.ast };
+    } catch (err) {
+      return classifyError(err);
+    }
+  },
+  evaluate(expr, ctx) {
+    if (expr.dialect !== "cel") {
+      return {
+        ok: false,
+        error: { kind: "dialect", message: `celEngine cannot evaluate dialect '${expr.dialect}'` }
+      };
+    }
+    const source = expr.source;
+    if (typeof source !== "string" || source.length === 0) {
+      return {
+        ok: false,
+        error: { kind: "parse", message: "AST-only evaluation not yet supported; persist `source`" }
+      };
+    }
+    const now = () => ctx.now ?? /* @__PURE__ */ new Date();
+    try {
+      const env = buildEnv(now);
+      const scope = buildScope(ctx);
+      const raw = env.evaluate(source, scope);
+      return { ok: true, value: coerce(raw) };
+    } catch (err) {
+      return classifyError(err);
+    }
+  }
+};
+
+// src/registry.ts
+var registry = /* @__PURE__ */ new Map();
+function register(engine) {
+  registry.set(engine.dialect, engine);
+}
+function getEngine(dialect) {
+  return registry.get(dialect);
+}
+function hasDialect(dialect) {
+  return registry.has(dialect) && !registry.get(dialect).dialect.startsWith("stub:");
+}
+function makeStub(dialect, reason) {
+  return {
+    dialect,
+    compile: () => ({ ok: false, error: { kind: "dialect", message: reason } }),
+    evaluate: () => ({ ok: false, error: { kind: "dialect", message: reason } })
+  };
+}
+register(celEngine);
+register(makeStub("js", "dialect 'js' not registered. Install @objectstack/plugin-js-vm"));
+register(makeStub("cron", "dialect 'cron' not registered. Install @objectstack/plugin-cron"));
+var ExpressionEngine = {
+  register,
+  getEngine,
+  hasDialect,
+  /**
+   * Compile-only — parse + type-check, returning the engine-native AST. Used
+   * by `objectstack compile` to normalize source into AST in artifacts.
+   */
+  compile(expr) {
+    const engine = registry.get(expr.dialect);
+    if (!engine) {
+      return {
+        ok: false,
+        error: { kind: "dialect", message: `No engine registered for dialect '${expr.dialect}'` }
+      };
+    }
+    if (typeof expr.source !== "string") {
+      return {
+        ok: false,
+        error: { kind: "parse", message: "Expression.source required for compile()" }
+      };
+    }
+    return engine.compile(expr.source);
+  },
+  /**
+   * Evaluate an expression in the given context. Never throws — branch on
+   * `result.ok`. Errors carry a `kind` for caller-side classification.
+   */
+  evaluate(expr, ctx) {
+    const engine = registry.get(expr.dialect);
+    if (!engine) {
+      return {
+        ok: false,
+        error: { kind: "dialect", message: `No engine registered for dialect '${expr.dialect}'` }
+      };
+    }
+    return engine.evaluate(expr, ctx);
+  }
+};
+
+// src/seed-eval.ts
+import { ExpressionSchema } from "@objectstack/spec";
+function isExpressionLike(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const v = value;
+  if (typeof v.dialect !== "string") return false;
+  return ExpressionSchema.safeParse(v).success;
+}
+function resolveSeed(value, ctx) {
+  if (value === null || value === void 0) {
+    return { ok: true, value };
+  }
+  const t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean") {
+    return { ok: true, value };
+  }
+  if (value instanceof Date) {
+    return { ok: true, value };
+  }
+  if (Array.isArray(value)) {
+    const out2 = [];
+    for (const item of value) {
+      const r = resolveSeed(item, ctx);
+      if (!r.ok) return r;
+      out2.push(r.value);
+    }
+    return { ok: true, value: out2 };
+  }
+  if (isExpressionLike(value)) {
+    return ExpressionEngine.evaluate(value, ctx);
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    const r = resolveSeed(v, ctx);
+    if (!r.ok) return r;
+    out[k] = r.value;
+  }
+  return { ok: true, value: out };
+}
+function resolveSeedRecord(record, ctx) {
+  const pinnedCtx = { ...ctx, now: ctx.now ?? /* @__PURE__ */ new Date() };
+  const result = resolveSeed(record, pinnedCtx);
+  return result;
+}
+
+// src/normalize.ts
+import {
+  ExpressionInputSchema,
+  ExpressionSchema as ExpressionSchema2
+} from "@objectstack/spec";
+function normalizeExpression(input) {
+  const parsed = ExpressionInputSchema.safeParse(input);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: { kind: "parse", message: parsed.error.message }
+    };
+  }
+  const expr = parsed.data;
+  if (expr.ast !== void 0 && expr.source === void 0) {
+    return { ok: true, value: expr };
+  }
+  const compiled = ExpressionEngine.compile(expr);
+  if (!compiled.ok) {
+    return compiled;
+  }
+  return {
+    ok: true,
+    value: {
+      ...expr,
+      ast: compiled.value
+    }
+  };
+}
+function normalizeExpressionTree(root, path = []) {
+  if (root === null || typeof root !== "object") return null;
+  if (looksLikeExpression(root)) {
+    const r = normalizeExpression(root);
+    if (!r.ok) return { path: path.join("."), error: r.error };
+    Object.assign(root, r.value);
+    return null;
+  }
+  if (Array.isArray(root)) {
+    for (let i = 0; i < root.length; i++) {
+      const r = normalizeExpressionTree(root[i], [...path, String(i)]);
+      if (r) return r;
+    }
+    return null;
+  }
+  for (const [k, v] of Object.entries(root)) {
+    const r = normalizeExpressionTree(v, [...path, k]);
+    if (r) return r;
+  }
+  return null;
+}
+function looksLikeExpression(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const v = value;
+  if (typeof v.dialect !== "string") return false;
+  return ExpressionSchema2.safeParse(v).success;
+}
+export {
+  DEFAULT_LIMITS,
+  ExpressionEngine,
+  buildScope,
+  celEngine,
+  getEngine,
+  hasDialect,
+  normalizeExpression,
+  normalizeExpressionTree,
+  register,
+  registerStdLib,
+  resolveSeed,
+  resolveSeedRecord
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cel-engine.ts","../src/stdlib.ts","../src/registry.ts","../src/seed-eval.ts","../src/normalize.ts"],"sourcesContent":["/**\n * CEL dialect engine — wraps `@marcbachmann/cel-js` with the ObjectStack\n * stdlib, bounded execution limits, and result coercion.\n *\n * Why a thin wrapper:\n *\n *  - cel-js returns `BigInt` for ints. The kernel and CRM expect plain\n *    numbers, so we coerce at the boundary.\n *  - cel-js parses dotted names as receiver-typed methods; we register\n *    `now()`, `today()`, `daysFromNow()` as bare functions and let `os.*`\n *    refer to context data only (see {@link buildScope}).\n *  - Bounds (`maxAstNodes`, `maxDepth`, …) are enforced spec-wide so\n *    third-party plugins can't ship runaway predicates.\n */\n\nimport { Environment } from '@marcbachmann/cel-js';\nimport type { Expression } from '@objectstack/spec';\n\nimport { buildScope, registerStdLib } from './stdlib';\nimport type { DialectEngine, EvalContext, EvalResult } from './types';\n\n/**\n * Default execution bounds. Picked conservatively — every metadata-authored\n * expression we've seen is well under these. If you hit them, the expression\n * is too complex for ObjectStack and should be moved to a hook (`dialect: js`).\n */\nexport const DEFAULT_LIMITS = {\n  maxAstNodes: 256,\n  maxDepth: 32,\n  maxListElements: 64,\n  maxMapEntries: 64,\n  maxCallArguments: 16,\n} as const;\n\nfunction buildEnv(now: () => Date): Environment {\n  const env = new Environment({\n    unlistedVariablesAreDyn: true,\n    enableOptionalTypes: true,\n    limits: DEFAULT_LIMITS,\n  });\n  return registerStdLib(env, now);\n}\n\n/** Coerce cel-js's BigInt-flavored return into spec-friendly JS values. */\nfunction coerce(value: unknown): unknown {\n  if (typeof value === 'bigint') {\n    // BigInt → number when safe, else string to avoid silent truncation.\n    if (value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) {\n      return Number(value);\n    }\n    return value.toString();\n  }\n  if (Array.isArray(value)) return value.map(coerce);\n  if (value && typeof value === 'object' && !(value instanceof Date)) {\n    const out: Record<string, unknown> = {};\n    for (const [k, v] of Object.entries(value)) out[k] = coerce(v);\n    return out;\n  }\n  return value;\n}\n\nfunction classifyError(err: unknown): EvalResult<never> {\n  const message = err instanceof Error ? err.message : String(err);\n  let kind: 'parse' | 'type' | 'runtime' | 'bounds' = 'runtime';\n  if (/Exceeded max/i.test(message)) kind = 'bounds';\n  else if (/parse|unexpected|syntax/i.test(message)) kind = 'parse';\n  else if (/type|unknown variable|undeclared/i.test(message)) kind = 'type';\n  return { ok: false, error: { kind, message } };\n}\n\nexport const celEngine: DialectEngine = {\n  dialect: 'cel',\n\n  compile(source: string): EvalResult<unknown> {\n    try {\n      // We use a wall-clock now() here purely for parse-time stdlib\n      // type-checking; the function is never actually called.\n      const env = buildEnv(() => new Date(0));\n      const compiled = env.parse(source);\n      // Surface check errors eagerly.\n      const checkErrors = compiled.check?.();\n      if (checkErrors && Array.isArray(checkErrors) && checkErrors.length > 0) {\n        return {\n          ok: false,\n          error: { kind: 'type', message: checkErrors.join('; ') },\n        };\n      }\n      return { ok: true, value: compiled.ast };\n    } catch (err) {\n      return classifyError(err);\n    }\n  },\n\n  evaluate<T = unknown>(expr: Expression, ctx: EvalContext): EvalResult<T> {\n    if (expr.dialect !== 'cel') {\n      return {\n        ok: false,\n        error: { kind: 'dialect', message: `celEngine cannot evaluate dialect '${expr.dialect}'` },\n      };\n    }\n    const source = expr.source;\n    if (typeof source !== 'string' || source.length === 0) {\n      // AST-only inputs: cel-js does not currently expose a public API to\n      // re-execute a parsed AST without re-serializing. We persist `source`\n      // as the canonical form during M9.1 and revisit AST-only execution in\n      // M9.7 when we cut the spec persistence over.\n      return {\n        ok: false,\n        error: { kind: 'parse', message: 'AST-only evaluation not yet supported; persist `source`' },\n      };\n    }\n\n    const now = () => ctx.now ?? new Date();\n    try {\n      const env = buildEnv(now);\n      const scope = buildScope(ctx);\n      const raw = env.evaluate(source, scope);\n      return { ok: true, value: coerce(raw) as T };\n    } catch (err) {\n      return classifyError(err);\n    }\n  },\n};\n","/**\n * ObjectStack standard CEL function library.\n *\n * Registered into the per-evaluation `Environment` by the CEL engine. All\n * functions are pure given a pinned `now` — that determinism is what makes\n * `objectstack build` artifacts byte-stable across runs.\n *\n * Function naming intentionally avoids the `os.` prefix because cel-js binds\n * dotted names to receiver types. Instead, the `os` namespace in CEL holds\n * *data* (`os.user`, `os.org`, `os.env`) supplied by the caller's\n * {@link EvalContext}.\n */\n\nimport type { Environment } from '@marcbachmann/cel-js';\n\nimport type { EvalContext } from './types';\n\n/** Truncate a Date to start-of-day in UTC. */\nfunction startOfDayUtc(d: Date): Date {\n  const out = new Date(d.getTime());\n  out.setUTCHours(0, 0, 0, 0);\n  return out;\n}\n\n/** Add `n` days to a Date in UTC; returns a new Date. */\nfunction addDaysUtc(d: Date, n: number): Date {\n  const out = new Date(d.getTime());\n  out.setUTCDate(out.getUTCDate() + n);\n  return out;\n}\n\n/**\n * Register the ObjectStack standard library into a CEL environment.\n *\n * The `now` resolver is closed over so each call uses the pinned\n * `EvalContext.now` (or wall-clock fallback). Implementations are kept tiny\n * and dependency-free — they're the contract surface for AI authors and must\n * stay legible.\n */\nexport function registerStdLib(\n  env: Environment,\n  now: () => Date,\n): Environment {\n  return env\n    .registerFunction('now(): google.protobuf.Timestamp', () => now())\n    .registerFunction(\n      'today(): google.protobuf.Timestamp',\n      () => startOfDayUtc(now()),\n    )\n    .registerFunction(\n      'daysFromNow(int): google.protobuf.Timestamp',\n      (n: bigint | number) => addDaysUtc(now(), Number(n)),\n    )\n    .registerFunction(\n      'daysAgo(int): google.protobuf.Timestamp',\n      (n: bigint | number) => addDaysUtc(now(), -Number(n)),\n    );\n}\n\n/**\n * Build the variable scope for a single evaluation. Absent fields are simply\n * not bound — CEL macros (`has(record.foo)`) handle missing-key safely.\n */\nexport function buildScope(ctx: EvalContext): Record<string, unknown> {\n  const scope: Record<string, unknown> = {};\n\n  if (ctx.record !== undefined) scope.record = ctx.record;\n  if (ctx.previous !== undefined) scope.previous = ctx.previous;\n  if (ctx.input !== undefined) scope.input = ctx.input;\n\n  // Namespaced data — written as `os.user.id`, `os.env`, etc. in CEL.\n  const os: Record<string, unknown> = {};\n  if (ctx.user !== undefined) os.user = ctx.user;\n  if (ctx.org !== undefined) os.org = ctx.org;\n  if (ctx.env !== undefined) os.env = ctx.env;\n  if (Object.keys(os).length > 0) scope.os = os;\n\n  if (ctx.extra !== undefined) Object.assign(scope, ctx.extra);\n\n  return scope;\n}\n","/**\n * Dialect-pluggable Expression engine registry.\n *\n * Replaces the per-call-site `compileFormula` / `evaluateFormula` direct\n * imports of the deleted custom engine. Call sites now ask the registry to\n * dispatch by `expression.dialect`.\n *\n * Stub dialects (`js`, `cron`) are registered at module load with explicit\n * `dialect`-error responses so call sites get a clear message instead of\n * silent `undefined` (the old engine's anti-pattern).\n */\n\nimport type { Expression } from '@objectstack/spec';\n\nimport { celEngine } from './cel-engine';\nimport type { DialectEngine, EvalContext, EvalResult } from './types';\n\nconst registry = new Map<string, DialectEngine>();\n\n/** Register or replace a dialect engine. */\nexport function register(engine: DialectEngine): void {\n  registry.set(engine.dialect, engine);\n}\n\n/** Look up a dialect engine without dispatching. */\nexport function getEngine(dialect: string): DialectEngine | undefined {\n  return registry.get(dialect);\n}\n\n/** Whether a dialect has a real (non-stub) implementation registered. */\nexport function hasDialect(dialect: string): boolean {\n  return registry.has(dialect) && !registry.get(dialect)!.dialect.startsWith('stub:');\n}\n\nfunction makeStub(dialect: string, reason: string): DialectEngine {\n  return {\n    dialect,\n    compile: () => ({ ok: false, error: { kind: 'dialect', message: reason } }),\n    evaluate: () => ({ ok: false, error: { kind: 'dialect', message: reason } }),\n  };\n}\n\n// Real engines.\nregister(celEngine);\n\n// Stubs — phased in by later milestones (M9.5+ for `js`, M9.6 for `cron`).\nregister(makeStub('js', \"dialect 'js' not registered. Install @objectstack/plugin-js-vm\"));\nregister(makeStub('cron', \"dialect 'cron' not registered. Install @objectstack/plugin-cron\"));\n\n/**\n * The unified evaluation entry point. Replaces the old direct calls to\n * `evaluateFormula` from the deleted custom engine.\n */\nexport const ExpressionEngine = {\n  register,\n  getEngine,\n  hasDialect,\n\n  /**\n   * Compile-only — parse + type-check, returning the engine-native AST. Used\n   * by `objectstack compile` to normalize source into AST in artifacts.\n   */\n  compile(expr: Expression): EvalResult<unknown> {\n    const engine = registry.get(expr.dialect);\n    if (!engine) {\n      return {\n        ok: false,\n        error: { kind: 'dialect', message: `No engine registered for dialect '${expr.dialect}'` },\n      };\n    }\n    if (typeof expr.source !== 'string') {\n      return {\n        ok: false,\n        error: { kind: 'parse', message: 'Expression.source required for compile()' },\n      };\n    }\n    return engine.compile(expr.source);\n  },\n\n  /**\n   * Evaluate an expression in the given context. Never throws — branch on\n   * `result.ok`. Errors carry a `kind` for caller-side classification.\n   */\n  evaluate<T = unknown>(expr: Expression, ctx: EvalContext): EvalResult<T> {\n    const engine = registry.get(expr.dialect);\n    if (!engine) {\n      return {\n        ok: false,\n        error: { kind: 'dialect', message: `No engine registered for dialect '${expr.dialect}'` },\n      };\n    }\n    return engine.evaluate<T>(expr, ctx);\n  },\n};\n","/**\n * Seed-value resolver.\n *\n * `Dataset.records` accepts {@link SeedValue} = primitive | Expression | array\n * | object — install-time resolution walks the tree and replaces any\n * Expression node with its evaluated result. This is what makes\n * `close_date: cel\\`now() + duration(\"P30D\")\\`` resolve to *the customer's*\n * \"today + 30 days\" instead of the developer's compile-time clock.\n */\n\nimport { ExpressionSchema, type Expression } from '@objectstack/spec';\n\nimport type { EvalContext, EvalResult } from './types';\nimport { ExpressionEngine } from './registry';\n\nexport type SeedPrimitive = string | number | boolean | null | Date;\nexport type SeedValue = SeedPrimitive | Expression | SeedValue[] | { [key: string]: SeedValue };\n\n/** Detect an Expression-shaped object without throwing on unrelated shapes. */\nfunction isExpressionLike(value: unknown): value is Expression {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;\n  const v = value as Record<string, unknown>;\n  if (typeof v.dialect !== 'string') return false;\n  return ExpressionSchema.safeParse(v).success;\n}\n\n/**\n * Recursively resolve a SeedValue. Records that contain Expression leaves are\n * evaluated with `ctx`; other values are passed through unchanged.\n *\n * Returns the first failure encountered. Callers (seed loader) typically\n * abort the whole record on failure rather than silently writing partial data.\n */\nexport function resolveSeed(\n  value: SeedValue,\n  ctx: EvalContext,\n): EvalResult<unknown> {\n  if (value === null || value === undefined) {\n    return { ok: true, value };\n  }\n  const t = typeof value;\n  if (t === 'string' || t === 'number' || t === 'boolean') {\n    return { ok: true, value };\n  }\n  if (value instanceof Date) {\n    return { ok: true, value };\n  }\n  if (Array.isArray(value)) {\n    const out: unknown[] = [];\n    for (const item of value) {\n      const r = resolveSeed(item, ctx);\n      if (!r.ok) return r;\n      out.push(r.value);\n    }\n    return { ok: true, value: out };\n  }\n  if (isExpressionLike(value)) {\n    return ExpressionEngine.evaluate(value, ctx);\n  }\n  // Plain object — recurse field-by-field.\n  const out: Record<string, unknown> = {};\n  for (const [k, v] of Object.entries(value as Record<string, SeedValue>)) {\n    const r = resolveSeed(v, ctx);\n    if (!r.ok) return r;\n    out[k] = r.value;\n  }\n  return { ok: true, value: out };\n}\n\n/**\n * Resolve a single record (object of fields), pinning `ctx.now` so all\n * expressions within see one logical clock.\n */\nexport function resolveSeedRecord(\n  record: Record<string, SeedValue>,\n  ctx: EvalContext,\n): EvalResult<Record<string, unknown>> {\n  const pinnedCtx: EvalContext = { ...ctx, now: ctx.now ?? new Date() };\n  const result = resolveSeed(record, pinnedCtx) as EvalResult<Record<string, unknown>>;\n  return result;\n}\n","/**\n * Build-time normalization helpers.\n *\n * The CLI `objectstack compile` step walks the assembled `objectstack.json`\n * artifact and rewrites every Expression so that:\n *\n *  1. String shorthand input is replaced by `{ dialect: 'cel', source }`.\n *  2. The persisted envelope carries an `ast` field produced by the dialect\n *     engine (M9.2 deliverable). Source is retained for round-trip / debug.\n *\n * Spec layer cannot do step 2 because it must remain dependency-free; this\n * package owns the engine import and therefore the AST step.\n */\n\nimport {\n  ExpressionInputSchema,\n  ExpressionSchema,\n  type Expression,\n  type ExpressionInput,\n} from '@objectstack/spec';\n\nimport { ExpressionEngine } from './registry';\nimport type { EvalResult } from './types';\n\n/**\n * Normalize an {@link ExpressionInput} (string shorthand OR full envelope) into\n * a fully-resolved {@link Expression} carrying both `source` and `ast`.\n *\n * Returns an EvalResult so the caller can render a structured compile error\n * pointing at the offending metadata path.\n */\nexport function normalizeExpression(input: ExpressionInput): EvalResult<Expression> {\n  const parsed = ExpressionInputSchema.safeParse(input);\n  if (!parsed.success) {\n    return {\n      ok: false,\n      error: { kind: 'parse', message: parsed.error.message },\n    };\n  }\n\n  const expr = parsed.data as Expression;\n\n  // Already AST-only — accept as-is.\n  if (expr.ast !== undefined && expr.source === undefined) {\n    return { ok: true, value: expr };\n  }\n\n  // Source-bearing: ask the dialect engine to compile. Failures surface here\n  // as part of the build (no silent skip).\n  const compiled = ExpressionEngine.compile(expr);\n  if (!compiled.ok) {\n    return compiled;\n  }\n\n  return {\n    ok: true,\n    value: {\n      ...expr,\n      ast: compiled.value,\n    },\n  };\n}\n\n/**\n * Walk an arbitrary JSON tree and normalize every embedded Expression in\n * place. Used by the build pipeline to traverse the assembled metadata\n * artifact. Returns the first error encountered (paired with the dotted path\n * for diagnostics) or `null` when fully clean.\n */\nexport function normalizeExpressionTree(\n  root: unknown,\n  path: string[] = [],\n): { path: string; error: import('./types').EvalError } | null {\n  if (root === null || typeof root !== 'object') return null;\n\n  if (looksLikeExpression(root)) {\n    const r = normalizeExpression(root as ExpressionInput);\n    if (!r.ok) return { path: path.join('.'), error: r.error };\n    Object.assign(root as Record<string, unknown>, r.value);\n    return null;\n  }\n\n  if (Array.isArray(root)) {\n    for (let i = 0; i < root.length; i++) {\n      const r = normalizeExpressionTree(root[i], [...path, String(i)]);\n      if (r) return r;\n    }\n    return null;\n  }\n\n  for (const [k, v] of Object.entries(root as Record<string, unknown>)) {\n    const r = normalizeExpressionTree(v, [...path, k]);\n    if (r) return r;\n  }\n  return null;\n}\n\nfunction looksLikeExpression(value: unknown): boolean {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;\n  const v = value as Record<string, unknown>;\n  if (typeof v.dialect !== 'string') return false;\n  return ExpressionSchema.safeParse(v).success;\n}\n"],"mappings":"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","names":["out","ExpressionSchema","ExpressionSchema"]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@objectstack/formula",
+  "version": "4.0.4",
+  "license": "Apache-2.0",
+  "description": "ObjectStack canonical expression engine — CEL (cel-js) + ObjectStack stdlib + dialect registry",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@marcbachmann/cel-js": "^7.6.1",
+    "@objectstack/spec": "4.0.4"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
+  },
+  "keywords": [
+    "objectstack",
+    "formula",
+    "expression",
+    "cel",
+    "predicate"
+  ],
+  "author": "ObjectStack",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/objectstack-ai/framework.git",
+    "directory": "packages/formula"
+  },
+  "homepage": "https://objectstack.ai/docs",
+  "bugs": "https://github.com/objectstack-ai/framework/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "test": "vitest run"
+  }
+}

package/src/cel-engine.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+
+import { celEngine } from './cel-engine';
+import type { Expression } from '@objectstack/spec';
+
+const cel = (source: string): Expression => ({ dialect: 'cel', source });
+
+describe('celEngine', () => {
+  it('evaluates simple arithmetic, coercing BigInt to number', () => {
+    const r = celEngine.evaluate(cel('1 + 2'), {});
+    expect(r).toEqual({ ok: true, value: 3 });
+  });
+
+  it('evaluates predicates against record context', () => {
+    const r = celEngine.evaluate(cel('record.amount > 1000'), {
+      record: { amount: 1500 },
+    });
+    expect(r).toEqual({ ok: true, value: true });
+  });
+
+  it('exposes os.* namespace from EvalContext', () => {
+    const r = celEngine.evaluate(cel('os.user.role == "manager"'), {
+      user: { id: 'u1', role: 'manager' },
+    });
+    expect(r).toEqual({ ok: true, value: true });
+  });
+
+  it('uses pinned now() for determinism', () => {
+    const pinned = new Date('2026-01-15T10:00:00Z');
+    const r = celEngine.evaluate(cel('now()'), { now: pinned });
+    expect(r.ok).toBe(true);
+    if (r.ok) expect((r.value as Date).toISOString()).toBe(pinned.toISOString());
+  });
+
+  it('today() truncates to UTC start-of-day', () => {
+    const pinned = new Date('2026-01-15T10:30:45.123Z');
+    const r = celEngine.evaluate(cel('today()'), { now: pinned });
+    expect(r.ok).toBe(true);
+    if (r.ok) expect((r.value as Date).toISOString()).toBe('2026-01-15T00:00:00.000Z');
+  });
+
+  it('daysFromNow(n) advances by n days from pinned now', () => {
+    const pinned = new Date('2026-01-15T10:00:00Z');
+    const r = celEngine.evaluate(cel('daysFromNow(30)'), { now: pinned });
+    expect(r.ok).toBe(true);
+    if (r.ok) expect((r.value as Date).toISOString()).toBe('2026-02-14T10:00:00.000Z');
+  });
+
+  it('classifies parse errors with kind=parse', () => {
+    const r = celEngine.evaluate(cel('1 +'), {});
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(['parse', 'type', 'runtime']).toContain(r.error.kind);
+  });
+
+  it('enforces AST size bounds (kind=bounds)', () => {
+    const huge = Array.from({ length: 500 }, (_, i) => i.toString()).join(' + ');
+    const r = celEngine.evaluate(cel(huge), {});
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error.kind).toBe('bounds');
+  });
+
+  it('rejects evaluation when dialect mismatches', () => {
+    const r = celEngine.evaluate({ dialect: 'js', source: 'x' } as Expression, {});
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error.kind).toBe('dialect');
+  });
+
+  it('compile() returns AST on success', () => {
+    const r = celEngine.compile('record.amount > 1000');
+    expect(r.ok).toBe(true);
+  });
+
+  it('handles timestamp + duration arithmetic', () => {
+    const pinned = new Date('2026-01-01T00:00:00Z');
+    const r = celEngine.evaluate(cel('now() + duration("720h")'), { now: pinned });
+    expect(r.ok).toBe(true);
+    if (r.ok) expect((r.value as Date).toISOString()).toBe('2026-01-31T00:00:00.000Z');
+  });
+
+  it('coerces large BigInt to string to avoid silent truncation', () => {
+    const r = celEngine.evaluate(cel('9999999999999999999'), {});
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(typeof r.value === 'string' || typeof r.value === 'number').toBe(true);
+  });
+});

package/src/cel-engine.ts

@@ -0,0 +1,123 @@
+/**
+ * CEL dialect engine — wraps `@marcbachmann/cel-js` with the ObjectStack
+ * stdlib, bounded execution limits, and result coercion.
+ *
+ * Why a thin wrapper:
+ *
+ *  - cel-js returns `BigInt` for ints. The kernel and CRM expect plain
+ *    numbers, so we coerce at the boundary.
+ *  - cel-js parses dotted names as receiver-typed methods; we register
+ *    `now()`, `today()`, `daysFromNow()` as bare functions and let `os.*`
+ *    refer to context data only (see {@link buildScope}).
+ *  - Bounds (`maxAstNodes`, `maxDepth`, …) are enforced spec-wide so
+ *    third-party plugins can't ship runaway predicates.
+ */
+
+import { Environment } from '@marcbachmann/cel-js';
+import type { Expression } from '@objectstack/spec';
+
+import { buildScope, registerStdLib } from './stdlib';
+import type { DialectEngine, EvalContext, EvalResult } from './types';
+
+/**
+ * Default execution bounds. Picked conservatively — every metadata-authored
+ * expression we've seen is well under these. If you hit them, the expression
+ * is too complex for ObjectStack and should be moved to a hook (`dialect: js`).
+ */
+export const DEFAULT_LIMITS = {
+  maxAstNodes: 256,
+  maxDepth: 32,
+  maxListElements: 64,
+  maxMapEntries: 64,
+  maxCallArguments: 16,
+} as const;
+
+function buildEnv(now: () => Date): Environment {
+  const env = new Environment({
+    unlistedVariablesAreDyn: true,
+    enableOptionalTypes: true,
+    limits: DEFAULT_LIMITS,
+  });
+  return registerStdLib(env, now);
+}
+
+/** Coerce cel-js's BigInt-flavored return into spec-friendly JS values. */
+function coerce(value: unknown): unknown {
+  if (typeof value === 'bigint') {
+    // BigInt → number when safe, else string to avoid silent truncation.
+    if (value >= BigInt(Number.MIN_SAFE_INTEGER) && value <= BigInt(Number.MAX_SAFE_INTEGER)) {
+      return Number(value);
+    }
+    return value.toString();
+  }
+  if (Array.isArray(value)) return value.map(coerce);
+  if (value && typeof value === 'object' && !(value instanceof Date)) {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(value)) out[k] = coerce(v);
+    return out;
+  }
+  return value;
+}
+
+function classifyError(err: unknown): EvalResult<never> {
+  const message = err instanceof Error ? err.message : String(err);
+  let kind: 'parse' | 'type' | 'runtime' | 'bounds' = 'runtime';
+  if (/Exceeded max/i.test(message)) kind = 'bounds';
+  else if (/parse|unexpected|syntax/i.test(message)) kind = 'parse';
+  else if (/type|unknown variable|undeclared/i.test(message)) kind = 'type';
+  return { ok: false, error: { kind, message } };
+}
+
+export const celEngine: DialectEngine = {
+  dialect: 'cel',
+
+  compile(source: string): EvalResult<unknown> {
+    try {
+      // We use a wall-clock now() here purely for parse-time stdlib
+      // type-checking; the function is never actually called.
+      const env = buildEnv(() => new Date(0));
+      const compiled = env.parse(source);
+      // Surface check errors eagerly.
+      const checkErrors = compiled.check?.();
+      if (checkErrors && Array.isArray(checkErrors) && checkErrors.length > 0) {
+        return {
+          ok: false,
+          error: { kind: 'type', message: checkErrors.join('; ') },
+        };
+      }
+      return { ok: true, value: compiled.ast };
+    } catch (err) {
+      return classifyError(err);
+    }
+  },
+
+  evaluate<T = unknown>(expr: Expression, ctx: EvalContext): EvalResult<T> {
+    if (expr.dialect !== 'cel') {
+      return {
+        ok: false,
+        error: { kind: 'dialect', message: `celEngine cannot evaluate dialect '${expr.dialect}'` },
+      };
+    }
+    const source = expr.source;
+    if (typeof source !== 'string' || source.length === 0) {
+      // AST-only inputs: cel-js does not currently expose a public API to
+      // re-execute a parsed AST without re-serializing. We persist `source`
+      // as the canonical form during M9.1 and revisit AST-only execution in
+      // M9.7 when we cut the spec persistence over.
+      return {
+        ok: false,
+        error: { kind: 'parse', message: 'AST-only evaluation not yet supported; persist `source`' },
+      };
+    }
+
+    const now = () => ctx.now ?? new Date();
+    try {
+      const env = buildEnv(now);
+      const scope = buildScope(ctx);
+      const raw = env.evaluate(source, scope);
+      return { ok: true, value: coerce(raw) as T };
+    } catch (err) {
+      return classifyError(err);
+    }
+  },
+};

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @objectstack/formula
+ *
+ * Canonical expression engine for ObjectStack. CEL (Common Expression
+ * Language) is the default dialect; `js` and `cron` are dispatched to
+ * dedicated plugin engines.
+ *
+ * @see content/docs/concepts/north-star.mdx §8 "No private expression DSL"
+ * @see ROADMAP.md M9 "Expression Unification"
+ */
+
+export { ExpressionEngine, getEngine, hasDialect, register } from './registry';
+export { celEngine, DEFAULT_LIMITS } from './cel-engine';
+export { registerStdLib, buildScope } from './stdlib';
+export { resolveSeed, resolveSeedRecord } from './seed-eval';
+export { normalizeExpression, normalizeExpressionTree } from './normalize';
+export type { SeedValue, SeedPrimitive } from './seed-eval';
+export type { DialectEngine, EvalContext, EvalResult, EvalError } from './types';