feat(files): the Files library API — folders, moving and keeping files, upload into a folder, the file's hash

/api/files is the library's home: list a user's done files (by folder, searched, sorted, or the
ones shared with them), rename / move / keep / delete a file, make, rename and delete own folders
(a deleted folder's files go back to their source folders), and set how long any folder keeps a
file — done files shift by the difference, never closer than the GC's warning window.

An upload can name its folder (an own folder or Uploads), checked before the body is read and again
before the file lands; it is hashed while it streams, and any file can be hashed on first ask. The
download says the hash (Repr-Digest) once it is known; a new file at an asset's path forgets it.

Uploads, deletes, keeps, moves and folder changes are audited (ids only). The fileless "expired"
rows of the old retention are deleted by migration 0103: an expired file now leaves the library.

The shared route helpers moved to routes/files.py; the old /api/downloads library routes delegate
to the new ones until the client moves over.

backend/app/downloads/folders.py

@@ -9,7 +9,9 @@ shared asset can be held by several users), so a rename or a move is a column up
 - an OWN folder is the user's, with the name they gave it.
 
 Every file of a user is in exactly one folder. The folder a new file lands in is decided here
-(`source_key_for` + `source_folder`), at every place a job is created, so the rule lives once.
+(`source_key_for` + `source_folder`), at every place a job is created, so the rule lives once. A file
+moves only into one of the user's own folders or back to its own source folder (`move`): a YouTube
+file in the TikTok folder would be a lie the folder's name tells.
 
 Retention is the folder's: a source folder keeps a file `download_retention_days` (the value when the
 folder was made; the user can change it), Uploads and own folders keep it until it is deleted. A
@@ -26,6 +28,7 @@ from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
 from app import sysconfig
+from app.downloads.status import JobStatus
 from app.models import DownloadJob, FileFolder, MediaAsset
 
 
@@ -137,3 +140,88 @@ def stamp_expiry(db: Session, job: DownloadJob) -> None:
     """Stamp a job that just became done (in this session) with its expiry."""
     job.expires_at = done_expiry(db, job.folder_id, job.kept)
     job.expiry_warned = False
+
+
+class FolderError(Exception):
+    """A folder change the rules refuse; `reason` is the refusal the route answers with."""
+
+    def __init__(self, reason: str) -> None:
+        super().__init__(reason)
+        self.reason = reason
+
+
+def upload_target(db: Session, user_id: int, folder_id: int) -> FileFolder:
+    """The folder an upload asked to land in, if it may: one of the user's own folders, or their
+    Uploads folder. A file put in a site's folder would claim an origin it does not have."""
+    folder = db.get(FileFolder, folder_id)
+    if folder is None or folder.user_id != user_id:
+        raise FolderError("file_folder_gone")
+    if folder.kind == FolderKind.SOURCE and folder.source_key != SourceKey.UPLOAD:
+        raise FolderError("file_folder_not_its_source")
+    return folder
+
+
+def restamp(db: Session, job: DownloadJob) -> None:
+    """Start a file's clock again from now: it moved to another folder, or its user stopped keeping
+    it. A file not done yet gets its expiry when it finishes (`stamp_expiry`), so it has none now."""
+    done = job.status == JobStatus.DONE
+    job.expires_at = done_expiry(db, job.folder_id, job.kept) if done else None
+    job.expiry_warned = False
+
+
+def set_kept(db: Session, job: DownloadJob, kept: bool) -> None:
+    """Keep a file until its user deletes it, or hand it back to its folder's retention."""
+    job.kept = kept
+    restamp(db, job)
+
+
+def move(db: Session, job: DownloadJob, folder: FileFolder) -> None:
+    """Put a file in `folder` — one of its user's own folders, or the source folder it came from.
+    The caller has checked that `folder` is the job's user's."""
+    if folder.kind == FolderKind.SOURCE and folder.source_key != source_key_for(db, job):
+        raise FolderError("file_folder_not_its_source")
+    if folder.id == job.folder_id:
+        return
+    job.folder_id = folder.id
+    restamp(db, job)
+
+
+def set_retention(db: Session, folder: FileFolder, days: int | None) -> None:
+    """Change how long `folder` keeps a file (None = until deleted). The done files already in it
+    move by the difference — each keeps the age it has — but none ends up closer than the GC's
+    warning window, so a shortened retention still warns before it takes anything."""
+    old = folder.retention_days
+    if old == days:
+        return
+    folder.retention_days = days
+    now = datetime.now(timezone.utc)
+    floor = now + timedelta(days=sysconfig.get_int(db, "download_gc_grace_days"))
+    jobs = db.execute(
+        select(DownloadJob).where(
+            DownloadJob.folder_id == folder.id,
+            DownloadJob.status == JobStatus.DONE,
+            DownloadJob.kept.is_(False),
+        )
+    ).scalars()
+    for job in jobs:
+        if days is None:
+            job.expires_at = None
+        elif old is None or job.expires_at is None:
+            job.expires_at = max(now + timedelta(days=days), floor)
+        else:
+            job.expires_at = max(job.expires_at + timedelta(days=days - old), floor)
+        job.expiry_warned = False
+
+
+def delete_own(db: Session, folder: FileFolder) -> int:
+    """Delete one of a user's own folders. Its files are not deleted: each goes back to the source
+    folder it came from, its clock starting there now. Returns how many moved."""
+    if folder.kind != FolderKind.OWN:
+        raise FolderError("file_folder_not_own")
+    jobs = db.execute(select(DownloadJob).where(DownloadJob.folder_id == folder.id)).scalars().all()
+    for job in jobs:
+        job.folder_id = source_folder(db, job.user_id, source_key_for(db, job)).id
+        restamp(db, job)
+    db.flush()  # the files leave before the folder goes: its foreign key RESTRICTs the delete
+    db.delete(folder)
+    return len(jobs)