@objectstack/formula 9.10.0 → 10.0.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/formula@9.10.0 build /home/runner/work/framework/framework/packages/formula
+> @objectstack/formula@10.0.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     29.97 KB
-ESM dist/index.mjs.map 83.86 KB
-ESM ⚡️ Build success in 81ms
-CJS dist/index.js     31.74 KB
-CJS dist/index.js.map 85.24 KB
-CJS ⚡️ Build success in 82ms
+CJS dist/index.js     45.02 KB
+CJS dist/index.js.map 120.34 KB
+CJS ⚡️ Build success in 115ms
+ESM dist/index.mjs     43.08 KB
+ESM dist/index.mjs.map 118.46 KB
+ESM ⚡️ Build success in 116ms
 DTS Build start
-DTS ⚡️ Build success in 4436ms
-DTS dist/index.d.mts 16.79 KB
-DTS dist/index.d.ts  16.79 KB
+DTS ⚡️ Build success in 5125ms
+DTS dist/index.d.mts 20.19 KB
+DTS dist/index.d.ts  20.19 KB

package/CHANGELOG.md

@@ -1,5 +1,95 @@
 # @objectstack/formula
 
+## 10.0.0
+
+### Minor Changes
+
+- cfd86ce: ADR-0058 — expression & predicate surface unification. Adds the canonical
+  CEL→FilterCondition pushdown compiler in `@objectstack/formula`
+  (`compileCelToFilter`, `isPushdownableCel`, `lowerCelAst`) plus an in-memory
+  `matchesFilterCondition` backend (one AST, three backends). `plugin-security`
+  (RLS `using`, via a SQL bridge) and `plugin-sharing` (`celToFilter`) cut over to
+  it, retiring the bespoke regex/field-equality front-ends. Compound sharing
+  conditions now compile and enforce end-to-end (closes #1887). The RLS `check`
+  clause is now enforced on the write post-image (insert/by-id update), fail-closed.
+  Non-pushdownable predicates (arithmetic, functions, subqueries, cross-object) are
+  an authoring compile error, never silently dropped (ADR-0049/0055).
+
+### Patch Changes
+
+- 48a307a: build: validate UI action `visible` / `disabled` predicates at compile time
+
+  Extends the ADR-0032 build-time expression check to cover action `visible` and
+  `disabled` predicates (stack-level and object-attached), evaluated record-scoped
+  like validation rules. A record-header / row action's `visible` is evaluated by
+  `ActionEngine` against `{ record, recordId, objectName, user, … }` with
+  fail-closed semantics, so a **bare** field reference (`!done` instead of
+  `!record.done`) throws at runtime and the action is **silently hidden on every
+  record** — the trap behind the #2183 "Mark Done never hides" debugging hunt.
+  `os build` now reports it as an error with the corrective `record.<field>`
+  message instead of letting it ship.
+
+  `@objectstack/formula`: `ctx` and `features` are added to the record-scope
+  namespace roots (alongside the existing `user`, `data`, `context`, …) so the
+  ambient globals real action predicates use (`record.id == ctx.user.id`,
+  `features.multiOrgEnabled`) are not false-positives. Verified against the full
+  monorepo build (every example + platform bundle still compiles clean).
+
+- 25fc0e4: build: extend ADR-0032 predicate validation to all flat record-scoped sites
+
+  Builds on the action-predicate guard. `os build` now also validates these
+  record-scoped predicates for bare field references (`status` instead of
+  `record.status`), which otherwise evaluate to nothing at runtime and silently
+  mis-behave:
+
+  - **field conditional rules** — `requiredWhen`, `readonlyWhen`,
+    `conditionalRequired`, `visibleWhen` (server-enforced; a broken one is
+    fail-open — the required/readonly rule just never fires);
+  - **sharing-rule `condition`** (security-critical — decides which rows a
+    principal sees);
+  - **lifecycle hook `condition`** (skips the handler when false);
+  - **nested `when`** on `conditional` validation rules (previously only the
+    top-level rule predicate was checked).
+
+  `@objectstack/formula`: adds `parent` to the record-scope namespace roots —
+  master-detail inline grids inject the header record as `parent` for a child
+  field's `readonlyWhen`/`requiredWhen` (ADR-0036, #1581), so `parent.status` is
+  legitimate, not a bare ref. Verified against the full monorepo build (76 tasks
+  clean).
+
+  Not yet covered (separate follow-up — needs a recursive view/page tree walker
+  and per-node scope classification): deeply-nested UI visibility predicates
+  (`view` element/section `visibleOn`/`condition`, `page` component `visibility`),
+  object field-group `visibleOn`, and app-nav `visible` (user/feature-scoped, not
+  record-scoped).
+
+- Updated dependencies [d7ff626]
+- Updated dependencies [2a1b16b]
+- Updated dependencies [e16f2a8]
+- Updated dependencies [e411a82]
+- Updated dependencies [a581385]
+- Updated dependencies [220ce5b]
+- Updated dependencies [3efe334]
+- Updated dependencies [feead7e]
+- Updated dependencies [6ca20b3]
+- Updated dependencies [5f875fe]
+- Updated dependencies [b469950]
+  - @objectstack/spec@10.0.0
+
+## 9.11.0
+
+### Patch Changes
+
+- Updated dependencies [e7f6539]
+- Updated dependencies [2365d07]
+- Updated dependencies [6595b53]
+- Updated dependencies [fa8964d]
+- Updated dependencies [36138c7]
+- Updated dependencies [a8e4f3b]
+- Updated dependencies [4c213c2]
+- Updated dependencies [2afb612]
+  - @objectstack/spec@9.11.0
+
 ## 9.10.0
 
 ### Minor Changes

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { Expression, ExpressionInput } from '@objectstack/spec';
-import { Environment } from '@marcbachmann/cel-js';
+import { Environment, ASTNode } from '@marcbachmann/cel-js';
+import { FilterCondition } from '@objectstack/spec/data';
 
 /**
  * @objectstack/formula — public types
@@ -296,6 +297,81 @@ declare function normalizeExpressionTree(root: unknown, path?: string[]): {
     error: EvalError;
 } | null;
 
+type CelFilterFailReason = 
+/** CEL did not parse (syntax error). */
+'parse-error'
+/** Shape is not pushdown-able (arithmetic, function call, relation traversal, …). */
+ | 'unsupported'
+/** A required `variableRoot` reference was undefined/null in `variables`. */
+ | 'unresolved-variable';
+type CelFilterCompileResult = {
+    ok: true;
+    filter: FilterCondition;
+} | {
+    ok: false;
+    reason: CelFilterFailReason;
+    detail: string;
+};
+interface CelFilterCompileOptions {
+    /** Member-access roots that denote a record FIELD path. Default `['record']`. */
+    fieldRoots?: readonly string[];
+    /** Roots resolved as VALUES against {@link variables}. Default `['current_user']`. */
+    variableRoots?: readonly string[];
+    /**
+     * Value-resolution context, keyed by variable root. e.g.
+     * `{ current_user: { id, organization_id, org_user_ids } }`. A `record.*`
+     * (field) reference is NEVER resolved here — only `variableRoot` leaves are.
+     */
+    variables?: Record<string, unknown>;
+}
+/**
+ * Compile a CEL predicate into a {@link FilterCondition}, resolving `variableRoot`
+ * leaves against `opts.variables`. Returns a discriminated result — never throws
+ * for an authoring-level fault; a `false` result with a reason is the caller's
+ * cue to fail closed (deny) or surface a compile error.
+ */
+declare function compileCelToFilter(input: string | {
+    source?: string;
+}, opts?: CelFilterCompileOptions): CelFilterCompileResult;
+/**
+ * Shape-only check: is this CEL predicate pushdown-able at all? Used by the
+ * authoring gate (ADR-0056 D4) to REJECT a predicate the runtime could only
+ * silently drop. Does not resolve `variables`.
+ */
+declare function isPushdownableCel(input: string | {
+    source?: string;
+}, opts?: Pick<CelFilterCompileOptions, 'fieldRoots' | 'variableRoots'>): {
+    ok: true;
+} | {
+    ok: false;
+    reason: CelFilterFailReason;
+    detail: string;
+};
+/**
+ * Lower a pre-parsed cel-js AST node — the variant that lets the interpreter and
+ * the compiler share ONE parse (ADR-0058 D6, "one AST, two backends").
+ */
+declare function lowerCelAst(ast: ASTNode, opts?: CelFilterCompileOptions, mode?: 'value' | 'shape'): CelFilterCompileResult;
+
+/**
+ * matchesFilterCondition — evaluate a Mongo-style {@link FilterCondition} against
+ * ONE in-memory record (ADR-0058 D4/D6).
+ *
+ * This is the third backend for the canonical filter shape, completing the
+ * round-trip: `compileCelToFilter` lowers CEL → FilterCondition; the engine runs
+ * it as a `where`; `read-scope-sql` lowers it to SQL; and THIS evaluates it
+ * against a single record for write-side validation — the RLS `check` clause
+ * (post-image of an insert/update), where there is no query to push down to.
+ *
+ * Security posture: **fail closed.** Anything it cannot evaluate — a malformed
+ * node, an unknown operator, a nested relation object a flat record can't
+ * satisfy — returns `false` (the write is denied), never `true`. The operator
+ * vocabulary mirrors `read-scope-sql.ts` so the in-memory and SQL backends agree.
+ */
+
+/** True iff `record` satisfies `filter`. A null/empty filter matches everything. */
+declare function matchesFilterCondition(record: Record<string, unknown>, filter: FilterCondition | null | undefined): boolean;
+
 /**
  * Shared expression validator (ADR-0032 §Decision 1/5).
  *
@@ -393,4 +469,4 @@ declare function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
  */
 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, formatValue, getEngine, hasDialect, introspectScope, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };
+export { CEL_STDLIB_FUNCTIONS, type CelFilterCompileOptions, type CelFilterCompileResult, type CelFilterFailReason, 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, compileCelToFilter, cronEngine, expectedDialect, formatValue, getEngine, hasDialect, introspectScope, isPushdownableCel, lowerCelAst, matchesFilterCondition, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Expression, ExpressionInput } from '@objectstack/spec';
-import { Environment } from '@marcbachmann/cel-js';
+import { Environment, ASTNode } from '@marcbachmann/cel-js';
+import { FilterCondition } from '@objectstack/spec/data';
 
 /**
  * @objectstack/formula — public types
@@ -296,6 +297,81 @@ declare function normalizeExpressionTree(root: unknown, path?: string[]): {
     error: EvalError;
 } | null;
 
+type CelFilterFailReason = 
+/** CEL did not parse (syntax error). */
+'parse-error'
+/** Shape is not pushdown-able (arithmetic, function call, relation traversal, …). */
+ | 'unsupported'
+/** A required `variableRoot` reference was undefined/null in `variables`. */
+ | 'unresolved-variable';
+type CelFilterCompileResult = {
+    ok: true;
+    filter: FilterCondition;
+} | {
+    ok: false;
+    reason: CelFilterFailReason;
+    detail: string;
+};
+interface CelFilterCompileOptions {
+    /** Member-access roots that denote a record FIELD path. Default `['record']`. */
+    fieldRoots?: readonly string[];
+    /** Roots resolved as VALUES against {@link variables}. Default `['current_user']`. */
+    variableRoots?: readonly string[];
+    /**
+     * Value-resolution context, keyed by variable root. e.g.
+     * `{ current_user: { id, organization_id, org_user_ids } }`. A `record.*`
+     * (field) reference is NEVER resolved here — only `variableRoot` leaves are.
+     */
+    variables?: Record<string, unknown>;
+}
+/**
+ * Compile a CEL predicate into a {@link FilterCondition}, resolving `variableRoot`
+ * leaves against `opts.variables`. Returns a discriminated result — never throws
+ * for an authoring-level fault; a `false` result with a reason is the caller's
+ * cue to fail closed (deny) or surface a compile error.
+ */
+declare function compileCelToFilter(input: string | {
+    source?: string;
+}, opts?: CelFilterCompileOptions): CelFilterCompileResult;
+/**
+ * Shape-only check: is this CEL predicate pushdown-able at all? Used by the
+ * authoring gate (ADR-0056 D4) to REJECT a predicate the runtime could only
+ * silently drop. Does not resolve `variables`.
+ */
+declare function isPushdownableCel(input: string | {
+    source?: string;
+}, opts?: Pick<CelFilterCompileOptions, 'fieldRoots' | 'variableRoots'>): {
+    ok: true;
+} | {
+    ok: false;
+    reason: CelFilterFailReason;
+    detail: string;
+};
+/**
+ * Lower a pre-parsed cel-js AST node — the variant that lets the interpreter and
+ * the compiler share ONE parse (ADR-0058 D6, "one AST, two backends").
+ */
+declare function lowerCelAst(ast: ASTNode, opts?: CelFilterCompileOptions, mode?: 'value' | 'shape'): CelFilterCompileResult;
+
+/**
+ * matchesFilterCondition — evaluate a Mongo-style {@link FilterCondition} against
+ * ONE in-memory record (ADR-0058 D4/D6).
+ *
+ * This is the third backend for the canonical filter shape, completing the
+ * round-trip: `compileCelToFilter` lowers CEL → FilterCondition; the engine runs
+ * it as a `where`; `read-scope-sql` lowers it to SQL; and THIS evaluates it
+ * against a single record for write-side validation — the RLS `check` clause
+ * (post-image of an insert/update), where there is no query to push down to.
+ *
+ * Security posture: **fail closed.** Anything it cannot evaluate — a malformed
+ * node, an unknown operator, a nested relation object a flat record can't
+ * satisfy — returns `false` (the write is denied), never `true`. The operator
+ * vocabulary mirrors `read-scope-sql.ts` so the in-memory and SQL backends agree.
+ */
+
+/** True iff `record` satisfies `filter`. A null/empty filter matches everything. */
+declare function matchesFilterCondition(record: Record<string, unknown>, filter: FilterCondition | null | undefined): boolean;
+
 /**
  * Shared expression validator (ADR-0032 §Decision 1/5).
  *
@@ -393,4 +469,4 @@ declare function introspectScope(role: FieldRole, schema?: ExprSchemaHint): {
  */
 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, formatValue, getEngine, hasDialect, introspectScope, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };
+export { CEL_STDLIB_FUNCTIONS, type CelFilterCompileOptions, type CelFilterCompileResult, type CelFilterFailReason, 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, compileCelToFilter, cronEngine, expectedDialect, formatValue, getEngine, hasDialect, introspectScope, isPushdownableCel, lowerCelAst, matchesFilterCondition, normalizeExpression, normalizeExpressionTree, register, registerStdLib, resolveSeed, resolveSeedRecord, templateEngine, validateExpression };