oskar ae16deb8d3 feat(mail-sync): scheduler PIHA, takt kb-ingest, runbook i dokumentacja

Domkniecie Kroku 7. Realizuje Decyzje (d) reconu (host schedulera + korekta
kadencji indeksowania) i doklada dokumentacje wg konwencji OKF.

Scheduler (NIEAKTYWOWANY — wlacza operator):
- jobs/mail-imap-sync/systemd/{service,timer,run.sh} — wzorzec 1:1 z kb-ingest,
  OnCalendar=hourly, Persistent=true, log do pliku (nigdy sam journal).
- hosts/piha/jobs.yaml — deklaracja jednostek host-level na PIHA. Nowy plik, bo
  services.yaml jest dla kontenerow (supervisor dopasowuje jego wpisy do world-state
  i wpis niekontenerowy dryfowalby wiecznie jako missing_service). Nic tego pliku
  nie czyta — istnieje po to, zeby "shadow-deploy family" z otwartego pytania 5
  reconu multiagentowego byla spisana, a nie tylko na nodzie.

Takt indeksowania (Decyzja (d), recon §3.3):
- kb-ingest.timer: 03:30 raz na dobe -> co 2 h. O 03:30 SOLARIA prawie na pewno spi
  (potwierdzone odczytem kb_ingest_embed_skipped 1 z 2026-08-06), a tick dostaje
  teraz etap mailowy: ~60 nowych chunkow na dobe pomijanych kazdej nocy sprawiloby,
  ze backlog rosnie monotonicznie i KbEmbedBacklogGrowing zapala sie NA STALE.
  Co 2 h zamiast stalej godziny — probe Ollamy sam wybiera okno, wiec ktorys tick
  w nie trafi niezaleznie od nawykow operatora.
- cyclic_ingest: etap mailowy (mail_body_ingest --only-unchunked), import miekki,
  wiec venv bez tego pakietu pomija etap zamiast wywracac wrapper. Predykat bledu
  JEST luzniejszy niz wlasne main() tamtego joba i to jedyne takie miejsce w tym
  wrapperze: pojedynczy trwale nieparsowalny mail nie moze zamrozic
  last_success_timestamp i zapalic KbIngestStale na zawsze. Bledy per-mail sa
  publikowane jako kb_ingest_mail_parse_errors, nie chowane.

Obserwowalnosc: KbMailSyncStale (6 h bez udanego ticku). Alert na cisze w skrzynce
ODRZUCONY (decyzja operatora, zgodna z reconem §3.4) — zero nowych maili to legalny
stan skrzynki, a alert zapalajacy sie na zdrowym systemie zostaje wyciszony
i przestaje dzialac wtedy, gdy jest potrzebny.

Dokumentacja:
- kb/services/job-mail-imap-sync.md (OKF), kb/runbooks/mail-sync-run.md — 9 krokow
  pierwszego uruchomienia, w tym checklista 4 punktow [do weryfikacji na zywo]
  z reconu (polityki dostawcow — do sprawdzenia, nie do zgadniecia) oraz pomiar
  STATUS (MESSAGES) na Fastmailu, na ktorym zapada ODLOZONA decyzja o historii.
- kb-mail-pillar.md: KOREKTA JMAP -> IMAP dla Fastmaila jako decyzja 2026-08-06;
  stary zapis zostaje jako historia z data. Zamkniete "unifikacja adaptera"
  i "sizing Gmaila"; otwarte zostaje "sizing Fastmaila" — celowo, bo rozstrzyga
  je pomiar, nie dyskusja.
- kb-m5-faza-mailowa.md: Krok 7 IN PROGRESS + tabela zakresu wdrozonego,
  kb-m5-faza3.md: korekta harmonogramu i sekwencji wrappera,
  pkg-kb-mail.md: rozpisany ze stubu, kb-postgres.md: lista migracji + 005.

Testy: 642 passed (calosc kb-mail, kb-retrieval i jobs). systemd-analyze verify
na timerze przechodzi, OnCalendar=0/2:00:00 normalizuje sie do co 2 h.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-06 15:30:57 +02:00

5.7 KiB

Raw Blame History

okf

type

visibility

status

updated

links

0.1

subsystem

private

active

2026-08-06

Filar maili — projekt (homelab-codex · KB · projekt #1)

Pierwszy filar. Wzorzec referencyjny dla pozostałych (archiwum, embeddingi na SOLARIA, szkielet agenta, deploy). Zasady przekrojowe: patrz kb-00-overview.md.

1. Rdzeń: archiwum, nie RAG

Realna potrzeba to najpierw archiwum, nie „RAG nad mailami". Dwie warstwy, fundamentalnie różne:

Archiwum — surowe, niezmienne, kompletne .eml / Maildir, append-only. To, co chcesz mieć u siebie na zawsze, niezależnie od jakiegokolwiek AI. Asset.
Indeks — pochodny, odtwarzalny, wyrzucalny. Parse → chunk → embed → pgvector. Re-budowalny z archiwum przy lepszym modelu.

2. Dwa żywe źródła (zmiana względem pierwotnego planu)

Gmail nie jest porzucany — zostaje jako konto śmieciowe / loginy / 2FA. Stąd maile mają dwa żywe wejścia:

Fastmail — source: fastmail, adapter IMAP (hasło aplikacji). Primary: tu ląduje sensowna poczta na przyszłość.
Gmail — source: gmail, adapter IMAP (protokół, nie Gmail API → przenośność). Ciągły sync żywej skrzynki.

Korekta 2026-08-06 — Fastmail przez IMAP, nie JMAP. Do tej daty ten dokument (i §7, §9 oraz §10 planu fazy mailowej) przewidywał dla Fastmaila JMAP i osobny jobs/fastmail-poller. Zapis historyczny: „Fastmail — adapter JMAP (read-only token)", 2026-06-24.

Decyzja z 2026-08-06 (recon kb/audits/mail-sync-2026-08-06.md Decyzja (b), zatwierdzona przez operatora) domyka otwartą od czerwca decyzję „unifikacja adaptera" z §9 na rzecz jednego wspólnego IMAP-a dla obu kont, w jednym jobie jobs/mail-imap-sync. Powody: JMAP synchronizuje po state — elegancko i niepotrzebnie przy jednym ticku na godzinę i ~37 mailach na dobę, skoro UIDVALIDITY/UIDNEXT rozwiązuje ten sam problem i tak trzeba go zaimplementować dla Gmaila; jeden adapter to jeden zestaw testów, jedna klasa błędów i jedna ścieżka hardeningu 8-bitowych nagłówków. JMAP nie jest zamknięty na zawsze — koperta i archiwum są protokołowo obojętne, więc wymiana transportu nie dotyka danych.

Plus jednorazowy bulk historyczny Gmaila (eksport „All Mail" / Takeout → surowy dump do archiwum). Operacja odwracalna i niezależna od reszty pipeline'u — robimy pierwsza. Urgency spadła (konto żyje), ale historia warta zassania od razu.

3. Koperta (kontrakt zamrożony)

id        — stabilny identyfikator wiadomości
source    — fastmail | gmail
ts        — UTC (data wiadomości)
geo       — null dla maili (uzupełniane cross-source w warstwie 3)
raw_ref   — wskaźnik do .eml w archiwum
entities[] — otwarte, wypełniane przy ingeście/enrich

Addytywna. Nic poza tym nie usztywniamy.

4. Filtr archiwum → indeks

Archiwizuj wszystko. Indeksuj selektywnie. Gmail śmieciowy (login/2FA/notyfikacje/newslettery) to szum — wpuszczony do wektorów zaśmieca wyszukiwanie i pali GPU na SOLARII. Filtr na wejściu do indeksu:

whitelist/blacklist nadawców i nagłówków (List-Unsubscribe, Auto-Submitted, typowe domeny powiadomień),
progi (np. odrzuć czysto automatyczne),
surowiec zawsze leży w archiwum — filtr nie kasuje, tylko decyduje co trafia do embeddingów.

Filtr jest częścią indeksu (odtwarzalny), nie archiwum.

5. Indexer

parse (.eml) → chunk → embed (bge-m3 na SOLARIA/ollama) → pgvector Retrieval hybrydowy: wektor + filtry metadanych (nadawca, zakres dat, etykieta, source). Załączniki: II tura (MVP = czysty tekst + nagłówki).

6. Agent maili (dedykowany, cienki)

Hybrydowy retrieval: wektor + filtry metadanych.
Wystawia tool/API, które agent interdyscyplinarny (warstwa 4) woła — wzorzec federacji.
Reużywa szkieletu agenta z control-plane (to samo DNA).

7. Deploy

Wszystko w homelab-codex, przez Git na SATURN, konwencja override hosts/<node>/runtime/<svc>/.
Usługi: mail-imap-sync (Fastmail + Gmail, jeden job — korekta 2026-08-06; wcześniej planowane jako osobne jmap-poller + imap-poller), indexer, embed (ollama na SOLARIA), postgres+pgvector, mail-agent; bulk importer jako one-shot job.
Deploy skryptem czytającym inventory/topology.yaml.

8. Kolejność budowy (w obrębie projektu)

✅ Zamroź kopertę + postaw Postgres+pgvector. (2026-06-17)
✅ Bulk Gmail historyczny → archiwum — jobs/gmail-bulk-import/ — KOD GOTOWY (2026-06-24); nie uruchomiony (Takeout ~27 GB na SOLARIA, do transferu na PIHA).
~~Fastmail JMAP live ingest~~ → Fastmail IMAP live sync → archiwum. (korekta 2026-08-06; kod gotowy, pierwszy żywy run po stronie operatora — kb/runbooks/mail-sync-run.md)
Gmail IMAP live sync → archiwum. (j.w. — ten sam job jobs/mail-imap-sync)
Filtr archiwum→indeks.
Indexer (parse → chunk → embed bge-m3) → pgvector.
Cienki agent maili + tool dla warstwy 4.

9. Decyzje otwarte (do przyklepania przed/w trakcie startu)

✅ Sizing Gmaila — ZAMKNIĘTE: 225 030 kopert, archiwum ~27 GB na PIHA (Etap B, 2026-08-06).
✅ Unifikacja adaptera — ZAMKNIĘTE 2026-08-06 na rzecz jednego IMAP-a dla obu kont (Decyzja (b) reconu, uzasadnienie w §2 wyżej).
Sizing Fastmaila — OTWARTE, i celowo: przesądza o tym, czy ciągniemy historię konta czy tylko przyrost. Rozstrzyga pomiar mail-imap-sync --measure, nie zgadywanie — kb/runbooks/mail-sync-run.md §5.
Reguły filtra — startowa lista blacklist domen/nagłówków.
Vector store: pgvector przyklepane (spine).
Embed model: bge-m3 przyklepane.

5.7 KiB Raw Blame History