soft-delete faza 05b — nagrobki dla konsumentów przyrostowych

[mpasternak]

Faza 05b stosu soft-delete. Baza: feat/soft-delete-05.

Konsument przyrostowy (harvester OAI-PMH, klient REST) dowiaduje się, że
rekord przestał być wystawiany — zamiast odkrywać to po cichej nieobecności.

Spec: docs/superpowers/specs/2026-08-15-soft-delete-nagrobki-design.md
Plan: docs/superpowers/plans/2026-08-16-soft-delete-05b-nagrobki.md

Cztery decyzje specu

D1	Nagrobek = dopełnienie ekspozycji, nie przynależności. Rekord, który przestał być eksportowany z JAKIEGOKOLWIEK powodu, dostaje nagrobek — nie tylko ten w koszu.
D2	Jeden strumień, jeden kursor. Nagrobki płyną razem z żywymi rekordami w tym samym porządku keyset.
D3	deletedRecord = "transient", nie persistent — nie gwarantujemy trwałości nagrobka (husk znika przy twardym kasowaniu albo czyszczeniu kosza w fazie 07).
D5	REST znaczy węziej niż OAI: /api/v1/usuniete/ wystawia wyłącznie kosz, bo REST nie składa obietnicy deletedRecord.

Rozszczepienie przynależność / ekspozycja

Dotychczasowy queryset() sklejał dwa różne pytania: „czy ten rekord jest
nasz?" (atrybucja tenanta) i „czy wolno go pokazać?" (reguły ekspozycji).
Nagrobek to różnica tych zbiorów, więc muszą zamieszkać w osobnych metodach:

• ProviderEncji.przynaleznosc(uczelnia, model) — sama atrybucja,
• ProviderEncji.nagrobki(...) — przynaleznosc − queryset.

Dlaczego nie dopełnienie całej widoczności: widoczne_jednostki()
filtruje uczelnia=uczelnia wprost, więc naiwne „wszystko minus widoczne"
zamieniłoby każdą jednostkę drugiej uczelni w nagrobek pierwszej — wyciek
identyfikatorów w multi-hosted. Pilnuje tego
test_nagrobki_nie_wyciekaja_miedzy_uczelniami.

Dlaczego strona() paginuje nadzbiór

resumptionToken niesie jeden kursor (datestamp, pk) i zakłada jeden
porządek. Nagrobki puszczone osobnym przebiegiem po żywych rekordach
wymagałyby drugiego kursora i rozjechałyby okno from/until — czyli
zepsułyby dokładnie tę przyrostowość, którą ta faza naprawia.

Skutkiem jest zmiana kształtu zwrotki: strona() zwraca
[(obiekt, czy_nagrobek)]. Wszyscy wołający zostali dostosowani; testy poza
test_nagrobki.py używają helpera tests/pomocnicze.py::strona_zywych,
który odtwarza dawną semantykę, więc ich asercje o widoczności zostały
nietknięte.

Odchylenia od planu (i dlaczego)

1. naleza_* używają global_objects po OBU stronach, nie tylko
   w podzapytaniu autorstwa jak w snippecie planu. Wydawnictwo_Ciagle.objects
   to menedżer soft-delete i ukrywa kosz — wersja z planu po cichu gubiłaby
   drogę „rekord w koszu". Udowodnione mutacyjnie: podmiana któregokolwiek
   managera na objects wywala odpowiednio przypadek kosz i
   odpiecie_autora w test_kazda_droga_znikniecia_daje_nagrobek.
2. Walidacja XSD: plan zakładał istniejący test walidujący odpowiedź.
   Takiego nie było — testy serializerów walidują pojedyncze encje profilu
   CERIF, a status="deleted" to konstrukcja koperty OAI-PMH. Zvendorowany
   OAI-PMH.xsd + plik spinający oba namespace'y (<metadata> ma
   processContents="strict", więc sam schemat koperty nie wystarcza dla
   rekordów żywych). Też mutation-tested.
3. Czerwona suita po Tasku 4 dotyczyła test_providery/serializery/widocznosc,
   a nie test_oai.py — ten ostatni chodzi po atrapach, więc kontraktu realnej
   klasy bazowej nie dotykał.
4. Ostrzeżenie o eksport_cerif_osoby poszło do docs/, nie w help_text —
   zmiana help_text wygenerowałaby migrację AlterField, a ta faza
   z założenia migracji nie dodaje.

Wyniki przebiegu lokalnego

CI nie biegnie na PR-ach do gałęzi feat/soft-delete*, więc to jedyny dowód.

uv run pytest -m "not playwright"   9611 passed, 4 skipped, 2 xfailed   (17:35)
uv run pytest -m playwright          157 passed, 1 skipped              (05:09)
npx vitest run                        81 passed
ruff check / format                   pliki tej fazy — czysto
makemigrations --check --dry-run      zero zgłoszeń dla src/
                                      (favicon/flexible_reports/siteblog — zastane)

Poza zakresem (świadomie, sekcja „Ograniczenia" specu)

• Przepięcie autorstwa do innej uczelni bez śladu w koszu nadal znika po cichu.
• Rekordy nigdy-niewidoczne też dostają nagrobek.
• Słowniki (Zrodlo, Konferencja, Projekt, Jednostka) nie są soft-delete —
  ich nagrobki biorą się z dopełnienia ekspozycji, więc twarde skasowanie
  takiego wiersza znika po cichu.

Stronicowanie /api/v1/usuniete/ (dołożone po pierwszym przebiegu)

Endpoint stronicuje BppLimitOffsetPagination — ale ORDER BY i
LIMIT/OFFSET wykonuje baza, nie Python.

Samo owinięcie sklejonej listy paginatorem byłoby półśrodkiem: każde żądanie
dalej ciągnęłoby cały kosz z sześciu modeli, a klient robiłby teraz N żądań
zamiast jednego — łączna praca by wzrosła. Zamiast tego sześć gałęzi
łączy UNION ALL o wspólnym kształcie (etykieta modelu, pk, deleted_at);
etykieta to stała z Value, bo po złączeniu klucze główne kolidują między
modelami.

Sortowanie (deleted_at, etykieta, pk) — sama data nie wystarcza: dwa
rekordy skasowane w tej samej mikrosekundzie miałyby niezdeterminowaną
kolejność, a to na granicy strony znaczy zgubiony albo zdublowany wiersz.
NULL-e lądują na końcu (Postgres, ASC), czyli tam, gdzie stawiał je
poprzedni sort w Pythonie.

Przy okazji każda gałąź dostaje .order_by() czyszczące Meta.ordering
modelu (Autor.sort, Praca_Doktorska.rok/tytul_oryginalny) — sortowanie po
kolumnach, których nawet nie ma w SELECT, i tak nadpisane przez zewnętrzny
ORDER BY.

test_usuniete_tnie_strone_w_bazie_a_nie_w_pythonie sprawdza, że złączone
zapytanie faktycznie niesie LIMIT — żeby ta optymalizacja nie
zdegradowała się po cichu do pesymalizacji.

Dług ujawniony przy okazji (nie naprawiany tutaj)

BppSoftDeleteQuerySet blokuje .update(deleted_at=...) (omijałoby
post_save, kaskadę *_Autor, SoftDeleteLog i reversion), ale gate
dziedziczy tylko AutorQuerySet — BppDeletedQuerySet publikacji nie.
Czyli Autor.deleted_objects...update(deleted_at=...) rzuca RuntimeError,
a to samo na Wydawnictwo_Ciagle przechodzi. Wygląda na przeoczenie, nie na
decyzję. Testy tej fazy na tej asymetrii nie polegają (opierają się na
zegarze i jawnie asertują, że znaczniki wyszły różne), więc domknięcie
gate'u ich nie zepsuje. Zapisane w handoffie fazy 06.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Drz3jfnuP864JmYxqfjsYK