@@ -0,0 +1,18 @@
+---
+'@objectstack/objectql': patch
+---
+
+fix(objectql): a `tree` field's `deleteBehavior` now takes effect when its parent record is deleted, and the default clears the reference
+
+Clause-②: no
+
+The spec gives a `tree` field (a record's parent in a hierarchy on its own object) a `deleteBehavior`, like a `lookup`. When the field declares none, the parse fills in `set_null`. The engine's referential delete pass only followed `master_detail` and `lookup` fields. So deleting a parent node returned success and left every child pointing at the deleted id. An authored `cascade` or `restrict` on a `tree` did nothing either.
+
+A by-id delete now applies a `tree` field's behaviour the way it applies a `lookup`'s:
+
+- `set_null` (the default): the children stay, and their parent field is cleared.
+- `cascade`: the whole subtree is deleted, at any depth, and nothing outside it. A cycle in the data (a row whose parent is its own descendant, or itself) ends: each row is deleted once.
+- `restrict`: deleting a node that still has children is refused with `DELETE_RESTRICTED` (409), and the dependent named is the tree's own object. A leaf node still deletes.
+- On a required `tree` field, `set_null` cannot clear the parent, so deleting a node that has children is refused with `DELETE_RESTRICTED`, as it is for a required `lookup`.
+
+Deleting a record of an object that has a `tree` field now runs as one transaction when the object is on the default datasource, as every delete that can cascade already does. If a node deep in the subtree refuses its delete (a `beforeDelete` hook, say), the nodes already deleted are restored and the call is refused. `lookup` and `master_detail` behave exactly as before.
@@ -25,6 +25,8 @@
  *    nothing outside it;
  *  - `restrict` refuses with the ADR-0112 envelope naming the tree's own object
  *    as the dependent, and keeps the row; a leaf still deletes;
+ *  - a REQUIRED tree's `set_null` escalates to that refusal, as a required
+ *    `lookup`'s does;
  *  - a cycle in the data terminates: a corrupt row pointing at its own
  *    descendant, and a row pointing at itself;
  *  - a subtree cascade is one unit of work: a refusal from a node deep in it
@@ -300,6 +302,28 @@ describe('[#22957] a tree field\'s deleteBehavior takes effect on a parent delet
     });
   });
 
+  describe('required', () => {
+    it('a required tree\'s set_null cannot clear the parent, so the parent delete is refused', async () => {
+      // The escalation a required `lookup` already takes: a parent that must
+      // be present cannot be cleared, so the delete is refused rather than
+      // answered with the child's own `required` refusal.
+      const { engine, driver } = await makeEngine([
+        treeObject('zt_rooted', parsedTree('zt_rooted', { required: true })),
+      ]);
+      // A required hierarchy's top points at itself; the engine refuses a
+      // reference to a row that does not exist yet, so it is written at the
+      // driver.
+      const root = await driver.create('zt_rooted', { id: 'root', name: 'root', parent: 'root' });
+      const c = await engine.insert('zt_rooted', { name: 'C', parent: root.id });
+
+      const err = await refusalOf(engine.delete('zt_rooted', { where: { id: root.id } } as any));
+
+      expect(err).toMatchObject({ code: 'DELETE_RESTRICTED', status: 409, dependentObject: 'zt_rooted' });
+      expect(driver.rowOf('zt_rooted', root.id)).toMatchObject({ name: 'root' });
+      expect(driver.rowOf('zt_rooted', c.id)).toMatchObject({ name: 'C', parent: root.id });
+    });
+  });
+
   describe('multiple: true', () => {
     it('is refused on a tree by the spec\'s parse, so no multi-valued tree reaches the walk through it', () => {
       const result = FieldSchema.safeParse({ type: 'tree', reference: 'zt_multi', multiple: true });