@objectstack/formula 7.5.0 → 7.7.0

package/src/template-engine.ts

@@ -1,17 +1,19 @@
 /**
- * Template dialect engine — strict Mustache subset.
+ * Template dialect engine — strict Mustache subset with a formatter whitelist.
  *
- * Supports `{{path.to.value}}` interpolation only. No conditionals, no loops,
- * no helpers. The variable scope is the same as CEL (`record`, `previous`,
- * `input`, `os.user`, `os.org`, `os.env`, plus `extra`), so authors can move
- * fluidly between a CEL formula and a template body without re-learning a
- * second variable namespace.
+ * Holes are `{{ path }}` or `{{ path | formatter[:'arg'] }}` (ADR-0032 §3).
+ * Holes are restricted to a **field/variable path** plus a **whitelisted
+ * formatter** — never arbitrary CEL logic — so the grammar stays small (low
+ * author/agent error surface), GUI-pickable (path + formatter dropdown), and
+ * display strings stay declarative. Real logic belongs in `Predicate`/`Expr`
+ * (CEL) fields, where it is validated and visible.
  *
- * Why a separate dialect from CEL: templates produce strings (notification
- * subjects, prompt bodies, titleFormat). CEL is a value-typed expression
- * language. Routing them through the same envelope (`{ dialect: 'template' }`)
- * keeps the AI author rule simple — "anything templated or computed is an
- * Expression" — without conflating the two semantics.
+ * The variable scope is the same as CEL (`record`, `previous`, `input`,
+ * `os.user/org/env`, plus `extra`), so authors move fluidly between a CEL
+ * formula and a template body without re-learning a namespace.
+ *
+ * Value→string semantics are explicit and defined per formatter (numbers,
+ * dates, money, percent, null), instead of implicit coercion.
  */
 
 import type { Expression } from '@objectstack/spec';
@@ -19,21 +21,110 @@ import type { Expression } from '@objectstack/spec';
 import { buildScope } from './stdlib';
 import type { DialectEngine, EvalContext, EvalResult } from './types';
 
-const PATH_RE = /\{\{\s*([\w.[\]]+?)\s*\}\}/g;
+/**
+ * A hole: capture the full inner content (no `}` allowed inside). Uses a single
+ * greedy `[^}]*` (not `\s*…\s*` around a lazy group) so the pattern is linear —
+ * `\s` is a subset of `[^}]`, and wrapping a lazy group in `\s*` creates an
+ * ambiguous (polynomial-ReDoS) matcher. Surrounding whitespace is stripped in
+ * `parseHole` instead.
+ */
+const HOLE_RE = /\{\{([^}]*)\}\}/g;
 
-function resolvePath(scope: Record<string, unknown>, path: string): unknown {
-  // Support `a.b.c` and `a[0].b` style. Bracket notation collapses to dotted.
-  const normalized = path.replace(/\[(\w+)\]/g, '.$1');
-  const segments = normalized.split('.').filter(Boolean);
-  let cursor: unknown = scope;
-  for (const seg of segments) {
-    if (cursor == null || typeof cursor !== 'object') return undefined;
-    cursor = (cursor as Record<string, unknown>)[seg];
+// ───────────────────────── formatter whitelist (ADR-0032 §3) ──────────────
+
+type Formatter = (value: unknown, arg: string | undefined, locale: string) => string;
+
+function asNumber(v: unknown): number | undefined {
+  if (typeof v === 'number') return v;
+  if (typeof v === 'bigint') return Number(v);
+  if (typeof v === 'string' && v.trim() !== '' && !Number.isNaN(Number(v))) return Number(v);
+  return undefined;
+}
+
+function asDate(v: unknown): Date | undefined {
+  if (v instanceof Date) return v;
+  if (typeof v === 'number') return new Date(v);
+  if (typeof v === 'string') {
+    const d = new Date(v);
+    if (!Number.isNaN(d.getTime())) return d;
   }
-  return cursor;
+  return undefined;
 }
 
-function stringify(value: unknown): string {
+const FORMATTERS: Record<string, Formatter> = {
+  upper: (v) => baseString(v).toUpperCase(),
+  lower: (v) => baseString(v).toLowerCase(),
+  trim: (v) => baseString(v).trim(),
+  // number | number:2  → grouped, optional fixed decimals
+  number: (v, arg, locale) => {
+    const n = asNumber(v);
+    if (n === undefined) return baseString(v);
+    const digits = arg !== undefined ? Number(arg) : undefined;
+    return new Intl.NumberFormat(locale, digits !== undefined && !Number.isNaN(digits)
+      ? { minimumFractionDigits: digits, maximumFractionDigits: digits } : {}).format(n);
+  },
+  // currency | currency:EUR  → defaults to USD
+  currency: (v, arg, locale) => {
+    const n = asNumber(v);
+    if (n === undefined) return baseString(v);
+    const code = (arg && arg.trim()) || 'USD';
+    try {
+      return new Intl.NumberFormat(locale, { style: 'currency', currency: code }).format(n);
+    } catch {
+      return new Intl.NumberFormat(locale, { style: 'currency', currency: 'USD' }).format(n);
+    }
+  },
+  // percent | percent:1  → 0.42 → "42%" (value is a 0..1 ratio)
+  percent: (v, arg, locale) => {
+    const n = asNumber(v);
+    if (n === undefined) return baseString(v);
+    const digits = arg !== undefined ? Number(arg) : 0;
+    return new Intl.NumberFormat(locale, {
+      style: 'percent',
+      minimumFractionDigits: Number.isNaN(digits) ? 0 : digits,
+      maximumFractionDigits: Number.isNaN(digits) ? 0 : digits,
+    }).format(n);
+  },
+  // date | date:long | date:iso  → date-only
+  date: (v, arg, locale) => {
+    const d = asDate(v);
+    if (!d) return baseString(v);
+    if (arg === 'iso') return d.toISOString().slice(0, 10);
+    const style = arg === 'long' ? 'long' : arg === 'medium' ? 'medium' : 'short';
+    return new Intl.DateTimeFormat(locale, { dateStyle: style as 'short' | 'medium' | 'long' }).format(d);
+  },
+  // datetime | datetime:long | datetime:iso
+  datetime: (v, arg, locale) => {
+    const d = asDate(v);
+    if (!d) return baseString(v);
+    if (arg === 'iso') return d.toISOString();
+    const style = arg === 'long' ? 'long' : arg === 'medium' ? 'medium' : 'short';
+    return new Intl.DateTimeFormat(locale, {
+      dateStyle: style as 'short' | 'medium' | 'long',
+      timeStyle: style as 'short' | 'medium' | 'long',
+    }).format(d);
+  },
+  // truncate:80  → cut with an ellipsis
+  truncate: (v, arg) => {
+    const s = baseString(v);
+    const len = arg !== undefined ? Number(arg) : 80;
+    if (Number.isNaN(len) || s.length <= len) return s;
+    return s.slice(0, Math.max(0, len - 1)) + '…';
+  },
+  // default:'N/A'  → fallback when the value is null/undefined/empty
+  default: (v, arg) => {
+    const s = baseString(v);
+    return s === '' ? (arg ?? '') : s;
+  },
+  json: (v) => {
+    try { return JSON.stringify(v); } catch { return String(v); }
+  },
+};
+
+/** Public list of whitelisted template formatters (for introspection/docs). */
+export const TEMPLATE_FORMATTERS: string[] = Object.keys(FORMATTERS);
+
+function baseString(value: unknown): string {
   if (value === null || value === undefined) return '';
   if (value instanceof Date) return value.toISOString();
   if (typeof value === 'string') return value;
@@ -46,23 +137,76 @@ function stringify(value: unknown): string {
   }
 }
 
-function compileTemplate(source: string): EvalResult<string[]> {
-  // Compile is only a structural validity check — no helpers, no balanced
-  // open/close beyond what the regex enforces.
-  const matches = source.match(/\{\{|\}\}/g) ?? [];
-  if (matches.length % 2 !== 0) {
-    return {
-      ok: false,
-      error: { kind: 'parse', message: 'template has unbalanced {{ }} delimiters' },
-    };
+function resolvePath(scope: Record<string, unknown>, path: string): unknown {
+  const normalized = path.replace(/\[(\w+)\]/g, '.$1');
+  const segments = normalized.split('.').filter(Boolean);
+  let cursor: unknown = scope;
+  for (const seg of segments) {
+    if (cursor == null || typeof cursor !== 'object') return undefined;
+    cursor = (cursor as Record<string, unknown>)[seg];
   }
-  const refs: string[] = [];
+  return cursor;
+}
+
+interface ParsedHole {
+  path: string;
+  filter?: { name: string; arg?: string };
+}
+
+const PATH_ONLY_RE = /^[\w.[\]]+$/;
+
+/**
+ * Parse a hole's inner content into a path + optional single formatter.
+ * Returns null when the inner content is not a valid path[+formatter] form
+ * (e.g. arbitrary CEL was written into a hole — rejected, ADR-0032 §3).
+ */
+function parseHole(inner: string): ParsedHole | null {
+  const pipe = inner.indexOf('|');
+  if (pipe === -1) {
+    const path = inner.trim();
+    return PATH_ONLY_RE.test(path) ? { path } : null;
+  }
+  const path = inner.slice(0, pipe).trim();
+  if (!PATH_ONLY_RE.test(path)) return null;
+  const filterPart = inner.slice(pipe + 1).trim();
+  // `name` or `name:arg` or `name:'arg'`
+  const colon = filterPart.indexOf(':');
+  let name = filterPart;
+  let arg: string | undefined;
+  if (colon !== -1) {
+    name = filterPart.slice(0, colon).trim();
+    arg = filterPart.slice(colon + 1).trim().replace(/^['"]|['"]$/g, '');
+  }
+  if (!FORMATTERS[name]) return null;
+  return { path, filter: { name, arg } };
+}
+
+function compileTemplate(source: string): EvalResult<ParsedHole[]> {
+  const open = (source.match(/\{\{/g) ?? []).length;
+  const close = (source.match(/\}\}/g) ?? []).length;
+  if (open !== close) {
+    return { ok: false, error: { kind: 'parse', message: 'template has unbalanced {{ }} delimiters' } };
+  }
+  const holes: ParsedHole[] = [];
   let m: RegExpExecArray | null;
-  PATH_RE.lastIndex = 0;
-  while ((m = PATH_RE.exec(source)) !== null) {
-    refs.push(m[1]);
+  HOLE_RE.lastIndex = 0;
+  while ((m = HOLE_RE.exec(source)) !== null) {
+    const parsed = parseHole(m[1]);
+    if (!parsed) {
+      return {
+        ok: false,
+        error: {
+          kind: 'parse',
+          message:
+            `invalid template hole \`{{ ${m[1]} }}\` — holes are a field path with an optional ` +
+            `formatter (\`{{ record.amount | currency }}\`), not arbitrary logic. ` +
+            `Move logic into a CEL field. Known formatters: ${TEMPLATE_FORMATTERS.join(', ')}.`,
+        },
+      };
+    }
+    holes.push(parsed);
   }
-  return { ok: true, value: refs };
+  return { ok: true, value: holes };
 }
 
 export const templateEngine: DialectEngine = {
@@ -80,17 +224,25 @@ export const templateEngine: DialectEngine = {
       };
     }
     if (typeof expr.source !== 'string') {
-      return {
-        ok: false,
-        error: { kind: 'parse', message: 'template Expression.source required' },
-      };
+      return { ok: false, error: { kind: 'parse', message: 'template Expression.source required' } };
     }
     const check = compileTemplate(expr.source);
     if (!check.ok) return check as EvalResult<T>;
 
     const scope = buildScope(ctx);
-    const out = expr.source.replace(PATH_RE, (_match, path) => {
-      return stringify(resolvePath(scope, path));
+    const locale =
+      (ctx.extra && typeof ctx.extra.locale === 'string' && ctx.extra.locale) ||
+      (typeof (ctx as { locale?: string }).locale === 'string' && (ctx as { locale?: string }).locale) ||
+      'en-US';
+
+    const out = expr.source.replace(HOLE_RE, (_match, inner) => {
+      const parsed = parseHole(String(inner));
+      if (!parsed) return _match; // compile already validated; defensive
+      const value = resolvePath(scope, parsed.path);
+      if (parsed.filter) {
+        return FORMATTERS[parsed.filter.name](value, parsed.filter.arg, locale as string);
+      }
+      return baseString(value);
     });
     return { ok: true, value: out as unknown as T };
   },

package/src/template-formatters.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect } from 'vitest';
+import { templateEngine, TEMPLATE_FORMATTERS } from './template-engine';
+
+function render(source: string, record: Record<string, unknown>): string {
+  const r = templateEngine.evaluate<string>({ dialect: 'template', source }, { record, extra: { locale: 'en-US' } });
+  if (!r.ok) throw new Error(r.error.message);
+  return r.value;
+}
+
+describe('template formatters (ADR-0032 §3)', () => {
+  it('keeps plain {{ path }} back-compatible (identity stringify)', () => {
+    expect(render('Hi {{ record.name }}', { name: 'Jane' })).toBe('Hi Jane');
+  });
+
+  it('currency (default USD + explicit code)', () => {
+    expect(render('{{ record.amt | currency }}', { amt: 1234.5 })).toBe('$1,234.50');
+    expect(render('{{ record.amt | currency:EUR }}', { amt: 1000 })).toContain('1,000');
+  });
+
+  it('number with fixed decimals', () => {
+    expect(render('{{ record.n | number:2 }}', { n: 1234.5 })).toBe('1,234.50');
+  });
+
+  it('percent (ratio → %)', () => {
+    expect(render('{{ record.r | percent }}', { r: 0.42 })).toBe('42%');
+    expect(render('{{ record.r | percent:1 }}', { r: 0.425 })).toBe('42.5%');
+  });
+
+  it('date:iso', () => {
+    expect(render('{{ record.d | date:iso }}', { d: '2026-06-02T10:00:00Z' })).toBe('2026-06-02');
+  });
+
+  it('truncate + upper + default', () => {
+    expect(render('{{ record.s | truncate:5 }}', { s: 'abcdefgh' })).toBe('abcd…');
+    expect(render('{{ record.s | upper }}', { s: 'hi' })).toBe('HI');
+    expect(render("{{ record.missing | default:'N/A' }}", {})).toBe('N/A');
+  });
+
+  it('rejects arbitrary logic in a hole (not a path+formatter)', () => {
+    const r = templateEngine.compile('{{ record.a > 5 ? "x" : "y" }}');
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error.message).toMatch(/field path with an optional formatter|arbitrary logic/);
+  });
+
+  it('rejects an unknown formatter', () => {
+    const r = templateEngine.compile('{{ record.a | bogus }}');
+    expect(r.ok).toBe(false);
+  });
+
+  it('exposes the formatter catalog', () => {
+    expect(TEMPLATE_FORMATTERS).toEqual(
+      expect.arrayContaining(['currency', 'number', 'percent', 'date', 'datetime', 'truncate', 'upper', 'lower', 'default']),
+    );
+  });
+});

package/src/validate.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest';
+import { validateExpression, introspectScope, expectedDialect } from './validate';
+
+describe('validateExpression (ADR-0032)', () => {
+  describe('predicates (CEL)', () => {
+    it('accepts a valid bare-CEL predicate', () => {
+      const r = validateExpression('predicate', 'record.rating >= 4');
+      expect(r.ok).toBe(true);
+      expect(r.errors).toHaveLength(0);
+    });
+
+    it('rejects the #1491 brace-in-CEL form with a corrective message', () => {
+      const r = validateExpression('predicate', '{record.rating} >= 4');
+      expect(r.ok).toBe(false);
+      expect(r.errors[0].message).toMatch(/map literal|bare reference|template brace/i);
+      expect(r.errors[0].message).toContain('record.rating');
+      expect(r.errors[0].source).toBe('{record.rating} >= 4');
+    });
+
+    it('rejects a CEL envelope placed in a template-only role', () => {
+      const r = validateExpression('template', { dialect: 'cel', source: 'record.x' });
+      expect(r.ok).toBe(false);
+    });
+
+    it('accepts an empty/absent expression (no-op)', () => {
+      expect(validateExpression('predicate', '').ok).toBe(true);
+      expect(validateExpression('predicate', null).ok).toBe(true);
+    });
+  });
+
+  describe('templates', () => {
+    it('accepts a valid {{ path }} template', () => {
+      const r = validateExpression('template', 'Hot lead: {{ record.full_name }}');
+      expect(r.ok).toBe(true);
+    });
+
+    it('flags single-brace {x} in a template and suggests {{ }}', () => {
+      const r = validateExpression('template', 'Hi {record.name}');
+      expect(r.ok).toBe(false);
+      expect(r.errors[0].message).toMatch(/\{\{ record\.name \}\}|double braces/);
+    });
+  });
+
+  describe('schema-aware field existence (v1)', () => {
+    it('flags an unknown record field with a did-you-mean', () => {
+      const r = validateExpression('predicate', 'record.raitng >= 4', { objectName: 'crm_lead', fields: ['rating', 'status'] });
+      expect(r.ok).toBe(false);
+      expect(r.errors[0].message).toMatch(/unknown field `raitng`/);
+      expect(r.errors[0].message).toMatch(/did you mean `rating`/);
+    });
+
+    it('passes when fields exist', () => {
+      const r = validateExpression('predicate', 'record.rating >= 4 && record.status == "new"', { fields: ['rating', 'status'] });
+      expect(r.ok).toBe(true);
+    });
+
+    it('skips field checks when no schema is provided', () => {
+      expect(validateExpression('predicate', 'record.anything > 1').ok).toBe(true);
+    });
+  });
+
+  describe('introspection', () => {
+    it('reports the dialect + scope for a field role', () => {
+      expect(expectedDialect('predicate')).toBe('cel');
+      expect(expectedDialect('template')).toBe('template');
+      const scope = introspectScope('predicate', { fields: ['rating'] });
+      expect(scope.dialect).toBe('cel');
+      expect(scope.fields).toContain('rating');
+      expect(scope.roots).toContain('record');
+      expect(scope.functions).toContain('daysFromNow');
+    });
+  });
+});

package/src/validate.ts

@@ -0,0 +1,207 @@
+/**
+ * Shared expression validator (ADR-0032 §Decision 1/5).
+ *
+ * One validator, used by every author surface — `objectstack build`,
+ * `registerFlow`/metadata registration, and the agent-callable
+ * `validate_expression` tool — so a malformed expression is caught the same
+ * way everywhere, with a message written for **self-correction** (Decision 1d):
+ * it states what is wrong AND the correct form.
+ *
+ * Field roles map to dialects (Decision 2):
+ *   - `predicate`  → bare CEL returning bool (`record.rating >= 4`)
+ *   - `value`      → bare CEL of any type   (`daysFromNow(3)`)
+ *   - `template`   → text with `{{ path }}` holes (`Hot lead: {{ record.name }}`)
+ *
+ * The #1 author error (human or LLM) is wrapping a field reference in single
+ * `{…}` braces inside a CEL field — `{x}` parses as a CEL map literal and fails.
+ * This validator detects that specific mistake and returns the exact fix.
+ */
+
+import { celEngine } from './cel-engine';
+import { templateEngine } from './template-engine';
+
+export type FieldRole = 'predicate' | 'value' | 'template';
+
+/**
+ * Loose input accepted by the validator: a bare string, or any object exposing
+ * `dialect`/`source` (the Expression envelope, or a not-yet-narrowed value from
+ * a `config.condition` / `edge.condition` field). Kept structural so call sites
+ * need not pre-narrow to the strict {@link Expression} dialect union.
+ */
+export type ExprInput = string | { dialect?: string; source?: string } | null | undefined;
+
+/** Optional schema context for field-existence checks (Decision 1b, v1). */
+export interface ExprSchemaHint {
+  /** Object the expression is authored against (for error text). */
+  objectName?: string;
+  /** Known top-level field names, so `record.<field>` can be checked. */
+  fields?: readonly string[];
+}
+
+export interface ExprValidationError {
+  /** Self-correcting message: what is wrong + the correct form. */
+  message: string;
+  /** The offending source, echoed for location. */
+  source: string;
+}
+
+export interface ExprValidationResult {
+  ok: boolean;
+  errors: ExprValidationError[];
+}
+
+/** A bare `{x}` that is NOT part of a `{{x}}` mustache hole. */
+const SINGLE_BRACE_RE = /(?:^|[^{])\{\s*([A-Za-z_$][\w.$]*)\s*\}(?!\})/;
+/** `record.<field>` / `previous.<field>` head references for field-existence. */
+const RECORD_REF_RE = /\b(?:record|previous)\.([A-Za-z_$][\w$]*)/g;
+
+/** The dialect a field role expects (Decision 2). */
+export function expectedDialect(role: FieldRole): 'cel' | 'template' {
+  return role === 'template' ? 'template' : 'cel';
+}
+
+function toSource(input: ExprInput): { dialect?: string; source: string } {
+  if (input == null) return { source: '' };
+  if (typeof input === 'string') return { source: input };
+  return { dialect: input.dialect, source: input.source ?? '' };
+}
+
+function bracesHint(source: string): string | null {
+  const m = SINGLE_BRACE_RE.exec(source);
+  if (!m) return null;
+  const ref = m[1];
+  return (
+    `it looks like a \`{${ref}}\` template brace was used inside a CEL expression — ` +
+    `\`{…}\` parses as a CEL map literal and fails. Write the bare reference instead, e.g. \`${ref}\`.`
+  );
+}
+
+function checkFieldExistence(source: string, schema: ExprSchemaHint | undefined, errors: ExprValidationError[]): void {
+  if (!schema?.fields || schema.fields.length === 0) return;
+  const known = new Set(schema.fields);
+  const seen = new Set<string>();
+  let m: RegExpExecArray | null;
+  RECORD_REF_RE.lastIndex = 0;
+  while ((m = RECORD_REF_RE.exec(source)) !== null) {
+    const field = m[1];
+    if (seen.has(field) || known.has(field)) continue;
+    seen.add(field);
+    const suggestion = nearest(field, schema.fields);
+    errors.push({
+      source,
+      message:
+        `unknown field \`${field}\`${schema.objectName ? ` on \`${schema.objectName}\`` : ''}` +
+        (suggestion ? ` — did you mean \`${suggestion}\`?` : ''),
+    });
+  }
+}
+
+/** Cheap edit-distance suggestion for typo'd field names. */
+function nearest(name: string, candidates: readonly string[]): string | undefined {
+  let best: string | undefined;
+  let bestD = Infinity;
+  for (const c of candidates) {
+    const d = levenshtein(name, c);
+    if (d < bestD) { bestD = d; best = c; }
+  }
+  return bestD <= Math.max(2, Math.floor(name.length / 3)) ? best : undefined;
+}
+
+function levenshtein(a: string, b: string): number {
+  const m = a.length, n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) => i);
+  for (let j = 1; j <= n; j++) {
+    let prev = dp[0];
+    dp[0] = j;
+    for (let i = 1; i <= m; i++) {
+      const tmp = dp[i];
+      dp[i] = Math.min(dp[i] + 1, dp[i - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = tmp;
+    }
+  }
+  return dp[m];
+}
+
+/**
+ * Validate one expression for a given field role. Never throws — returns a
+ * structured result. Call sites decide whether to throw (build/registration)
+ * or report (agent tool).
+ */
+export function validateExpression(
+  role: FieldRole,
+  input: ExprInput,
+  schema?: ExprSchemaHint,
+): ExprValidationResult {
+  const { dialect, source } = toSource(input);
+  const errors: ExprValidationError[] = [];
+  if (!source.trim()) return { ok: true, errors };
+
+  if (role === 'template') {
+    // Templates must be the `template` dialect (or untyped string). Reject a
+    // CEL envelope mistakenly placed in a text field.
+    if (dialect && dialect !== 'template') {
+      errors.push({ source, message: `expected a text template but got a \`${dialect}\` expression.` });
+      return { ok: false, errors };
+    }
+    const compiled = templateEngine.compile(source);
+    if (!compiled.ok) {
+      errors.push({ source, message: `invalid template: ${compiled.error.message} (holes use \`{{ path }}\`).` });
+    }
+    // A single `{x}` in a template is the legacy/deprecated form (ADR-0032 §3).
+    const hint = SINGLE_BRACE_RE.test(source) ? bracesHintForTemplate(source) : null;
+    if (hint) errors.push({ source, message: hint });
+    return { ok: errors.length === 0, errors };
+  }
+
+  // predicate | value → CEL
+  if (dialect && dialect !== 'cel') {
+    errors.push({ source, message: `expected a CEL expression but got a \`${dialect}\` dialect.` });
+    return { ok: false, errors };
+  }
+  const compiled = celEngine.compile(source);
+  if (!compiled.ok) {
+    const hint = bracesHint(source);
+    errors.push({
+      source,
+      message:
+        `invalid CEL ${role}: ${compiled.error.message}` +
+        (hint ? ` — ${hint}` : ` — ${role}s are bare CEL (e.g. \`record.rating >= 4\`).`),
+    });
+  } else {
+    checkFieldExistence(source, schema, errors);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+function bracesHintForTemplate(source: string): string {
+  const m = SINGLE_BRACE_RE.exec(source);
+  const ref = m?.[1] ?? 'field';
+  return `single-brace \`{${ref}}\` is not a valid template hole — use double braces: \`{{ ${ref} }}\`.`;
+}
+
+/**
+ * Introspect what an author (esp. an agent) may use in a field (Decision 1e):
+ * the expected dialect, the in-scope field references, and the callable
+ * functions. Feeds the authoring context so the model does not guess.
+ */
+export function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
+  dialect: 'cel' | 'template';
+  fields: string[];
+  roots: string[];
+  functions: string[];
+} {
+  return {
+    dialect: expectedDialect(role),
+    fields: [...(schema?.fields ?? [])],
+    roots: ['record', 'previous', 'input', 'os', 'vars'],
+    functions: CEL_STDLIB_FUNCTIONS,
+  };
+}
+
+/** Public catalog of CEL stdlib functions available in expressions. */
+export const CEL_STDLIB_FUNCTIONS: string[] = [
+  'now', 'today', 'daysFromNow', 'daysBetween', 'date', 'datetime', 'timestamp',
+  'isBlank', 'isEmpty', 'coalesce', 'len', 'size', 'int', 'float', 'string', 'bool',
+  'upper', 'lower', 'trim', 'contains', 'startsWith', 'endsWith', 'matches',
+  'has', 'min', 'max', 'abs', 'round',
+];