@@ -0,0 +1,37 @@
+---
+'@objectstack/verify': minor
+'@objectstack/cli': minor
+---
+
+feat(verify): the delete-behaviour family — every `deleteBehavior` a reference field declares is what a delete of the referenced record does, runnable as `os verify --delete-behaviors` (#15953)
+
+Clause-②: yes
+
+A fourth derived proof family beside `runCrudVerification`, `runRlsProofs` and `runReferenceShapeProofs`. It needs no hand-written test: from the app's own objects it takes every field whose type is in `REFERENCE_VALUE_TYPES` (`lookup`, `master_detail`, `user`, `tree`) and reads what the declaration states through the spec's own parse of the field (`FieldSchema`), which is the value a built artifact carries: a `lookup` or `tree` that authors nothing states `set_null`, an authored value is kept, and a bare `master_detail` states none. For each field it creates a fresh target record and a holder referencing it, deletes the target by id, and reads back what the engine left, through two doors: the REST data route as the signed-in caller, and the engine's own delete as the system principal.
+
+- `cascade` holds when the holder is gone with the target.
+- `set_null` holds when the holder survives and no longer references the deleted record.
+- `restrict` holds when the delete is refused with `DELETE_RESTRICTED` naming the holder's object, and both records are still there.
+- In every case a second holder, referencing another record of the same target object, must be untouched.
+
+A refusal for any other reason (a hook's veto, a validation rule, a permission) is `unattributed`, so an engine that refused every delete would not read as a proven `restrict`. A field is `proven`, `contradicted` (a delete did something else), `failed` (a door faulted), `inconclusive` (an unattributed refusal, or a fixture the app refused; the report says why), `excluded` or `not-derivable`. `contradicted + failed` is the report's `hardFailures`.
+
+Two shapes are `excluded` rather than given an expectation, because an engine rule decides what a delete does to them, not the declaration: a `set_null` on a required reference (it cannot be cleared), and a field whose parse carries no `deleteBehavior` (a bare `master_detail`, a `user`). A field is `not-derivable` when no fixture can be built from the app's metadata: its target is not an object the app declares (such as `sys_user`), it is `readonly` or `system`, or the CRUD derivation cannot synthesize its holder or target. Only by-id deletes are asked; a predicate or multi-row delete is outside the family.
+
+**`@objectstack/verify` — new exports.**
+
+- `runDeleteBehaviorProofs(stack, token, config, { doors? })` → `DeleteBehaviorReport`. Run it on a fresh stack of its own: every `restrict` probe leaves its records behind.
+- `deriveDeleteBehaviorCases(config)`, `formatDeleteBehaviorReport(report)`.
+- Types: `DeclaredDeleteBehavior`, `DeleteBehaviorCase`, `DeleteBehaviorDoor`, `DeleteBehaviorAnswer`, `DeleteBehaviorProbeResult`, `DeleteBehaviorFieldStatus`, `DeleteBehaviorFieldResult`, `DeleteBehaviorReport`, `DeleteBehaviorProofOptions`.
+
+```ts
+import { bootStack, runDeleteBehaviorProofs, formatDeleteBehaviorReport } from '@objectstack/verify';
+
+const stack = await bootStack(myApp);
+const report = await runDeleteBehaviorProofs(stack, await stack.signIn(), myApp);
+console.log(formatDeleteBehaviorReport(report));
+expect(report.summary.hardFailures).toBe(0);
+await stack.stop();
+```
+
+**`@objectstack/cli` — `os verify --delete-behaviors`.** Opt-in, like `--reference-shapes`, on a fresh boot of its own. A contradicted declaration, or a door that faulted, counts in `hardFailures` and fails the run. A `tree` field's delete is not honoured today (deleting the parent leaves the child's reference in place), so an app that declares one fails the run with the flag. The `--json` document carries the report as `deleteBehaviors` when the flag is given; without the flag the run and its document are unchanged.
@@ -1923,6 +1923,7 @@ os verify                                      # Author-time rules, then CRUD ro
 os verify --app ./objectstack.config.ts --rls  # Also prove the cross-owner RLS invariant
 os verify --rls --multi-tenant --json          # Org-scoped boot, structured report
 os verify --reference-shapes                   # Also prove reference fields refuse non-id values
+os verify --delete-behaviors                   # Also prove each declared deleteBehavior is what a delete does
 ```
 
 1. **Author-time rules.** The rule registry `os validate` runs, over the stack
@@ -1951,6 +1952,20 @@ os verify --reference-shapes                   # Also prove reference fields ref
    door; a field that admits one fails the run. It is opt-in because the engine
    still admits wrong-shaped elements on a `multiple: true` `lookup` or `user`
    field, so an app that declares one would fail until the engine refuses them.
+   With `--delete-behaviors`, another fresh boot proves that every
+   `deleteBehavior` a reference field declares is what a delete of the
+   referenced record does: per field, a fresh target and a holder referencing
+   it, then the target is deleted by id through the REST door and the system
+   door. `cascade` must remove the holder, `set_null` must keep it with the
+   link cleared, `restrict` must refuse the delete naming the holder's object,
+   and a holder of another record must be left alone; a delete that does
+   anything else fails the run. The declaration is read as the spec's parse of
+   the field states it (a `lookup` or `tree` that authors nothing states
+   `set_null`). A `set_null` on a required reference, and a field the parse
+   gives no `deleteBehavior` (a bare `master_detail`, a `user`), are reported
+   `excluded` rather than compared, because an engine rule decides their
+   outcome, not the declaration. It is opt-in, and a `tree` field's delete is
+   not honoured today, so an app that declares one would fail.
    `--multi-tenant` boots org-scoped so tenant-isolation RLS policies
    apply; a walled tenancy posture (`OS_TENANCY_POSTURE` set to `isolated` or
    `group`) asks for the same boot.
@@ -1978,8 +1993,9 @@ document carries depends on where the run ended:
   `path`, `message`, `hint`, plus `package` for a finding raised inside one
   package of the artifact), or the schema issues when the stack does not parse.
 - **Reached the runtime stage:** the report — `app`, `config`, `multiTenant`,
-  `crud`, `rls` (with `--rls`), `referenceShapes` (with `--reference-shapes`)
-  and `hardFailures`, the count the exit status is read from.
+  `crud`, `rls` (with `--rls`), `referenceShapes` (with `--reference-shapes`),
+  `deleteBehaviors` (with `--delete-behaviors`) and `hardFailures`, the count
+  the exit status is read from.
 - **Could not run:** `{ "error": "<sentence>" }`, plus `code` and `httpStatus`
   when the failure carries them.
 
 
@@ -17,9 +17,12 @@ import {
   rlsProbeSecurity,
   runReferenceShapeProofs,
   formatReferenceShapeReport,
+  runDeleteBehaviorProofs,
+  formatDeleteBehaviorReport,
   type VerifyReport,
   type RlsReport,
   type ReferenceShapeReport,
+  type DeleteBehaviorReport,
   type RlsProbeDescriptor,
   type RlsPositionPersonaInput,
 } from '@objectstack/verify';
@@ -85,18 +88,22 @@ export function resolveVerifyMultiTenant(flags: { 'multi-tenant'?: boolean }): b
  *        - reference-value shape (--reference-shapes, ADR-0104 D1): every
  *          client-writable reference field refuses a value that is not a
  *          record id, through the REST door and the system door
+ *        - delete behaviour (--delete-behaviors): every `deleteBehavior` a
+ *          reference field declares is what a by-id delete of the referenced
+ *          record does, through the REST door and the system door
  *
  * Exits non-zero on either stage's failures so it drops straight into CI.
  */
 export default class Verify extends Command {
   static override description =
-    'Run the author-time rules os validate runs, then boot the app in-process and verify it through the real HTTP stack (CRUD round-trip fidelity, plus the cross-owner RLS invariant and the reference-value shape proofs on request)';
+    'Run the author-time rules os validate runs, then boot the app in-process and verify it through the real HTTP stack (CRUD round-trip fidelity, plus the cross-owner RLS invariant, the reference-value shape proofs and the declared delete-behaviour proofs on request)';
 
   static override examples = [
     '<%= config.bin %> verify',
     '<%= config.bin %> verify --app ./objectstack.config.ts --rls',
     '<%= config.bin %> verify --rls --multi-tenant --json',
     '<%= config.bin %> verify --reference-shapes',
+    '<%= config.bin %> verify --delete-behaviors',
   ];
 
   static override flags = {
@@ -112,6 +119,10 @@ export default class Verify extends Command {
       description: 'Also prove every client-writable reference field refuses a value that is not a record id (a boolean, a number, an embedded record), through the REST door and the system door (ADR-0104 value shapes)',
       default: false,
     }),
+    'delete-behaviors': Flags.boolean({
+      description: 'Also prove every deleteBehavior a reference field declares (cascade, set_null, restrict) is what a delete of the referenced record does, through the REST door and the system door',
+      default: false,
+    }),
     'multi-tenant': Flags.boolean({
       description: 'Boot org-scoped (register the @objectstack/organizations plugin) so tenant-isolation RLS policies apply (also honors a walled $OS_TENANCY_POSTURE, and the legacy $OS_MULTI_ORG_ENABLED it falls back to)',
       default: false,
@@ -190,6 +201,7 @@ export default class Verify extends Command {
     app?: string;
     rls: boolean;
     'reference-shapes': boolean;
+    'delete-behaviors': boolean;
     'multi-tenant': boolean;
     json: boolean;
   }): Promise<void> {
@@ -305,6 +317,20 @@ export default class Verify extends Command {
       }
     }
 
+    // The delete-behaviour proofs run on a fresh stack of their own too: every
+    // `restrict` probe leaves its target and holder behind, and the fixtures
+    // the family creates would collide with the other phases' on a unique field.
+    let deleteBehaviors: DeleteBehaviorReport | undefined;
+    if (flags['delete-behaviors']) {
+      const deleteStack = await bootStack(config, { multiTenant, hostRoot });
+      try {
+        const adminToken = await deleteStack.signIn();
+        deleteBehaviors = await runDeleteBehaviorProofs(deleteStack, adminToken, config);
+      } finally {
+        await deleteStack.stop();
+      }
+    }
+
     // Failure contract: a "real" runtime break the app's author must see.
     // A degraded RLS probe counts: the run reported verdicts it could not have
     // established, which is worse than no verifier at all.
@@ -325,17 +351,22 @@ export default class Verify extends Command {
       // faulted on one. Inconclusive fields (the probe could not be attributed
       // or written) are reported, not counted, exactly as CRUD's
       // `needs-fixture` is.
-      (referenceShapes?.summary.hardFailures ?? 0);
+      (referenceShapes?.summary.hardFailures ?? 0) +
+      // A declared deleteBehavior a delete contradicted, or a door that
+      // faulted on one. Inconclusive, excluded and not-derivable fields are
+      // reported, not counted.
+      (deleteBehaviors?.summary.hardFailures ?? 0);
 
     if (flags.json) {
       // `emitJson`, not `this.log`: stdout is reserved (see `run()`), so the
       // report has to leave through the real stream — and awaiting the write
       // drains a report larger than one pipe buffer before `this.exit` below.
-      await emitJson({ app: crud.app, config: absolutePath, multiTenant, crud, rls, referenceShapes, hardFailures });
+      await emitJson({ app: crud.app, config: absolutePath, multiTenant, crud, rls, referenceShapes, deleteBehaviors, hardFailures });
     } else {
       this.log(formatReport(crud));
       if (rls) this.log(formatRlsReport(rls));
       if (referenceShapes) this.log(formatReferenceShapeReport(referenceShapes));
+      if (deleteBehaviors) this.log(formatDeleteBehaviorReport(deleteBehaviors));
       this.log('');
       this.log(
         hardFailures > 0
 
@@ -0,0 +1,183 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * PIN — `os verify --delete-behaviors` runs the delete-behaviour family and
+ * counts what it finds in the exit status.
+ *
+ * ## What is pinned
+ *
+ *   - without the flag the run is what it was: no `deleteBehaviors` key in the
+ *     `--json` document, and the exit status reads CRUD only;
+ *   - with the flag, each declared behaviour (`cascade`, `restrict`, and the
+ *     `set_null` the spec states for a lookup that authors nothing) is
+ *     `proven` through both doors, `hardFailures` stays 0 and the run exits 0;
+ *   - with the flag, on the same metadata plus a `beforeDelete` hook that
+ *     detaches the cascading holders before the engine's referential pass
+ *     runs, the `cascade` field is reported contradicted, `hardFailures`
+ *     counts it and the run exits 1 — the negative control, through the CLI.
+ *
+ * Spawned rather than run in-process: the exit status is the contract a CI
+ * gate reads, and only a real process has one.
+ */
+
+import { describe, expect, it, beforeAll, afterAll } from 'vitest';
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CLI, TSX, childEnv } from './helpers/serve-process.js';
+import { defineStackSource, defineStackSourceFromLiteral, linkSpec } from './helpers/define-stack-fixture.js';
+
+const MANIFEST = {
+  id: 'com.example.verify-delete-behaviors',
+  namespace: 'vdb',
+  version: '1.0.0',
+  name: 'Verify Delete Behaviors',
+  type: 'app',
+  engines: { protocol: '^18' },
+};
+
+const OBJECTS = [
+  {
+    name: 'vdb_account',
+    label: 'Account',
+    pluralLabel: 'Accounts',
+    sharingModel: 'private',
+    fields: { name: { type: 'text', label: 'Name', required: true } },
+  },
+  {
+    name: 'vdb_contact',
+    label: 'Contact',
+    pluralLabel: 'Contacts',
+    sharingModel: 'private',
+    fields: {
+      name: { type: 'text', label: 'Name', required: true },
+      account: { type: 'lookup', reference: 'vdb_account', label: 'Account', deleteBehavior: 'cascade' },
+    },
+  },
+  {
+    name: 'vdb_note',
+    label: 'Note',
+    pluralLabel: 'Notes',
+    sharingModel: 'private',
+    fields: {
+      name: { type: 'text', label: 'Name', required: true },
+      account: { type: 'lookup', reference: 'vdb_account', label: 'Account', deleteBehavior: 'restrict' },
+    },
+  },
+  {
+    name: 'vdb_tag',
+    label: 'Tag',
+    pluralLabel: 'Tags',
+    sharingModel: 'private',
+    fields: {
+      name: { type: 'text', label: 'Name', required: true },
+      account: { type: 'lookup', reference: 'vdb_account', label: 'Account' },
+    },
+  },
+];
+
+/** The same app, plus a hook that undoes the cascade before the engine judges the delete. */
+const CONTROL_SOURCE = `{
+  manifest: ${JSON.stringify({ ...MANIFEST, id: 'com.example.verify-delete-behaviors-control' })},
+  objects: ${JSON.stringify(OBJECTS)},
+  hooks: [
+    {
+      name: 'vdb_account_detaches_contacts',
+      object: 'vdb_account',
+      events: ['beforeDelete'],
+      handler: async (ctx) => {
+        const contacts = ctx.api.object('vdb_contact');
+        for (const row of await contacts.find({ where: { account: ctx.input.id } })) {
+          await contacts.updateById(row.id, { account: null });
+        }
+      },
+    },
+  ],
+}`;
+
+interface Run {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+interface Doc {
+  hardFailures?: number;
+  deleteBehaviors?: {
+    results: Array<{ object: string; field: string; declared?: string; status: string }>;
+    summary: { proven: number; contradicted: number; hardFailures: number };
+  };
+}
+
+function runCli(dir: string, args: string[]): Run {
+  // Through tsx, so the child runs this checkout's `src/`.
+  const r = spawnSync(TSX, [CLI, ...args], {
+    cwd: dir,
+    encoding: 'utf8',
+    env: childEnv({ NO_COLOR: '1' }),
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return { status: r.status, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+}
+
+const docOf = (run: Run): Doc => JSON.parse(run.stdout) as Doc;
+
+describe('os verify --delete-behaviors', () => {
+  let root: string;
+  let plain: Run;
+  let proven: Run;
+  let control: Run;
+
+  beforeAll(() => {
+    root = mkdtempSync(join(tmpdir(), 'os-verify-delete-behaviors-'));
+    const app = join(root, 'app');
+    const controlApp = join(root, 'control');
+    for (const [dir, source] of [
+      [app, defineStackSource({ manifest: MANIFEST, objects: OBJECTS })],
+      [controlApp, defineStackSourceFromLiteral(CONTROL_SOURCE)],
+    ] as const) {
+      mkdirSync(dir);
+      writeFileSync(join(dir, 'objectstack.config.mjs'), source);
+      linkSpec(dir);
+    }
+    plain = runCli(app, ['verify', '--json']);
+    proven = runCli(app, ['verify', '--delete-behaviors', '--json']);
+    control = runCli(controlApp, ['verify', '--delete-behaviors', '--json']);
+  }, 480_000);
+
+  afterAll(() => {
+    if (root) rmSync(root, { recursive: true, force: true });
+  });
+
+  it('leaves the run unchanged without the flag', () => {
+    expect(plain.status, `${plain.stdout}\n${plain.stderr}`).toBe(0);
+    const doc = docOf(plain);
+    expect('deleteBehaviors' in doc).toBe(false);
+    expect(doc.hardFailures).toBe(0);
+  });
+
+  it('proves each declared behaviour, and exits 0', () => {
+    expect(proven.status, `${proven.stdout}\n${proven.stderr}`).toBe(0);
+    const doc = docOf(proven);
+    expect(doc.deleteBehaviors?.results).toEqual([
+      expect.objectContaining({ object: 'vdb_contact', field: 'account', declared: 'cascade', status: 'proven' }),
+      expect.objectContaining({ object: 'vdb_note', field: 'account', declared: 'restrict', status: 'proven' }),
+      expect.objectContaining({ object: 'vdb_tag', field: 'account', declared: 'set_null', status: 'proven' }),
+    ]);
+    expect(doc.deleteBehaviors?.summary).toMatchObject({ proven: 3, contradicted: 0, hardFailures: 0 });
+    expect(doc.hardFailures).toBe(0);
+  });
+
+  it('NEGATIVE CONTROL: reports a cascade a hook undid, counts it, and exits 1', () => {
+    expect(control.status, `${control.stdout}\n${control.stderr}`).toBe(1);
+    const doc = docOf(control);
+    expect(doc.deleteBehaviors?.results).toEqual([
+      expect.objectContaining({ object: 'vdb_contact', field: 'account', declared: 'cascade', status: 'contradicted' }),
+      expect.objectContaining({ object: 'vdb_note', field: 'account', status: 'proven' }),
+      expect.objectContaining({ object: 'vdb_tag', field: 'account', status: 'proven' }),
+    ]);
+    expect(doc.deleteBehaviors?.summary).toMatchObject({ proven: 2, contradicted: 1, hardFailures: 1 });
+    expect(doc.hardFailures).toBe(1);
+  });
+});
@@ -229,6 +229,14 @@ const CALLERS: Record<string, Classification> = {
       "to the SOURCE object (the REST data routes, which judge that object's exposure, and the engine's system write) " +
       'and reads no record of the target',
   },
+  'packages/verify/src/delete-behavior.ts': {
+    kind: 'not-a-served-read',
+    reason:
+      "the verification harness's delete-behaviour family: the target names the object whose records the family " +
+      'itself creates and then deletes, through the REST data routes (where that object is the ADDRESSED one, ' +
+      "judged as such) and the engine's system delete. It reads those records back only through the harness's " +
+      'system read, to see whether the delete removed them, and serves no field of the target to any caller',
+  },
 };
 
 const SCAN_TIMEOUT_MS = 60_000;