@object-ui/core 16.0.0 → 17.1.0

package/dist/validation/validators/object-validation-engine.d.ts

@@ -6,23 +6,92 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * @object-ui/core - Object-Level Validation Engine
- *
- * ObjectStack Spec v2.0.1 compliant validation engine for object-level validation rules.
- * Supports all 9 validation types from the specification:
- * - ScriptValidation
- * - UniquenessValidation
- * - StateMachineValidation
- * - CrossFieldValidation
- * - AsyncValidation
- * - ConditionalValidation
- * - FormatValidation
- * - RangeValidation
+ * @object-ui/core - Object-Level Validation Engine — **DEPRECATED** (#3110)
+ *
+ * A client-side pre-check of the rules an object declares in
+ * `ObjectSchema.validations`. The authority is the server
+ * (`objectql/src/validation/rule-validator.ts`), which evaluates the same rules
+ * on the write path.
+ *
+ * ## Why this is deprecated rather than finished
+ *
+ * Validation rules are ENFORCEMENT, and enforcement is single-implementation on
+ * the server by design. `evaluator/fieldRules.ts` draws that line explicitly:
+ * PRESENTATION predicates (`visibleWhen` / `readonlyWhen` / `requiredWhen`) are
+ * evaluated client-side by delegating to the canonical `ExpressionEngine`,
+ * "rather than re-implementing a parallel evaluator" (ADR-0036). This module is
+ * that parallel evaluator, on the enforcement side of the line.
+ *
+ * #3103 converged its semantics onto the server rule-for-rule, with eight
+ * mutation-tested gates — and it STILL left a known divergence: the server
+ * carries ADR-0113's legacy-violation exemption (reject only when the merged
+ * state violates AND this write makes it worse, so a pre-existing violation on
+ * an old row passes), and this engine does not. Editing an unrelated field on a
+ * legacy row would be blocked here and accepted there. That is the argument in
+ * one line: mirroring cross-repo behaviour is structurally unreliable, not
+ * unreliable-this-time.
+ *
+ * ## What to use instead
+ *
+ * Let the write fail and render the server's rejection — it is already
+ * structured (`field` / `code` / `message`, plus a label since objectstack#3957).
+ * If pre-submit feedback is wanted, the answer is a **validate-only (dry-run)
+ * write** on the server: identical UX, zero parity risk, and it also covers the
+ * two rule kinds a client can never check — `unique` (needs the database) and
+ * `json_schema` (ajv lives server-side).
+ *
+ * Nothing here has been removed or changed in behaviour; existing callers keep
+ * working. `validation-engine-stays-unwired.test.ts` fails if a production
+ * module starts importing this one, so the decision is a mechanism rather than
+ * this comment (#3017).
+ *
+ * ## When to revisit
+ *
+ * Offline writes (`OfflineConfig`). With no server to ask, a client evaluator
+ * stops being redundant and becomes necessary. The precondition then is
+ * conformance fixtures shipped by `@objectstack/spec` — golden
+ * (rule, record, verdict) triples both repos run in CI — because that is the
+ * only thing that turns cross-repo parity into a mechanism instead of a habit.
+ * Reverse the decision in #3110 before reversing it here.
+ *
+ * ## Semantics (unchanged, for as long as this exists)
+ *
+ * The rule types come from `@object-ui/types`, which derives them from
+ * `@objectstack/spec/data` (objectstack#4115). Semantics mirrored from the
+ * server:
+ *
+ *  - **Polarity.** A `script` / `cross_field` `condition` and a `conditional`
+ *    `when` express the FAILURE condition: predicate TRUE ⇒ rule VIOLATED.
+ *  - **Fail-open on broken, fail-closed on violated.** A predicate that cannot
+ *    be evaluated (parse error, unknown identifier, unusable expression
+ *    envelope) is a broken rule, not a violated one — it is skipped, not
+ *    reported. Likewise a malformed `regex`.
+ *  - **Spec defaults, not falsy reads.** `active` defaults to `true` and
+ *    `events` to `['insert','update']` — they arrive absent from `/meta`
+ *    because the spec applies those defaults at parse time. Reading an absent
+ *    `active` as "off" would silently disable every rule authored without it.
+ *  - **`priority` orders execution** (lower first, stable).
+ *  - **`format` and `state_machine` only fire when the write TOUCHES the
+ *    field**, matching the server; emptiness and requiredness belong to the
+ *    field-shape validator.
+ *
+ * Two documented divergences from the server, both in the safe direction:
+ *
+ *  1. The default evaluator is a small non-CEL parser (see
+ *     `SimpleExpressionEvaluator`), so a predicate using real CEL constructs
+ *     evaluates to nothing and fails open. Pass a CEL-backed
+ *     `ValidationExpressionEvaluator` to close that gap.
+ *  2. `unique` / `async` / `range` rules are still dispatched. They are
+ *     @deprecated objectui-local variants that the spec's `ValidationRuleSchema`
+ *     rejects outright, so they cannot arrive from `/meta` — only a caller
+ *     building rules by hand can produce one.
  *
  * @module object-validation-engine
  * @packageDocumentation
  */
 import type { ObjectValidationRule } from '@object-ui/types';
+/** Write contexts a rule can run on. The spec retired `delete` (objectstack#3184). */
+export type ObjectValidationEvent = 'insert' | 'update';
 /**
  * Validation context for object-level validations
  */
@@ -56,63 +125,114 @@ export interface ValidationExpressionEvaluator {
     evaluate(expression: string, context: Record<string, any>): any;
 }
 /**
- * Object-Level Validation Engine
- * Implements ObjectStack Spec v2.0.1 validation framework
+ * Object-Level Validation Engine — the client pre-check described at the top of
+ * this module.
+ *
+ * @deprecated (#3110) Validation rules are enforcement, and enforcement is
+ * single-implementation on the server (`objectql`'s rule-validator). Render the
+ * server's rejection instead; for pre-submit feedback, use a validate-only
+ * (dry-run) write. Still functional and still correct as of #3103 — but it
+ * cannot stay in step with the server without a conformance-fixture mechanism
+ * that does not exist yet. See the module header.
  */
 export declare class ObjectValidationEngine {
     private expressionEvaluator;
     private uniquenessChecker?;
     constructor(expressionEvaluator?: ValidationExpressionEvaluator, uniquenessChecker?: (fields: string[], values: Record<string, any>, scope?: string, context?: ObjectValidationContext) => Promise<boolean>);
     /**
-     * Validate a record against a set of validation rules
+     * Validate a record against a set of validation rules.
+     *
+     * Rules run in `priority` order (lower first, stable within a priority), and
+     * only when `active` is not explicitly `false` and `events` covers this write
+     * context — reading the spec's defaults, not the falsiness of an absent key.
      */
-    validateRecord(rules: ObjectValidationRule[], context: ObjectValidationContext, event?: 'insert' | 'update' | 'delete'): Promise<ObjectValidationResult[]>;
+    validateRecord(rules: ObjectValidationRule[], context: ObjectValidationContext, event?: ObjectValidationEvent): Promise<ObjectValidationResult[]>;
     /**
-     * Validate a single rule
+     * Validate a single rule.
+     *
+     * `rule` is widened past `ObjectValidationRule` because a `conditional`'s
+     * `then` / `otherwise` branch may be any rule the SPEC's union admits —
+     * including `json_schema`, which this engine does not implement.
      */
     private validateRule;
     /**
-     * Validate script-based rule
+     * The evaluation scope for a predicate.
+     *
+     * The server binds `{ record, previous }`, so a spec-authored predicate reads
+     * `record.amount`. objectui's own rules have always been written against the
+     * bare field name (`amount`). Both are bound — the roots last so a field
+     * literally called `record` cannot shadow them.
      */
-    private validateScript;
+    private scopeFor;
+    /**
+     * Evaluate a `script` / `cross_field` predicate.
+     *
+     * Both variants share one path on the server, and so do they here. The
+     * predicate is the FAILURE condition: TRUE means the rule is violated. A
+     * predicate that cannot be evaluated is a BROKEN rule and fails open.
+     */
+    private validatePredicate;
     /**
      * Validate uniqueness constraint
      */
     private validateUniqueness;
     /**
-     * Validate state machine transitions
+     * Validate state machine transitions (ADR-0020).
+     *
+     * A flat `field` plus a `{ from: [allowedTo] }` map. Semantics mirror the
+     * server-side rule-validator:
+     *
+     *   INSERT
+     *   - no `initialStates` declared        → allow (legacy no-op)
+     *   - field absent from the write        → allow (requiredness is not our job)
+     *   - value empty                        → allow (ditto)
+     *   - value ∉ initialStates              → reject (the FSM entry point, #3165)
+     *
+     *   UPDATE
+     *   - field absent from the write        → allow (no transition to police)
+     *   - no prior record                    → allow (cannot reason)
+     *   - field unchanged, or cleared        → allow (no transition)
+     *   - `from` not declared in the map     → lenient allow (unconstrained)
+     *   - `to` ∉ transitions[from]           → reject
      */
     private validateStateMachine;
-    /**
-     * Validate cross-field constraints
-     */
-    private validateCrossField;
     /**
      * Validate async/remote validation
      */
     private validateAsync;
     /**
-     * Validate conditional rules
+     * Validate a conditional rule.
+     *
+     * Evaluates `when`, then recurses into `then` (TRUE) or `otherwise` (FALSE).
+     * The nested rule supplies the violation; an un-evaluable `when` is a broken
+     * rule and fails open. A branch whose own `active` is explicitly `false` is
+     * skipped, matching the server.
      */
     private validateConditional;
     /**
-     * Validate format/pattern
+     * Validate a field's format against `regex` and/or a named `format`.
+     *
+     * Mirrors the server: the rule only fires when the write TOUCHES the field and
+     * the value is non-empty (requiredness and type-shape belong to the
+     * field-level validator, so an absent or blank value is not a format
+     * violation). Both checks apply when both are declared. A `regex` that will
+     * not compile is a BROKEN rule — logged and skipped, never a violation.
      */
     private validateFormat;
     /**
      * Validate range constraints
      */
     private validateRange;
-    /**
-     * Get predefined regex pattern
-     */
-    private getPredefinedPattern;
 }
 /**
  * Default instance
+ *
+ * @deprecated (#3110) See `ObjectValidationEngine`.
  */
 export declare const defaultObjectValidationEngine: ObjectValidationEngine;
 /**
  * Convenience function to validate a record
+ *
+ * @deprecated (#3110) See `ObjectValidationEngine`.
  */
-export declare function validateRecord(rules: ObjectValidationRule[], context: ObjectValidationContext, event?: 'insert' | 'update' | 'delete'): Promise<ObjectValidationResult[]>;
+export declare function validateRecord(rules: ObjectValidationRule[], context: ObjectValidationContext, event?: ObjectValidationEvent): Promise<ObjectValidationResult[]>;