fix(cacbg): спирай краула по срок, за да оцелее кешът

[todorkolev]

Какво се счупи

Пуск 31889519937 - пълен краул срещу stage. Падна на 300-минутния таван и загуби всичко:

9  Crawl CACBG (full corpus)     cancelled
10 Save raw CACBG corpus cache   success   <- зелена, а не е записала нищо

В лога на стъпка 10:

/usr/bin/tar: scratch/cacbg/raw/2016y: file changed as we read it
##[warning]Failed to save: "/usr/bin/tar" failed with exit code 1

Три неща се събраха:

1. Таванът уби стъпката, но не и процеса на node - машината накрая докладва Terminate orphan process: pid (2351).
2. Осиротелият краул продължи да пише, докато always() стъпката пускаше tar върху същата папка. tar се отказа.
3. actions/cache/save понижава провала при запис до предупреждение и излиза 0. Стъпката светна зелена.

Пет часа любезно теглене, нула запазени байта, а следващият пуск започва пак от празен кеш.

Колко голям е корпусът всъщност

ADR-0012 предполагаше ~135 000 декларации за 2017-2025. Указателят на регистъра обявява:

комплекти	37 (2015-2026)
декларации	~281 000
стигнати за 300 мин	36 от 37

Разликата идва от *y преизданията в края на годината и от комплектите за съответствие. Тоест студен корпус не се побира в един пуск - това не беше известно, когато таванът беше избран.

Поправката

fetch.mjs приема --deadline-minutes. Изтече ли срокът, краулът спира да раздава работа, изчаква текущите заявки да се приберат и се връща нормално. Дървото е спокойно, tar успява, кешът пази изтегленото, а следващият пуск продължава оттам - fetch.mjs и без това прескача файловете, които са на диска.

Студен корпус става за два пуска вместо за нула.

Срокът се проверява на три места, и трите с отделен тест:

• в началото на всеки комплект, преди mkdir и list.xml - празна папка с кеширан списък би изглеждала на следващия пуск като посетен комплект;
• преди всяка задача в басейна, за да спре в рамките на една заявка на работник;
• след всеки комплект, защото при последния комплект другите две не се задействат.

Спирането по срок е самостоятелна присъда

Не минава през assessCompleteness, и това е нарочно. Спиране точно на граница между комплекти оставя всеки достигнат комплект напълно изтеглен, тоест аритметиката казва „пълен" при липсващи цели години. Гейтът щеше да пусне корпус без 2015-2019 и да излезе 0.

--allow-incomplete също нарочно не го омеква. Този ключ значи „видях този недостиг и го приемам"; будилник, звъннал по средата, не е видяна преценка. Който иска част от корпуса, я взима с --folders и я приема съзнателно.

В заданието

• краулът спира на 240 при таван 300, тъй че на tar му остава цял час;
• нова стъпка проверява, че кешът наистина съществува (lookup-only, нищо не се тегли). Стъпката за запис по конструкция не може да падне, тъй че зелено до нея не е доказателство - точно това ни подведе.

Проверих, че lookup-only и fail-on-cache-miss наистина съществуват в actions/cache/restore на закования SHA, вместо да го предположа.

Тестове

11 в fetch-gate.test.mjs (4 нови), 21 в fetch.test.mjs (4 нови). Часовникът се подава отвън и се движи от подставения четец на заявки - по едно тиктакане на заявка - тъй че „кога" пада срокът се изразява в заявки, а не в реално време.

Шест мутации, всичките убити:

мутация	убита от
гейтът пренебрегва deadlineHit	спиране на граница между комплекти
без проверка в началото на комплекта	пропуснат комплект изяжда бюджета
без проверка в края на комплекта	--allow-incomplete при срок
басейнът пренебрегва shouldStop	срок вътре в комплект
--allow-incomplete омеква срока	--allow-incomplete при срок
проверката е след mkdir	пропуснат комплект изяжда бюджета

Извън обхвата

audit.test.mjs и extract-companies.test.mjs падат и на main, и без тази промяна - packages/shared/src/company-name-key.ts внася ./format без разширение. Не го пипам тук.

---

Втори кръг: поправки по независим преглед

Пуснах промяната на независим преглед. Той намери две неща, които първият вариант не хващаше. И двете са потвърдени с пускане, не по разсъждение.

1. Кешът се самоизяждаше при повторен опит

Ключът беше само run_id. run_id не се сменя при повторен опит - точно за това съществува run_attempt. Проверено емпирично: три пускания в това репо имат attempt 2 при същия run_id.

Записите в Actions кеша са неизменни. Оттам:

опит 1: спира на 240, записва cacbg-raw-X, проверката минава, задачата червена
   ↓ „Re-run failed jobs" - естественият отговор, и точно каквото този PR подканваше
опит 2: възстановява cacbg-raw-X, краули часове, опитва се да пише пак върху X
   → отказ → предупреждение → стъпката ЗЕЛЕНА
   → проверката намира записа от опит 1 и удостоверява загубата като успех

Поправката работеше при ново пускане и се проваляше мълчаливо при повторен опит - разлика между два почти еднакви бутона, никъде неотбелязана. По-лошото: новата проверка щеше да прикрие точно загубата, заради която я добавих.

Ключът вече носи run_id-run_attempt и на трите места. При повторен опит точният ключ не улучва, префиксът cacbg-raw- връща снимката от предишния опит, а записът отива на нов ключ.

2. Пълен корпус се обявяваше за частичен

Спирането се извеждаше от часовника, а не от това дали наистина е задържана работа. Комплект, чиято последна заявка се приземява секунда след бюджета, е изтеглен докрай - нищо не е задържано. Възпроизведено:

"notAttempted": 0, "incomplete": false     ← пълен корпус
✖ CRAWL STOPPED ON ITS DEADLINE
>>> EXIT CODE: 1

В производство това уцелва точно пуска, който довършва корпуса: изход 1, зареждането прескочено, четири часа червено за успяла работа.

pool() вече връща дали е задържал редове, и това решава. Същият опит сега дава изход 0.

3. Гол флаг без стойност

--deadline-minutes без стойност падаше на подразбирането, тоест „без срок" - защитата изключена от печатна грешка, мълчаливо. get() вече гърми. Важи и за --limit, --concurrency, --folders, където беше същото.

Тестовете бяха слаби на две места

Всички тестове за срока вървяха с един работник, а производството - с осем. Мутант, при който само първият работник спазва спирането, оцеляваше: в производство седем от осем щяха да пишат точно в прозореца, запазен за tar.

Тестът за пропуснат комплект минаваше по грешна причина - изход 1 идваше от заварения гейт за пълнота, не от срока. Сега върви с --allow-incomplete, тъй че само срокът може да даде този изход.

37 теста (от 32). Нови: пълен корпус, засякъл срока; срок при 8 работника; точно попадение в границата; голи флагове.

Десет мутации, всичките убити:

мутация	убита от
гейтът пренебрегва deadlineHit	спиране на граница между комплекти
без проверка в началото на комплекта	пропуснат комплект изяжда бюджета
без проверка withheld след басейна	--allow-incomplete при срок
басейнът пренебрегва shouldStop	срок при 8 работника
--allow-incomplete омеква срока	пропуснат комплект изяжда бюджета
само работник 0 спазва срока	срок при 8 работника
>= става >	точно попадение в границата
връщане на бъга от находка 2	пълен корпус, засякъл срока
басейнът твърди, че не е задържал	--allow-incomplete при срок
гол флаг пак подразбира	голи флагове

Коментарът за запаса беше по-уверен от кода

Часовникът тръгва вътре във fetch.mjs, а не при старта на задачата - значи подготовката излиза от 300-те преди минута нула. Спирането може да надскочи с една верига опити. И на пуск, който не удари срока, в същия час трябва да се вместят извличането, износът от D1, двайсетминутният Търговски регистър, разрешаването, одитът, миграциите и изпращането. Записано както си е, с изричното „ако стъпките надолу пораснат, сваляй срока, не вдигай тавана".

Какво съзнателно не влезе

PR-ът прави частичните кешове нормално състояние, а нищо надолу по веригата не различава отрязан корпус от пълен. Заварено свойство, което този PR изостря, но не внася - и одитът за необратимост хваща голямото срутване. Отделно issue, не тук.

[github-actions]

Test coverage

Workspace	Lines	Δ	Branches	Δ	Functions	Statements
apps/etl	75.43%	+1.43pp	63.52%	+5.32pp	70.00%	74.11%
apps/web	91.07%	+0.07pp	82.44%	+0.04pp	91.30%	89.75%
packages/config	92.85%	+0.05pp	72.22%	+0.02pp	92.85%	89.18%
packages/db	94.55%	+0.05pp	79.34%	+0.04pp	87.29%	91.58%
packages/ingest	89.71%	+3.41pp	85.52%	+5.12pp	81.74%	88.14%
packages/shared	95.50%	+0.00pp	80.83%	+0.03pp	92.30%	89.56%
Total (informational)	91.43%	—	81.30%	—	87.21%	89.32%

✅ No workspace dropped below its baseline (tolerance 0.5pp).

📈 Coverage rose by more than 1pp — run node scripts/check-coverage.mjs --update locally and commit coverage-baseline.json to ratchet the threshold up.

[ydimitrof]

Преглед на PR: „спирай краула по срок, за да оцелее кешът"

Обща оценка: силен PR, готов за мърдж след дребна корекция в документацията.

Фаза 0 — Сигурност (сканиране): ЧИСТО

• Няма твърдо кодирани тайни, пароли или токени.
• Няма нови/променени URL адреси извън вече използвания register.cacbg.bg; всички actions/cache/* са пинати по SHA (55cc8345…).
• Няма злонамерени шаблони, backdoor-и или обфускация.
• Няма нови зависимости. Нов таван MAX_CONCURRENCY = 8 реално подобрява сигурността — премахва възможността --concurrency 500 да отвори стотици паралелни връзки към държавен регистър.

Логика (fetch.mjs) — коректна

• pool вече връща дали е задържана работа (i < items.length), а не заключение от часовника — това правилно разграничава „последната заявка е паднала след срока, но корпусът е пълен" (exit 0) от „реален срочен стоп" (exit 1). Разграничението е покрито от тест.
• Проверката за срок е на два места: в началото на цикъла по папки (out-of-budget сет не оставя следа) и след pool (стоп в средата на сет). И двата пътя са тествани, вкл. при concurrency 8.
• Валидацията на опции е стегната: празен флаг (--deadline-minutes без стойност или последван от друг флаг) сега хвърля грешка вместо тихо да падне към подразбиране — правилно.
• --allow-incomplete умишлено НЕ понижава срочния стоп — коректно за платформа за прозрачност.

Тестове — отлични (3.0/3.0)

Тестовете са проектирани да разкриват дефекти, не да минават тривиално: граница на сет, пропуснат list.xml консумиращ бюджета, точно попадане на срока (>=), срок обвързващ ВСЕки работник при concurrency 8, никога недостигнат срок. Инжектираният часовник прави случаите детерминистични. Няма „чийтър" тестове.

Единствена находка (документация, non-blocking)

Абзацът в ADR-0012 за „re-run" противоречи на реалното поведение на новия ключ run_id-run_attempt и на коментара в самия workflow (виж inline коментара). Това е оперативно подвеждащо и трябва да се коригира, но не блокира.

Заключение

Атомарен, добре тестван и добре обоснован PR. Код и тестове: одобрявам. Препоръка: COMMENT — да се изчисти неточността в ADR-0012 преди мърдж, след което PR е за одобрение.