Jaggob · Sep 29, 2026 · Sep 26, 2026 · Sep 26, 2026 · Sep 26, 2026 · Sep 26, 2026
diff --git a/README.md b/README.md
@@ -11,8 +11,8 @@ This plugin lets you surface pads from an Etherpad instance inside Nextcloud and
 - Public folder/file share support for `.pad`
 - Periodic sync from Etherpad into `.pad` snapshots
 - Pad text is searchable through Nextcloud's full-text search, where that is set up
-- Trash deletes on Etherpad (with deferred retry when Etherpad is temporarily unavailable)
-- Restore recreates pads from `.pad` snapshot data
+- A pad lives as long as its file: the trash keeps it, and it goes once the file is deleted for good
+- A `.pad` file whose pad is gone gets a new one from its snapshot: at once when it comes back from the trash, and offered when it is opened
 
 ## Screenshots
 
@@ -100,7 +100,7 @@ and configure:
 - Etherpad API key (OAuth is not required; Etherpad API key auth is used)
 - Copy content to `.pad` file interval
 - Which pad types users may create (see below)
-- Delete-on-trash policy
+- Whether a pad is deleted with its file deleted for good
 - External public pad policy
 
 Two settings control which pad types the app offers, both enabled by default:
@@ -235,9 +235,10 @@ existing name asks for confirmation because the previous file is gone for good.
 
 ### Trash/Restore
 
-- When a `.pad` file is moved to the Nextcloud trash, the linked Etherpad pad is deleted.
-- If Etherpad is temporarily unavailable, delete is deferred and retried.
-- When the `.pad` file is restored from the Nextcloud trash, a new pad is recreated and the snapshot from the `.pad` file is replayed.
+- A `.pad` file moved to the Nextcloud trash keeps its pad; restored, it has the same pad back, with its history.
+- Once the file is deleted for good - from the trash, past it, or with the account that owned it - a background job deletes the pad within minutes, and tries again while Etherpad is unavailable.
+- A file restored without a pad - one Etherpad lost, or one trashed under 1.1.0-beta.1 - gets a new pad from the snapshot in the file.
+- What each way of deleting a file does to its pad: [docs/deleting-pads.md](docs/deleting-pads.md).
 
 ## Troubleshooting
 
@@ -293,6 +294,7 @@ existing name asks for confirmation because the previous file is gone for good.
 ## Documentation
 
 - Architecture: [docs/architecture.md](docs/architecture.md)
+- When a pad is deleted: [docs/deleting-pads.md](docs/deleting-pads.md)
 - API routes: [docs/api-reference.md](docs/api-reference.md)
 - Etherpad integration details: [docs/etherpad-integration.md](docs/etherpad-integration.md)
 - `.pad` format: [docs/pad-format.md](docs/pad-format.md)

diff --git a/appinfo/info.xml b/appinfo/info.xml
@@ -18,6 +18,9 @@
 		<php min-version="8.1" max-version="8.5"/>
 		<nextcloud min-version="31.0.9" max-version="34"/>
 	</dependencies>
+	<background-jobs>
+		<job>OCA\EtherpadNextcloud\BackgroundJob\GoneFileSweepJob</job>
+	</background-jobs>
 	<repair-steps>
 		<post-migration>
 			<step>OCA\EtherpadNextcloud\Migration\RegisterMimeType</step>

diff --git a/appinfo/routes.php b/appinfo/routes.php
@@ -23,15 +23,12 @@
 	['name' => 'padSession#initializeById', 'url' => '/api/v1/pads/initialize-by-id/{fileId}', 'verb' => 'POST'],
 	['name' => 'padLifecycle#syncStatusById', 'url' => '/api/v1/pads/sync-status/{fileId}', 'verb' => 'GET'],
 	['name' => 'padLifecycle#syncById', 'url' => '/api/v1/pads/sync/{fileId}', 'verb' => 'POST'],
-	['name' => 'padLifecycle#trash', 'url' => '/api/v1/pads/trash', 'verb' => 'POST'],
-	['name' => 'padLifecycle#restore', 'url' => '/api/v1/pads/restore', 'verb' => 'POST'],
 	['name' => 'padLifecycle#recoverByFileId', 'url' => '/api/v1/pads/recover-from-snapshot/{fileId}', 'verb' => 'POST'],
 	['name' => 'padLifecycle#findOriginalByFileId', 'url' => '/api/v1/pads/find-original/{fileId}', 'verb' => 'GET'],
 	['name' => 'admin#saveSettings', 'url' => '/api/v1/admin/settings', 'verb' => 'POST'],
 	['name' => 'admin#healthCheck', 'url' => '/api/v1/admin/health', 'verb' => 'POST'],
 	['name' => 'admin#consistencyCheck', 'url' => '/api/v1/admin/consistency-check', 'verb' => 'POST'],
 	['name' => 'admin#settlePending', 'url' => '/api/v1/admin/settle-pending', 'verb' => 'POST'],
-	['name' => 'admin#setTestFault', 'url' => '/api/v1/admin/test-fault', 'verb' => 'POST'],
 	['name' => 'admin#listPadTemplates', 'url' => '/api/v1/admin/templates', 'verb' => 'GET'],
 	['name' => 'admin#uploadPadTemplate', 'url' => '/api/v1/admin/templates', 'verb' => 'POST'],
 	['name' => 'admin#deletePadTemplate', 'url' => '/api/v1/admin/templates/delete', 'verb' => 'POST'],

diff --git a/docs/api-reference.md b/docs/api-reference.md
diff --git a/docs/architecture.md b/docs/architecture.md
diff --git a/docs/deleting-pads.md b/docs/deleting-pads.md
@@ -0,0 +1,121 @@
+# When a Pad Is Deleted
+
+SPDX-License-Identifier: AGPL-3.0-or-later
+
+A pad lives in Etherpad; its `.pad` file lives in Nextcloud. The pad lives
+as long as the file: the trash keeps it, and it is deleted once the file is
+deleted for good. The technical side is in [architecture.md](architecture.md),
+under "Trash/Restore" and "Files gone for good".
+
+What counts is the file, not its name: a `.pad` file renamed to something
+else keeps its pad, and the pad goes once the file is deleted for good.
+
+This applies to pads this Nextcloud manages, with the admin setting
+`delete_pad_with_file` on - the default; `delete_on_trash` before,
+whose value it takes over. A `.pad` file that links a pad on another
+Etherpad server never deletes that pad.
+
+## Moved to the trash
+
+A file goes to the trash when it is deleted through Files, a desktop or
+mobile client, or a WebDAV `DELETE`, in a user's own folders as in a team
+folder. So does a file replaced by moving another file onto it (WebDAV
+`MOVE` with `Overwrite: T`), and every file in a folder moved to the trash.
+
+The pad stays as it is, and nothing is written into the file.
+
+- **A protected pad** loses its sessions: whoever still has it open can
+  write no more from their next change on, and nobody opens it until the
+  file is back. On a folder with many protected pads, what does not fit in
+  a few seconds is left to expire, within six hours.
+- **A public pad** stays reachable by its link, and can be written into.
+  The file in the trash is not synced, so what is written there is in the
+  pad, not in the file's snapshot; a restore brings it back with the pad.
+- **A `.pad` file that names another user's group** - a legacy Ownpad file
+  can - takes no sessions along: only a group that holds its pad alone
+  loses them.
+
+## Restored from the trash
+
+- **A `.pad` file, or a folder with `.pad` files in it:** the file has its
+  pad back as it was, with its history and anything written into it
+  meanwhile. Opening it makes a new session for a protected pad.
+- **A `.pad` file whose pad Etherpad has lost meanwhile:** a new pad is made
+  from the snapshot in the file, at once. It holds the content, not the
+  pad's history. If Etherpad does not answer during the restore, the file
+  is restored all the same, and its next open offers the new pad. A folder
+  restored does not ask for each of its files: those whose pad is lost offer
+  a new one when they are opened.
+- **A `.pad` file a share recipient deleted:** Nextcloud puts the file
+  itself into its owner's trash and a copy into the recipient's. The
+  owner's restore brings the pad back. The recipient's copy, restored, is a
+  copy: it holds the file's content as of its last sync - what was written
+  into the pad after that lives only in the pad, with the original - and
+  its open offers a new pad from it, while the pad stays with the file in
+  the owner's trash until that goes.
+- **A `.pad` file trashed under an earlier version,** whose trash deleted
+  the pad (1.1.0-beta.1 and before): a new pad is made from the snapshot in
+  the file, at once. A
+  copy of another `.pad` file that was never opened is left as it is: its
+  pad was not deleted, and opening it offers that pad or a new one.
+
+## Deleted for good
+
+| How the file is deleted for good | When the pad is deleted |
+|---|---|
+| From the trash: the trash emptied, the item deleted there, expired, or `occ trashbin:cleanup`. A user's trash or a team folder's. | By a background job, within minutes; for a folder's files too. |
+| Past the trash: a WebDAV `DELETE` with `X-NC-Skip-Trashbin: true`, the trash app switched off for the user, or a move to the trash that fails or that another app keeps from the trash. | By a background job, within minutes; for a folder's files too. |
+| With the account: the account deleted. | The pads of the account's own files - those in its home and its trash, shared ones included - by a background job, within minutes. Files in team folders, and files the account put into folders others shared with it, are not the account's: they stay, and so do their pads. The account's own Etherpad sessions go as the delete starts, as on a logout. |
+
+"A background job" runs on every tick of a five-minute system cron; with
+AJAX or webcron, only as often as those run. It deletes the pad of a file
+deleted for good once five minutes have passed, so the pad goes within
+about ten minutes; the admin page's "Check pending pads" does it at once. When Etherpad does not answer, the job deletes the pad once
+it does; until then the admin page counts it as a pending delete.
+
+On Nextcloud 34, Nextcloud reports the files inside a folder deleted for
+good under the wrong ids - and a trash emptied as a whole, from the Files
+app or with `occ trashbin:cleanup`, is deleted as one folder. The fix
+(nextcloud/server#63998) is in 35.0.1; its backport to 34
+(nextcloud/server#64497) is planned for 34.0.5 and not merged yet. The app
+cannot tell which files they were, so the pads of the `.pad` files inside
+such a folder, or in a trash emptied as a whole, stay, and the consistency
+check lists them. A `.pad` file deleted on its own - past the trash, or
+from the trash by itself or when it expires - and an account deleted, are
+not affected.
+
+## Gone without being deleted in Nextcloud
+
+A file can also leave without anyone deleting it in Nextcloud. Its pad
+stays:
+
+- files removed outside Nextcloud - on an external storage, or in the data
+  directory - that a scan then drops;
+- a team folder deleted as a whole by an admin, and an external storage
+  removed. Files that were in the team folder's trash then may go as from
+  a trash, and take their pads along: on a team folder kept on Nextcloud's
+  own storage, not on one with a storage of its own.
+
+A pad that stays keeps its content in Etherpad, and nobody reaches it
+through Nextcloud any more; a public pad stays reachable by its link. The
+consistency check on the admin page counts these pads and lists up to 25 of
+them by pad id (`vanished_file_count`). The app keeps their rows: deleting
+such a pad in Etherpad does not take it off the list.
+
+## When Etherpad has lost a pad
+
+If Etherpad no longer has a pad - deleted there by hand, or lost with its
+database - opening its file says so. Whoever may edit the file can make a
+new pad from the content saved in it; from then on the file opens the new
+pad. The same happens for a public pad that someone visited by its link
+after it was lost, which Etherpad makes anew, empty; an editor still open on
+the file does not write that empty pad into it as it closes, so the content
+stays for the new pad. A copied `.pad` file,
+which has no pad of its own, offers the same. A file restored from the
+trash does not ask: it gets its new pad on its own.
+
+## With `delete_pad_with_file` off
+
+The app deletes no pad at all: the pads of files deleted for good stay, and
+the admin page counts them as pending deletes. Switched back on, the job
+deletes them.
diff --git a/docs/etherpad-integration.md b/docs/etherpad-integration.md
@@ -54,20 +54,18 @@ that file destroy their group, their pad and their sessions. A group that
 holds only the pad being deleted, or nothing at all, has nothing else to
 lose.
 
-It answers true when it removed something, the pad or the empty group a
-protected pad left behind, and false when Etherpad says there was nothing
-left: no such pad, or no such group. A caller that has just heard the pad
-is gone says so (`knownAbsent`); a public pad then costs no call, a
-protected one is still asked about its group.
+It is done when it removed something, the pad or the empty group a
+protected pad left behind, and when Etherpad says there was nothing left:
+no such pad, or no such group. A caller that has just heard the pad is
+gone says so (`knownAbsent`); a public pad then costs no call, a protected
+one is still asked about its group.
 
 A group Etherpad cannot list is given up by default: the pad goes alone,
 the half that was always safe, and the empty group stays. A caller that
 keeps its row and tries again says so (`retried`) and gets the failed read
-instead, with nothing removed: the trash, which then owes the deletion,
-and the sweep for a file gone for good while the deletion has been owed
-for less than a day, counted from the trash. One that cannot try again -
-the sweep once it has taken a trashed file's row, the clean-up after a
-replacement or a released row - takes the default.
+instead, with nothing removed: the sweep of files gone for good, which
+tries again an hour later. One that cannot try again - the clean-up after
+a replacement - takes the default.
 
 The shape rule itself lives in `Util\PadId` and is the same one that
 classifies a binding as protected. It used to be stricter here, so a pad
@@ -159,9 +157,10 @@ which is how the open request can read it in the first place.
   open of any other protected pad happened to overwrite the cookie and cut
   it off; that only ever helped if the user opened another pad, and did
   nothing otherwise. Revoking a share does not end the Etherpad sessions
-  already issued for it: only expiry, a logout, or removing the group
-  behind the pad clears them, so the window is the session TTL either way
-  — it is just no longer shortened by accident.
+  already issued for it: only expiry, a logout, the recipient's account
+  being deleted, or removing the group behind the pad clears them, so the
+  window is the session TTL either way — it is just no longer shortened
+  by accident.
 
 ### Author Resolution Strategy
 
@@ -227,8 +226,9 @@ away itself:
   every socket message and keeps the session id it was handed when the pad
   connected – read in 2.7.3, 3.0.0 and 3.3.3 – so a session that expires
   mid-edit rejects the next keystroke, and no later cookie reaches that
-  socket. Revocation fires on an explicit logout and nowhere else, and is
-  capped, so for most sessions the lifetime is what bounds the window.
+  socket. Revocation fires on an explicit logout, on the account's
+  deletion and on a delete of the pad's file (below), and is capped, so
+  for most sessions the lifetime is what bounds the window.
 - Expired sessions are left to the background sweep described below. Only
   what is expired by both clocks counts as expired: Etherpad judges
   `validUntil` with its own, so a session ours calls dead may still be
@@ -246,9 +246,22 @@ cached id is therefore not dropped when an open fails – an emptied cache
 cannot be told from a user who never opened a protected pad, and a logout
 after a brief outage would revoke nothing.
 
-**Only logout.** Losing a share does not revoke anything, and neither does
-a permission downgrade, a deleted or disabled account, or a deleted public
-link. A session issued before any of those stays valid until `validUntil`.
+**A delete of the file revokes the pad's sessions** – every session of
+the pad's group, whoever it was issued to, once the file goes to the
+trash or past it, for a folder's protected pads too: the trash keeps the
+pad, and a session would keep giving it to whoever holds one. Which
+groups, and within what budget: `docs/architecture.md`, "Trash/Restore".
+
+**Deleting an account revokes its sessions**, as a logout does, as the
+delete starts (`RevokeSessionsOnAccountDeleteListener`): Nextcloud removes
+the account's settings, the cached author among them, before it reports
+the account gone. A delete the user backend then refuses has lost them as
+a logout would, and the next open makes new ones.
+
+**Otherwise, only expiry.** Losing a share does not revoke anything, and
+neither does a permission downgrade, a disabled account, or a deleted
+public link. A session issued before any of those stays valid until
+`validUntil`.
 Covering them one event at a time means enumerating every way access can
 end, and that list has no natural end – a public link in particular opens
 under its own Etherpad author whose id is deliberately never cached, so

diff --git a/docs/pad-format.md b/docs/pad-format.md
@@ -104,8 +104,9 @@ Protected + external is not supported.
 - `trashed` / `purged`
   - legacy parser compatibility only; new writes do not use these states
 
-The DB binding table uses `active`, `pending_delete` and `restore_pending`. Successful trash deletes
-the binding row; restore can recreate it from the `.pad` frontmatter and snapshot.
+The DB binding table uses `active`, and `pending_delete` for a file deleted for good whose pad
+has yet to go. A trash keeps the binding row and the pad; a file restored without a row, or
+whose pad Etherpad lost, gets a new pad from the `.pad` frontmatter and snapshot.
 External pads are not managed in the DB binding table, so trash/restore only moves
 the Nextcloud file and never creates, deletes, or restores anything on the remote
 Etherpad server.
@@ -129,7 +130,7 @@ Snapshot write flow:
 
 - `PadFileService::withExportSnapshot(...)` builds the new `.pad` content after an Etherpad export.
 - `PadFileLockRetryService::putContentWithSyncLockRetry(...)` writes that content back to the Nextcloud file with bounded lock retry.
-- Stored snapshots are read by `RestoreService` when restoring a pad and by the forced sync when comparing content. No viewer path reads them.
+- Stored snapshots are read by `RestoreService` when restoring a pad, by the forced sync when comparing content, and by an open that may write and the sync to tell whether Etherpad has lost the pad. No viewer path shows them.
 - External public pad create/sync paths both use the validated, host-pinned `/export/txt` fetch internally (via `ExternalPadExportFetcher`) and store no HTML snapshot:
   - create uses `ExternalPadExportFetcher::normalizeAndFetchExternalPublicPadTextOrEmpty(...)`, allowing the `.pad` file to be created with an empty initial snapshot if the export is not available yet.
   - sync uses `ExternalPadExportFetcher::normalizeAndFetchExternalPublicPadText(...)`, keeping later export failures visible.
@@ -138,6 +139,7 @@ Snapshot write flow:
 
 - Sync writes only when the upstream snapshot actually differs.
 - `force=1` requests an immediate upstream re-check, but unchanged snapshots are still not rewritten.
+- A pad Etherpad made anew in place of the file's - without a single revision, with other text than the file saved - is not written, forced or not: the sync answers `pad_missing`, and the file keeps its content for a new pad.
 - On successful sync:
   - `snapshot_rev` is updated
   - body is replaced:

diff --git a/docs/release-process.md b/docs/release-process.md
@@ -37,7 +37,6 @@ What it does:
 - If Nextcloud test credentials are present, runs core E2E checks:
   - pad flow
   - protected cookie contract (session cookie attrs + no `HttpOnly` for current Etherpad runtime compatibility)
-  - lifecycle state guards
   - public folder share flow
   - public single-file share flow
   - external URL security checks
@@ -92,23 +91,13 @@ RUN_FAILURE_PATHS=1 FAILURE_PATHS_PREPARED=1 NC_BASE_URL=... NC_USER=... NC_APP_
 Included:
 
 - sync failure path
-- trash deferred-delete failure path
-- restore failure path
-
-Optional debug-only lifecycle fault-injection checks:
-
-```bash
-RUN_DEBUG_FAULT_PATHS=1 NC_BASE_URL=... NC_USER=... NC_APP_PASSWORD=... ./tests/integration/release-check.sh "/release-debug-faults"
-```
 
 Notes:
 
 - `release-check.sh` will only run failure-path tests when both flags are set:
   - `RUN_FAILURE_PATHS=1`
   - `FAILURE_PATHS_PREPARED=1`
 - This prevents false failures on healthy environments where outage conditions were not prepared.
-- Requires admin credentials.
-- Requires Nextcloud `debug` mode enabled.
 
 ## 3) Tagging