122 lines
11 KiB
Markdown
122 lines
11 KiB
Markdown
---
|
||
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 перед добавлением; с 2026-11-17 — ready-to-paste текст в completion report, агент не пишет CHANGELOG.md — user-managed); 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 (user-managed, 2026-11-17: ready-to-paste текст в отчёт)
|
||
- [[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 -->
|