feat(migrations): complete the reusable database upgrade framework

.gitattributes

@@ -9,3 +9,8 @@ integrations/dsh/plugins/powercontext/lib/*.js text eol=lf
 integrations/dsh/plugins/powercontext/lib/*.d.ts text eol=lf
 # Generated guidance compares canonical bytes; keep user notes outside its markers untouched.
 integrations/**/skills/powercontext-project-context/** text eol=lf
+# Migration evidence hashes exact resource bytes on every platform.
+src/powercontext/builtin/persistence/migrations/resources/** text eol=lf
+src/powercontext/builtin/persistence/migrations/mysql_resources/** text eol=lf
+src/powercontext/builtin/persistence/migrations/server_resources/** text eol=lf
+src/powercontext/builtin/persistence/migration_resources/** text eol=lf

.github/actions/setup-upgrade-oceanbase/action.yml

@@ -0,0 +1,62 @@
+name: Setup upgrade OceanBase
+description: Start the disposable MySQL tenant used by installed-release upgrade checks
+runs:
+  using: composite
+  steps:
+    - name: Start and verify OceanBase
+      shell: bash
+      env:
+        OCEANBASE_IMAGE: ghcr.io/oceanbase/oceanbase-ce:4.3.5.6-106000012026040916
+      run: |
+        docker run --detach --name upgrade-oceanbase \
+          --publish 127.0.0.1:2881:2881 \
+          --ulimit nofile=65536:65536 \
+          --env MODE=slim \
+          --env OB_DATABASE=pc_upgrade_test \
+          --env OB_TENANT_PASSWORD=powercontext-e2e \
+          "$OCEANBASE_IMAGE"
+        for attempt in $(seq 1 120); do
+          if docker exec upgrade-oceanbase \
+            obclient -h127.0.0.1 -P2881 -uroot@test -ppowercontext-e2e \
+            -Dpc_upgrade_test -e 'SELECT 1' >/dev/null 2>&1; then
+            # The slim image's default 1 GB maximum is too small for the
+            # indexes created across the clean migration acceptance cases.
+            docker exec upgrade-oceanbase \
+              obclient -h127.0.0.1 -P2881 -uroot@sys \
+              -e "ALTER SYSTEM SET datafile_maxsize='8G'; ALTER SYSTEM SET datafile_next='512M'; ALTER SYSTEM SET datafile_size='4G';"
+            datafile_ready=false
+            for config_attempt in $(seq 1 30); do
+              docker exec upgrade-oceanbase \
+                obclient -h127.0.0.1 -P2881 -uroot@sys --batch --skip-column-names \
+                -e "SHOW PARAMETERS WHERE name IN ('datafile_size', 'datafile_maxsize', 'datafile_next');" \
+                > "$RUNNER_TEMP/upgrade-datafile.tsv"
+              if awk '
+                $5 == "datafile_size" && $7 == "4G" { size = 1 }
+                $5 == "datafile_maxsize" && $7 == "8G" { maximum = 1 }
+                $5 == "datafile_next" && $7 == "512M" { increment = 1 }
+                END { exit !(size && maximum && increment) }
+              ' "$RUNNER_TEMP/upgrade-datafile.tsv"; then
+                datafile_ready=true
+                break
+              fi
+              sleep 2
+            done
+            cat "$RUNNER_TEMP/upgrade-datafile.tsv"
+            if [ "$datafile_ready" != true ]; then
+              echo 'OceanBase datafile configuration did not become effective within one minute.' >&2
+              exit 1
+            fi
+            docker exec upgrade-oceanbase \
+              obclient -h127.0.0.1 -P2881 -uroot@test -ppowercontext-e2e \
+              -Dpc_upgrade_test \
+              -e "CREATE DATABASE pc_upgrade_fresh; CREATE DATABASE pc_upgrade_code_test; CREATE DATABASE pc_upgrade_code_fresh; CREATE DATABASE pc_upgrade_vector_test; CREATE DATABASE pc_upgrade_vector_fresh; CREATE DATABASE pc_upgrade_vector_code_test; CREATE DATABASE pc_upgrade_vector_code_fresh; SET GLOBAL recyclebin=OFF; SELECT VERSION(); SHOW VARIABLES LIKE 'ob_compatibility_mode'; SHOW VARIABLES LIKE 'recyclebin';"
+            exit 0
+          fi
+          if [ "$(docker inspect --format '{{.State.Running}}' upgrade-oceanbase)" != true ]; then
+            echo 'OceanBase exited before becoming ready.' >&2
+            exit 1
+          fi
+          sleep 5
+        done
+        echo 'OceanBase did not become ready within 10 minutes.' >&2
+        exit 1

.github/workflows/desktop.yml

@@ -132,13 +132,15 @@ jobs:
             desktop/.artifacts/windows-smoke.json
             desktop/.artifacts/ci-compatibility.json
             desktop/.artifacts/real-server.json
+            desktop/.artifacts/real-server-*/
             desktop/.artifacts/real-cli.json
             desktop/.artifacts/installed-ui.json
             desktop/.artifacts/installed-ui.png
             desktop/.artifacts/installed-ui-driver.log
             desktop/.artifacts/installed-ui-app.log
             desktop/.artifacts/installed-ui-processes.json
             desktop/.artifacts/installed-ui-window.png
+            desktop/.artifacts/installed-ui-server-*/
           # Early validation failures can leave no installer or acceptance evidence.
           # Still reject missing artifacts when every preceding step succeeded.
           if-no-files-found: ${{ job.status == 'success' && 'error' || 'warn' }}

.github/workflows/e2e-harness.yml

@@ -175,6 +175,46 @@ jobs:
             tests/builtin/persistence/test_database_snapshots.py \
             --junitxml=.powercontext/recall-effort-ci/regressions.xml -q -rs
 
+      - name: Recover and maintain the full Server chain on real OceanBase without skips
+        env:
+          POWERCONTEXT_TEST_MIGRATION_OCEANBASE_URL: >-
+            mysql+aoceanbase://root%40test:powercontext-e2e@127.0.0.1:2881/pc_migration_probe_server_recovery?charset=utf8mb4
+        run: |
+          docker exec recall-effort-oceanbase \
+            obclient -h127.0.0.1 -P2881 -uroot@test -ppowercontext-e2e \
+            -Dpowercontext_test -e 'CREATE DATABASE pc_migration_probe_server_recovery'
+          timeout --signal=TERM --kill-after=10s 600s uv run --locked pytest -q -rs \
+            tests/builtin/persistence/test_mysql_migration_runner.py::test_mysql_full_server_interruption_preserves_history_and_original_maintenance \
+            tests/builtin/persistence/test_mysql_migration_runner.py::test_oceanbase_full_server_client_exit_requires_acknowledgement_and_preserves_recovery \
+            -o faulthandler_timeout=180 --durations=10 \
+            -k oceanbase --junitxml=.powercontext/recall-effort-ci/full-server-recovery.xml
+
+      - name: Maintain the registered Server chain on real OceanBase without skips
+        env:
+          POWERCONTEXT_TEST_MIGRATION_OCEANBASE_URL: >-
+            mysql+aoceanbase://root%40test:powercontext-e2e@127.0.0.1:2881/pc_migration_probe_server_recovery?charset=utf8mb4
+        run: |
+          timeout --signal=TERM --kill-after=10s 600s uv run --locked pytest -q -rs \
+            tests/builtin/persistence/test_mysql_migration_runner.py::test_mysql_registered_processing_mode_switch_preserves_revision_and_history \
+            tests/builtin/persistence/test_mysql_migration_runner.py::test_mysql_atomic_compatibility_command_uses_shared_server_upgrade \
+            tests/builtin/persistence/test_mysql_migration_runner.py::test_mysql_registered_projection_repair_preserves_authority_and_revision \
+            tests/builtin/persistence/test_mysql_migration_runner.py::test_mysql_topic_bundle_refuses_managed_server_storage \
+            tests/builtin/persistence/test_mysql_migration_runner.py::test_mysql_managed_identity_initialization_requires_no_ddl \
+            -o faulthandler_timeout=180 --durations=10 \
+            -k oceanbase --junitxml=.powercontext/recall-effort-ci/full-server-maintenance.xml
+          uv run --locked python - <<'PY'
+          from pathlib import Path
+          from xml.etree import ElementTree
+
+          reports = (
+              Path(".powercontext/recall-effort-ci/full-server-recovery.xml"),
+              Path(".powercontext/recall-effort-ci/full-server-maintenance.xml"),
+          )
+          cases = [case for report in reports for case in ElementTree.parse(report).iter("testcase")]
+          if len(cases) != 10 or any(case.find(tag) is not None for case in cases for tag in ("skipped", "failure", "error")):
+              raise SystemExit("All ten native full Server recovery and maintenance scenarios must pass without skips.")
+          PY
+
       - name: Collect the database log
         if: always()
         run: |
@@ -202,7 +242,7 @@ jobs:
       ${{ !cancelled() && (github.event_name != 'workflow_dispatch' || inputs.suite != 'recall-effort') &&
           (needs.changes.result != 'success' || fromJSON(needs.changes.outputs.suites || '{}').database) }}
     runs-on: ubuntu-latest
-    timeout-minutes: 70
+    timeout-minutes: 100
     env:
       OCEANBASE_IMAGE: ghcr.io/oceanbase/oceanbase-ce:4.3.5.6-106000012026040916
       POWERCONTEXT_TEST_MIGRATION_OCEANBASE_URL: >-
@@ -290,13 +330,14 @@ jobs:
             tests/e2e/test_background_metrics.py
 
       - name: Run clean migration evidence, grants and vectors without skips
-        timeout-minutes: 45
+        timeout-minutes: 60
         run: |
           uv run --locked python scripts/run_atomic_memory_clean_migration.py \
             oceanbase --output "$MIGRATION_REPORTS/clean-migration"
 
       - name: Test long-query retrieval and admission without skips
-        timeout-minutes: 10
+        # Eight isolated cases include full Server setup and retain 180s deadlines.
+        timeout-minutes: 30
         run: |
           uv run --locked python scripts/run_atomic_memory_clean_migration.py \
             oceanbase --output "$MIGRATION_REPORTS/long-query" --tests \

.github/workflows/kimi-code-acceptance.yml

@@ -135,6 +135,8 @@ jobs:
           reports.mkdir(exist_ok=True)
           for evidence in (temporary / "kimi-acceptance").glob("*/evidence.json"):
               shutil.copy2(evidence, reports / (evidence.parent.name + ".json"))
+          for evidence in (temporary / "kimi-acceptance").glob("*/server-startup.json"):
+              shutil.copy2(evidence, reports / (evidence.parent.name + "-server-startup.json"))
           PY
 
       - name: Upload controlled acceptance evidence

.github/workflows/master.yml

@@ -19,6 +19,113 @@ jobs:
   changes:
     uses: ./.github/workflows/ci-changes.yml
 
+  upgrade-release-gate:
+    name: Upgrade release gate
+    runs-on: ubuntu-24.04
+    timeout-minutes: 180
+    env:
+      PC_UPGRADE_OCEANBASE_URL: mysql+aoceanbase://root%40test:powercontext-e2e@127.0.0.1:2881/pc_upgrade_test?charset=utf8mb4
+      PC_UPGRADE_OCEANBASE_FRESH_URL: mysql+aoceanbase://root%40test:powercontext-e2e@127.0.0.1:2881/pc_upgrade_fresh?charset=utf8mb4
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+      - name: Verify upgrade policy and gate regressions
+        run: |
+          make upgrade-policy-check
+          uv run pytest -q tests/test_upgrade_release_gate.py tests/test_upgrade_publication.py
+      - name: Build the target artifact
+        run: uv build --out-dir dist
+      - name: Start the isolated upgrade OceanBase environment
+        uses: ./.github/actions/setup-upgrade-oceanbase
+
+      - name: Run declared installed-release acceptance
+        run: >-
+          uv run python scripts/run_upgrade_release_gate.py
+          --output "$RUNNER_TEMP/upgrade-release-evidence"
+      - name: Preserve OceanBase diagnostics
+        if: always()
+        run: |
+          mkdir -p "$RUNNER_TEMP/upgrade-release-evidence"
+          docker logs upgrade-oceanbase > "$RUNNER_TEMP/upgrade-release-evidence/oceanbase.log" 2>&1 || true
+          docker inspect --format '{{json .State}}' upgrade-oceanbase \
+            > "$RUNNER_TEMP/upgrade-release-evidence/oceanbase-state.json" 2>&1 || true
+      - name: Stop the isolated upgrade OceanBase environment
+        if: always()
+        run: docker rm --force upgrade-oceanbase
+      - name: Preserve upgrade acceptance evidence
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: upgrade-release-evidence-${{ github.sha }}
+          path: ${{ runner.temp }}/upgrade-release-evidence/
+          if-no-files-found: error
+          retention-days: 30
+
+  oceanbase-engine-recovery:
+    name: OceanBase engine crash recovery
+    needs: changes
+    if: ${{ !cancelled() && (needs.changes.result != 'success' || fromJSON(needs.changes.outputs.suites || '{}').tests) }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    env:
+      POWERCONTEXT_TEST_MIGRATION_OCEANBASE_URL: mysql+aoceanbase://root%40test:powercontext-e2e@127.0.0.1:2881/pc_migration_probe_engine_crash?charset=utf8mb4
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+      - name: Start an isolated OceanBase engine
+        uses: ./.github/actions/setup-upgrade-oceanbase
+      - name: Bind the destructive probe to this job's owned container
+        run: |
+          docker exec upgrade-oceanbase \
+            obclient -h127.0.0.1 -P2881 -uroot@test -ppowercontext-e2e \
+            -e 'CREATE DATABASE pc_migration_probe_engine_crash;'
+          container_id=$(docker inspect --format '{{.Id}}' upgrade-oceanbase)
+          [[ "$container_id" =~ ^[0-9a-f]{64}$ ]]
+          echo "POWERCONTEXT_TEST_MIGRATION_OCEANBASE_ENGINE_CRASH_ID=$container_id" >> "$GITHUB_ENV"
+      - name: Verify migration recovery after observer SIGKILL
+        run: |
+          mkdir -p "$RUNNER_TEMP/oceanbase-engine-recovery"
+          uv run pytest -q tests/native/test_oceanbase_engine_recovery.py \
+            --junitxml "$RUNNER_TEMP/oceanbase-engine-recovery/junit.xml" \
+            --basetemp "$RUNNER_TEMP/oceanbase-engine-recovery/cases"
+          uv run python - <<'PY'
+          import os
+          from pathlib import Path
+          from xml.etree import ElementTree
+          path = Path(os.environ["RUNNER_TEMP"]) / "oceanbase-engine-recovery/junit.xml"
+          suites = list(ElementTree.parse(path).getroot().iter("testsuite"))
+          assert sum(int(s.get("tests", 0)) for s in suites) == 1
+          assert all(int(s.get(key, 0)) == 0 for s in suites for key in ("failures", "errors", "skipped"))
+          PY
+      - name: Report recovery failures
+        if: failure()
+        run: >-
+          uv run python .github/scripts/report_pytest_failures.py
+          "$RUNNER_TEMP/oceanbase-engine-recovery/junit.xml"
+      - name: Preserve diagnostics and stop the owned engine
+        if: always()
+        run: |
+          mkdir -p "$RUNNER_TEMP/oceanbase-engine-recovery"
+          docker logs upgrade-oceanbase > "$RUNNER_TEMP/oceanbase-engine-recovery/container.log" 2>&1 || true
+          docker stop --timeout 30 upgrade-oceanbase || true
+      - name: Save engine recovery evidence
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: oceanbase-engine-recovery-${{ github.sha }}
+          path: ${{ runner.temp }}/oceanbase-engine-recovery/
+          if-no-files-found: error
+          retention-days: 7
+
   quality:
     timeout-minutes: 20
     runs-on: ubuntu-latest
@@ -277,7 +384,7 @@ jobs:
   code-seekdb:
     needs: changes
     if: ${{ !cancelled() && (needs.changes.result != 'success' || fromJSON(needs.changes.outputs.suites || '{}').database) }}
-    timeout-minutes: 20
+    timeout-minutes: 30
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -298,7 +405,9 @@ jobs:
         run: make code-seekdb-test
 
       - name: Test unified migrations with embedded seekdb
-        timeout-minutes: 10
+        # Full-Server cases run in separate processes and exceed fifteen minutes
+        # in aggregate; each runner keeps its 180-second deadline below.
+        timeout-minutes: 25
         env:
           POWERCONTEXT_TEST_MIGRATION_SEEKDB: "1"
           POWERCONTEXT_TEST_MIGRATION_SQL_LOG: "1"

.github/workflows/native-service.yml

@@ -50,6 +50,9 @@ jobs:
           wheel=$(find dist -name '*.whl' -print -quit)
           uv venv .native-venv
           uv pip install --python .native-venv/bin/python "powercontext[cli,server] @ file://$PWD/$wheel" pytest
+          uv venv .native-source-venv
+          uv pip install --python .native-source-venv/bin/python "powercontext[cli,server] @ https://files.pythonhosted.org/packages/30/bd/463f998f8794bc7f8ff588d47157ca0e62dd03a9f3ae466e2eb34fb66045/powercontext-1.3.0-py3-none-any.whl#sha256=8da7983763f3a6ab80b413c770a4973a46c557a54e1a1fa675099e58d47305e5"
+          echo "POWERCONTEXT_NATIVE_UPGRADE_SOURCE_PYTHON=$PWD/.native-source-venv/bin/python" >> "$GITHUB_ENV"
 
       - name: Exercise the real systemd user lifecycle
         run: >-
@@ -105,6 +108,9 @@ jobs:
           # Finish bytecode compilation during installation, before launchd
           # runs the cold-start lifecycle under its bounded startup deadline.
           uv pip install --compile-bytecode --python .native-venv/bin/python "powercontext[cli,server] @ file://$PWD/$wheel" pytest
+          uv venv .native-source-venv
+          uv pip install --compile-bytecode --python .native-source-venv/bin/python "powercontext[cli,server] @ https://files.pythonhosted.org/packages/30/bd/463f998f8794bc7f8ff588d47157ca0e62dd03a9f3ae466e2eb34fb66045/powercontext-1.3.0-py3-none-any.whl#sha256=8da7983763f3a6ab80b413c770a4973a46c557a54e1a1fa675099e58d47305e5"
+          echo "POWERCONTEXT_NATIVE_UPGRADE_SOURCE_PYTHON=$PWD/.native-source-venv/bin/python" >> "$GITHUB_ENV"
 
       - name: Exercise the real LaunchAgent lifecycle
         run: >-
@@ -157,6 +163,9 @@ jobs:
           $wheelUri = "file:///" + $wheel.Replace('\', '/')
           uv venv .native-venv
           uv pip install --python .native-venv\Scripts\python.exe "powercontext[cli,server] @ $wheelUri" pytest
+          uv venv .native-source-venv
+          uv pip install --python .native-source-venv\Scripts\python.exe "powercontext[cli,server] @ https://files.pythonhosted.org/packages/30/bd/463f998f8794bc7f8ff588d47157ca0e62dd03a9f3ae466e2eb34fb66045/powercontext-1.3.0-py3-none-any.whl#sha256=8da7983763f3a6ab80b413c770a4973a46c557a54e1a1fa675099e58d47305e5"
+          "POWERCONTEXT_NATIVE_UPGRADE_SOURCE_PYTHON=$PWD\.native-source-venv\Scripts\python.exe" >> $env:GITHUB_ENV
 
       - name: Verify binary cursor persistence and restart compatibility
         shell: pwsh