Files
crank/_bmad-output/implementation-artifacts/spec-deploy-legacy-fingerprint-normalization.md
T

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
{project-root}/_bmad-output/project-context.md

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 операции, доказать preflight 0 → 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, apply 0 → 13, exact preflight current 13, representative row preserved.
  • Финальный admin-api image собран локально как 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