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,82 @@
+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;
+                CREATE DATABASE pc_upgrade_140_test;
+                CREATE DATABASE pc_upgrade_140_fresh;
+                CREATE DATABASE pc_upgrade_140_code_test;
+                CREATE DATABASE pc_upgrade_140_code_fresh;
+                CREATE DATABASE pc_upgrade_140_vector_test;
+                CREATE DATABASE pc_upgrade_140_vector_fresh;
+                CREATE DATABASE pc_upgrade_140_vector_code_test;
+                CREATE DATABASE pc_upgrade_140_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/candidate-schema-replay.yml

@@ -0,0 +1,70 @@
+name: Candidate schema replay
+
+on:
+  pull_request:
+    paths:
+      - src/powercontext/builtin/persistence/**
+      - src/powercontext/builtin/artifacts/**
+      - tests/builtin/persistence/**
+      - scripts/replay_candidate_migration.py
+      - .github/workflows/candidate-schema-replay.yml
+      - .github/actions/setup-upgrade-oceanbase/**
+      - pyproject.toml
+      - uv.lock
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: candidate-replay-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  replay:
+    name: Candidate replay (${{ matrix.backend }})
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        backend: [sqlite, seekdb, oceanbase]
+    env:
+      POWERCONTEXT_TEST_MIGRATION_SEEKDB: "1"
+      POWERCONTEXT_TEST_MIGRATION_OCEANBASE_URL: mysql+aoceanbase://root%40test:powercontext-e2e@127.0.0.1:2881/pc_migration_probe_candidate_replay?charset=utf8mb4
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: ./.github/actions/setup-python-env
+      - name: Start isolated OceanBase
+        if: matrix.backend == 'oceanbase'
+        uses: ./.github/actions/setup-upgrade-oceanbase
+      - name: Create the scratch database namespace
+        if: matrix.backend == 'oceanbase'
+        run: >-
+          docker exec upgrade-oceanbase
+          obclient -h127.0.0.1 -P2881 -uroot@test -ppowercontext-e2e
+          -e 'CREATE DATABASE pc_migration_probe_candidate_replay'
+      - name: Replay and recover the frozen Candidate conversion without skips
+        run: >-
+          uv run --locked --extra seekdb python scripts/replay_candidate_migration.py
+          ${{ matrix.backend }} --output "$RUNNER_TEMP/candidate-replay"
+      - name: Preserve OceanBase diagnostics
+        if: always() && matrix.backend == 'oceanbase'
+        run: |
+          mkdir -p "$RUNNER_TEMP/candidate-replay"
+          docker logs upgrade-oceanbase > "$RUNNER_TEMP/candidate-replay/oceanbase.log" 2>&1 || true
+          docker stop --timeout 30 upgrade-oceanbase || true
+      - name: Save generated inventories and comparisons
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: candidate-replay-${{ matrix.backend }}-${{ github.sha }}
+          path: ${{ runner.temp }}/candidate-replay/
+          if-no-files-found: error
+          retention-days: 14

.github/workflows/capture-release-schema.yml

@@ -0,0 +1,63 @@
+name: Capture released Server schema
+
+on:
+  pull_request:
+    paths:
+      - scripts/capture_release_schema.py
+      - scripts/upgrade_database_probe.py
+      - scripts/upgrade_process.py
+      - tests/release_upgrades/test_full_server.py
+      - .github/workflows/capture-release-schema.yml
+      - .github/actions/setup-upgrade-oceanbase/**
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-schema-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  capture:
+    name: Capture 1.4.0 (${{ matrix.backend }}, ${{ matrix.configuration }})
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        backend: [sqlite, seekdb, oceanbase]
+        configuration: [full-server-no-vector, full-server-code, full-server-vector, full-server-vector-code]
+    env:
+      PC_UPGRADE_OCEANBASE_URL: mysql+aoceanbase://root%40test:powercontext-e2e@127.0.0.1:2881/pc_upgrade_test?charset=utf8mb4
+    steps:
+      - name: Check out
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: ./.github/actions/setup-python-env
+      - name: Start isolated OceanBase
+        if: matrix.backend == 'oceanbase'
+        uses: ./.github/actions/setup-upgrade-oceanbase
+      - name: Capture installed release without current runtime initialization
+        run: >-
+          .venv/bin/python scripts/upgrade_process.py
+          --parent-pid $$ --timeout 1800 --shutdown-timeout 60 --
+          .venv/bin/python scripts/capture_release_schema.py
+          ${{ matrix.backend }} --configuration ${{ matrix.configuration }}
+          --output "$RUNNER_TEMP/release-schema"
+      - name: Preserve OceanBase diagnostics
+        if: always() && matrix.backend == 'oceanbase'
+        run: |
+          mkdir -p "$RUNNER_TEMP/release-schema"
+          docker logs upgrade-oceanbase > "$RUNNER_TEMP/release-schema/oceanbase.log" 2>&1 || true
+          docker stop --timeout 30 upgrade-oceanbase || true
+      - name: Save source schema and provenance
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: release-1.4.0-${{ matrix.backend }}-${{ matrix.configuration }}-${{ github.sha }}
+          path: ${{ runner.temp }}/release-schema/
+          if-no-files-found: error
+          retention-days: 30

.github/workflows/desktop.yml

@@ -134,13 +134,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' }}