Skip to content

Commit 931f02a

Browse files
os-support-aiclaude
andcommitted
docs(skills): the formula skill and the flows page teach the null-guard gate on a record-triggered flow's conditions
The publish-time null-guard gate judges a record-triggered flow's start `config.condition`, every edge `condition` (nested regions too) and every `decision` branch `expression`. The formula skill now teaches which slots are judged, the `count` / `sum` roll-up exception, the bare-name rule, the start-condition guard spelled `record.<field> != null` so both doors accept it, and the run-fails outcome; one eval exercises a refused flow edge. The flows page carries the same rule where edge and decision conditions are taught. Paid in the same file: the `previous` callout restating §5 and the pre-ADR-0032 history clause. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WGufzfSZ55f7xwAfpfkPgY
1 parent c76c0e0 commit 931f02a

4 files changed

Lines changed: 54 additions & 16 deletions

File tree

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'@objectstack/skills': patch
3+
---
4+
5+
docs(skills): the formula skill teaches the null-guard gate on a record-triggered flow's conditions
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
The publish-time null-guard gate (`os validate` / `os build` / `os lint` and the runtime publish gate) has judged a record-triggered flow's start `config.condition`, every edge `condition` and every `decision` branch `expression` since the lint change that widened it; the formula skill now says so where it teaches the gate: which slots are judged, that a `count` / `sum` roll-up is always valued while `min` / `max` / `avg` stay nullable, that a bare field name in a flow condition is the field and is judged alike, that a guard in the start condition holds at every edge and branch and is spelled `record.<field> != null` so both doors accept it, and that an unguarded null fails the run while the write that fired it still lands. One eval exercises a refused flow edge. The flows docs page carries the same rule where edge and decision conditions are taught.

‎content/docs/automation/flows.mdx‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1810,7 +1810,7 @@ Edges connect nodes and define the execution path:
18101810
| `source` | `string` | ✅ | Source node ID |
18111811
| `target` | `string` | ✅ | Target node ID |
18121812
| `type` | `enum` | optional | `'default'` (success), `'fault'` (error), `'conditional'` (expression-guarded), or `'back'` (declared back-edge, ADR-0044); defaults to `'default'` |
1813-
| `condition` | `string` | optional | Boolean CEL predicate for branching (a bare string is stored as `{ dialect: 'cel', source }`) |
1813+
| `condition` | `string` | optional | Boolean CEL predicate for branching (a bare string is stored as `{ dialect: 'cel', source }`); on a record-triggered flow a nullable field needs its `!= null` guard — see [Expressions in flows](#expressions-in-flows) |
18141814
| `label` | `string` | optional | Label displayed on the connector — cosmetic only. It does **not** select a path except on a branching node (`decision` / `approval`), which picks its out-edge by label. |
18151815
| `isDefault` | `boolean` | optional | BPMN default flow — the **"otherwise" branch**. Traversed only when no sibling `condition` on the same source node matched; never part of the unconditional parallel fan-out. Mutually exclusive with `condition`, at most one per node |
18161816

@@ -2443,6 +2443,18 @@ and is read as `vars["current_user"]` / `vars["vars"]`.
24432443
4. **A single-brace token in a text slot** — `title: 'Deal won: {record.name}'`
24442444
— is refused with its `{{ }}` spelling ([text slots](#text-slots-read-double-brace-holes)): it is no placeholder there,
24452445
and would go out as literal text.
2446+
5. **An ordering or arithmetic operator on a nullable field, unguarded** — on a
2447+
record-triggered flow (`triggerType: 'record-*'`), `os validate` and the
2448+
runtime publish gate refuse a start `condition`, an edge `condition` (nested
2449+
regions too) or a `decision` branch `expression` that applies `< <= > >=` or
2450+
`+ - * / %` to a field of the trigger object with no `required: true`,
2451+
`defaultValue` or default option (a `count` / `sum` roll-up reads `0` when
2452+
empty; `min` / `max` / `avg` stay nullable), unguarded by `!= null` /
2453+
`== null` / `!isBlank()` in the same branch: the run binds every declared
2454+
field, `null` when empty, CEL has no `>` for null, and the run fails there
2455+
while the write that fired it still lands. A bare `budget` is `record.budget`,
2456+
judged alike; a start-condition guard holds at every edge and branch — spell
2457+
it `record.budget != null`, which both doors accept, and `has()` is no guard.
24462458
</Callout>
24472459

24482460
<Callout type="info">

‎skills/objectstack-formula/SKILL.md‎

Lines changed: 21 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -112,9 +112,12 @@ record.start_date != null && record.end_date != null && record.end_date < record
112112

113113
**This is a publish-time rejection, not advice.** `os build` /
114114
`os validate` / `os lint` and the runtime publish gate reject any validation-rule
115-
or hook predicate that applies an ordering (`< <= > >=`) or arithmetic
115+
or hook predicate — and a record-triggered flow's (`triggerType: 'record-*'`)
116+
start `config.condition`, edge `condition` (nested regions too) or `decision`
117+
branch `expression` — that applies an ordering (`< <= > >=`) or arithmetic
116118
(`+ - * / %`) operator to a **declared nullable** field — no `required: true`,
117-
no `defaultValue`, no default option — unless an explicit `!= null` / `== null` /
119+
no `defaultValue`, no default option, not a `count` / `sum` roll-up (empty reads
120+
`0`; `min` / `max` / `avg` stay nullable) — unless an explicit `!= null` / `== null` /
118121
`!isBlank()` test dominates it in the same boolean branch. `has()` deliberately
119122
does not satisfy that gate. `has()` over an **undeclared** key stays legal: that
120123
is its real use — telling "absent from this PATCH" apart from "explicitly null".
@@ -379,17 +382,21 @@ When migrating Salesforce-flavor metadata, apply these rules in order:
379382
| `ISCHANGED(x)` | `previous.x != record.x` |
380383
| `MONTH_DIFF`, `MID`, `LEFT`, `RIGHT`, `SUBSTITUTE` | _not in stdlib — propose addition_ |
381384

382-
> ⚠️ `OLD.x` and `ISCHANGED(x)` both land on `previous.x`, which has a value
383-
> only where `previous` is a **row** — see §5. On an insert event `previous` is
384-
> `null`, so the read does not quietly skip the hook, it **fails the write**
385-
> unless guarded by `previous != null &&`. On update and delete
386-
> events it IS bound, per matched row, in `before*` and `after*` alike, on bulk
387-
> and single-record writes.
388-
389-
> ⚠️ **Flow conditions are the exception to row 1.** The automation engine
390-
> spreads the record's variables to top level, so a bare `status` resolves in a
391-
> flow start condition. `record.status` resolves there too and is the only
392-
> spelling valid on every other surface — prefer it.
385+
> ⚠️ `OLD.x` and `ISCHANGED(x)` both land on `previous.x`, which is `null` on an
386+
> insert event and **fails the write** there unless guarded by `previous != null
387+
> &&`; on update and delete events it is bound per matched row — see §5.
388+
389+
> ⚠️ **Flow conditions are the exception to row 1.** The engine spreads the
390+
> trigger record's fields, nulls included, to top level wherever no flow variable
391+
> or node id holds the name, so in a start, edge or `decision` condition a bare
392+
> `budget` IS `record.budget`: the null-guard gate judges either spelling (bare
393+
> names only while every node's bindings are declared), a guard on one spelling
394+
> guards both, and what the start condition proves non-null is presumed at every
395+
> edge and branch. Spell that start guard `record.budget != null`: the runtime
396+
> publish gate judges the written flow alone, proves nothing from a bare
397+
> `budget != null`, and refuses the edge `os validate` passed. An unguarded null
398+
> fails the **run** at that condition; the write that fired it still lands.
399+
> `record.x` is the only spelling valid on every other surface — prefer it.
393400
394401
---
395402

@@ -453,8 +460,7 @@ data instead, `{{ amount | currency:@currency_code }}`.
453460

454461
## Verify your work
455462

456-
A malformed expression does not fail silently (ADR-0032). It used to evaluate to
457-
`null` / `false` — a flow "fired" and did nothing; now `os validate` and
463+
A malformed expression does not fail silently (ADR-0032): `os validate` and
458464
`os build` run the shared validator over every formula and predicate in the
459465
stack — CEL syntax **plus** `record.<field>` existence on the target object —
460466
and fail non-zero with a located, did-you-mean message, while at runtime the

‎skills/objectstack-formula/evals/cel-predicates-formulas.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,16 @@
8080
"must_contain": ["currency:@"],
8181
"must_not_contain": ["currency:currency_code", "currency:USD", "currency:CNY", "| currency }}"]
8282
}
83+
},
84+
{
85+
"id": 9,
86+
"prompt": "A record-change flow on `project` (start `triggerType: 'record-after-update'`, `objectName: 'project'`) escalates when the budget passes 200000. `budget` is a currency field with no `required` and no `defaultValue`. Write the edge condition from the decision node to the escalation branch.",
87+
"expected_output": "`record.budget != null && record.budget > 200000`. The run binds every declared field of the trigger record, `null` when empty, and CEL has no `>` overload for null, so `os validate` and the runtime publish gate refuse the unguarded edge; at runtime the run would fail at that edge while the write that fired it still lands. A bare `budget > 200000` is the same field and is refused the same way, and `has(record.budget)` is not a guard: a declared field holding null is still present.",
88+
"files": [],
89+
"assertions": {
90+
"must_contain": ["record.budget != null", "record.budget > 200000"],
91+
"must_not_contain": ["has(record.budget) && record.budget >", "{record."]
92+
}
8393
}
8494
]
8595
}

0 commit comments

Comments
 (0)