obsidian-vault/syntheses/idempotent-wiki-ingest-pipeline.md
2026-09-20 20:40:46 +03:00

122 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
pageType: synthesis
id: synthesis.idempotent-wiki-ingest-pipeline
title: Idempotent-Wiki-Ingest-Pipeline
sourceIds:
- MEMORY.md
- evt_wiki-ingest_1787558280137385335_be1fa714e18eb85ab56e6b87
claims:
- text: "Step 2A (2026-08-24): full backup — `wiki_full_backup.py`: Obsidian vault
+ 5 векторных sqlite (online backup API, НЕ файловая копия) + manifest
(events_db_md5) в ОДИН tar.gz; lease-guard (SKIP при живом in_progress,
rc=0, без артефактов); verify из архива после записи; retention 7d+4w;
`backups-full/`."
status: supported
evidence:
- kind: source-file
sourceId: source.memory
path: MEMORY.md
lines: "174"
note: "snapshot stale (sources/memory.md от 2026-08-22); canonical workspace source: MEMORY.md, буллет Step 2A (wiki_full_backup.py, vault + sqlite через backup API, lease-guard SKIP, verify, retention 7d+4w, backups-full/)"
confidence: 0.95
- kind: source-file
sourceId: source.changelog
path: CHANGELOG.md
lines: "117"
note: "canonical workspace source: CHANGELOG.md, запись Step 2A — один tar.gz, sqlite online backup API (НЕ файловая копия), manifest events_db_md5, lease-guard (rc=0, без артефактов), verify после записи, retention 7d+4w"
confidence: 0.95
updatedAt: 2026-08-24T11:34:57+03:00
- text: "Cron `wiki-full-backup` (id 7c9f7164-8063-46f2-812d-278000bf7e6f): `0 5 *
* *` MSK, command-джоб (wrapper run_full_backup_cron.sh, flock -n, лог
/home/owner/wiki-full-backup/), delivery none, timeout 300s."
status: supported
evidence:
- kind: source-file
sourceId: source.changelog
path: CHANGELOG.md
lines: "122"
note: "canonical workspace source: CHANGELOG.md — cron wiki-full-backup (id 7c9f7164-8063-46f2-812d-278000bf7e6f, 0 5 * * * MSK, command-джоб run_full_backup_cron.sh, delivery none, timeout 300s)"
confidence: 0.95
- kind: source-file
sourceId: source.memory
path: MEMORY.md
lines: "510"
note: "canonical workspace source: MEMORY.md, live-cron-список (актуально 2026-08-24) — wiki-full-backup (ежедневно 05:00 MSK, command-джоб: wrapper + wiki_full_backup.py, flock -n, лог /home/owner/wiki-full-backup/)"
confidence: 0.95
updatedAt: 2026-08-24T11:34:57+03:00
- text: "Ручной baseline-прогон Step 2A 2026-08-24 10:51 MSK:
wiki-full-20260824T075132.tar.gz (39.2M, md5
d71ea8b562c6ec7b2b3a33b47c211b23), 101 vault-файл + 5 sqlite,
restore-verify 106/106 ok, независимый --verify PASS, duration 4s."
status: supported
evidence:
- kind: source-file
sourceId: source.changelog
path: CHANGELOG.md
lines: "123"
note: "canonical workspace source: CHANGELOG.md, верификация — ручной baseline-прогон 2026-08-24 10:51 MSK: rc=0, wiki-full-20260824T075132.tar.gz (39.2M, md5 d71ea8b562c6ec7b2b3a33b47c211b23), 101 vault-файл + 5 sqlite, --verify 106/106 ok, duration 4s"
confidence: 0.95
updatedAt: 2026-08-24T11:34:57+03:00
- text: "Evaluator по Step 2A: PASS, тесты 12/12 (полный сьют 86/86), 4 minor
findings без блокеров (extractall-filter на py<3.11, ts_tag-коллизия,
lease==now-граница, multi in_progress)."
status: supported
evidence:
- kind: source-file
sourceId: source.changelog
path: CHANGELOG.md
lines: "123"
note: "canonical workspace source: CHANGELOG.md — evaluator PASS (2026-08-24): 12/12 тестов, lease-guard-анализ, 0 критичных/major, 4 minor без блокеров"
confidence: 0.95
- kind: source-file
sourceId: source.changelog
path: CHANGELOG.md
lines: "120"
note: "canonical workspace source: CHANGELOG.md, тесты — 12 новых, полный сьют 86 passed, 0 failed (74 старых + 12 новых)"
confidence: 0.95
updatedAt: 2026-08-24T11:34:57+03:00
status: active
updatedAt: 2026-08-24T21:13:50.905Z
confidence: 0.95
---
# Idempotent-Wiki-Ingest-Pipeline
## Notes
<!-- openclaw:human:start -->
<!-- openclaw:human:end -->
## Summary
<!-- openclaw:wiki:generated:start -->
# Idempotent Wiki-Ingest Pipeline
## Summary
Wiki-ingest переведён на fingerprint-based идемпотентный протокол: один file-change-батч = одно событие с детерминированным `event_id` = одна обработка. Параллельные пути (event-driven §16 main-agent и cron `wiki-ingest-event` 30m) конкурируют за один и тот же `event_id` через атомарный claim — дубли ingest исключены. Введён 2026-08-22 (замена mtime-сравнения против last_ingest.json, причины — self-loop из 6 idempotent-циклов за ~8 часов и дубли event-driven+cron).
## Механизм
- **Trigger:** `skills/wiki-ingest/scripts/wiki_ingest_check.py --trigger` — fingerprint (path + `mtime_ns` + size + sha256 контента) против таблицы `file_state`; НЕ mtime-сравнение. Откат mtime на старое значение с прежним контентом всё равно срабатывает (несоответствие hash/размера/mtime).
- **event_id:** `evt_wiki-ingest_{max_mt}_{sha256(batch-json)[:24]}` — детерминирован; cron и agent независимо вычисляют один id.
- **State:** SQLite `skills/wiki-ingest/state/events.db` (WAL + busy_timeout 5000): `processed_events` / `event_files` (снапшот батча на claim) / `file_state` / `pipeline_state`. `last_ingest.json` — только маркер/отладка, на fire не влияет.
- **Протокол:** trigger → `claim <event_id> --by NAME` (claim_token, **lease 7200s (страховочный) + renew heartbeat**; CAS-рекаим при истёкшем lease; `active_lease`/`already_done`/`max_attempts` = тихий skip) → ingest → `complete <event_id> <claim_token>` / `fail <event_id> <claim_token> [reason]`. Основной механизм защиты длинного ingest — renew: worker во время обработки каждые 300с вызывает `renew <event_id> <claim_token>`; при `ok:false` (чужой токен / истёкший lease / другой статус) → **НЕМЕДЛЕННЫЙ abort**: worker перестаёт считать себя владельцем, обработку НЕ продолжает, логирует "lost ownership, aborting".
- **complete** — одна транзакция: `file_state` обновляется только для файлов, не изменившихся с момента claim (в ответе `ingested_files` / `skipped_changed` / `watermark`); перезаписывает `last_ingest.json` как маркер. Ответы **complete и fail** пишут `duration_seconds` (int, now − created_at), `attempts` (int), `batch_size` (int).
- **reason-словарь fail:** `not_found` (событие отсутствует), `already_done` (статус done), `stale_token`, `lease_expired`, `wrong_state`.
- **Dead-letter:** `skills/wiki-ingest/events/failed.jsonl`; max 3 попытки (sweep истёкших lease при каждом trigger); `rearm <event_id>` — ручной перезапуск.
- **Контракт идемпотентности downstream:** `skills/wiki-ingest/README.md` — wiki upsert по source_id/event_id (без дублей страниц); ровно одна CHANGELOG-запись на event_id (проверка grep перед добавлением); MEMORY.md только через заменяемые маркеры `<!-- wiki-ingest:section -->` при реальном изменении финального состояния; volatile-state (counts/timestamps) в MEMORY.md не писать; `skipped_changed`-файлы = необработанные, повтор в следующем цикле.
- **Тесты:** `skills/wiki-ingest/tests/` — полный сьют 86/86 (test_wiki_ingest_check.py 62 + test_wiki_ingest_backup.py 12 + test_wiki_full_backup.py 12, tempfile-изоляция).
## События
- Baseline-событие `evt_wiki-ingest_1787412505516256332_0b0993ada9ac7d08d2832ce9` — посеяно и closed (done, watermark 2026-08-22T21:50:17, file_state 7 строк); после посева `--trigger` → fire:false (up_to_date).
- Второе событие `evt_wiki-ingest_1787425422725853723_78b371f5c278de5c5edaba37` (2026-08-22 22:16 MSK) — первый не-baseline-ингест: upsert этой страницы, одна CHANGELOG-запись, MEMORY.md не тронут.
- Третье событие `evt_wiki-ingest_1787481877263896350_d7e21f9a1f2d981456bbbb05` (2026-08-23, Step 1 lease-защита) — документационное эхо уже завершённой работы: upsert этой страницы, новая CHANGELOG-запись НЕ создавалась.
- Четвёртое событие `evt_wiki-ingest_1787558280137385335_be1fa714e18eb85ab56e6b87` (2026-08-24, Step 2A full backup): worker (setup-agent) упал во время обработки (context overflow, lease жив) → takeover main-agent протоколом `fail → rearm → claim` (token 85f0980a...; alert send_failed — DNS-аномалия Telegram, non-fatal). Ingest: upsert этой страницы (claims Step 2A, kind=event), ровно одна CHANGELOG-запись (2026-08-24 08:10 MSK «Step 2A: full backup» — существует, дубль не создаётся), MEMORY.md не тронут (контент финальное состояние). Побочное событие `evt_wiki-ingest_1787548236297937413_30d50c7bdf7e064bd3d02ef4` (предыдущий батч MEMORY.md) стало `stale_event` при claim'е (fingerprint больше не совпадает с актуальным MEMORY.md) — из реестра удалено штатным механизмом; его содержимое уже в CHANGELOG (запись 08:10) и bridge-импорте sources.
## Related
- [[concepts/Bridge-Mode]] — bookkeeping volatile-состояния vault
- [[concepts/Change-Logging]] — одна CHANGELOG-запись на event_id
- [[entities/Infrastructure]] — live cron set (wiki-ingest-event 30m, wiki-ingest-backup 04:00, wiki-full-backup 05:00)
<!-- openclaw:wiki:generated:end -->
## Related
<!-- openclaw:wiki:related:start -->
- No related pages yet.
<!-- openclaw:wiki:related:end -->