Summary

Implements the platform upgrade system as a single reviewable PR with phase-level commits.

Phases

• Release identity: canonical VERSION, Python and gateway health metadata, Docker image inclusion, and platform_upgrade history migration.
• Migration safety: same-session advisory lock and applied-state recheck, plus read-only plan/dry-run behavior.
• Recovery: encrypted PostgreSQL custom-format and ClickHouse checkpoints with manifests, SHA-256 verification, restore tooling, and explicit rollback.
• Upgrade orchestration: clean-tree and release checks, migration plan, mandatory verified backup, confirmation gates, Compose restart, health verification, and platform verification.
• Operations: reference-only seed mode, maintenance-window documentation, migration documentation corrections, and script documentation.
• Tests: release identity, shell syntax, seed boundaries, checkpoint verification, tamper detection, migration behavior, and source validation.

Verification

• KOKONUT_ALLOW_PLAINTEXT_ENV=true .venv/bin/python -m pytest tests/test_migration.py tests/test_upgrade.py -q
• 23 tests passed.
• KOKONUT_ALLOW_PLAINTEXT_ENV=true .venv/bin/python -m services.migration validate --schemas-only
• 343 migration sources validated.
• bash -n passed for upgrade, rollback, backup, restore, verification, and seed scripts.

Operational notes

• Regular Docker Compose upgrades remain maintenance-window deployments; Swarm-only rolling settings are not used.
• Rollback is operator-confirmed and never automatic.
• Pilot seeding and metric recomputation remain separate from normal upgrades.
• Release version is currently 0.1.0; change it deliberately when defining the first production release.