@@ -0,0 +1,9 @@
+---
+'@objectstack/skills': patch
+---
+
+docs(skills): `objectstack-data` and `objectstack-formula` state that `previous` is `null` on insert — `previous == null` judges an insert, a column read off it there faults, and only a write to an existing row whose prior state is not in hand leaves it unbound (#23983)
+
+Clause-②: no
+
+`skills/objectstack-data/references/data-hooks.md` and `skills/objectstack-formula/SKILL.md` said `previous` is unbound on insert events and told authors to write insert-event conditions over `record` alone. Since `@objectstack/objectql` binds `previous` to `null` on insert in validation rules and declarative hook conditions (the binding a flow's start condition already had), that text was false: `previous == null || …` judges an insert and `previous != null && …` skips one; only a column read off `previous` on insert (`previous.status`) still has no value and still fails the write, and only a write to an existing row whose prior state is not in hand leaves `previous` unbound, failing closed. The bullet, the scope-table row, the abort note and the legacy-translation note now state that binding and the `null` guard; the `record`-alone advice stays correct and is no longer presented as the rule. Text only; nothing an author writes changes, and a hook's `ctx.previous` is unchanged.
@@ -244,15 +244,18 @@ in neither). So:
   `previous.done != true && record.done == true`. `previous` is the stored
   pre-write row, made total over the same declared fields, and it is the same
   binding a validation predicate reads.
-- **`previous` is UNBOUND where there is no prior state**, and a reference to an
-  unbound root makes the whole condition unevaluable. One case: insert events
-  (`beforeInsert` / `afterInsert`) — write those over `record` alone. The
-  `before*` dispatch of a predicate (`multi: true`) write is **not** a second
-  case: `beforeUpdate` / `beforeDelete` dispatch once per matched row, each on a
-  single-record-shaped context whose `previous` is that row's pre-image and whose
-  `input.id` names the row (ADR-0058 Addendum II, D1/D2), so a transition
-  condition evaluates there exactly as on a single-record write, and `record` is
-  that row's state, stored ⊕ payload. Only the *payload* stays batch-scoped (D3):
+- **`previous` is `null` on insert** (`beforeInsert` / `afterInsert`), so
+  `previous == null || …` judges an insert and `previous != null && …` skips
+  one; a column read off it there (`previous.done`) has no value and faults.
+  `previous` is UNBOUND only for a write to an existing row whose prior state
+  is not in hand, which fails closed rather than reading an update as an
+  insert. The `before*` dispatch of a predicate (`multi: true`) write is
+  **not** such a case: `beforeUpdate` / `beforeDelete` dispatch once per
+  matched row, each on a single-record-shaped context whose `previous` is that
+  row's pre-image and whose `input.id` names the row (ADR-0058 Addendum II,
+  D1/D2), so a transition condition evaluates there exactly as on a
+  single-record write, and `record` is that row's state, stored ⊕ payload. Only
+  the *payload* stays batch-scoped (D3):
   every row's dispatch carries the one payload, so a rewrite made on any row
   applies to every matched row, and a rewrite *decided* per row must assign the
   same key set on every row, in place (`ctx.input.x = …`, never a replaced
@@ -274,20 +277,18 @@ in neither). So:
   question about your spelling, not about your data.
 
 ⚠️ **An unevaluable condition ABORTS the operation.** A typo'd key
-(`record.stauts`), a `previous` reference on an insert, or a comparison CEL has
-no overload for does **not** degrade to "the hook did not fire" — it **fails the
-write**. Until protocol 17 the gate emitted a `logger.warn` and returned `false`,
-which is why the unbound-`previous` and `has(...)` bullets above are load-bearing
-rather than stylistic: a `before*` guard swallowed into `false` silently let
-writes through, and an audit hook swallowed into `false` silently dropped
-records. Those are opposite failures, so "the condition said no" and "the
-platform could not work out what the condition says" are now different outcomes
-and the second one is loud.
+(`record.stauts`), a column read off `previous` on an insert, or a comparison
+CEL has no overload for does **not** degrade to "the hook did not fire" — it
+**fails the write**. Until protocol 17 the gate emitted a `logger.warn` and
+returned `false`, which is why the `previous`-on-insert and `has(...)` bullets
+above are load-bearing rather than stylistic: a `before*` guard swallowed into
+`false` silently let writes through, and an audit hook swallowed into `false`
+silently dropped records.
 
 Practical consequence when authoring: spell keys against the object's **declared**
-fields, and put a condition that reads `previous` on an update or delete event —
-either phase — never on an insert event. That mistake used to cost you a hook
-that quietly never ran, and now costs you every write the hook is attached to.
+fields, and on an insert event read `previous` only against `null` — a column
+read off it there is the mistake that used to cost you a hook that quietly never
+ran, and now costs you every write the hook is attached to.
 
 #### `onError` — Error Handling
 
 
@@ -303,19 +303,21 @@ roots — one scope, one meaning, whichever surface reads it.
 | Surface / event | `previous` |
 |:---|:---|
 | Update hook `condition` (single-record write), validation rule on update | the stored pre-write row |
-| Insert events (`beforeInsert` / `afterInsert`), validation rule on insert | **unbound** — there is no prior state |
+| Insert events (`beforeInsert` / `afterInsert`), validation rule on insert | **`null`** — `previous == null \|\| …` judges an insert, `previous != null && …` skips one; a column read off it (`previous.x`) has no value and faults |
+| A write to an existing row whose prior state is not in hand | **unbound** — fails closed, so `previous == null` never reads an update as an insert |
 | **`after*` hook `condition` / record-change flow trigger on a predicate (`multi: true`) write** | **that row's pre-write row** — a bulk write fires after-hooks once PER MATCHED ROW |
 | Validation rule on a predicate bulk update | that row's pre-write row — per row |
 | `before*` hook `condition` on a predicate (`multi: true`) write | **that row's pre-write row** — `beforeUpdate` / `beforeDelete` dispatch once PER MATCHED ROW too, each on a single-record-shaped context whose `input.id` names the row (ADR-0058 Addendum II, D1/D2); `record` is that row's state, stored ⊕ payload, as on any update. Only the *payload* stays batch-scoped — see below the table |
 
-⚠️ **An unevaluable condition ABORTS the operation.** Referencing
-`previous` where it is unbound — like a typo'd key (`record.stauts`), a retired
-field, or a comparison CEL has no overload for — does **not** degrade to "the
-hook did not fire": it **fails the write**, with an error naming the hook and
-the key — `before*` and `after*` alike, with no `onError` escape (`onError`
-governs a handler that throws, and the condition is evaluated before any handler
-runs). A condition that does not even **compile** aborts the same way. So write
-insert-event conditions over `record` alone.
+⚠️ **An unevaluable condition ABORTS the operation.** A column read off
+`previous` on an insert (`previous.status`, where `previous` is `null`) — like
+a typo'd key (`record.stauts`), a retired field, or a comparison CEL has no
+overload for — does **not** degrade to "the hook did not fire": it **fails the
+write**, with an error naming the hook and the key — `before*` and `after*`
+alike, with no `onError` escape (`onError` governs a handler that throws, and
+the condition is evaluated before any handler runs). A condition that does not
+even **compile** aborts the same way. So on an insert event read `previous`
+only against `null`, and put a column read off it behind `previous != null &&`.
 
 **A transition condition needs no special handling for bulk writes.**
 Write it once, on a `before*` or an `after*` event, and it means the same thing
@@ -371,9 +373,10 @@ When migrating Salesforce-flavor metadata, apply these rules in order:
 | `ISCHANGED(x)` | `previous.x != record.x` |
 | `MONTH_DIFF`, `MID`, `LEFT`, `RIGHT`, `SUBSTITUTE` | _not in stdlib — propose addition_ |
 
-> ⚠️ `OLD.x` and `ISCHANGED(x)` both land on `previous.x`, which exists only
-> where `previous` is **bound** — see §5. On an insert event it is not; that
-> does not quietly skip the hook, it **fails the write**. On update and delete
+> ⚠️ `OLD.x` and `ISCHANGED(x)` both land on `previous.x`, which has a value
+> only where `previous` is a **row** — see §5. On an insert event `previous` is
+> `null`, so the read does not quietly skip the hook, it **fails the write**
+> unless guarded by `previous != null &&`. On update and delete
 > events it IS bound, per matched row, in `before*` and `after*` alike, on bulk
 > and single-record writes.
 
 
@@ -24,7 +24,7 @@
     {
       "id": 3,
       "prompt": "Run an automation only when a support case has just become `escalated` — on single updates and on bulk updates alike.",
-      "expected_output": "Writes the transition once as `P`previous.status != 'escalated' && record.status == 'escalated'``: `record` is the record's post-write state (true on every update of an already-escalated case), so only a `previous` comparison says \"just became\"; `previous` is bound per matched row on `before*` and `after*` update events, bulk included. Not usable on insert events (unbound `previous` aborts the write). There is no `ISCHANGED()` function.",
+      "expected_output": "Writes it once as `P`previous.status != 'escalated' && record.status == 'escalated'``: `record` is the post-write state (true on every later update too), so only `previous` says \"just became\"; `previous` is bound per row on `before*`/`after*` update events, bulk too. On insert `previous` is `null`: the `previous.status` read faults and aborts the write, so to run on inserts guard with `previous != null &&`. No `ISCHANGED()` function.",
       "files": [],
       "assertions": {
         "must_contain": ["previous.status", "record.status", "!="],
Original file line number	Diff line number	Diff line change
`@@ -24,7 +24,7 @@`
`24`	`24`	`{`
`25`	`25`	`"id": 3,`
`26`	`26`	"prompt": "Run an automation only when a support case has just become `escalated` — on single updates and on bulk updates alike.",
`27`		- "expected_output": "Writes the transition once as `P`previous.status != 'escalated' && record.status == 'escalated'``: `record` is the record's post-write state (true on every update of an already-escalated case), so only a `previous` comparison says \"just became\"; `previous` is bound per matched row on `before` and `after` update events, bulk included. Not usable on insert events (unbound `previous` aborts the write). There is no `ISCHANGED()` function.",
	`27`	+ "expected_output": "Writes it once as `P`previous.status != 'escalated' && record.status == 'escalated'``: `record` is the post-write state (true on every later update too), so only `previous` says \"just became\"; `previous` is bound per row on `before`/`after` update events, bulk too. On insert `previous` is `null`: the `previous.status` read faults and aborts the write, so to run on inserts guard with `previous != null &&`. No `ISCHANGED()` function.",
`28`	`28`	`"files": [],`
`29`	`29`	`"assertions": {`
`30`	`30`	`"must_contain": ["previous.status", "record.status", "!="],`