@@ -0,0 +1,12 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the `ValidationRule` `condition` example guards its nullable `amount` comparison with `record.amount != null`
+
+Clause-②: no
+Metadata-protocol: none
+
+The publish-time null-guard rule refuses an ordering or arithmetic operator on a declared-nullable field in a validation `condition` unless an explicit `!= null` test guards it. The `condition` `.describe()` text compared `record.amount` without one; it now reads `record.amount != null && record.amount < 0`, and the generated `content/docs/references/data/validation.mdx` rows follow. The two doc-comment examples in the same file (the `cross_field` discount limit and the `conditional` enterprise rule) get the same guard.
+
+The spec change is description and doc-comment text only: no schema shape changes, and no accept set moves.
@@ -142,7 +142,7 @@ export const opportunityApproval: Flow = {
       config: {
         triggerType: 'record-after-update',
         objectName: 'opportunity',
-        condition: "record.amount >= 50000 && record.stage == 'proposal'",
+        condition: "record.amount != null && record.amount >= 50000 && record.stage == 'proposal'",
       },
     },
     {
 
@@ -2470,7 +2470,7 @@ placeholder such as `{today}` among them, which the query engine resolves.
 
 | Where | Dialect | Write it like | Bindings |
 |:---|:---|:---|:---|
-| Start-node `condition` | **CEL** (bare, no braces) | `record.amount > 500` | `record.*`, `previous.*`, bare field names, `vars.*`, `current_user` |
+| Start-node `condition` | **CEL** (bare, no braces) | `record.amount != null && record.amount > 500` | `record.*`, `previous.*`, bare field names, `vars.*`, `current_user` |
 | Edge `condition` | **CEL** (bare, no braces) | `record.status == 'open'` | same as above |
 | Decision-node `conditions[].expression` | **CEL** (bare, no braces) | `order_amount > 10000` | flow variables by name, `vars.*` and `current_user` |
 | Field values and assignment values, as a **literal** | none — written as it is | `'open'`, `42`, `true`, `['a', 'b']` | — (a `{…}` template token is refused here since [#19939](https://github.com/objectstack-ai/objectstack/issues/19939), `{$User.*}` and the date macros `{NOW()}` / `{TODAY() ± N}` included: a date is `isoDate(today())` / `isoDatetime(now())` in an envelope) |
 
@@ -71,7 +71,7 @@ Pure formula. No IO, no mutation. This is the `body.language: 'expression'` shap
 { "language": "expression", "source": "input.amount > 1000 && input.status == 'open'" }
 ```
 
-Hook `condition` is a **separate field with a different envelope** — a bare CEL string, or `{ dialect: 'cel', source }` (`ExpressionInputSchema` in `packages/spec/src/shared/expression.zod.ts`), not a `{ language, source }` body. e.g. `condition: 'record.status == "open" && record.amount > 1000'`.
+Hook `condition` is a **separate field with a different envelope** — a bare CEL string, or `{ dialect: 'cel', source }` (`ExpressionInputSchema` in `packages/spec/src/shared/expression.zod.ts`), not a `{ language, source }` body. e.g. `condition: 'record.status == "open" && record.amount != null && record.amount > 1000'`.
 
 Both forms are evaluated by the same formula engine that powers field formulas — see [Formula Reference](/docs/data-modeling/formulas).
 
 
@@ -116,7 +116,7 @@ export const Invoice = ObjectSchema.create({
       expression: F`record.subtotal + record.subtotal * record.tax_rate`,
     }),
     po_number: Field.text({
-      requiredWhen: P`record.amount > 10000`,
+      requiredWhen: P`record.amount != null && record.amount > 10000`,
     }),
     // M9.9b — declarative default, evaluated at insert time
     issued_date: Field.date({
@@ -353,7 +353,7 @@ ObjectSchema.create({
 Field.text({
   visibleWhen: P`record.type == 'business'`,
   readonlyWhen: P`record.status == 'approved'`,
-  requiredWhen: P`record.amount > 10000`,
+  requiredWhen: P`record.amount != null && record.amount > 10000`,
 })
 ```
 
@@ -391,14 +391,16 @@ clock at install time.
 {
   name: 'amount_positive',
   type: 'script',
-  condition: P`record.amount <= 0`,
+  condition: P`record.amount != null && record.amount <= 0`,
   message: 'Amount must be positive.',
 }
 ```
 
 The generic CEL rule is `type: 'script'`. For `script` rules, the `condition`
 is the **failure** predicate — when it evaluates TRUE the validation fails, so
-invert the test (here `amount <= 0` rejects non-positive amounts).
+invert the test (here `amount <= 0` rejects non-positive amounts). An optional
+field needs the `!= null` test first: the publish gate refuses `<`, `<=`, `>`, `>=`
+or arithmetic on a nullable field unless a null test guards it.
 
 ### Hook condition
 
 
@@ -326,7 +326,7 @@ validations: [
     type: 'script',
     severity: 'error',
     message: 'Order amount must be positive',
-    condition: 'record.amount <= 0',
+    condition: 'record.amount != null && record.amount <= 0',
     events: ['insert', 'update'],
     priority: 10,
   },
 
@@ -309,7 +309,8 @@ Define a multi-step approval flow for records.
     sharingModel: 'private',
     fields: {
       title: { label: 'Title', type: 'text', required: true },
-      amount: { label: 'Amount', type: 'currency' },
+      // Required: the approval flow below branches on it.
+      amount: { label: 'Amount', type: 'currency', required: true },
       status: { label: 'Status', type: 'select', options: [
         { label: 'Draft', value: 'draft', default: true },
         { label: 'Submitted', value: 'submitted' },
 
@@ -167,7 +167,7 @@ const result = ConditionalValidationSchema.parse(data);
 | **_packageVersion** | `string` | optional | Owning package version. |
 | **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
 | **type** | `'script'` | ✅ |  |
-| **condition** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL). If TRUE, validation fails. e.g. P`record.amount < 0`. A TRUE INVARIANT, not a transition gate: re-evaluated against the merged record (the prior row overlaid with this write) on every write, with no exemption for a violation that was already stored — a row that already violates is refused on ANY edit until a repairing write lands (frozen, not bricked). Need a transition condition instead — one that only has to hold from a given state onward — use `Field.requiredWhen` or a field bound (`min` / `max` / `maxLength`), which judge the write rather than the stored row. |
+| **condition** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL). If TRUE, validation fails. e.g. P`record.amount != null && record.amount < 0`. A TRUE INVARIANT, not a transition gate: re-evaluated against the merged record (the prior row overlaid with this write) on every write, with no exemption for a violation that was already stored — a row that already violates is refused on ANY edit until a repairing write lands (frozen, not bricked). Need a transition condition instead — one that only has to hold from a given state onward — use `Field.requiredWhen` or a field bound (`min` / `max` / `maxLength`), which judge the write rather than the stored row. |
 
 ### Nested Shape: `ConditionalValidation.then[type='state_machine']`
 
@@ -288,7 +288,7 @@ const result = ConditionalValidationSchema.parse(data);
 | **_packageVersion** | `string` | optional | Owning package version. |
 | **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
 | **type** | `'script'` | ✅ |  |
-| **condition** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL). If TRUE, validation fails. e.g. P`record.amount < 0`. A TRUE INVARIANT, not a transition gate: re-evaluated against the merged record (the prior row overlaid with this write) on every write, with no exemption for a violation that was already stored — a row that already violates is refused on ANY edit until a repairing write lands (frozen, not bricked). Need a transition condition instead — one that only has to hold from a given state onward — use `Field.requiredWhen` or a field bound (`min` / `max` / `maxLength`), which judge the write rather than the stored row. |
+| **condition** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL). If TRUE, validation fails. e.g. P`record.amount != null && record.amount < 0`. A TRUE INVARIANT, not a transition gate: re-evaluated against the merged record (the prior row overlaid with this write) on every write, with no exemption for a violation that was already stored — a row that already violates is refused on ANY edit until a repairing write lands (frozen, not bricked). Need a transition condition instead — one that only has to hold from a given state onward — use `Field.requiredWhen` or a field bound (`min` / `max` / `maxLength`), which judge the write rather than the stored row. |
 
 ### Nested Shape: `ConditionalValidation.otherwise[type='state_machine']`
 
@@ -502,7 +502,7 @@ const result = ConditionalValidationSchema.parse(data);
 | **_packageVersion** | `string` | optional | Owning package version. |
 | **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
 | **type** | `'script'` | ✅ |  |
-| **condition** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL). If TRUE, validation fails. e.g. P`record.amount < 0`. A TRUE INVARIANT, not a transition gate: re-evaluated against the merged record (the prior row overlaid with this write) on every write, with no exemption for a violation that was already stored — a row that already violates is refused on ANY edit until a repairing write lands (frozen, not bricked). Need a transition condition instead — one that only has to hold from a given state onward — use `Field.requiredWhen` or a field bound (`min` / `max` / `maxLength`), which judge the write rather than the stored row. |
+| **condition** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL). If TRUE, validation fails. e.g. P`record.amount != null && record.amount < 0`. A TRUE INVARIANT, not a transition gate: re-evaluated against the merged record (the prior row overlaid with this write) on every write, with no exemption for a violation that was already stored — a row that already violates is refused on ANY edit until a repairing write lands (frozen, not bricked). Need a transition condition instead — one that only has to hold from a given state onward — use `Field.requiredWhen` or a field bound (`min` / `max` / `maxLength`), which judge the write rather than the stored row. |
 
 
 ---
@@ -568,7 +568,7 @@ This schema accepts one of the following structures:
 | **_packageVersion** | `string` | optional | Owning package version. |
 | **_lockDocsUrl** | `string` | optional | Optional documentation link surfaced next to _lockReason. |
 | **type** | `'script'` | ✅ |  |
-| **condition** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL). If TRUE, validation fails. e.g. P`record.amount < 0`. A TRUE INVARIANT, not a transition gate: re-evaluated against the merged record (the prior row overlaid with this write) on every write, with no exemption for a violation that was already stored — a row that already violates is refused on ANY edit until a repairing write lands (frozen, not bricked). Need a transition condition instead — one that only has to hold from a given state onward — use `Field.requiredWhen` or a field bound (`min` / `max` / `maxLength`), which judge the write rather than the stored row. |
+| **condition** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | ✅ | Predicate (CEL). If TRUE, validation fails. e.g. P`record.amount != null && record.amount < 0`. A TRUE INVARIANT, not a transition gate: re-evaluated against the merged record (the prior row overlaid with this write) on every write, with no exemption for a violation that was already stored — a row that already violates is refused on ANY edit until a repairing write lands (frozen, not bricked). Need a transition condition instead — one that only has to hold from a given state onward — use `Field.requiredWhen` or a field bound (`min` / `max` / `maxLength`), which judge the write rather than the stored row. |
 
 ---
 
 
@@ -177,7 +177,7 @@ export const ScriptValidationSchema = lazySchema(() => strictObject({
 }, {
   ...BASE_VALIDATION_SHAPE,
   type: z.literal('script'),
-  condition: EvaluatedExpressionInputSchema.describe('Predicate (CEL). If TRUE, validation fails. e.g. P`record.amount < 0`. A TRUE INVARIANT, not a transition gate: re-evaluated against the merged record (the prior row overlaid with this write) on every write, with no exemption for a violation that was already stored — a row that already violates is refused on ANY edit until a repairing write lands (frozen, not bricked). Need a transition condition instead — one that only has to hold from a given state onward — use `Field.requiredWhen` or a field bound (`min` / `max` / `maxLength`), which judge the write rather than the stored row.'),
+  condition: EvaluatedExpressionInputSchema.describe('Predicate (CEL). If TRUE, validation fails. e.g. P`record.amount != null && record.amount < 0`. A TRUE INVARIANT, not a transition gate: re-evaluated against the merged record (the prior row overlaid with this write) on every write, with no exemption for a violation that was already stored — a row that already violates is refused on ANY edit until a repairing write lands (frozen, not bricked). Need a transition condition instead — one that only has to hold from a given state onward — use `Field.requiredWhen` or a field bound (`min` / `max` / `maxLength`), which judge the write rather than the stored row.'),
 }));
 
 /**
@@ -254,7 +254,7 @@ export const FormatValidationSchema = lazySchema(() => strictObject({
  * {
  *   type: 'cross_field',
  *   name: 'discount_limit',
- *   condition: 'record.discount > (record.amount * 0.40)',
+ *   condition: 'record.discount != null && record.amount != null && record.discount > (record.amount * 0.40)',
  *   fields: ['discount', 'amount'],
  *   message: 'Discount cannot exceed 40% of the amount'
  * }
@@ -529,7 +529,7 @@ export const ValidationRuleSchema: z.ZodType<BaseValidationRuleShape, BaseValida
  *   then: {
  *     type: 'cross_field',
  *     name: 'amount_approval',
- *     condition: 'record.amount > 100000 && record.approval == null',
+ *     condition: 'record.amount != null && record.amount > 100000 && record.approval == null',
  *     fields: ['amount', 'approval']
  *   }
  * }
Original file line number	Diff line number	Diff line change
`@@ -142,7 +142,7 @@ export const opportunityApproval: Flow = {`
`142`	`142`	`config: {`
`143`	`143`	`triggerType: 'record-after-update',`
`144`	`144`	`objectName: 'opportunity',`
`145`		`- condition: "record.amount >= 50000 && record.stage == 'proposal'",`
	`145`	`+ condition: "record.amount != null && record.amount >= 50000 && record.stage == 'proposal'",`
`146`	`146`	`},`
`147`	`147`	`},`
`148`	`148`	`{`