GÜNCELLEME (2026-09-05): publish dışı tüm 18.A eksikleri tamamlandı — inbox.*, feed actor_type, tri-state update_me (
actos.UNSETsentineli), comments body_html, openapi+types regen, README/PLAN düzeltmeleri. Kapılar yeşil (pytest 114, mypy --strict, ruff, unasync, generate_types --check). Kalan yalnızca yayın (PyPI).
Durum özeti: SDK, backend Faz 18.A'dan önceki spec'e göre bilinçli ve eksiksiz kodlanmış (Faz 0–16
[x], sözleşmenin 16 maddesi test edilmiş, ruff/mypy --strict/pytest hepsi yeşil). Backend Faz 18.A 2026-09-03'te bitti; bu SDK artık spec'in gerisinde: repodakiopenapi.jsonkopyası 42 yol, canlı spec 45 yol. Fark tamamen ekleyici (inbox uçları + birkaç yeni alan/parametre), kırıcı değil.verifications.*ayrı bir konu: backend'de süresiz ertelendi, "bekleniyor" değil — plandan düşülmeli. En kritik somut bulgu:tests/unit/test_types.py:: test_generate_types_check_clibu ortamda (kardeşactos-backendreposu mevcut olduğu için) şu an gerçekten kırmızı — drift otomatik yakalanıyor.Son kontrol: 2026-09-03, backend Faz 18.A sonrası. Doğrulama:
.venv/bin/python scripts/generate_types.py --check,.venv/bin/python -m pytest -q -m "not contract",.venv/bin/python -m mypy actos tests --strict,ruff check .,scripts/unasync.py --check, ve backendopenapi.jsonile repo kopyasının Python ile programatik diff'i.
Kaynak spec: /home/efe/Documents/actos/actos-backend/docs/openapi.json (45 yol).
Repo kopyası: /home/efe/Documents/actos/python/openapi.json (42 yol, eski).
Programatik diff ile doğrulandı — fark şu üç yol ve üç şema:
/me/inbox, /me/inbox/read, /me/inbox/{id}/read;
InboxResponse, NotificationSummary, MarkAllReadResponse.
Ayrıca 4 mevcut şema/parametreye alan eklendi (aşağıda ayrı ayrı).
-
openapi.jsonkopyasını tazele.python/openapi.json→ backend'deki güncel kopyayla değiştirilecek (cp ../actos-backend/docs/openapi.json openapi.jsonya dascripts/generate_types.py'ninBACKEND_SPEC_PATHfallback'i zaten kardeş repo varken bunu otomatik kullanıyor — asıl mesele committed kopyanın kardeş repo olmadan kurulumlarda kullanılacak olması). Dosya:python/openapi.json. Neden:scripts/generate_types.py:22-36resolve_default_source()önce../actos-backend/docs/openapi.json'a bakıyor, o yoksa yerel kopyaya düşüyor — CI'da (tek repo checkout) sadece yerel kopya var, o yüzden CI bugün bu drift'i yakalamıyor (bkz. §4, tuzak notu). -
actos/types.py'yi yeniden üret ve commit'le.uv run python scripts/generate_types.py(kardeş repo mevcutken otomatik güncel spec'i kullanır). Doğrulandı: bu komut şu anActorSummary'yeavatar_url+trust_level,ContentSummary'yebody_html, ve üç yeni şemayı (InboxResponse,NotificationSummary,MarkAllReadResponse) ekliyor — çıktı gerçek diff olarak alındı, tahmini değil. Dosya:actos/types.py. Bu tek başına yapılıncatests/unit/test_types.py::test_generate_types_check_cli(satır 126-137) tekrar yeşile döner. -
inbox.*kaynağını uygula (PLAN.md Faz 13.B,- [ ]satır 436-445). Backend uçları artık var, doğrulandı (actos-backend/docs/openapi.json→/me/inboxGET,/me/inbox/readPOST,/me/inbox/{id}/readPATCH).client.inbox.list(unread=False, limit=, cursor=)→GET /me/inbox,InboxResponse.notifications+.next_cursor+.unread_count.client.inbox.iter(...)→ auto-paging.client.inbox.read(notification_id)→PATCH /me/inbox/{id}/read. Doğrulandı: spec'e göre 204 döner, başka actor'ün bildirimi404verir (id sızdırmaz), zaten okunmuşu tekrar işaretlemek de 204 — idempotent.client.inbox.read_all(up_to_cursor=None)→POST /me/inbox/read,cursorverilmezse tümü işaretlenir;MarkAllReadResponse.markeddöner. Spec açıkça "Idempotent" diyor.client.inbox.unread_count()→ PLAN.md'de ayrı bir uç yok, muhtemelenlist(limit=1)çağırıpInboxResponse.unread_count'u döndürmek (spec: "unread_count is always the TOTAL unread count, not the number of items on this page"). Doğrulanamadı: spec'te bunun için ayrı bir hafif uç yok, PLAN.md da HTTP karşılığını belirtmiyor (§3 satır 218'de "↑ yanıttaki sayacı döner" yazıyor) — uygulayan ajanlist()üzerinden türetmeli, ekstra bir uç uydurmamalı.client.inbox.watch(interval=...)yoklama yardımcısı (PLAN.md satır 440-442): sonsuz üreteç,Retry-After/rate-limit header'larına uyar.- Dosyalar: yeni
actos/resources/_async/inbox.py+actos/resources/_sync/inbox.py(unasync ile üretilecek, elle yazılmayacak — bkz.scripts/unasync.py),actos/client.py:125-137ve:203-215'eself.inbox = ...satırı,actos/__init__.py'ye export. - Testler:
tests/unit/test_inbox.py(yok, oluşturulmalı) +tests/contract/test_contract.py'ye dokunmaya gerek yok (16 madde zaten API yüzeyinden bağımsız sözleşme kuralları, ama yeni bircontract_17gerekmiyor — inbox sözleşmenin bir parçası değil, §3 "API yüzeyi" haritasının bir parçası).
-
feed.list/feed.following'eactor_typeparametresi ekle. Doğrulandı:actos/resources/_async/feed.py:18-59(list) ve:90-131(following) — ikisinde deparamssözlüğündeactor_typeyok, docstring'de açıkça "Strictly does not supportactor_typefiltering (§0.2)" yazıyor (satır 29). Spec diff'i doğruladı:/feedve/feed/followingGET parametrelerineactor_typeeklenmiş (query parametre listesi programatik olarak karşılaştırıldı).actors.py'dekilist()zaten aynı deseni kullanıyor (actor_type: ActorType | str | None, satır 32-52) — oradaki desen kopyalanabilir. Sync taraf unasync ile otomatik gelir, elle dokunulmaz. -
actors.update_me'yeavatarparametresi ekle. Doğrulandı:actos/resources/_async/actors.py:105-130— imzadaavataryok, docstring'de "NOTE: Avatar updates are deferred and not supported (§0.2)" yazıyor (satır 113). Spec:UpdateProfileRequest.avatareklendi (string | null, upload'ın dış id'sif_...). Tuzak: alanOption<Option<T>>deseni taşıyor (spec açıklaması) —display_name/bioile aynı "gönderilmezse dokunma,nullgönderilirse temizle, değer gönderilirse güncelle" davranışı. Mevcut kod zatendisplay_name/bioiçin bu ayrımı yapmıyor (satır 122-126:if display_name is not None: payload[...]— yani kullanıcıbio=""ile temizleyebilir amabio=Noneile "dokunma" ile "temizle" arasındaki farkı ifade edemez,Noneher zaman "dokunma" anlamına geliyor).avatareklenirken bu sınırlama miras alınacaksa bilerek alınmalı;None→ "dokunma", avatar'ı temizlemek isteyen kullanıcı için ayrı bir yol (avatar=UNSETgibi bir sentinel) düşünülmeli — bugünküdisplay_name/biodavranışıyla tutarlı olsun istenmiyorsa bu üçü birlikte ele alınmalı, sadeceavatarfarklı davranmamalı. -
comments.list/comments.iter'abody_html: boolparametresi ekle. Doğrulandı:actos/resources/_async/comments.py:61-104(list) ve:106-136(iter) —body_htmlparametresi yok. Spec:GET /posts/{id}/commentsüzerinde yenibody_htmlquery parametresi (boolean, varsayılanfalse),fieldsdeğil — spec'in kendi açıklaması: bu uçta?fields=desteklenmiyor çünkü ağaç yapısını (replies) bozar, o yüzden ayrı bayrak var. PLAN.md'nin §0.2 tablosunda bu madde hiç yok (plan yazıldığında bu parametre spec'te yoktu, tahmin edilmemiş) — yani PLAN.md'ye de eklenmesi gereken yeni bir satır. Not:posts.get()vecomments.get()zaten genelfields=desteğine sahip, oralardabody_htmlzatenfields=["body_html"]ile çekilebilir (spec: "Tekil uçlar ?fields='ten bağımsız her zaman doldurur" — yanifieldsfiltrelemesi tekil uçlardabody_html'i etkilemiyor bile, otomatik dolu geliyor). Sadece tree/list uçları için ayrı parametre gerekiyor. -
ActorSummary.avatar_urlve.trust_level— tip üretiminden sonra SDK tarafında elle yapılacak bir şey yok, ama doğrulanmalı. Bu iki alanactos/types.pyyeniden üretildiğinde otomatik gelir (madde 2). Kod tarafındaActorSummary'yi elle inşa eden tek yeractos/resources/_async/feed.py:56ve:128(Post.model_construct(**item)—fields=verildiğinde şema doğrulamasını atlıyor) etkilenmez çünkü orasıContentSummary(Postalias'ı) kullanıyor,ActorSummarydeğil. Yeni alanlarextra="allow"sayesinde bugün demodel_extraüzerinden erişilebilir durumda ama tip güvenli değil —actor.trust_levelmypy --strict altındaattr-definedhatası verir (tip üretilmeden). Regenerasyondan sonra ek bir kod değişikliği gerekmiyor, sadece testlerde bu alanların varlığının doğrulandığından emin olunmalı (madde 9, test_types.py).
Bu kategoride hiçbir madde bulunamadı — [x] işaretli Faz 0-16 maddeleri
tek tek kodla karşılaştırıldı (dosya varlığı, testlerin geçmesi, README/
CHANGELOG tutarlılığı) ve hepsi doğrulandı:
.venv/bin/python -m pytest -q -m "not contract"→ 107 geçti, 18 deselect edildi (contract testleri), sadece 1 test kırmızı (test_generate_types_check_cli— bu §1'in sonucu, "planda[x]ama eskimiş" değil, "backend ilerledi, SDK henüz onu takip etmedi")..venv/bin/python -m mypy actos tests --strict→ temiz, 57 dosya..venv/bin/python -m ruff check .→ temiz..venv/bin/python scripts/unasync.py --check→ temiz, sync/async senkron.tests/contract/test_contract.py→ §2'nin 16 maddesinin hepsi için test var (test_contract_1_...→test_contract_16_..., satır 71-420).grep -rn "skip\|xfail" tests/→ boş, hiçbir test atlanmış değil.scratch/boş ve git'e hiç girmemiş (bkz. §4).
Not: --check şu an bu ortamda kırmızı olsa da, bu "planda [x] ama kod
eskimiş" kategorisine girmiyor çünkü kod bittiğinde (Faz 1, 2026 başlarında)
spec gerçekten 42 yol'du ve types.py o spec'le doğruydu — sonradan backend
ilerledi. Bu §1'in konusu.
verifications.create/check/list/delete—PLAN.md:220-222(§3 API yüzeyi) vePLAN.md:443(Faz 13.B,- [ ]madde), ayrıcaNOTES.md:25(deferred tablosu) bunu "backend Faz 18.A'yı bekliyor" gibi sunuyor. Bu artık yanlış. Doğrulandı:/home/efe/Documents/actos/actos-backend/NOTES.md§9.2 başlığı "Alan adı doğrulaması — ERTELENDİ (2026-09-03), tasarım burada saklı" ve açıkça yazıyor: "Karar: v1'e girmiyor." Gerekçe §9.2.4-9.2.5: HTTPS yöntemi seçilirse SSRF yüzeyi (saldırgan sunucuya127.0.0.1:3101gibi iç adresler denetletebilir) ve DNS rebinding TOCTOU riski (kontrol ile bağlantı arasında alan adı127.0.0.1'e çözümlenebilir) — bu yüzden "henüz olmayan bir problemi çözüyor, bedeli bugün somut, faydası bugün sıfır" denip süresiz ertelenmiş./me/ verifications*uçları canlı spec'te hiç yok (45 yolun hiçbiri bu değil, programatik olarak doğrulandı) ve backend'in kendi notuna göre hiç olmayacak. Eylem:PLAN.mdFaz 13.B'dekiverifications.*maddesi (satır 443) "[ ]= bekliyor" değil, tamamen silinmeli ya da açıkça "YAPILMAYACAK — bkz. backend NOTES.md §9.2" notuyla işaretlenmeli. §3'teki API yüzeyi haritasından (satır 220-222) da çıkarılmalı — orada hâlâ SDK'nın bir parçasıymış gibi duruyor.NOTES.md:19-29'daki "Deferred Items" tablosundakiverifications.*satırı da aynı şekilde yanlış ve düzeltilmeli (bu dosyayı ben değiştirmedim, yöneticiye bırakıyorum). Bu repo dışına da not düşülmeli mi (node/rust SDK'larının PLAN.md'sinde aynı satır olabilir) — doğrulanamadı, kapsam dışı, sadece bu repo incelendi.
scripts/generate_types.py'nin kaynak önceliği CI'ı kör bırakıyor.resolve_default_source()(satır 29-36) önce kardeşactos-backendreposuna bakıyor; CI (.github/workflows/ci.yml:33, tek repo checkout) o dizini hiç görmüyor, otomatik olarak yerelopenapi.jsonkopyasına düşüyor. Doğrulandı:--source openapi.jsonile--checkçalıştırıldığında[OK]dönüyor (yerel kopya kendi içinde tutarlı), ama kardeş repo mevcutken (bu geliştirme ortamında olduğu gibi)--checkkırmızı. Yani bugünkü CI, yerelopenapi.jsonkopyası güncellenmeden types.py'nin gerçek backend spec'inden saptığını asla yakalamaz — tek güvence, birinin elleopenapi.json'ı tazeleyip PR açmasıdır. Bu otomatik değil, insan hafızasına bağlı bir süreç. Madde 1'deki güncellemeyle birlikte bu döngü kapanır ama mekanizma kırılgan kalır — ileride backend spec'i her değiştiğinde bu SDK'nın bunu nasıl öğreneceği (polling? backend CI'da bir "spec değişti" bildirimi?) planlanmamış. Doğrulanamadı: böyle bir mekanizma olması gerekip gerekmediği bu görevin kapsamı dışında, sadece mevcut durumun kırılganlığını not ediyorum.scratch/dizini tamamen boş ve git'e hiç girmemiş (git ls-files scratch/boş döner,git log --all -- scratch/boş döner). Kalması için görünür bir sebep yok. Ya silinsin ya da ne için ayrıldığı bir.gitkeep+ tek satır açıklamayla belirtilsin. Düşük öncelik.README.md:194kaynak tablosu küçük ölçüde güncel değil (18.A ile ilgisiz, önceden var olan bir tutarsızlık):client.authsatırıdelete_keymetodundan bahsediyor ama gerçek metot adırevoke_key(actos/resources/_async/auth.py:105);recoververegenerate_recovery_codestabloda hiç yok.client.commentssatırıtreediye bir metottan bahsediyor, böyle bir metot yok — gerçek metotlarcreate/list/iter/get/update/delete(actos/resources/_async/comments.py:24,61,106,138,158,178). İşlevsel bir hata değil, sadece dokümantasyon küçük drift'i; inbox eklenirken bu tablo da güncellenirse iyi olur (aynı PR).PLAN.md§0.2 tablosu (satır 55-59) ve §3 API yüzeyi (satır 220-222, 229-232) madde 1 ve 3'teki değişikliklerle güncellenmeli:body_htmlparametresi tabloya hiç girmemiş (spec büyüdüğünde fark edilmemiş bir madde),verifications.*çıkarılmalı. Bu değişiklikleri ben yapmadım (görev tanımı gereği), yöneticiye bırakıyorum.
openapi.jsonkopyasını tazele +actos/types.py'yi yeniden üret ve commit'le (§1.1-2). Tek başına bu, kırmızı testi yeşile çevirir ve sonraki tüm işin temelini atar.feed.list/feed.following'eactor_typeekle (§1.4) — en küçük, bağımsız,actors.list'teki mevcut desenin kopyası.comments.list/iter'abody_htmlekle (§1.6) — küçük, bağımsız.actors.update_me'yeavatarekle (§1.5) —Option<Option<T>>tuzağı için öncedisplay_name/bio'nun bugünkü davranışına karar vermek gerekiyor (tutarlı mı bırakılacak, üçü birden mi düzeltilecek); bu yüzden 2 ve 3'ten sonra, tek başına ele alınmalı.inbox.*kaynağını uygula (§1.3) — en büyük parça, yeni dosyalar, yeni testler; 1-4 bittikten sonra çünkütypes.pyüzerindenInboxResponse/NotificationSummary/MarkAllReadResponse'a bağımlı.PLAN.md'yi güncelle: Faz 13.B'yi tamamla,verifications.*maddesini plandan düşür (§3), §0.2 ve §3 tablolarını düzelt (yönetici işi).- §4'teki küçük teknik borç maddeleri (README tablosu,
scratch/) — 5'le aynı PR'a eklenebilir, ayrı bir tur gerektirmez.