9.6 KiB
title, type, created, status, review_loop_iteration, baseline_commit, context
| title | type | created | status | review_loop_iteration | baseline_commit | context | |
|---|---|---|---|---|---|---|---|
| Нормализовать fingerprint последовательно обновлённой legacy-схемы | bugfix | 2026-09-02 | done | 0 | 2759fde81f |
|
Intent
Problem: Shadow migration production backup блокируется на preflight.legacy_fingerprint, хотя база имеет опубликованный pre-ledger контракт. Fingerprint ошибочно считает ordinal_position частью семантики: после исторических ALTER TABLE ADD/DROP COLUMN физический порядок отличается от fresh-схемы 8318e4b, хотя именованные SQL-контракты эквивалентны.
Approach: Исключить только физический ordinal колонок из детерминированного PostgreSQL-16 fingerprint, пересчитать allowlist по подтверждённым опубликованным схемам и доказать acceptance для fresh и последовательного upgrade-layout. Все значимые свойства схемы и fail-closed shadow gate сохранить.
Boundaries & Constraints
Always: Проверять relation kind, имя/тип/nullability/default каждой колонки, constraints, indexes, non-internal triggers, RLS/policies, состояние internal triggers, index validity/readiness/liveness, persistence и replica identity. Выполнять migration postflight внутри транзакции. До успешной проверки backup не запускать live Compose.
Ask First: Любое ослабление проверки кроме игнорирования несемантического ordinal_position; поддержка схем, которые нельзя связать с опубликованной историей Crank; изменение migration sequence или wire-контракта diagnostics.
Never: Принимать неизвестную/частичную схему, отключать fingerprint, переписывать ledger вручную, применять DDL во время диагностики, выводить raw schema/SQL/rows/credentials или обходить shadow migration.
I/O & Edge-Case Matrix
| Scenario | Input / State | Expected Output / Behavior | Error Handling |
|---|---|---|---|
| Fresh legacy | Fresh-схема последнего pre-ledger релиза | apply выполняет 0 → 13, postflight возвращает current 13 |
Транзакционный rollback при postflight failure |
| Sequential legacy | Те же именованные колонки, но ordinal отличается после исторических ADD/DROP | Считается тем же опубликованным контрактом, данные сохраняются | Не отклоняется только из-за ordinal |
| Structural drift | Изменены имя, тип, default, constraint, index или trigger state | Adoption отклоняется до записи core ledger | partial_sequence / preflight.legacy_fingerprint |
| Foreign/partial DB | Неполный набор Crank relations либо future objects без ledger | Не классифицируется как допустимая legacy-схема | Fail closed без DDL |
Code Map
crates/crank-registry/src/migrations/schema_guard_legacy_v1.rs— формирует catalog JSON и SHA-256; сейчас включаетordinal_position, здесь находится root cause и allowlist.crates/crank-registry/src/migrations/authority.rs— классифицирует ledgerless baseline и выполняет transactional postflight; поведение mutation менять не требуется.crates/crank-registry/tests/integration/migrations/legacy_adoption.rs— positive/negative PostgreSQL-16 evidence; добавить layout с переставленными через ADD/DROP колонками и сохранностью данных.scripts/deploy-community.sh— восстанавливает production backup в isolated PostgreSQL и блокирует live rollout до current 13; сохранить без bypass.- История
a8aa324,5922aea,8a1cc17,2b2ff92,8318e4b— read-only evidence последовательных ADD/DROP дляplatform_api_keysиapproval_requests.
Tasks & Acceptance
Execution:
schema_guard_legacy_v1.rs— убрать ordinal из canonical column item, пересчитать exact SHA allowlist и не менять остальные catalog checks.legacy_adoption.rs— создать regression layout через исторически эквивалентные DROP/ADD операции, доказать preflight0 → 13, сохранность representative rows и current 13.legacy_adoption.rs— сохранить negative evidence для column/default/constraint/index/trigger/RLS drift и отсутствие committed ledger.scripts/deploy-community.sh— повторно проверить итоговым image восстановление backup, непривилегированного owner, apply и строгий current 13.
Acceptance Criteria:
- Given логически эквивалентная опубликованная legacy-схема с другим ordinal, when выполняется shadow migration, then она завершается current 13 и сохраняет данные.
- Given любое семантическое catalog-отличие, when выполняется apply, then транзакция откатывается и core ledger не появляется.
- Given успешный локальный historical-dump shadow run, when fix пушится, then live deployment всё равно запускается только после проверки production backup.
Spec Change Log
Design Notes
ordinal_position отражает физическую историю ALTER TABLE, но Crank обращается к колонкам по именам. Его исключение объединяет fresh и in-place layouts без принятия новых колонок или изменения их контрактов: список column items по-прежнему содержит имя, тип, UDT, nullability и default и сортируется детерминированно.
Verification
Commands:
cargo test -p crank-registry --test integration integration::migrations::legacy_adoption -- --nocapture— positive и fail-closed regression зелёные.cargo test -p crank-registry— полный crate suite зелёный.scripts/check-rust-code-health.sh && scripts/check-community-scope.sh && cargo fmt --all --check && git diff --check— repository gates зелёные.- Production-equivalent Docker shadow run — restore custom dump, owner
NOSUPERUSER, apply0 → 13, exact preflight current 13, representative row preserved. - Финальный
admin-apiimage собран локально какcrank/admin-api:legacy-fingerprint-hotfix; migration binary запускается. Полный restore production backup локально невозможен без самого backup и deploy.env; этот fail-closed шаг остаётся обязательным в pipeline до live Compose.
Suggested Review Order
Нормализация контракта
-
Канонизация сохраняет семантику колонок, исключая только физический ordinal.
schema_guard_legacy_v1.rs:134 -
Пересчитанный allowlist покрывает baseline, оба MCP-layout и extension ledger.
schema_guard_legacy_v1.rs:8
Историческая совместимость
-
Fixture воспроизводит опубликованную последовательность DROP/ADD и реальные ordinal gaps.
legacy_adoption.rs:109 -
Нестандартные sentinel-значения доказывают сохранность данных при миграции.
legacy_adoption.rs:149 -
Явная проверка ordinal гарантирует воспроизведение production-дефекта.
legacy_adoption.rs:167
Границы принятия
-
Первый опубликованный MCP-layout отдельно проходит upgrade до current 13.
legacy_adoption.rs:238 -
Семантический drift по-прежнему отклоняется до создания core ledger.
legacy_adoption.rs:328