@@ -0,0 +1,26 @@
+---
+'@objectstack/spec': patch
+'@objectstack/objectql': patch
+---
+
+feat(objectql): restore a recycle-bin entry under its original ids, and publish `data.record.restored` (ADR-0148 D2)
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+
+`ObjectQL.restore(entryId, { context })` writes one recycle-bin entry back: every row of the entry, the master first and its master-detail details after it, under the ids they had, with `created_by` / `created_at` as they were. No insert hook runs, no default or autonumber is issued: a restore is not a create. The references the delete cleared (`set_null` lookups) are re-linked where nothing has changed them since: a single-valued field while it still holds no value, a multi-valued one while it no longer holds the member. Roll-ups recompute from the rows that are back, one `data.record.restored` event is published per row, and the entry is removed. It answers what came back (`RecycleBinRestoreResult`: the entry, the master's object and id, every row, how many references were re-linked), or `null` when no entry with that id is visible to the caller's organization or the composition registers no bin.
+
+The entry is the unit: every row comes back or none does. A restore that would write what it should not is refused `409` before anything is written, and the entry stays:
+
+- `RESTORE_PACKAGE_UNINSTALLED`: an object of the entry is no longer registered.
+- `RESTORE_PARENT_PURGED`: a row's master-detail parent is neither live, nor a row of the entry, nor the record of another recycle-bin entry.
+- `RESTORE_PARENT_IN_RECYCLE_BIN`: a row's master-detail parent is not live but is the record of another recycle-bin entry. The refusal names that entry (`parentEntryId`, beside `parentObject` / `parentId`) and says to restore it first; unlike the other three, it clears once that entry is restored.
+- `RESTORE_UNIQUE_VALUE_TAKEN`: a live row holds the id or a unique value of a snapshotted row, found by a probe before the write or by the store's own unique constraint at it.
+
+The writes run in one transaction when every object involved is stored by the recycle bin's driver; otherwise each write already made is undone when a later one fails.
+
+The restore is dispatched as the new `restore` operation on the business object, with no query AST and no id, like `purge(entryId)`. `beforeRestore` / `afterRestore` stay outside the engine's hook namespace, so registering them only warns, as before. `restore` advances the write epoch. Until `@objectstack/plugin-security` maps the verb to `allowRestoreOwnDeleted` / `manageRecycleBin`, its fail-closed backstop refuses every restore by a caller that is not the system.
+
+`@objectstack/spec`: `DataEventType` and `RealtimeEventType` gain `data.record.restored` (`RECORD_RESTORED_EVENT`), now that the engine emits it. A pure widening: a consumer that matches the event names it knows keeps working, and one that wants restores subscribes to the new name. A consumer keyed on `data.record.created` does not see a restore.
+
+`@objectstack/spec`: `RECYCLE_BIN_RESTORE_REFUSAL_CODES` gains `parentInRecycleBin` (`'RESTORE_PARENT_IN_RECYCLE_BIN'`), registered in the error-code ledger under `@objectstack/objectql`, 409 like the other three. Also a widening: a consumer that switches over the codes it knows keeps working and treats the new one as an unknown 409; one that wants to offer "restore the parent first" reads `parentEntryId`.
@@ -417,7 +417,7 @@ const result = AutomationApiErrorCode.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +362 more>` | ✅ | The inner refusal's code in its WIRE spelling - the ADR-0112 member a record save of the same write answers in `error.code` (e.g. `UNIQUE_VIOLATION`); the closed set `ApiErrorSchema.code` parses against |
+| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +363 more>` | ✅ | The inner refusal's code in its WIRE spelling - the ADR-0112 member a record save of the same write answers in `error.code` (e.g. `UNIQUE_VIOLATION`); the closed set `ApiErrorSchema.code` parses against |
 | **message** | `string` | ✅ | The inner refusal's own diagnostic text, verbatim, without the node and operation prefixes the run's failure text adds |
 
 ### Allowed Values: `FlowInnerRefusal.code`
@@ -707,6 +707,7 @@ const result = AutomationApiErrorCode.parse(data);
 * `RESEED_NO_ROWS`
 * `RESEED_SKIPPED`
 * `RESTORE_PACKAGE_UNINSTALLED`
+* `RESTORE_PARENT_IN_RECYCLE_BIN`
 * `RESTORE_PARENT_PURGED`
 * `RESTORE_UNIQUE_VALUE_TAKEN`
 * `RESUME_CHILD_PENDING`
 
@@ -28,7 +28,7 @@ const result = ApiErrorSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +362 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
+| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +363 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
 | **declaredCode** | `string` | optional | The producer-declared code, verbatim, when it is not a member of the closed `code` vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
 | **message** | `string` | ✅ | Readable error message |
 | **userMessage** | `string` | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces `message`. |
@@ -325,6 +325,7 @@ const result = ApiErrorSchema.parse(data);
 * `RESEED_NO_ROWS`
 * `RESEED_SKIPPED`
 * `RESTORE_PACKAGE_UNINSTALLED`
+* `RESTORE_PARENT_IN_RECYCLE_BIN`
 * `RESTORE_PARENT_PURGED`
 * `RESTORE_UNIQUE_VALUE_TAKEN`
 * `RESUME_CHILD_PENDING`
 
@@ -492,6 +492,7 @@ const result = ErrorCode.parse(data);
 * `RESEED_NO_ROWS`
 * `RESEED_SKIPPED`
 * `RESTORE_PACKAGE_UNINSTALLED`
+* `RESTORE_PARENT_IN_RECYCLE_BIN`
 * `RESTORE_PARENT_PURGED`
 * `RESTORE_UNIQUE_VALUE_TAKEN`
 * `RESUME_CHILD_PENDING`
 
@@ -56,7 +56,7 @@ const result = BulkDataEventSchema.parse(data);
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
 | **id** | `string` | ✅ | Unique event identifier |
-| **type** | `Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted'>` | ✅ | Event type |
+| **type** | `Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted' \| 'data.record.restored'>` | ✅ | Event type |
 | **object** | `string` | ✅ | Object name |
 | **recordId** | `string` | ✅ | Record ID |
 | **organizationId** | `string` | optional | Organization the record belongs to (its organization_id), so a tenant-scoped consumer can discriminate the event's tenant without reading the record body. Absent when the record belongs to no organization: a row of an object outside the wall (environment-wide, or no organization column), and every row of a composition that registers no organization object. A single-posture deployment stamps every tenant row with its Default Organization, so its events carry it — read absence as "not behind any organization wall", never as "unknown". Present = exactly that organization; never fabricated, and the empty string is refused. |
@@ -76,6 +76,7 @@ const result = BulkDataEventSchema.parse(data);
 * `data.record.created`
 * `data.record.updated`
 * `data.record.deleted`
+* `data.record.restored`
 
 
 ---
 
@@ -71,6 +71,7 @@ Realtime event type: a record-change event name the runtime emits
 * `data.record.created`
 * `data.record.updated`
 * `data.record.deleted`
+* `data.record.restored`
 * `data.records.updated`
 * `data.records.deleted`
 
@@ -119,7 +120,7 @@ Realtime event type: a record-change event name the runtime emits
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **type** | `Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted' \| 'data.records.updated' \| 'data.records.deleted'>` | ✅ | Type of event to subscribe to |
+| **type** | `Enum<'data.record.created' \| 'data.record.updated' \| 'data.record.deleted' \| 'data.record.restored' \| 'data.records.updated' \| 'data.records.deleted'>` | ✅ | Type of event to subscribe to |
 | **object** | `string` | optional | Object name to subscribe to |
 | **filters** | `any` | optional | Filter conditions |
 
 
@@ -187,7 +187,10 @@ its master comes back with its master.
 
 - a **unique value has since been taken** by a live row;
 - the **parent was purged** — the row's master-detail parent is no longer in the bin and no longer live;
-- the **object's package was uninstalled** — the object no longer exists in the registry.
+- the **object's package was uninstalled** — the object no longer exists in the registry;
+- the **parent is in the bin** — the row's master-detail parent is not live but is the record of another entry; the
+  refusal names that entry, and restoring it first lets this one through (added 2026-11-07 by the maintainer's ruling
+  on #30237, record [`6710220841`](https://github.com/objectstack-ai/objectstack/issues/30237#issuecomment-6710220841)).
 
 Each refusal is a named code in the ADR-0112 envelope (#30235 names them; #30237 answers them and pins one test per
 refusal), so the Console and an AI caller read the reason, not a generic failure.
@@ -392,7 +395,8 @@ of days and a default; the plan that maps to those days lives in the host that c
   write per operation; bulk delete is a later item with its own cap.
 - **Bin storage** is real storage until purge, counted and shown separately.
 - **Restore is best-effort by design**: the three refusals are permanent for that entry (a taken unique value, a
-  purged parent, an uninstalled package) and the person is told why rather than given a forced write.
+  purged parent, an uninstalled package) and the person is told why rather than given a forced write. The fourth, a
+  parent that is in the bin, is not: it names the parent's entry, and restoring that entry first clears it.
 - **Forward-only**: nothing deleted before the engine slice lands is in the bin.
 - A restore brings a record back without its secret-channel values until the later item holds them.
 
 
@@ -2,7 +2,8 @@
 //
 // [#7809] The engine's MIDDLEWARE DISPATCH VOCABULARY is fixed. Of the
 // destructive lifecycle verbs (`purge` / `transfer` / `restore`) it contains
-// `purge` alone (#30237, the recycle bin), and `purge` never carries an AST.
+// `purge` and `restore` (#30237, the recycle bin), and neither ever carries an
+// AST.
 //
 // ── Why a pin here, in objectql, for a finding filed against plugin-security ──
 //
@@ -19,14 +20,15 @@
 // the same select-only object is scoped (#7665).
 //
 // The finding's own first question was whether those verbs can reach that path
-// at all. They cannot reach the AST path. `transfer` and `restore` reach no
-// path; `purge` reaches the by-id and object-level ones only:
+// at all. They cannot reach the AST path. `transfer` reaches no path; `purge`
+// reaches the by-id and object-level ones only, and `restore` the object-level
+// one only:
 //
-//   1. `OperationContext['operation']` is the 8-member union pinned below.
-//      Of the destructive lifecycle verbs, `purge` alone is a member (#30237),
-//      and every dispatch of it is built without an `ast`: the permanent by-id
-//      delete (`permanent: true`, refused on any delete that is not by id),
-//      `purge(entryId)` and `empty(object)`.
+//   1. `OperationContext['operation']` is the 9-member union pinned below.
+//      Of the destructive lifecycle verbs, `purge` and `restore` are members
+//      (#30237), and every dispatch of either is built without an `ast`: the
+//      permanent by-id delete (`permanent: true`, refused on any delete that is
+//      not by id), `purge(entryId)`, `empty(object)` and `restore(entryId)`.
 //   2. Middleware is invoked from exactly one place — the PRIVATE
 //      `executeWithMiddleware(ctx: OperationContext, …)`. There is no other
 //      caller, and no public seam that hands a middleware a context the engine
@@ -37,8 +39,8 @@
 // So step 3 passing `opCtx.operation` raw is SAFE TODAY — not by accident, but
 // because the vocabulary cannot deliver a verb it fails to handle ON THAT PATH.
 // This file exists so that stays true by assertion rather than by luck. The
-// recycle bin (ADR-0148, #30237) made `purge` dispatchable, and kept it off the
-// AST path, which the AST-set lock below proves; the by-id permanent delete is
+// recycle bin (ADR-0148, #30237) made `purge` and `restore` dispatchable, and
+// kept both off the AST path, which the AST-set lock below proves; the by-id permanent delete is
 // judged by step 2.7, which normalises `purge -> delete`. The day a destructive
 // verb reaches the AST path, this pin goes red and names the two sites that
 // must normalise first.
@@ -127,6 +129,8 @@ const DISPATCHED_OPERATIONS = [
   'aggregate',
   // [#30237] The recycle bin's removal verb: the permanent delete, purge, empty.
   'purge',
+  // [#30237] The recycle bin's restore: one entry written back, object-level.
+  'restore',
 ] as const;
 
 type Declared = (typeof DISPATCHED_OPERATIONS)[number];
@@ -193,8 +197,8 @@ function readDispatchedUnionFromEngineSource(): string[] {
  */
 const DESTRUCTIVE_LIFECYCLE_VERBS = ['purge', 'transfer', 'restore'] as const;
 
-/** [#30237] The one destructive lifecycle verb the engine dispatches, never with an AST. */
-const DISPATCHED_DESTRUCTIVE_VERBS = ['purge'] as const;
+/** [#30237] The destructive lifecycle verbs the engine dispatches, never with an AST. */
+const DISPATCHED_DESTRUCTIVE_VERBS = ['purge', 'restore'] as const;
 
 const NOTE_SCHEMA = {
   name: 'note',
@@ -215,7 +219,8 @@ const ROW = { id: 'n1', title: 'x', owner: 'me' };
 
 /**
  * [#30237] The recycle bin, registered so the probe reaches its three `purge`
- * dispatches: an entry the driver always has, of a `note`.
+ * dispatches and its `restore`: an entry the driver always has, of a `note`
+ * whose row is not live ({@link RESTORED_ID}), so the restore writes it back.
  */
 const BIN_SCHEMA = {
   name: 'sys_recycle_bin',
@@ -225,7 +230,13 @@ const BIN_SCHEMA = {
     record_id: { type: 'text' },
   },
 };
-const ENTRY = { id: 'e1', object_name: 'note', record_id: 'n1' };
+const RESTORED_ID = 'n_binned';
+const ENTRY = {
+  id: 'e1',
+  object_name: 'note',
+  record_id: RESTORED_ID,
+  snapshot: { rows: [{ object: 'note', id: RESTORED_ID, values: { title: 'x', owner: 'me' } }], clearedReferences: [] },
+};
 
 // `any` on the double itself, matching the sibling read-filter test: this is a
 // deliberately PARTIAL driver (the engine only reaches the members listed), and
@@ -239,7 +250,8 @@ function makeDriver(): any {
     supports: {},
     connect: vi.fn().mockResolvedValue(undefined),
     disconnect: vi.fn().mockResolvedValue(undefined),
-    find: vi.fn(async (object: string) => [object === 'sys_recycle_bin' ? { ...ENTRY } : { ...ROW }]),
+    find: vi.fn(async (object: string, ast?: any) =>
+      object === 'sys_recycle_bin' ? [{ ...ENTRY }] : ast?.where?.id === RESTORED_ID ? [] : [{ ...ROW }]),
     findOne: vi.fn(async () => ({ ...ROW })),
     count: vi.fn(async () => 1),
     aggregate: vi.fn(async () => []),
@@ -317,6 +329,8 @@ async function driveEveryPublicMethod(ql: ObjectQL): Promise<void> {
   await ql.delete('note', { where: { id: 'n1' }, permanent: true, context: ctx });
   await ql.purge('e1', { context: ctx });
   await ql.empty('note', { context: ctx });
+  // [#30237] The recycle bin's `restore` dispatch.
+  await ql.restore('e1', { context: ctx });
 }
 
 describe('[#7809] engine middleware dispatch vocabulary', () => {
@@ -329,7 +343,7 @@ describe('[#7809] engine middleware dispatch vocabulary', () => {
     expect(fromSource.slice().sort()).toEqual([...DISPATCHED_OPERATIONS].sort());
   });
 
-  it('the engine union declares `purge` and no other destructive lifecycle verb', () => {
+  it('the engine union declares `purge` and `restore` and no other destructive lifecycle verb', () => {
     const fromSource = readDispatchedUnionFromEngineSource();
     const destructive = fromSource.filter((op) =>
       (DESTRUCTIVE_LIFECYCLE_VERBS as readonly string[]).includes(op),
@@ -340,29 +354,31 @@ describe('[#7809] engine middleware dispatch vocabulary', () => {
     expect(destructive).toEqual([...DISPATCHED_DESTRUCTIVE_VERBS]);
   });
 
-  it('a real engine driven through every public method dispatches exactly the 8', async () => {
+  it('a real engine driven through every public method dispatches exactly the 9', async () => {
     const { ql, seen } = await makeEngine();
     await driveEveryPublicMethod(ql);
 
     const observed = [...new Set(seen.map((s) => s.operation))].sort();
     expect(observed).toEqual([...DISPATCHED_OPERATIONS].sort());
   });
 
-  it('of the destructive lifecycle verbs, only `purge` reaches a middleware, and never with an AST', async () => {
+  it('of the destructive lifecycle verbs, only `purge` and `restore` reach a middleware, and never with an AST', async () => {
     const { ql, seen } = await makeEngine();
     await driveEveryPublicMethod(ql);
 
     expect(seen.length).toBeGreaterThan(0);
     const destructive = seen.filter((s) =>
       (DESTRUCTIVE_LIFECYCLE_VERBS as readonly string[]).includes(s.operation),
     );
-    // [#30237] The permanent delete, `purge` and `empty`, in the order driven.
-    // Only the permanent delete names a live row: step 2.7 judges that row
-    // as a delete (`purge -> delete`); `purge` and `empty` are object-level.
+    // [#30237] The permanent delete, `purge`, `empty` and `restore`, in the
+    // order driven. Only the permanent delete names a live row: step 2.7
+    // judges that row as a delete (`purge -> delete`); `purge`, `empty` and
+    // `restore` are object-level.
     expect(destructive).toEqual([
       { operation: 'purge', hasAst: false, hasId: true },
       { operation: 'purge', hasAst: false, hasId: false },
       { operation: 'purge', hasAst: false, hasId: false },
+      { operation: 'restore', hasAst: false, hasId: false },
     ]);
   });
 
@@ -410,13 +426,16 @@ describe('[#7809] engine middleware dispatch vocabulary', () => {
     expect(astOperations).toEqual(['aggregate', 'count', 'delete', 'find', 'findOne', 'update']);
 
     // The by-id write branches, conversely, must NOT carry an ast; nor does
-    // any `purge` (#30237: the permanent delete, `purge`, `empty`).
+    // any `purge` (#30237: the permanent delete, `purge`, `empty`), nor the
+    // `restore` (#30237). The restore's re-links and its rows' writes are raw
+    // or by-id, so the restore adds no AST-carrying dispatch either.
     expect(seen.filter((s) => !s.hasAst).map((s) => s.operation).sort()).toEqual([
       'delete',
       'insert',
       'purge',
       'purge',
       'purge',
+      'restore',
       'update',
     ]);
   });
 
@@ -410,7 +410,7 @@ function eventMatchedCount(value: unknown): number | undefined {
  */
 export async function publishDataEvent(
   this: Pick<RealtimePublishHost, 'realtimeService' | 'logger' | '_registry'>,
-  action: 'created' | 'updated' | 'deleted',
+  action: 'created' | 'updated' | 'deleted' | 'restored',
   object: string,
   input: {
     recordId: unknown;