@objectstack/formula 7.5.0 → 7.6.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/formula@7.5.0 build /home/runner/work/framework/framework/packages/formula
+> @objectstack/formula@7.6.0 build /home/runner/work/framework/framework/packages/formula
 > tsup --config ../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     13.16 KB
-ESM dist/index.mjs.map 34.88 KB
-ESM ⚡️ Build success in 91ms
-CJS dist/index.js     14.65 KB
-CJS dist/index.js.map 35.85 KB
-CJS ⚡️ Build success in 91ms
+ESM dist/index.mjs     21.98 KB
+ESM dist/index.mjs.map 55.52 KB
+ESM ⚡️ Build success in 76ms
+CJS dist/index.js     23.69 KB
+CJS dist/index.js.map 56.88 KB
+CJS ⚡️ Build success in 78ms
 DTS Build start
-DTS ⚡️ Build success in 4396ms
-DTS dist/index.d.mts 10.73 KB
-DTS dist/index.d.ts  10.73 KB
+DTS ⚡️ Build success in 4811ms
+DTS dist/index.d.mts 14.02 KB
+DTS dist/index.d.ts  14.02 KB

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @objectstack/formula
 
+## 7.6.0
+
+### Minor Changes
+
+- c4a4cbd: ADR-0032 (phase 1): validate-by-default expression layer — no silent failure.
+
+  Kills the #1491 class where a malformed predicate (e.g. the `{record.x}`
+  template-brace-in-CEL mistake) silently evaluated to `false` and made a flow
+  "fire" with no effect:
+
+  - **service-automation**: flow `evaluateCondition` no longer swallows CEL
+    failures to `false` — it throws an attributed, corrective error; and
+    `registerFlow` now parse-validates every predicate (start/decision/edge
+    condition) at registration, failing loudly with the offending location +
+    source + the fix.
+  - **formula**: new shared validator — `validateExpression(role, src, schema?)`,
+    `introspectScope`, `CEL_STDLIB_FUNCTIONS` — with schema-aware field-existence
+    - did-you-mean. The `{{ }}` template engine gains a formatter whitelist
+      (`currency`/`number`/`percent`/`date`/`datetime`/`truncate`/`upper`/`lower`/
+      `default`/…) with defined value→string semantics; arbitrary logic in holes is
+      rejected. Plain `{{ path }}` stays back-compatible.
+  - **cli**: `objectstack compile` validates every flow / validation-rule /
+    field-formula predicate against the resolved object schema and fails the
+    build with located, corrective messages.
+  - **service-ai**: new agent-callable `validate_expression` tool so authoring
+    agents self-correct before committing.
+  - **spec**: fix the `FlowSchema` JSDoc example that taught the bad
+    `condition: "{amount} < 500"` single-brace form.
+
+### Patch Changes
+
+- Updated dependencies [955d4c8]
+- Updated dependencies [c4a4cbd]
+- Updated dependencies [b046ec2]
+- Updated dependencies [2170ad9]
+- Updated dependencies [02d6359]
+- Updated dependencies [7648242]
+- Updated dependencies [8fa1e7f]
+- Updated dependencies [55866f5]
+- Updated dependencies [60f9c45]
+  - @objectstack/spec@7.6.0
+
 ## 7.5.0
 
 ### Patch Changes

package/dist/index.d.mts

@@ -179,21 +179,25 @@ declare const celEngine: DialectEngine;
 declare const cronEngine: DialectEngine;
 
 /**
- * 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.
  */
 
+/** Public list of whitelisted template formatters (for introspection/docs). */
+declare const TEMPLATE_FORMATTERS: string[];
 declare const templateEngine: DialectEngine;
 
 /**
@@ -271,4 +275,72 @@ declare function normalizeExpressionTree(root: unknown, path?: string[]): {
     error: EvalError;
 } | null;
 
-export { DEFAULT_LIMITS, type DialectEngine, type EvalContext, type EvalError, type EvalResult, ExpressionEngine, type SeedPrimitive, type SeedValue, buildScope, celEngine, cronEngine, getEngine, hasDialect, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine };
+/**
+ * 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.
+ */
+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.
+ */
+type ExprInput = string | {
+    dialect?: string;
+    source?: string;
+} | null | undefined;
+/** Optional schema context for field-existence checks (Decision 1b, v1). */
+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[];
+}
+interface ExprValidationError {
+    /** Self-correcting message: what is wrong + the correct form. */
+    message: string;
+    /** The offending source, echoed for location. */
+    source: string;
+}
+interface ExprValidationResult {
+    ok: boolean;
+    errors: ExprValidationError[];
+}
+/** The dialect a field role expects (Decision 2). */
+declare function expectedDialect(role: FieldRole): 'cel' | 'template';
+/**
+ * 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).
+ */
+declare function validateExpression(role: FieldRole, input: ExprInput, schema?: ExprSchemaHint): ExprValidationResult;
+/**
+ * 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.
+ */
+declare function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
+    dialect: 'cel' | 'template';
+    fields: string[];
+    roots: string[];
+    functions: string[];
+};
+/** Public catalog of CEL stdlib functions available in expressions. */
+declare const CEL_STDLIB_FUNCTIONS: string[];
+
+export { CEL_STDLIB_FUNCTIONS, DEFAULT_LIMITS, type DialectEngine, type EvalContext, type EvalError, type EvalResult, type ExprSchemaHint, type ExprValidationError, type ExprValidationResult, ExpressionEngine, type FieldRole, type SeedPrimitive, type SeedValue, TEMPLATE_FORMATTERS, buildScope, celEngine, cronEngine, expectedDialect, getEngine, hasDialect, introspectScope, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };

package/dist/index.d.ts

@@ -179,21 +179,25 @@ declare const celEngine: DialectEngine;
 declare const cronEngine: DialectEngine;
 
 /**
- * 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.
  */
 
+/** Public list of whitelisted template formatters (for introspection/docs). */
+declare const TEMPLATE_FORMATTERS: string[];
 declare const templateEngine: DialectEngine;
 
 /**
@@ -271,4 +275,72 @@ declare function normalizeExpressionTree(root: unknown, path?: string[]): {
     error: EvalError;
 } | null;
 
-export { DEFAULT_LIMITS, type DialectEngine, type EvalContext, type EvalError, type EvalResult, ExpressionEngine, type SeedPrimitive, type SeedValue, buildScope, celEngine, cronEngine, getEngine, hasDialect, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine };
+/**
+ * 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.
+ */
+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.
+ */
+type ExprInput = string | {
+    dialect?: string;
+    source?: string;
+} | null | undefined;
+/** Optional schema context for field-existence checks (Decision 1b, v1). */
+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[];
+}
+interface ExprValidationError {
+    /** Self-correcting message: what is wrong + the correct form. */
+    message: string;
+    /** The offending source, echoed for location. */
+    source: string;
+}
+interface ExprValidationResult {
+    ok: boolean;
+    errors: ExprValidationError[];
+}
+/** The dialect a field role expects (Decision 2). */
+declare function expectedDialect(role: FieldRole): 'cel' | 'template';
+/**
+ * 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).
+ */
+declare function validateExpression(role: FieldRole, input: ExprInput, schema?: ExprSchemaHint): ExprValidationResult;
+/**
+ * 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.
+ */
+declare function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
+    dialect: 'cel' | 'template';
+    fields: string[];
+    roots: string[];
+    functions: string[];
+};
+/** Public catalog of CEL stdlib functions available in expressions. */
+declare const CEL_STDLIB_FUNCTIONS: string[];
+
+export { CEL_STDLIB_FUNCTIONS, DEFAULT_LIMITS, type DialectEngine, type EvalContext, type EvalError, type EvalResult, type ExprSchemaHint, type ExprValidationError, type ExprValidationResult, ExpressionEngine, type FieldRole, type SeedPrimitive, type SeedValue, TEMPLATE_FORMATTERS, buildScope, celEngine, cronEngine, expectedDialect, getEngine, hasDialect, introspectScope, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };