@@ -0,0 +1,27 @@
+---
+'@objectstack/spec': patch
+'@objectstack/plugin-security': patch
+'@objectstack/plugin-sharing': patch
+'@objectstack/core': patch
+'@objectstack/objectql': patch
+'@objectstack/verify': patch
+'@objectstack/lint': patch
+---
+
+feat(security): the recycle bin's two grants are read: `restore` asks `allowRestoreOwnDeleted` and `purge` asks `manageRecycleBin`, and a member restores only the entries they deleted
+
+Clause-②: yes (widening)
+Metadata-protocol: none
+Skills-docs: follow-up #30847
+
+Until now every `restore` and `purge` dispatch was refused for every caller but the system, whatever the caller's permission sets granted. The two recycle-bin keys on an object permission are now read (ADR-0148 D5):
+
+- **`allowRestoreOwnDeleted`** answers `restore`. It restores only the entries the caller deleted: restoring an entry someone else deleted is refused `403 PERMISSION_DENIED` unless the caller holds `manageRecycleBin` on the object. When the platform cannot tell what the caller holds, that restore is refused.
+- **`manageRecycleBin`** answers `purge`: purging one entry, emptying an object's entries, and the permanent delete (`delete(…, { permanent: true })`). It also restores any entry, not only your own.
+- **How the keys fold**: each is bounded by read; `modifyAllRecords` implies both; `manageRecycleBin` implies `allowRestoreOwnDeleted`; `allowDelete` implies neither. `objectPermissionGrants` (`@objectstack/spec/security`) answers both keys this way, and `/me/permissions` reports them.
+- **The tenant wall on the bin**: a caller the organization wall denies (for example, signed in with no active organization on a multi-organization deployment) now sees no entry: `restore` answers `null`, `purge` answers `false` and `empty` answers `0`. Before, such a caller's `purge` and `empty` were not scoped to any organization. The removal is scoped by the verdict the security layer recorded on the dispatch when it recorded one.
+- **Record sharing on the permanent delete**: the sharing write gate judges `purge` as the delete it is, so the permanent delete of a record by id is refused (`403 FORBIDDEN`) unless the caller may delete that record (ownership, write depth or Modify All Data; an edit share is not enough), and a bulk permanent delete is scoped to the records the caller may delete. `security/explain` reports a purge against the same delete gate.
+- **The retired `allowRestore` / `allowPurge` keys stay refused**, but their prescription (and that of the bare `restore` / `purge` keys) no longer says the operations do not exist: it says to delete the key and names the grants that gate the operations now, `allowRestoreOwnDeleted` and `manageRecycleBin`. The residue lint's rule explanation says the same.
+- `@objectstack/verify`: a write observer now also sees `purge` and `restore`.
+
+Grant `allowRestoreOwnDeleted` (with read) to the people who should take back what they deleted, and `manageRecycleBin` to the people who administer the bin. Nothing changes for a caller who holds neither.
@@ -75,7 +75,7 @@ deployment suppresses it. A deployment-wide data superuser needs
 </Callout>
 
 <Callout type="warn">
-**Lifecycle operations are partly pending:** the dedicated `transfer` / `restore` / `purge` ObjectQL operations do not exist yet (roadmap M2). `allowTransfer` is **already enforced today** through the ordinary `insert` / `update` door — `owner_id` is system-managed, so planting a record under another user or reassigning / disowning one is denied unless the caller holds `allowTransfer` (or `modifyAllRecords`, which implies it) (#3004), and the future `transfer` op is pre-mapped to the same bit. The former `allowRestore` / `allowPurge` flags were **retired** (#12497, ADR-0049 — they claimed to gate operations that do not exist, so authoring them granted nothing); a dispatched `restore` / `purge` is denied unconditionally by the fail-closed destructive-operation backstop, and the flags return with the M2 lifecycle batch (#1883).
+**Lifecycle operations:** `allowTransfer` is enforced through the ordinary `insert` / `update` door — `owner_id` is system-managed, so planting a record under another user or reassigning / disowning one is denied unless the caller holds `allowTransfer` (or `modifyAllRecords`, which implies it) (#3004); a dedicated `transfer` ObjectQL operation does not exist yet (roadmap M2), and is pre-mapped to the same bit. The recycle bin's `restore` and `purge` operations exist (ADR-0148) and are gated by their own keys (#30237): `restore` asks `allowRestoreOwnDeleted` and restores only the entries the caller deleted, while `purge` — purging an entry, emptying an object's entries, and the permanent delete — asks `manageRecycleBin`, which also restores anyone's entry. Each key is bounded by `allowRead`; `modifyAllRecords` implies both; `allowDelete` implies neither. The former `allowRestore` / `allowPurge` flags stay **retired** (#12497, ADR-0049): they grant nothing, and the schema refuses them.
 </Callout>
 
 ---
 
@@ -150,6 +150,8 @@ bugs — it is the protection or the side effect that silently does not happen.
 | 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `recordReferenceCheckElevation` |
 | 29b | A traversing validation rule's related read skips the **caller's bounds** | objectql | Get: no row bound from the caller's own read on a related object no organization wall scopes, no read door on a header the rule reads through a `master_detail` field, and a related read even with no organization under a walled posture (a `tenantId` on the context still scopes it). Every caller that is not system is held to all three: a header its read door does not return is unavailable to the rule exactly as a header that exists nowhere is, whatever it holds, and a header it can read is judged on its stored values. A plain `lookup` to an object an organization wall scopes asks no read door, system caller or not | `resolveOneHopRelated` |
 | 29c | A detail write's master-detail header read asks **no read door** | objectql | Get: the write binds the header a parent-scoped `requiredWhen` / `readonlyWhen` reads as `parent` from the header's stored row whoever can read it, as before. Every caller that is not system meets its own read door first: a header that read does not return answers as a header that exists nowhere — an unbound `parent`, and `reference_not_found` on the reference check (which a system caller's write skips, a flow run's excepted) | `masterDetailHeadersCallerReads` |
+| 29d | The recycle bin's tenant wall does not apply: `restore`, `purge` and `empty` read and remove **every organization's** entries | objectql | Get: the bin's own doors reach any entry, as the system reaches every wall. Every caller that is not system is held to the Layer-0 verdict: one the wall denies (a signed-in caller with no active organization under a walled posture) sees no entry, so `restore` answers `null`, `purge` `false` and `empty` `0`, and the removal is scoped by the verdict the security layer recorded on the dispatch when it recorded one (#30237) | `recycleBinWallDenies` |
+| 29e | A restore of an entry someone else deleted asks **no recycle-bin grant** | objectql | Get: the system restores any entry. Every caller that is not system restores only the entries whose `deleted_by` is its own `userId` unless its effective permissions grant `manageRecycleBin` on the entry's object; otherwise `403 PERMISSION_DENIED`, and the same refusal when no permission resolver is registered or it throws (#30237, ADR-0148 D5) | `assertCallerMayRestoreEntry` |
 | 30 | **Bulk data event `organizationId` OMITTED** — the batch is published "not asserted" | plugin-security | Get: nothing — the `data.records.*` event still publishes. Lose: the per-organization attribution: this exit is taken before the security middleware composes any tenant wall, so it records no Layer 0 verdict on the operation (`OperationContext.tenantLayer0Verdict`, #15813), and the engine's bulk producer — which reads that recorded verdict and nothing else — omits the key rather than filling it from the caller's `tenantId`; a tenant-scoped consumer then does not deliver the event inside an organization wall (#15225) | `registerAuthzMiddleware` |
 | 30b | **The import doors admit a control opt-out** — `runAutomations: false` and `treatAsHistorical: true` on `POST /data/:object/import` and `/import/jobs` | rest | Get: an import whose rows are written with `skipAutomations` (no metadata-bound hook, no record-change trigger: an app's approvals and record freezes among them) or with `skipStateMachine` and `preserveAudit`. Every other caller, every signed-in user and administrator included, is refused `403 PERMISSION_DENIED` before the body is parsed, so nothing is written and no job is created. Inbound HTTP never carries the flag, so this is an in-process caller's door. Note: the flag still suppresses none of those controls by itself (see below); it only admits the opt-outs that do | `importControlOptOutRefusal` |
 | 30c | **The import undo keeps the control skips** — `POST /data/import/jobs/:jobId/undo` | rest | Get: an undo whose deletes and restores are written with `skipAutomations` and `skipStateMachine`, so no metadata-bound hook, record-change trigger or `state_machine` rule refuses a reversal. Every other caller, every signed-in user and administrator included, undoes under those controls: a reversal one of them refuses is reported per row in the undo answer's `failures` and kept in the job's undo log, and the job is stamped reverted only once every row is. A historical job's `preserveAudit` belongs to the job, not the caller, and rides every undo. Inbound HTTP never carries the flag, so this is an in-process caller's door | `importUndoWriteContext` |
@@ -551,6 +553,8 @@ and CI refuses one that differs from what the tree produces.
 | `packages/objectql/src/engine.ts#isSystem` | 1 | 64 |
 | `packages/objectql/src/engine.ts#update` | 4 | 19, 20 |
 | `packages/objectql/src/internal-field-evaluation-guard.ts#rejectInternalFieldEvaluation` | 1 | 18e |
+| `packages/objectql/src/recycle-bin/purge.ts#recycleBinWallDenies` | 1 | 29d |
+| `packages/objectql/src/recycle-bin/restore.ts#assertCallerMayRestoreEntry` | 1 | 29e |
 | `packages/objectql/src/stored-metadata-type-read-gate.ts#storedMetadataTypeReadFilter` | 1 | 18d |
 | `packages/observability/src/perf-timing.ts#isPerfDisclosurePrincipal` | 1 | 13 |
 | `packages/plugins/organizations/src/organizations-plugin.ts#start` | 1 | 62 |
 
@@ -101,15 +101,17 @@ Beyond the four CRUD flags, the schema also exposes lifecycle and super-user gra
 | --- | --- |
 | `allowCreate` / `allowRead` / `allowEdit` / `allowDelete` | Standard CRUD |
 | `allowTransfer` | Change record ownership (assign/reassign/disown `owner_id`) — *enforced now via the insert/update `owner_id` guard (#3004); the dedicated `transfer` op is still M2* |
+| `allowRestoreOwnDeleted` | Recycle bin: restore the entries of this object the caller deleted (`restore`). Bounded by read; implied by `manageRecycleBin` and `modifyAllRecords`, not by `allowDelete` |
+| `manageRecycleBin` | Recycle bin administration: restore any entry, and `purge` (purging an entry, emptying the object's entries, the permanent delete). Bounded by read; implied by `modifyAllRecords` |
 | `viewAllRecords` | Read every record, bypassing sharing & ownership |
 | `modifyAllRecords` | Write every record, bypassing sharing & ownership |
 
 > The former `allowRestore` / `allowPurge` flags were **retired** (#12497,
-> ADR-0049): the `restore` / `purge` operations they claimed to gate have never
-> existed, so authoring them granted nothing — the schema now refuses them with
-> a migration prescription. A dispatched `restore` / `purge` is denied
-> unconditionally (fail-closed destructive-operation backstop). The flags
-> return with the M2 lifecycle initiative (feature + RBAC in one batch, #1883).
+> ADR-0049): when they were retired the `restore` / `purge` operations did not
+> exist, so authoring them granted nothing — the schema refuses them with a
+> migration prescription. The operations now exist with the recycle bin
+> (ADR-0148), and their grants are spelled `allowRestoreOwnDeleted` and
+> `manageRecycleBin` (#30237).
 >
 > One exception, by ruling: the boolean literal `false` — the default the
 > published 17.x toolchain emitted into every built artifact — parses as inert