@@ -0,0 +1,35 @@
+---
+"@objectstack/spec": patch
+---
+
+Every example predicate in the `ConditionalValidationSchema` TSDoc docblock (all seven Use Cases, plus the ObjectStack side of the "Salesforce Pattern Comparison" block, above the schema in `packages/spec/src/data/validation.zod.ts`) is rewritten in the CEL the evaluator actually accepts, so an author or agent who copies a documented example gets a rule that evaluates instead of one that refuses every write it guards (#20026).
+
+Clause-②: no
+
+17 of the 19 predicates used `=` for comparison (or `AND`/`NOT`/`REGEX(...)` word-form operators) — a CEL parse error, since `@marcbachmann/cel-js` rejects a lone `=` as an unexpected character; CEL equality is `==`, and CEL has no `AND`/`OR`/`NOT` keyword form — and the other 2 (`order_total > 10000`, `approval_amount > 50000`) named a bare field with no `record.` root, an unknown-variable type error. `REGEX(tax_id, "…")` is rewritten to the evaluator's registered `matches(record.tax_id, "…")` stdlib function — the CEL form it accepts, not a literal transliteration — with the escape-free character class `[0-9]` rather than `\d`: a `\d` inside the CEL string literal parses fine as written in this TSDoc comment (comments are not JS-escape-processed), but a reader who pastes the same text into a real `.ts` string literal gets ONE level of JS unescaping the comment never applied, so `\\d` in the comment becomes `\d` at runtime and cel-js refuses it (`Invalid escape sequence: \d` — this was this round's own rework: a prior revision of this changeset claimed a passing result for that predicate without measuring it on the copied literal). The Salesforce-formula half of the comparison (`IF(ISPICKVAL(...), AND(...), FALSE)`) is deliberately untouched: it documents Salesforce's own syntax, not CEL.
+
+Measured through `ExpressionEngine.evaluate` (`@objectstack/formula`), taking each predicate as the RUNTIME STRING a reader gets by pasting the docblock's literal into real `.ts` source — the literal is extracted from the source file byte for byte and handed to Node's own parser to unescape, never hand-retyped — against a record that makes each rewritten predicate true and one that makes it false; both branches evaluate as expected for all 19 (plus one extra disjunct check on the regex branch) — transcript in the PR body. The strings ship in the published `dist/object.zod-*.d.ts`, confirmed before and after this change with a lit/dark control: every rewritten string is present exactly once and every original broken string is absent.
+
+| old (fails) | new (evaluates) |
+|:--|:--|
+| `account_type = "enterprise"` | `record.account_type == 'enterprise'` |
+| `approval_status = null` | `record.approval_status == null` |
+| `requires_shipping = true` | `record.requires_shipping == true` |
+| `shipping_address = null OR shipping_address = ""` | `record.shipping_address == null \|\| record.shipping_address == ''` |
+| `order_total > 10000` | `record.order_total > 10000` |
+| `manager_approval_id = null` | `record.manager_approval_id == null` |
+| `payment_method = null` | `record.payment_method == null` |
+| `region = "EU"` | `record.region == 'EU'` |
+| `gdpr_consent_given = false` | `record.gdpr_consent_given == false` |
+| `tos_accepted = false` | `record.tos_accepted == false` |
+| `country = "US"` | `record.country == 'US'` |
+| `state = "CA"` | `record.state == 'CA'` |
+| `tax_id = null OR NOT(REGEX(tax_id, "^\d{2}-\d{7}$"))` | `record.tax_id == null \|\| !matches(record.tax_id, "^[0-9]{2}-[0-9]{7}$")` |
+| `is_taxable = true` | `record.is_taxable == true` |
+| `tax_code = null OR tax_code = ""` | `record.tax_code == null \|\| record.tax_code == ''` |
+| `user_role = "manager"` | `record.user_role == 'manager'` |
+| `approval_amount > 50000` | `record.approval_amount > 50000` |
+| `type = "enterprise"` (Salesforce comparison) | `record.type == 'enterprise'` |
+| `amount > 100000 AND approval = null` (Salesforce comparison) | `record.amount > 100000 && record.approval == null` |
+
+`packages/spec/src/data/validation.test.ts`'s `ConditionalValidationSchema` fixtures move with the docblock (parse-only — `ValidationRuleSchema.parse(...).not.toThrow()`, no CEL evaluation, so no behaviour change): the six exact copies of Use Cases 1-3's original seven strings; `manager_approval = null` (the `order_value_validation` fixture whose message text and structure mirror Use Case 3's manager-approval example one field-name spelling apart), now `record.manager_approval == null`; and, under this round's rework, ten more fixtures whose surrounding test name and message text are verbatim copies of Use Cases 4, 5, 6 and 7's docblock text — `is_taxable = true` / `tax_code = null` (`tax_validation`, Use Case 6, the `tax_code` fixture now the full `record.tax_code == null || record.tax_code == ''`), `region = "EU"` / `gdpr_consent_given = false` / `tos_accepted = false` (`regional_validation`, Use Case 4), `user_role = "manager"` / `approval_amount > 50000` (`role_based_validation`, Use Case 7), and `country = "US"` / `state = "CA"` / `tax_id = null` (`nested_validation`, Use Case 5 — the `tax_id` fixture now the full `record.tax_id == null || !matches(record.tax_id, "^[0-9]{2}-[0-9]{7}$")`, escape-free for the same copy-paste reason as the docblock). 17 fixture strings moved in total. No schema, behaviour, or public export changes — TSDoc text only, in the same two files the strings already lived in.
@@ -511,12 +511,12 @@ describe('ValidationRuleSchema (Discriminated Union)', () => {
         type: 'conditional' as const,
         name: 'enterprise_validation',
         message: 'Enterprise accounts require approval',
-        when: 'account_type = "enterprise"',
+        when: "record.account_type == 'enterprise'",
         then: {
           type: 'script' as const,
           name: 'require_approval',
           message: 'Approval required for enterprise accounts',
-          condition: 'approval_status = null',
+          condition: 'record.approval_status == null',
         },
       };
 
@@ -551,17 +551,17 @@ describe('ValidationRuleSchema (Discriminated Union)', () => {
         type: 'conditional' as const,
         name: 'nested_validation',
         message: 'Complex conditional validation',
-        when: 'country = "US"',
+        when: "record.country == 'US'",
         then: {
           type: 'conditional' as const,
           name: 'state_validation',
           message: 'State-specific validation',
-          when: 'state = "CA"',
+          when: "record.state == 'CA'",
           then: {
             type: 'script' as const,
             name: 'ca_tax',
             message: 'California requires tax ID',
-            condition: 'tax_id = null',
+            condition: 'record.tax_id == null || !matches(record.tax_id, "^[0-9]{2}-[0-9]{7}$")',
           },
         },
       };
@@ -592,12 +592,12 @@ describe('ValidationRuleSchema (Discriminated Union)', () => {
         type: 'conditional' as const,
         name: 'shipping_validation',
         message: 'Shipping validation',
-        when: 'requires_shipping = true',
+        when: 'record.requires_shipping == true',
         then: {
           type: 'script' as const,
           name: 'shipping_address_required',
           message: 'Shipping address is required',
-          condition: 'shipping_address = null OR shipping_address = ""',
+          condition: "record.shipping_address == null || record.shipping_address == ''",
         },
       };
 
@@ -609,18 +609,18 @@ describe('ValidationRuleSchema (Discriminated Union)', () => {
         type: 'conditional' as const,
         name: 'order_value_validation',
         message: 'Order value validation',
-        when: 'order_total > 10000',
+        when: 'record.order_total > 10000',
         then: {
           type: 'script' as const,
           name: 'high_value_approval',
           message: 'Orders over $10,000 require manager approval',
-          condition: 'manager_approval = null',
+          condition: 'record.manager_approval == null',
         },
         otherwise: {
           type: 'script' as const,
           name: 'standard_validation',
           message: 'Payment method required',
-          condition: 'payment_method = null',
+          condition: 'record.payment_method == null',
         },
       };
 
@@ -632,12 +632,12 @@ describe('ValidationRuleSchema (Discriminated Union)', () => {
         type: 'conditional' as const,
         name: 'tax_validation',
         message: 'Tax validation',
-        when: 'is_taxable = true',
+        when: 'record.is_taxable == true',
         then: {
           type: 'script' as const,
           name: 'tax_code_required',
           message: 'Tax code is required for taxable items',
-          condition: 'tax_code = null',
+          condition: "record.tax_code == null || record.tax_code == ''",
         },
       };
 
@@ -701,18 +701,18 @@ describe('ValidationRuleSchema (Discriminated Union)', () => {
         type: 'conditional' as const,
         name: 'regional_validation',
         message: 'Regional compliance validation',
-        when: 'region = "EU"',
+        when: "record.region == 'EU'",
         then: {
           type: 'script' as const,
           name: 'gdpr_consent',
           message: 'GDPR consent required for EU customers',
-          condition: 'gdpr_consent_given = false',
+          condition: 'record.gdpr_consent_given == false',
         },
         otherwise: {
           type: 'script' as const,
           name: 'tos_acceptance',
           message: 'Terms of Service acceptance required',
-          condition: 'tos_accepted = false',
+          condition: 'record.tos_accepted == false',
         },
       };
 
@@ -724,12 +724,12 @@ describe('ValidationRuleSchema (Discriminated Union)', () => {
         type: 'conditional' as const,
         name: 'role_based_validation',
         message: 'Role-based validation',
-        when: 'user_role = "manager"',
+        when: "record.user_role == 'manager'",
         then: {
           type: 'script' as const,
           name: 'manager_approval_limit',
           message: 'Managers can approve up to $50,000',
-          condition: 'approval_amount > 50000',
+          condition: 'record.approval_amount > 50000',
         },
       };
 
 
@@ -375,53 +375,53 @@ export const ValidationRuleSchema: z.ZodType<BaseValidationRuleShape, BaseValida
  * {
  *   type: 'conditional',
  *   name: 'enterprise_approval_required',
- *   when: 'account_type = "enterprise"',
+ *   when: "record.account_type == 'enterprise'",
  *   message: 'Enterprise validation',
  *   then: {
  *     type: 'script',
  *     name: 'require_approval',
  *     message: 'Enterprise accounts require manager approval',
- *     condition: 'approval_status = null'
+ *     condition: 'record.approval_status == null'
  *   }
  * }
  * ```
- * 
+ *
  * ### 2. Conditional Field Requirements
  * Require certain fields only when specific conditions are met.
  * ```typescript
  * {
  *   type: 'conditional',
  *   name: 'shipping_address_when_required',
- *   when: 'requires_shipping = true',
+ *   when: 'record.requires_shipping == true',
  *   message: 'Shipping validation',
  *   then: {
  *     type: 'script',
  *     name: 'shipping_address_required',
  *     message: 'Shipping address is required for physical products',
- *     condition: 'shipping_address = null OR shipping_address = ""'
+ *     condition: "record.shipping_address == null || record.shipping_address == ''"
  *   }
  * }
  * ```
- * 
+ *
  * ### 3. Amount-Based Validation
  * Apply different rules based on transaction amount.
  * ```typescript
  * {
  *   type: 'conditional',
  *   name: 'high_value_approval',
- *   when: 'order_total > 10000',
+ *   when: 'record.order_total > 10000',
  *   message: 'High value order validation',
  *   then: {
  *     type: 'script',
  *     name: 'manager_approval_required',
  *     message: 'Orders over $10,000 require manager approval',
- *     condition: 'manager_approval_id = null'
+ *     condition: 'record.manager_approval_id == null'
  *   },
  *   otherwise: {
  *     type: 'script',
  *     name: 'standard_validation',
  *     message: 'Payment method is required',
- *     condition: 'payment_method = null'
+ *     condition: 'record.payment_method == null'
  *   }
  * }
  * ```
@@ -432,19 +432,19 @@ export const ValidationRuleSchema: z.ZodType<BaseValidationRuleShape, BaseValida
  * {
  *   type: 'conditional',
  *   name: 'regional_compliance',
- *   when: 'region = "EU"',
+ *   when: "record.region == 'EU'",
  *   message: 'EU compliance validation',
  *   then: {
  *     type: 'script',
  *     name: 'gdpr_consent',
  *     message: 'GDPR consent is required for EU customers',
- *     condition: 'gdpr_consent_given = false'
+ *     condition: 'record.gdpr_consent_given == false'
  *   },
  *   otherwise: {
  *     type: 'script',
  *     name: 'tos_acceptance',
  *     message: 'Terms of Service acceptance required',
- *     condition: 'tos_accepted = false'
+ *     condition: 'record.tos_accepted == false'
  *   }
  * }
  * ```
@@ -455,53 +455,53 @@ export const ValidationRuleSchema: z.ZodType<BaseValidationRuleShape, BaseValida
  * {
  *   type: 'conditional',
  *   name: 'country_state_validation',
- *   when: 'country = "US"',
+ *   when: "record.country == 'US'",
  *   message: 'US-specific validation',
  *   then: {
  *     type: 'conditional',
  *     name: 'california_validation',
- *     when: 'state = "CA"',
+ *     when: "record.state == 'CA'",
  *     message: 'California-specific validation',
  *     then: {
  *       type: 'script',
  *       name: 'ca_tax_id_required',
  *       message: 'California requires a valid tax ID',
- *       condition: 'tax_id = null OR NOT(REGEX(tax_id, "^\\d{2}-\\d{7}$"))'
+ *       condition: 'record.tax_id == null || !matches(record.tax_id, "^[0-9]{2}-[0-9]{7}$")'
  *     }
  *   }
  * }
  * ```
- * 
+ *
  * ### 6. Tax Validation for Taxable Items
  * Only validate tax fields when the item is taxable.
  * ```typescript
  * {
  *   type: 'conditional',
  *   name: 'tax_field_validation',
- *   when: 'is_taxable = true',
+ *   when: 'record.is_taxable == true',
  *   message: 'Tax validation',
  *   then: {
  *     type: 'script',
  *     name: 'tax_code_required',
  *     message: 'Tax code is required for taxable items',
- *     condition: 'tax_code = null OR tax_code = ""'
+ *     condition: "record.tax_code == null || record.tax_code == ''"
  *   }
  * }
  * ```
- * 
+ *
  * ### 7. Role-Based Validation
  * Apply validation based on user role.
  * ```typescript
  * {
  *   type: 'conditional',
  *   name: 'role_based_approval_limit',
- *   when: 'user_role = "manager"',
+ *   when: "record.user_role == 'manager'",
  *   message: 'Manager approval limits',
  *   then: {
  *     type: 'script',
  *     name: 'manager_limit',
  *     message: 'Managers can approve up to $50,000',
- *     condition: 'approval_amount > 50000'
+ *     condition: 'record.approval_amount > 50000'
  *   }
  * }
  * ```
@@ -525,11 +525,11 @@ export const ValidationRuleSchema: z.ZodType<BaseValidationRuleShape, BaseValida
  * {
  *   type: 'conditional',
  *   name: 'enterprise_high_value',
- *   when: 'type = "enterprise"',
+ *   when: "record.type == 'enterprise'",
  *   then: {
  *     type: 'cross_field',
  *     name: 'amount_approval',
- *     condition: 'amount > 100000 AND approval = null',
+ *     condition: 'record.amount > 100000 && record.approval == null',
  *     fields: ['amount', 'approval']
  *   }
  * }