feat(objectql,metadata-protocol,rest,spec): the object read names the objects a delete can cascade into

.changeset/28001-cascade-delete-objects-beside-item.md

@@ -0,0 +1,16 @@
+---
+'@objectstack/spec': minor
+'@objectstack/objectql': patch
+'@objectstack/metadata-protocol': patch
+'@objectstack/rest': patch
+---
+
+feat: the object read names the objects a delete can cascade into, beside the item
+
+Clause-②: yes (widening)
+Metadata-protocol: added
+Skills-docs: none — `cascadeDeleteObjects` is a served-only key beside the object read with no authorable spelling; no file under `skills/**` teaches the object read's envelope keys (a `git grep` of `skills/` for `cascadeDeleteObjects` and `disabledActions` names nothing), and every taught `deleteBehavior` use stays true.
+
+- **Served beside the object** (`@objectstack/metadata-protocol`, `@objectstack/rest`). `GET /api/v1/meta/object/:name` serves `cascadeDeleteObjects` beside `item`: the names of the objects that deleting a record of this object can also delete. That is every object whose relation into it cascades (a `master_detail` by default, a `lookup` or `tree` that declares `deleteBehavior: 'cascade'`), and the objects that cascade into those in turn, each once. A `restrict` or `set_null` relation removes nothing and is not named. The default cached door carries it too, and the list is folded into that door's ETag, so an object registered later that cascades into this one changes the ETag. The key is absent where no engine answered, on a draft read, on the list read and on every type other than `object`; `[]` means nothing cascades. `item` is unchanged. A delete confirmation can now name what else a delete removes without keeping its own copy of the rule.
+- **The fact it serves** (`@objectstack/objectql`). `ObjectQL.getCascadeDeleteObjects(object)` answers that list from the delete walk's own relation scan, which the delete and this read now share. It reads the registry and no row, so it never says which records or how many. It returns `undefined` for an object the registry does not hold.
+- **The declaration** (`@objectstack/spec`). `GetMetaItemResponseSchema` and `GetMetaItemCachedResponseSchema` gain the optional `cascadeDeleteObjects` (an array of object names), and `IObjectQLEngine` gains the optional member `getCascadeDeleteObjects(objectName)`, which the metadata read calls through the kernel's service table. Nothing about it is authorable.

content/docs/references/api/protocol.mdx

@@ -1335,6 +1335,7 @@ This schema accepts one of the following structures:
 | **version** | `string` | optional | Metadata version identifier |
 | **registration** | `{ state: 'registered' } \| { state: 'refused'; reason: object } \| { state: 'unregistered' }` | optional | The automation engine's verdict on the flow in `data`, read live on every call and never part of `etag` (see `FlowRegistrationSchema`). Present only for a `flow` read answered by a process that runs an automation service; a read that carries it is never answered `notModified`. Absent otherwise, and absence means no engine judged it, never `registered`. |
 | **disabledActions** | `string[]` | optional | The names in the `actions` of the object in `data` that this deployment's activation ledger switches off (a call to any of them is refused 409 `ACTION_DISABLED`), read live on every call and never part of `etag`. Present only for an `object` read answered by a process whose data engine has an activation ledger attached, `[]` when none is switched off; this method never answers `notModified` for a read that carries it (the REST door folds the served list into the ETag it checks instead, so its 304 comes back only while the switched-off set is unchanged). Absent otherwise, and absence means no ledger answered, never that nothing is switched off. |
+| **cascadeDeleteObjects** | `string[]` | optional | The objects, by name, that deleting a record of the object in `data` can also delete (the item read's `cascadeDeleteObjects`), read live on every call and never part of `etag`. Present only for an `object` read answered by a process whose data engine answers it, `[]` when nothing cascades; this method never answers `notModified` for a read that carries it (the REST door folds the served list into the ETag it checks instead). Absent otherwise, and absence means no engine answered, never that nothing cascades. |
 
 ### Nested Shape: `GetMetaItemCachedResponse.etag`
 
@@ -1462,6 +1463,7 @@ This schema accepts one of the following structures:
 | **version** | `string \| null` | optional | ADR-0008 version token of the STORED row a save to this item compares against, at this read's scope (the environment's partition and `?package=`) and lifecycle (`?state=draft` reads the draft row, the plain read the active row). The same keyed token a save receipt's `version` serves for that row: send it back as the `If-Match` request header on `PUT /meta/:type/:name` (with `?mode=draft` for the draft) and a concurrent edit is refused 409 `METADATA_CONFLICT` instead of overwritten. `null` when no stored row is there — an item served from code or a package artifact, or from a row in another scope (a package-less row a package read falls back to) — so the next save creates one: pin it with `If-None-Match: *`. A `null` beside `editable: false` is no such invitation: that item takes no save at this address, so no pin is prescribed for it. ABSENT on the cached published-value branch and on a `?preview=draft` read, which publish no version: absence means "not published here", never "no row". Opaque — echo it verbatim, never parse it. |
 | **registration** | `{ state: 'registered' } \| { state: 'refused'; reason: object } \| { state: 'unregistered' }` | optional | The automation engine's verdict on this flow (see `FlowRegistrationSchema`): `registered`, or `refused` with the engine's `reason` verbatim, or `unregistered`. Present only on a `flow` read answered by a process that runs an automation service; absent otherwise, and absence means no engine judged it, never `registered`. Unlike the protection keys it is published by the cached branch too, read live and never part of the ETag, so a cached read that carries it is never answered 304; it is absent on a draft read, whose pending body no engine holds. The verdict is the answering process's engine. Beside `item`, never inside it: the item's `status` stays what its author declared. |
 | **disabledActions** | `string[]` | optional | The names in `item.actions` that this deployment's activation ledger switches off (an administrator turned them off under Setup › Packaged automation): a call to any of them is refused 409 `ACTION_DISABLED`. Present only on an `object` read answered by a process whose data engine has an activation ledger attached, and then `[]` when none of this object's actions is switched off. Absent otherwise, and absence means no ledger answered, never that nothing is switched off. Unlike the protection keys it is published by the cached branch too, read live and folded into the ETag, so a cached read revalidates to 304 only while the switched-off set is unchanged; it is absent on a draft read. The ledger is the answering process's engine's. Beside `item`, never inside it: `item.actions` is served as declared, a switched-off action included. |
+| **cascadeDeleteObjects** | `string[]` | optional | The objects, by name, that deleting a record of this object can also delete: every object whose relation into it cascades (a `master_detail` by default, a `lookup` or `tree` that declares `deleteBehavior: 'cascade'`), and the objects that cascade into those in turn, each once, in the order the delete reaches them. This object itself is named only when a cascading relation leads back to it. A `restrict` or `set_null` relation removes nothing and is not named. Read from the rule the delete runs, and object-level: it never says which records or how many. Present only on an `object` read answered by a process whose data engine answers it, and then `[]` when nothing cascades. Absent otherwise, and absence means no engine answered, never that nothing cascades. Unlike the protection keys it is published by the cached branch too, read live and folded into the ETag; it is absent on a draft read. Beside `item`, never inside it: it is derived from other objects' definitions and is not authorable. |
 | **draftChanges** | `{ path: string[]; by: Enum<'copilot' \| 'mcp' \| 'studio' \| 'api'>; actor: string \| null; client?: object; … }[]` | optional | Per-key provenance of the pending draft: which authoring surface last changed each key path of `item`, under which actor, and when. The draft save records it: each draft save is compared with the body that save replaced (the previous draft, or the stored published row for the draft's first save; a draft of an item with no stored published row is recorded as `[]`, the whole body). A `migrate-stored` rewrite of a draft row records nothing, since it is not authoring. The entries are kept from the first recorded save until the draft is published or discarded, which remove the draft row and the entries with it; and no two entries share a path: a save replaces every entry at or under each path it changes, so the last write to change a key is the entry whose `path` is the longest prefix of that key's path, and entries under a key's path are changes inside it. The entries name which writes changed what; they are not a list of every difference from the published body (compare the two bodies for that). Served only on a `?state=draft` read that answers a stored draft row. ABSENT on the active read, the cached branch and a `?preview=draft` read, and for a draft row whose saves recorded none: absence means "not recorded", never "no changes". |
 
 ### Nested Shape: `GetMetaItemResponse.sortability`

packages/metadata-protocol/src/protocol.object-cascade-delete-objects.test.ts

@@ -0,0 +1,204 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [#28001] The `object` item read serves, beside the item, the objects a
+ * delete of one of its records can cascade into: `cascadeDeleteObjects` on
+ * both doors. It takes `disabledActions`' (#27842) four positions:
+ *
+ *  - read through the kernel's service table by name (`objectql`), for the
+ *    optional member the engine declares on `IObjectQLEngine`
+ *    (`getCascadeDeleteObjects`) — this package imports no engine and holds no
+ *    copy of which relations cascade;
+ *  - absent where no engine answered (no engine, an engine without the
+ *    member, or one that does not hold the object), never `[]` there;
+ *  - `[]` where the engine answered that nothing cascades;
+ *  - on the cached default door too, never in its ETag, and a read that
+ *    carries it is never answered 304 (the REST door folds it instead).
+ *
+ * `item` is served as stored: the list is beside it, never in it.
+ *
+ * The engine double answers the way `ObjectQL` does (pinned on the real
+ * engine, with the real protocol, in `@objectstack/objectql`'s
+ * `engine-cascade-delete-objects.test.ts`).
+ */
+import { describe, expect, it, vi } from 'vitest';
+import { assertEngineFindOnePredicate } from '@objectstack/metadata-core';
+import { ObjectStackProtocolImplementation } from './protocol.js';
+
+interface StoredRow {
+    id: string;
+    type: string;
+    name: string;
+    package_id: string | null;
+    state: string;
+    metadata: string;
+}
+
+const storedRow = (type: string, name: string, body: unknown, extra: Partial<StoredRow> = {}): StoredRow => ({
+    id: `r_${type}_${name}_${extra.state ?? 'active'}`,
+    type,
+    name,
+    package_id: null,
+    state: 'active',
+    metadata: JSON.stringify(body),
+    ...extra,
+});
+
+/** [#24371] One `where` value as the store reads it: `{ $in: [...] }` or equality. */
+const whereValueMatches = (actual: unknown, want: unknown): boolean =>
+    want !== null && typeof want === 'object' && Array.isArray((want as { $in?: unknown }).$in)
+        ? (want as { $in: unknown[] }).$in.includes(actual)
+        : actual === want;
+
+const TASK = {
+    name: 'showcase_task',
+    label: 'Task',
+    fields: { title: { name: 'title', type: 'text', label: 'Title' } },
+    actions: [
+        { name: 'showcase_mark_done', label: 'Mark Done', type: 'script', locations: ['record_header'] },
+        { name: 'showcase_snooze', label: 'Snooze', type: 'script', locations: ['record_header'] },
+    ],
+};
+const PROJECT = {
+    name: 'showcase_project',
+    label: 'Project',
+    fields: { title: { name: 'title', type: 'text', label: 'Title' } },
+    actions: [{ name: 'showcase_archive', label: 'Archive', type: 'script' }],
+};
+const NOTE = { name: 'showcase_note', label: 'Note', fields: { body: { name: 'body', type: 'text', label: 'Body' } } };
+const ROWS = [storedRow('object', TASK.name, TASK), storedRow('object', PROJECT.name, PROJECT), storedRow('object', NOTE.name, NOTE)];
+
+/**
+ * The store double: `find` / `findOne` over `sys_metadata` rows, and a
+ * registry that holds nothing of its own. ⛔ No write verb — the reads under
+ * test issue none.
+ */
+function harness(rows: StoredRow[], services: Map<string, unknown> = new Map()) {
+    const matching = (where: Record<string, unknown>) => {
+        for (const k of Object.keys(where)) {
+            if (k.startsWith('$')) throw new Error(`[test double] unsupported WHERE combinator '${k}'`);
+        }
+        return rows.filter((r) =>
+            Object.entries(where).every(([k, v]) => v === undefined || whereValueMatches((r as unknown as Record<string, unknown>)[k], v)),
+        );
+    };
+    const engine: any = {
+        async find(table: string, opts?: { where?: Record<string, unknown>; limit?: number }) {
+            if (table !== 'sys_metadata') return [];
+            const matched = matching(opts?.where ?? {});
+            // `check:objectql-double-limit` — the caller's bound, applied after the filter.
+            return opts?.limit === undefined ? matched : matched.slice(0, opts.limit);
+        },
+        async findOne(table: string, opts?: { where?: Record<string, unknown> }) {
+            // `check:engine-double-contract` — refuses what the real engine refuses.
+            assertEngineFindOnePredicate(table, opts);
+            if (table !== 'sys_metadata') return null;
+            return matching(opts?.where ?? {})[0] ?? null;
+        },
+        registry: {
+            listItems: () => [],
+            getItem: () => undefined,
+            getArtifactItem: () => undefined,
+            getObject: () => undefined,
+            registerItem: () => undefined,
+            registerObject: () => undefined,
+            getPackage: () => undefined,
+            isPackageDisabled: () => false,
+            applyNavContributions: (app: unknown) => app,
+        },
+    };
+    return new ObjectStackProtocolImplementation(engine, () => services as Map<string, any>);
+}
+
+/** The engine's answer: the cascade per object name, `undefined` for an object it does not hold. */
+function engineDouble(cascades: Record<string, string[]>) {
+    return {
+        getCascadeDeleteObjects: vi.fn((objectName: string): string[] | undefined =>
+            Object.prototype.hasOwnProperty.call(cascades, objectName) ? [...cascades[objectName]!] : undefined),
+    };
+}
+
+const CASCADES = { [TASK.name]: ['showcase_subtask', 'showcase_checklist_item'], [PROJECT.name]: [] };
+const withEngine = (cascades: Record<string, string[]> = CASCADES) =>
+    new Map<string, unknown>([['objectql', engineDouble(cascades)]]);
+
+describe('[#28001] the item read: `cascadeDeleteObjects` beside `item`, the engine\'s answer or nothing', () => {
+    it('names what a delete of this object cascades into, and serves `item` as stored', async () => {
+        const plain: any = await harness(ROWS).getMetaItem({ type: 'object', name: TASK.name });
+        const judged: any = await harness(ROWS, withEngine()).getMetaItem({ type: 'object', name: TASK.name });
+
+        expect(judged.cascadeDeleteObjects).toEqual(['showcase_subtask', 'showcase_checklist_item']);
+        expect(JSON.stringify(judged.item)).toBe(JSON.stringify(plain.item));
+        expect(judged.item).not.toHaveProperty('cascadeDeleteObjects');
+        expect(judged).toHaveProperty('lock');
+    });
+
+    it('`[]` when the engine answered that nothing cascades', async () => {
+        expect((await harness(ROWS, withEngine()).getMetaItem({ type: 'object', name: PROJECT.name }) as any).cascadeDeleteObjects)
+            .toEqual([]);
+    });
+
+    it('control: no key where no engine answered — no engine, an engine without the member, an object it does not hold', async () => {
+        const cases: Array<[Map<string, unknown>, string]> = [
+            [new Map<string, unknown>(), TASK.name],
+            [new Map<string, unknown>([['objectql', { find: async () => [] }]]), TASK.name],
+            [withEngine(), NOTE.name],
+        ];
+        for (const [services, name] of cases) {
+            const read: any = await harness(ROWS, services).getMetaItem({ type: 'object', name });
+            expect(read.item.name).toBe(name);
+            expect(read).not.toHaveProperty('cascadeDeleteObjects');
+        }
+    });
+
+    it('the plural spelling of the type is folded first and answers the same', async () => {
+        const read: any = await harness(ROWS, withEngine()).getMetaItem({ type: 'objects', name: TASK.name });
+        expect(read.cascadeDeleteObjects).toEqual(['showcase_subtask', 'showcase_checklist_item']);
+    });
+
+    it('a type other than `object` reads no key, and the engine is never asked', async () => {
+        const services = withEngine();
+        const read: any = await harness(
+            [...ROWS, storedRow('view', 'task_board', { name: 'task_board', label: 'Board' })], services,
+        ).getMetaItem({ type: 'view', name: 'task_board' });
+
+        expect(read).not.toHaveProperty('cascadeDeleteObjects');
+        expect((services.get('objectql') as ReturnType<typeof engineDouble>).getCascadeDeleteObjects).not.toHaveBeenCalled();
+    });
+
+    it('the execution face carries none', async () => {
+        const read: any = await harness(ROWS, withEngine()).getMetaItemForExecution({ type: 'object', name: TASK.name });
+        expect(read).not.toHaveProperty('cascadeDeleteObjects');
+    });
+
+    it('the list carries none: the item read is the one the delete confirmations read', async () => {
+        const list: any = await harness(ROWS, withEngine()).getMetaItems({ type: 'object' });
+        expect(list.items.length).toBe(3);
+        expect(list).not.toHaveProperty('cascadeDeleteObjects');
+        for (const item of list.items) expect(item).not.toHaveProperty('cascadeDeleteObjects');
+    });
+});
+
+describe('[#28001] the cached read — the default door — carries it beside `data`, never in the ETag', () => {
+    it('serves the engine\'s answer beside the document, with an ETag over the document alone', async () => {
+        const judged: any = await harness(ROWS, withEngine()).getMetaItemCached({ type: 'object', name: TASK.name });
+        const unjudged: any = await harness(ROWS).getMetaItemCached({ type: 'object', name: TASK.name });
+
+        expect(judged.cascadeDeleteObjects).toEqual(['showcase_subtask', 'showcase_checklist_item']);
+        expect(judged.data).not.toHaveProperty('cascadeDeleteObjects');
+        expect(judged.etag).toEqual(unjudged.etag);
+        expect(unjudged).not.toHaveProperty('cascadeDeleteObjects');
+    });
+
+    it('a read that carries the key is never answered 304; control: one where no engine answered still is', async () => {
+        const first: any = await harness(ROWS, withEngine()).getMetaItemCached({ type: 'object', name: TASK.name });
+        const revalidate = { type: 'object', name: TASK.name, cacheRequest: { ifNoneMatch: `"${first.etag.value}"` } };
+
+        const judged: any = await harness(ROWS, withEngine()).getMetaItemCached(revalidate);
+        expect(judged.notModified).toBe(false);
+        expect(judged.cascadeDeleteObjects).toEqual(['showcase_subtask', 'showcase_checklist_item']);
+
+        const unjudged: any = await harness(ROWS, new Map()).getMetaItemCached(revalidate);
+        expect(unjudged.notModified).toBe(true);
+    });
+});