@@ -0,0 +1,15 @@
+---
+'@objectstack/spec': patch
+---
+
+docs(spec): the `allowRestore` / `allowPurge` migration texts stop promising the keys back with M2 and name the recycle bin's grants
+
+Clause-②: no
+Metadata-protocol: none
+
+- **Conversion `permission-allow-restore-purge-removed`.** Its `summary`, which `os migrate meta` prints, said the keys "return with the M2 lifecycle initiative". It now says the keys do not return: the `restore` / `purge` operations exist with the recycle bin (ADR-0148), and their grants are `allowRestoreOwnDeleted` and `manageRecycleBin`. Its docblock says the same. The conversion's `id`, `toMajor`, `retiredAfter`, `surface`, transform and fixture are byte-identical.
+- **Semantic entry `permission-restore-purge-bits-retired`.** Its `replacement` names the two grants instead of "the bits return together with the operations they gate". Its `reason` and `acceptanceCriteria` keep the history (the operations did not exist when the keys were retired) and no longer say a `restore` or `purge` request is denied for every principal: stripping the keys still changes no access decision, because nothing reads them.
+- **Step 18's rationale and the four retired-key rows** for `allowRestore` / `allowPurge` (authoring and effective faces) say the same, so the protocol 17 → 18 upgrade guide no longer names M2 as their return path.
+- **Liveness notes.** The two `dead` rows in `liveness/permission.json` and the file's note say the same; their status and evidence are unchanged.
+
+Text only, matching the tombstone prescriptions PR #31438 rewrote: no schema, accepted set, conversion behaviour, tombstone or runtime answer changes.
@@ -98,10 +98,12 @@ objects: {
 
 > **Retired:** the former `allowRestore` / `allowPurge` keys were removed
 > (#12497, ADR-0049) — the `restore` / `purge` operations they claimed to gate
-> do not exist yet, so authoring them granted nothing. Authoring either key is
-> now a loud publish-time error carrying this prescription. The keys return
-> with the M2 lifecycle initiative (feature + RBAC in one batch, #1883);
-> until then a dispatched `restore` / `purge` is denied unconditionally.
+> did not exist then, so authoring them granted nothing. Authoring either key is
+> now a loud publish-time error carrying this prescription. The keys do not
+> return: the operations now exist with the recycle bin (ADR-0148), and their
+> grants are `allowRestoreOwnDeleted` (restore the entries you deleted) and
+> `manageRecycleBin` (restore any entry, purge an entry, and empty an
+> object's entries).
 >
 > **Exactly one value is still accepted, and it is not an author's to write:**
 > the literal `false` that the published 17.x toolchain materialized into every
 
@@ -51,7 +51,7 @@ export const SalesUser = definePermissionSet({
 |------------|-------------|
 | `allowCreate` / `allowRead` / `allowEdit` / `allowDelete` | CRUD on records the user can see |
 | `allowExport` | Bulk data egress — an opt-in grant on top of read, see below |
-| `allowTransfer` | Lifecycle class: change record ownership — enforced today via the `owner_id` guard (#3004). The former `allowRestore` / `allowPurge` keys were retired (#12497, ADR-0049 — the operations they claimed to gate do not exist yet) and return with the M2 lifecycle batch (#1883) |
+| `allowTransfer` | Lifecycle class: change record ownership — enforced today via the `owner_id` guard (#3004). The former `allowRestore` / `allowPurge` keys were retired (#12497, ADR-0049 — the operations they claimed to gate did not exist then) and do not return: the recycle bin's `restore` / `purge` are granted by `allowRestoreOwnDeleted` and `manageRecycleBin` (ADR-0148) |
 | `viewAllRecords` | Read ALL records regardless of ownership (super-user read) |
 | `modifyAllRecords` | Edit and delete ALL records regardless of ownership (super-user write); `allowDelete: false` beside it is refused |
 
 
@@ -113,8 +113,10 @@ export function retiredKeyPrescription(key: string): string | null {
 /**
  * [#22161] The `fix:` line, cut from the retirement's own prescription: its
  * "Delete the key" sentence up to its end, and up to its first ` — ` when the
- * whole sentence would run past 200 characters (both keys' do: the clause after
- * the dash, on what stays denied, is the explanation's). It cuts and never
+ * whole sentence would run past 200 characters (neither key's does: each
+ * prescription spells "Delete the key." as its own sentence, and the sentences
+ * after it, naming the recycle bin's grants `allowRestoreOwnDeleted` /
+ * `manageRecycleBin` (ADR-0148), are the explanation's). It cuts and never
  * rewrites, so the single-wording discipline above holds; a prescription with
  * no such sentence is returned whole rather than replaced by an invented line.
  */
 
@@ -1207,9 +1207,13 @@ export class MetadataPlugin implements Plugin {
      * releases); an artifact authored at the current (or a newer) surface
      * converts nothing and answers to the strict parse, tombstones included.
      * The version key is what keeps this a conversion
-     * rather than an amnesty — the retired keys return with the M2 lifecycle
-     * batch (#1883), and artifacts authored against that surface must never
-     * have them stripped by history.
+     * rather than an amnesty — an artifact authored against the current surface
+     * that still writes a retired key is an authoring error its tombstone must
+     * report (only the #12840 `false` residue is tolerated, at the schema), never
+     * a strip this door performs. (`allowRestore` /
+     * `allowPurge`, the keys this door was built for, stay retired: the recycle
+     * bin's grants are the new keys `allowRestoreOwnDeleted` /
+     * `manageRecycleBin`, ADR-0148 D5.)
      *
      * Notices surface the way the stored-row pass's do — operator-visible and
      * deduped — as one summary line per conversion per artifact rather than
 
@@ -1,6 +1,6 @@
 {
   "type": "permission",
-  "_note": "PermissionSetSchema (the `profile` alias and isProfile flag were removed by ADR-0090 D2). Seeded from docs/audits/2026-06-security-identity-property-liveness.md. CRUD/FLS/RLS enforced via plugin-security. allowTransfer/Restore/Purge are RBAC-mapped in the evaluator (#1883) — deny unless granted; the ObjectQL operations themselves are pending M2. 2026-07-30 security-subset re-verification (#3896 follow-up): every entry call-graph-closed by hand; TWO corrections — rowLevelSecurity.enabled was live-with-wrong-evidence and UNREAD anywhere (a disabled policy kept granting; enforced in rls-compiler the same day), rowLevelSecurity.priority is semantically void under OR-combination → dead+authorWarn. tabPermissions was UNDERSTATED (all four rank values read, not just 'hidden').",
+  "_note": "PermissionSetSchema (the `profile` alias and isProfile flag were removed by ADR-0090 D2). Seeded from docs/audits/2026-06-security-identity-property-liveness.md. CRUD/FLS/RLS enforced via plugin-security. allowTransfer is RBAC-mapped in the evaluator (#1883) — deny unless granted; the transfer ObjectQL operation itself is pending M2 (see its row). 2026-07-30 security-subset re-verification (#3896 follow-up): every entry call-graph-closed by hand; TWO corrections — rowLevelSecurity.enabled was live-with-wrong-evidence and UNREAD anywhere (a disabled policy kept granting; enforced in rls-compiler the same day), rowLevelSecurity.priority is semantically void under OR-combination → dead+authorWarn. tabPermissions was UNDERSTATED (all four rank values read, not just 'hidden'). 2026-11-08 (#31508): `allowRestore`/`allowPurge` are retiredKey tombstones (#12497) and do not return; `restore`/`purge` exist with the recycle bin (ADR-0148) and the evaluator reads the new keys `allowRestoreOwnDeleted` / `manageRecycleBin` (#30237).",
   "props": {
     "name": {
       "status": "live",
@@ -91,13 +91,13 @@
           "status": "dead",
           "verifiedAt": "2026-08-26",
           "evidence": "packages/spec/src/security/permission.zod.ts (retiredKey tombstone — authored values REJECT with the prescription; z.input types the key never)",
-          "note": "REMOVED 2026-08-26 (#12497, ADR-0049 enforce-or-remove — maintainer ruling accepting #1883's recommendation B) — the `restore` ObjectQL operation the bit claimed to gate has never existed (no destructive lifecycle verb in the engine's dispatch vocabulary, #8106 pin), so granting it delivered nothing. The former 'live' verdict cited only the evaluator's pre-mapping row, which retired in the same batch: a mapping onto an unwritable bit is a claim about a surface that rejects authoring. A dispatched `restore` stays denied fail-closed via DESTRUCTIVE_OPERATIONS. Tombstoned at the schema and stripped from sources by the protocol-18 conversion `permission-allow-restore-purge-removed`. The entry stays because retiredKey keeps the key in the walked shape (the rls.priority precedent); the key RETURNS with the M2 lifecycle initiative (#1883, feature + RBAC in one batch) — drop the tombstone (and this entry) only if M2 respells it."
+          "note": "REMOVED 2026-08-26 (#12497, ADR-0049 enforce-or-remove — maintainer ruling accepting #1883's recommendation B) — the `restore` ObjectQL operation the bit claimed to gate had never existed (no destructive lifecycle verb in the engine's dispatch vocabulary, #8106 pin), so granting it delivered nothing. The former 'live' verdict cited only the evaluator's pre-mapping row, which retired in the same batch: a mapping onto an unwritable bit is a claim about a surface that rejects authoring. A dispatched `restore` then stayed denied fail-closed via DESTRUCTIVE_OPERATIONS. Tombstoned at the schema and stripped from sources by the protocol-18 conversion `permission-allow-restore-purge-removed`. The entry stays because retiredKey keeps the key in the walked shape (the rls.priority precedent); the key does NOT return: the `restore` operation now exists with the recycle bin (ADR-0148), and its grants are the NEW keys `allowRestoreOwnDeleted` / `manageRecycleBin` (ADR-0148 D5, their own rows below), never this tombstoned spelling."
         },
         "allowPurge": {
           "status": "dead",
           "verifiedAt": "2026-08-26",
           "evidence": "packages/spec/src/security/permission.zod.ts (retiredKey tombstone — authored values REJECT with the prescription; z.input types the key never)",
-          "note": "REMOVED 2026-08-26 (#12497, ADR-0049 enforce-or-remove — maintainer ruling accepting #1883's recommendation B) — the `purge` ObjectQL operation the bit claimed to gate has never existed (no destructive lifecycle verb in the engine's dispatch vocabulary, #8106 pin), so granting it delivered nothing; worse, an admin who set `allowPurge: false` believed a lock on GDPR hard-deletion existed. The former 'live' verdict cited only the evaluator's pre-mapping row, which retired in the same batch. A dispatched `purge` stays denied fail-closed via DESTRUCTIVE_OPERATIONS. Tombstoned at the schema and stripped from sources by the protocol-18 conversion `permission-allow-restore-purge-removed`. The entry stays because retiredKey keeps the key in the walked shape (the rls.priority precedent); the key RETURNS with the M2 lifecycle initiative (#1883, feature + RBAC in one batch) — drop the tombstone (and this entry) only if M2 respells it."
+          "note": "REMOVED 2026-08-26 (#12497, ADR-0049 enforce-or-remove — maintainer ruling accepting #1883's recommendation B) — the `purge` ObjectQL operation the bit claimed to gate had never existed (no destructive lifecycle verb in the engine's dispatch vocabulary, #8106 pin), so granting it delivered nothing; worse, an admin who set `allowPurge: false` believed a lock on GDPR hard-deletion existed. The former 'live' verdict cited only the evaluator's pre-mapping row, which retired in the same batch. A dispatched `purge` then stayed denied fail-closed via DESTRUCTIVE_OPERATIONS. Tombstoned at the schema and stripped from sources by the protocol-18 conversion `permission-allow-restore-purge-removed`. The entry stays because retiredKey keeps the key in the walked shape (the rls.priority precedent); the key does NOT return: the `purge` operation now exists with the recycle bin (ADR-0148), and its grant is the NEW key `manageRecycleBin` (ADR-0148 D5, its own row below), never this tombstoned spelling."
         },
         "allowRestoreOwnDeleted": {
           "status": "live",
 
@@ -19,17 +19,18 @@ import { isDict, stripKeys } from '../shared.js';
  * (protocol 18, #12497 — ADR-0049 enforce-or-remove, maintainer ruling
  * 2026-08-26 accepting #1883's recommendation B).
  *
- * The `restore` / `purge` ObjectQL operations the bits claimed to gate have
- * never existed: no destructive lifecycle verb is in the engine's dispatch
- * vocabulary (pinned by objectql's
- * `engine-middleware-operation-vocabulary.test.ts`, #8106). Authoring the bits
- * therefore granted nothing — an advertised switch with nothing behind it, on
- * the most destructive operations (undelete, GDPR hard-delete). A pure
- * lossless delete: a dispatched `restore`/`purge` was denied before (deny
- * unless a bit nothing could ever exercise was granted) and stays denied after
- * (the evaluator's `DESTRUCTIVE_OPERATIONS` fail-closed backstop — the
- * pre-mapping rows retired in the same batch, #12497). The keys RETURN with
- * the M2 lifecycle initiative (feature + RBAC in one batch); #1883 stays open.
+ * The `restore` / `purge` ObjectQL operations the bits claimed to gate did
+ * not exist when they were retired: no destructive lifecycle verb was then in
+ * the engine's dispatch vocabulary (#8106). Authoring the bits therefore
+ * granted nothing — an advertised switch with nothing behind it, on the most
+ * destructive operations (undelete, GDPR hard-delete). A pure lossless delete:
+ * a dispatched `restore`/`purge` was denied before (deny unless a bit nothing
+ * could ever exercise was granted) and stayed denied after (the evaluator's
+ * `DESTRUCTIVE_OPERATIONS` fail-closed backstop — the pre-mapping rows retired
+ * in the same batch, #12497). The keys do NOT return: the operations now exist
+ * with the recycle bin (ADR-0148), and their grants are NEW spellings,
+ * `allowRestoreOwnDeleted` and `manageRecycleBin` (ADR-0148 D5), never these
+ * tombstoned ones.
  *
  * `allowTransfer` — the third lifecycle bit — is ENFORCED (#3004) and stays.
  *
@@ -52,10 +53,9 @@ const permissionAllowRestorePurgeRemoved: MetadataConversion = {
   surface: 'permission.objects.<object>.allowRestore / permission.objects.<object>.allowPurge',
   summary:
     "object-permission keys 'allowRestore' and 'allowPurge' removed (ADR-0049 — the "
-    + '`restore`/`purge` operations they claimed to gate have never existed, so granting the '
-    + 'bits delivered nothing; dispatched destructive lifecycle verbs stay denied fail-closed. '
-    + 'The keys return with the M2 lifecycle initiative, which builds undelete and purge together '
-    + 'with the permission bits that gate them)',
+    + '`restore`/`purge` operations they claimed to gate did not exist then, so granting the '
+    + 'bits delivered nothing. The keys do not return: the operations now exist with the recycle '
+    + 'bin (ADR-0148), and their grants are spelled `allowRestoreOwnDeleted` and `manageRecycleBin`)',
   apply(stack, emit) {
     return mapCollection(stack, 'permissions', (ps, path) => {
       const objects = (ps as { objects?: unknown }).objects;
 
@@ -3,7 +3,8 @@
 // #12497 — the RESPONSE-side face of `security/ObjectPermission:allowPurge`
 // (see that entry for the full rationale: ADR-0049 enforce-or-remove,
 // maintainer ruling 2026-08-26 accepting #1883's recommendation B; the key
-// returns with the M2 lifecycle initiative). `EffectiveObjectPermissionSchema`
+// stays retired — the recycle bin's grants are new keys, ADR-0148 D5).
+// `EffectiveObjectPermissionSchema`
 // extends the same closed base shape (`.extend({ apiOperations }).strip()`,
 // both faces behind the #12840 residue stage since 2026-08-28) — the clone
 // shares the authoring shape's per-property schema instances, so the
 
@@ -3,7 +3,8 @@
 // #12497 — the RESPONSE-side face of `security/ObjectPermission:allowRestore`
 // (see that entry for the full rationale: ADR-0049 enforce-or-remove,
 // maintainer ruling 2026-08-26 accepting #1883's recommendation B; the key
-// returns with the M2 lifecycle initiative). `EffectiveObjectPermissionSchema`
+// stays retired — the recycle bin's grants are new keys, ADR-0148 D5).
+// `EffectiveObjectPermissionSchema`
 // extends the same closed base shape (`.extend({ apiOperations }).strip()`,
 // both faces behind the #12840 residue stage since 2026-08-28) — the clone
 // shares the authoring shape's per-property schema instances, so the
 
@@ -2,19 +2,19 @@
 
 // #12497 — ADR-0049 enforce-or-remove (maintainer ruling 2026-08-26, decision-
 // inbox batch 5, accepting #1883's recommendation B). `allowPurge` claimed to
-// gate a `purge` (hard-delete / GDPR erase) ObjectQL operation that has never
-// existed: no destructive lifecycle verb is in the engine's dispatch
-// vocabulary (pinned by objectql's
-// `engine-middleware-operation-vocabulary.test.ts`, #8106). This was ADR-0049's
+// gate a `purge` (hard-delete / GDPR erase) ObjectQL operation that did not
+// exist then: no destructive lifecycle verb was in the engine's dispatch
+// vocabulary (#8106). This was ADR-0049's
 // worst false-compliance shape — an admin who set `allowPurge: false` believed
 // a lock on permanent deletion existed, when the operation itself did not.
 // The permission evaluator's pre-mapping row (`OPERATION_TO_PERMISSION`
 // purge→allowPurge) retired in the same batch: with the bit unwritable, a
 // mapping onto it was a claim about a surface that rejects authoring. A
-// dispatched `purge` stays denied fail-closed via the evaluator's
-// `DESTRUCTIVE_OPERATIONS` backstop — there is no ungated window in either
-// direction. THE KEY RETURNS with the M2 lifecycle initiative (feature + RBAC
-// in one batch, maintainer 2026-08-03); anchor card #1883 stays open.
+// dispatched `purge` then stayed denied fail-closed via the evaluator's
+// `DESTRUCTIVE_OPERATIONS` backstop — there was no ungated window in either
+// direction. THE KEY DOES NOT RETURN: the `purge` operation now exists with
+// the recycle bin (ADR-0148), and its grant is the NEW key `manageRecycleBin`
+// (ADR-0148 D5).
 //
 // Registered under 18, not 17: v17.0.0 was cut before this landed, so the
 // removal ships on the 17.x line (launch-window convention: accept-set