feat(documents): let the picker bring back a deleted document

The document picker showed a document deleted in HealthLog as "Deleted
in HealthLog" and would not let it be ticked, so a person who deleted an
imported document by mistake met a dead end exactly where they would look
for it again.

Such a row can now be ticked, and the import sends revive: true for it.
A document still in Recently deleted is restored through the shared
restore, nothing is fetched, and the row reads "Restored from Recently
deleted". One the purge already removed is fetched and stored again, and
only once it is stored does the ledger forget its key, so a failed fetch
leaves the deletion standing. Without revive the route answers "deleted"
as before, and the token upload has no such switch: a Paperless workflow
or the import script re-sending a deleted document is still refused,
whether it is in Recently deleted or long purged.

The search names the document a deleted key still points at (documentId,
null once purged), so the row can say "In Recently deleted" rather than
"Deleted in HealthLog". The outcome gains "restored", sent only in answer
to revive. The row logic moves to picker-rows.ts.

Refs #1275

docs/api/openapi.yaml

@@ -25487,9 +25487,12 @@ paths:
         waits and then answers `duplicate`. The key check counts toward the lookup allowance, the fetch toward the
         search allowance, and only a file that arrived toward the upload allowance. A source key the vault already holds
         is answered without a download: `duplicate` for a live document (same id), `deleted` for one the person deleted
-        in HealthLog, which is never stored again. Bytes already in the vault under another key are `duplicate` too, and
-        the key is remembered for that document. `link` files the document against the record the picker was opened from
-        (a condition, a visit or a vaccination, which must be the caller's own and live; checked before anything is
+        in HealthLog, which is not stored again unless the request sends `revive: true`: then a document still in
+        Recently deleted is restored (`restored`), and one already removed for good is fetched and stored again, its key
+        leaving the import ledger. A token upload (`POST /api/documents/inbound`) has no such switch, so an importer
+        never brings a deleted document back. Bytes already in the vault under another key are `duplicate` too, and the
+        key is remembered for that document. `link` files the document against the record the picker was opened from (a
+        condition, a visit or a vaccination, which must be the caller's own and live; checked before anything is
         fetched), including a duplicate. `kind` sets the document type (default OTHER). Automatic AI reading follows the
         person's own setting. Counts against the person's upload allowance (60 an hour) and storage quota. 201 for a new
         document, 200 otherwise. Cookie session only; not delegable."
@@ -25537,11 +25540,14 @@ paths:
                   required:
                     - kind
                     - id
+                revive:
+                  type: boolean
               required:
                 - sourceId
       responses:
         "200":
-          description: Already held (`duplicate`) or deleted in HealthLog (`deleted`).
+          description: Already held (`duplicate`), deleted in HealthLog (`deleted`), or brought back from Recently deleted
+            (`restored`).
           content:
             application/json:
               schema:
@@ -90451,6 +90457,8 @@ components:
             - imported
             - deleted
         documentId:
+          description: The vault document for `imported`. For `deleted`, the document while it is still in Recently deleted
+            (restorable), null once it has been removed for good.
           type:
             - string
             - "null"
@@ -90489,6 +90497,9 @@ components:
             - imported
             - duplicate
             - deleted
+            - restored
+          description: "`restored` only answers a request that sent `revive: true`: the deleted document was still in Recently
+            deleted and is back in the vault."
         documentId:
           type:
             - string

docs/self-hosting/document-sources.md

@@ -82,13 +82,18 @@ limit for a document).
 
 - Imports count against the person's normal upload allowance (60 an hour) and
   storage quota.
-- A document that is already in HealthLog is not stored twice, and one the
-  person deleted in HealthLog is not brought back by picking it again. Each
-  import is keyed by system, instance (the archive's origin) and document id,
-  so the same id on two Paperless-ngx instances is two documents; a key
-  imported before v1.39.3 carries no instance and matches any instance. These
-  are the same rules the document token and `scripts/import-documents.mjs`
-  follow.
+- A document that is already in HealthLog is not stored twice. Each import is
+  keyed by system, instance (the archive's origin) and document id, so the
+  same id on two Paperless-ngx instances is two documents; a key imported
+  before v1.39.3 carries no instance and matches any instance. These are the
+  same rules the document token and `scripts/import-documents.mjs` follow.
+- A document the person deleted in HealthLog is never brought back by the
+  document token or the import script, however often they re-send it. The
+  person can bring it back themselves: from Recently deleted on the Documents
+  page for 30 days, or by picking it again in the picker, which says "In Recently
+  deleted" or "Deleted in HealthLog" on such a row. Picking one still in
+  Recently deleted restores that same document; picking one already removed
+  for good imports it again.
 - A picked document follows the person's own automatic AI reading setting.
 - Only the owner of a record can connect an archive or import from it. People
   with shared access to a record, whatever their level, do not see the picker.