rename(547): the server is grimoire — package, image, DB defaults, backups

Step 2 of the Scribe -> Grimoire rename.

- src/scribe -> src/grimoire, and every import, patch target, module path,
  hypercorn entry point and `python -m grimoire.restore` with it; pyproject,
  uv.lock and the frontend package are named grimoire.
- Image git.fabledsword.com/bvandeusen/fabledgrimoire; CI's Postgres service
  runs as grimoire / grimoire_test.
- Compose files default the DB user, database and (prod) volume to grimoire,
  each overridable from .env, so an install created as Scribe keeps its data
  by setting POSTGRES_USER, POSTGRES_DB and PGDATA_VOLUME.
- Backups are written as grimoire-<ts>.tar with format grimoire-backup-tar.
  Archives named scribe-* with the scribe-backup-tar manifest still restore
  and are still counted at the destination (folder and S3), with tests.
- Exports, the MCP auth realm, the ASGI scope key and the persistent logger
  carry the new name.

Kept on purpose: the secret-sealing key label stays "scribe.secrets.v1",
because every stored secret was derived under it.

Plugin identity (plugin name, hooks, env vars, .scribe marker, skills) is
step 3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/grimoire/services/trash.py

@@ -0,0 +1,266 @@
+"""Soft-delete / trash service — single source of truth for recoverable deletes.
+
+A delete stamps `deleted_at` + a shared `deleted_batch_id` on the target row and
+its descendants (cascade). Restore clears the batch; purge hard-deletes it; the
+retention cron purges rows older than the configured window. Live reads exclude
+trashed rows via `alive()`.
+"""
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timedelta, timezone
+
+from sqlalchemy import delete as sql_delete, or_, select, update
+
+from grimoire.models import async_session
+from grimoire.models.note import Note
+from grimoire.models.project import Project
+from grimoire.models.milestone import Milestone
+from grimoire.models.rulebook import Rulebook, RulebookTopic, Rule
+from grimoire.models.base import iso
+
+# entity_type -> Model. Used to resolve which table a trash op targets.
+_MODEL_FOR = {
+    "note": Note,
+    "task": Note,
+    "project": Project,
+    "milestone": Milestone,
+    "rulebook": Rulebook,
+    "topic": RulebookTopic,
+    "rule": Rule,
+}
+
+
+def _owner_clause(model, user_id: int):
+    """Boolean expr scoping `model` rows to the ones `user_id` owns.
+
+    EVERY trash query (exists-check, restore, purge, list, retention sweep)
+    must carry this — a batch_id is a bearer token, so without an owner
+    predicate a leaked/guessed id lets one tenant read, restore, or
+    permanently destroy another's content. Topics and rules carry no
+    user_id of their own; ownership is derived through the parent rulebook
+    (or, for project-scoped rules, the owning project).
+    """
+    if model is Rulebook:
+        return Rulebook.owner_user_id == user_id
+    if model is RulebookTopic:
+        return RulebookTopic.rulebook_id.in_(
+            select(Rulebook.id).where(Rulebook.owner_user_id == user_id)
+        )
+    if model is Rule:
+        return or_(
+            Rule.topic_id.in_(
+                select(RulebookTopic.id)
+                .join(Rulebook, RulebookTopic.rulebook_id == Rulebook.id)
+                .where(Rulebook.owner_user_id == user_id)
+            ),
+            Rule.project_id.in_(
+                select(Project.id).where(Project.user_id == user_id)
+            ),
+        )
+    # Note, Project, Milestone all carry user_id directly.
+    return model.user_id == user_id
+
+
+async def _set(session, model, where, batch, now) -> None:
+    """Stamp deleted_at + batch on live rows matching `where`."""
+    await session.execute(
+        update(model)
+        .where(*where, model.deleted_at.is_(None))
+        .values(deleted_at=now, deleted_batch_id=batch)
+    )
+
+
+async def _exists_alive(session, user_id: int, etype: str, eid: int) -> bool:
+    model = _MODEL_FOR[etype]
+    where = [model.id == eid, model.deleted_at.is_(None), _owner_clause(model, user_id)]
+    return (await session.execute(select(model.id).where(*where))).first() is not None
+
+
+async def _cascade(session, user_id: int, etype: str, eid: int, batch: str, now) -> None:
+    if etype == "project":
+        await _set(session, Note, [Note.user_id == user_id, Note.project_id == eid], batch, now)
+        await _set(session, Milestone, [Milestone.user_id == user_id, Milestone.project_id == eid], batch, now)
+        # Project-scoped rules cascade with the project they're attached to.
+        await _set(session, Rule, [Rule.project_id == eid], batch, now)
+        await _set(session, Project, [Project.user_id == user_id, Project.id == eid], batch, now)
+    elif etype == "milestone":
+        await _set(session, Note, [Note.user_id == user_id, Note.milestone_id == eid], batch, now)
+        await _set(session, Milestone, [Milestone.user_id == user_id, Milestone.id == eid], batch, now)
+    elif etype in ("note", "task"):
+        # Stamp the entire sub-task subtree (not just direct children) so a
+        # deeply nested task and all its descendants trash/restore as one batch.
+        ids = [eid]
+        frontier = [eid]
+        while frontier:
+            children = (await session.execute(
+                select(Note.id).where(
+                    Note.user_id == user_id,
+                    Note.parent_id.in_(frontier),
+                    Note.deleted_at.is_(None),
+                )
+            )).scalars().all()
+            frontier = [c for c in children if c not in ids]
+            ids.extend(frontier)
+        await _set(session, Note, [Note.user_id == user_id, Note.id.in_(ids)], batch, now)
+    elif etype == "rulebook":
+        topic_ids = (await session.execute(
+            select(RulebookTopic.id)
+            .join(Rulebook, RulebookTopic.rulebook_id == Rulebook.id)
+            .where(Rulebook.id == eid, Rulebook.owner_user_id == user_id)
+        )).scalars().all()
+        if topic_ids:
+            await _set(session, Rule, [Rule.topic_id.in_(topic_ids)], batch, now)
+        await _set(session, RulebookTopic, [RulebookTopic.rulebook_id == eid], batch, now)
+        await _set(session, Rulebook, [Rulebook.id == eid, Rulebook.owner_user_id == user_id], batch, now)
+    elif etype == "topic":
+        await _set(session, Rule, [Rule.topic_id == eid], batch, now)
+        await _set(session, RulebookTopic, [RulebookTopic.id == eid], batch, now)
+    elif etype == "rule":
+        await _set(session, Rule, [Rule.id == eid], batch, now)
+    else:
+        raise ValueError(f"unknown entity_type: {etype!r}")
+
+
+async def delete(user_id: int, entity_type: str, entity_id: int) -> str | None:
+    """Soft-delete an entity + its descendants under one batch_id.
+
+    Returns the batch_id, or None if the entity wasn't found / not owned.
+    """
+    batch = str(uuid.uuid4())
+    now = datetime.now(timezone.utc)
+    async with async_session() as session:
+        if not await _exists_alive(session, user_id, entity_type, entity_id):
+            return None
+        await _cascade(session, user_id, entity_type, entity_id, batch, now)
+        await session.commit()
+    return batch
+
+
+# All soft-deletable models, and their trash-listing type label.
+_ALL = [Note, Project, Milestone, Rulebook, RulebookTopic, Rule]
+_TYPE = {
+    Note: "note", Project: "project", Milestone: "milestone",
+    Rulebook: "rulebook", RulebookTopic: "topic", Rule: "rule",
+}
+
+
+def alive(stmt, model):
+    """Append a 'not trashed' filter to a select. Use in every live read."""
+    return stmt.where(model.deleted_at.is_(None))
+
+
+async def restore(user_id: int, batch_id: str) -> int:
+    """Clear deleted_at for every row in the batch. Returns rows restored."""
+    n = 0
+    async with async_session() as session:
+        for model in _ALL:
+            res = await session.execute(
+                update(model)
+                .where(model.deleted_batch_id == batch_id, _owner_clause(model, user_id))
+                .values(deleted_at=None, deleted_batch_id=None)
+            )
+            n += res.rowcount or 0
+        await session.commit()
+    return n
+
+
+async def restore_entity(user_id: int, entity_type: str, entity_id: int) -> int | None:
+    """Restore ONE trashed entity by id, by reviving the batch that took it.
+
+    The inverse of `delete(user_id, entity_type, entity_id)`, which returns a
+    batch id the caller usually doesn't keep. Callers that need to undo their own
+    soft-delete later — snippet un-merge — know the entity id, not the
+    batch, and looking it up here keeps them from reaching into the column set.
+
+    Restores the whole batch on purpose, not just the row: the batch is the
+    entity plus its cascaded descendants, so reviving the parent alone would
+    leave them orphaned in the trash. That is the same thing the trash UI does.
+
+    Returns rows restored, or None if the entity isn't trashed / not owned.
+    """
+    model = next((m for m, label in _TYPE.items() if label == entity_type), None)
+    if model is None:
+        return None
+    async with async_session() as session:
+        batch = (await session.execute(
+            select(model.deleted_batch_id).where(
+                model.id == entity_id,
+                _owner_clause(model, user_id),
+                model.deleted_at.isnot(None),
+            )
+        )).scalars().first()
+    if not batch:
+        return None
+    return await restore(user_id, batch)
+
+
+async def purge(user_id: int, batch_id: str) -> int:
+    """Hard-delete every row in the batch. Irreversible."""
+    n = 0
+    async with async_session() as session:
+        for model in _ALL:
+            res = await session.execute(
+                sql_delete(model).where(
+                    model.deleted_batch_id == batch_id, _owner_clause(model, user_id)
+                )
+            )
+            n += res.rowcount or 0
+        await session.commit()
+    return n
+
+
+async def list_trash(user_id: int) -> list[dict]:
+    """Trashed rows across all soft-deletable tables, grouped by batch_id."""
+    batches: dict[str, dict] = {}
+    async with async_session() as session:
+        for model in _ALL:
+            rows = (await session.execute(
+                select(model).where(
+                    model.deleted_at.isnot(None), _owner_clause(model, user_id)
+                )
+            )).scalars().all()
+            for r in rows:
+                grp = batches.setdefault(
+                    r.deleted_batch_id,
+                    {"batch_id": r.deleted_batch_id,
+                     "deleted_at": iso(r.deleted_at),
+                     "items": []},
+                )
+                grp["items"].append({
+                    "type": _TYPE[model], "id": r.id,
+                    "title": getattr(r, "title", "") or "",
+                })
+    out = list(batches.values())
+    for g in out:
+        lead = g["items"][0]
+        g["summary"] = lead["title"] or f"{lead['type']} {lead['id']}"
+        g["count"] = len(g["items"])
+    out.sort(key=lambda g: g["deleted_at"] or "", reverse=True)
+    return out
+
+
+async def purge_expired(user_id: int, retention_days: int) -> int:
+    """Cron entry: hard-delete THIS user's rows trashed more than retention_days ago.
+
+    Scoped to one owner so the scheduler can apply each user's own
+    `trash_retention_days` window — a single global sweep would let one
+    user's short window prematurely destroy another's data.
+    retention_days <= 0 disables auto-purge (returns 0 without touching anything).
+    """
+    if retention_days <= 0:
+        return 0
+    cutoff = datetime.now(timezone.utc) - timedelta(days=retention_days)
+    n = 0
+    async with async_session() as session:
+        for model in _ALL:
+            res = await session.execute(
+                sql_delete(model).where(
+                    model.deleted_at.isnot(None),
+                    model.deleted_at < cutoff,
+                    _owner_clause(model, user_id),
+                )
+            )
+            n += res.rowcount or 0
+        await session.commit()
+    return n