release: finalize unified particle.26

Co-authored-by: Bart Louwers <bart@emeel.net>

.github/workflows/android-ci.yml

@@ -26,7 +26,7 @@ jobs:
     outputs:
       should_skip: ${{ github.event_name != 'workflow_dispatch' && steps.changed-files.outputs.android_any_modified != 'true' }}
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -46,7 +46,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        renderer: [opengl, vulkan]
+        renderer: [opengl, vulkan, multiBackend]
     defaults:
       run:
         working-directory: platform/android
@@ -57,14 +57,14 @@ jobs:
       SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
       SENTRY_DSN: ${{ secrets.SENTRY_DSN_ANDROID }}
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
 
       - uses: ./.github/actions/setup-android-ci
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: ".nvmrc"
 
@@ -169,6 +169,7 @@ jobs:
           case "${{ matrix.renderer }}" in
             opengl) echo "renderer=OpenGL" >> "$GITHUB_ENV" ;;
             vulkan) echo "renderer=Vulkan" >> "$GITHUB_ENV" ;;
+            multiBackend) echo "renderer=MultiBackend" >> "$GITHUB_ENV" ;;
             *) echo "::error ::Unknown renderer '${{ matrix.renderer }}'"; exit 1 ;;
           esac
 
@@ -210,7 +211,7 @@ jobs:
         working-directory: test/android
 
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -255,7 +256,7 @@ jobs:
     if: needs.pre_job.outputs.should_skip != 'true'
 
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -283,7 +284,7 @@ jobs:
     env:
       IS_LOCAL_DEVELOPMENT: false
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -316,7 +317,7 @@ jobs:
       C_COMPILER: aarch64-linux-android26-clang
       BINDGEN_TARGET: aarch64-linux-android26
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -390,7 +391,7 @@ jobs:
 
       # automatically trigger android-release when code is pushed to main
       # and the platform/android/VERSION file has changed
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         if: github.ref == 'refs/heads/main' && github.event_name == 'push'
 
       - name: VERSION file changed

.github/workflows/android-device-test.yml

@@ -78,11 +78,11 @@ jobs:
     runs-on: ubuntu-latest
     if: github.repository_owner == 'maplibre' && github.event.workflow_run.conclusion == 'success'
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: '.nvmrc'
 
@@ -145,7 +145,7 @@ jobs:
 
       - name: Configure AWS Credentials
         if: env.run_device_test == 'true'
-        uses: aws-actions/configure-aws-credentials@517a711dbcd0e402f90c77e7e2f81e849156e31d # v6.2.2
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
         with:
           aws-region: us-west-2
           role-to-assume: ${{ vars.OIDC_AWS_ROLE_TO_ASSUME }}

.github/workflows/android-release.yml

@@ -15,7 +15,7 @@ jobs:
       run:
         working-directory: platform/android
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Validate and set version
         working-directory: .
@@ -52,7 +52,7 @@ jobs:
 
       - name: Create release (draft)
         id: create_release
-        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3.0.1
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         with:
           tag_name: ${{ steps.prepare_release.outputs.version_tag }}
           name: ${{ steps.prepare_release.outputs.version_tag }}
@@ -74,19 +74,20 @@ jobs:
         RENDERER:
           - vulkan
           - opengl
+          - multiBackend
         BUILDTYPE:
           - Release
           - Debug
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: ".nvmrc"
 
-      - uses: actions/setup-java@0f481fcb613427c0f801b606911222b5b6f3083a # v5.5.0
+      - uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5.7.0
         with:
           distribution: "temurin"
           java-version: "17"
@@ -118,7 +119,7 @@ jobs:
              "build/debug-symbols-maplibre-android-${{ matrix.RENDERER }}-${{ env.buildtype }}-$version_tag.tar.gz"
 
       - name: Upload release assets (${{ matrix.RENDERER }}, ${{ matrix.BUILDTYPE }})
-        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3.0.1
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         with:
           tag_name: ${{ needs.android-create-release.outputs.version_tag }}
           fail_on_unmatched_files: true
@@ -133,8 +134,12 @@ jobs:
           if [ "$renderer" = "opengl" ]; then
             ./gradlew :MapLibreAndroid:publishOpengl${{ env.buildtype }}PublicationToMavenCentralRepository
             ./gradlew :MapLibreAndroid:publishDefault${{ env.buildtype }}PublicationToMavenCentralRepository
-          else
+          elif [ "$renderer" = "vulkan" ]; then
             ./gradlew :MapLibreAndroid:publishVulkan${{ env.buildtype }}PublicationToMavenCentralRepository
+          elif [ "$renderer" = "multiBackend" ]; then
+            ./gradlew :MapLibreAndroid:publishMultibackend${{ env.buildtype }}PublicationToMavenCentralRepository
+          else
+            echo "::error ::Unknown renderer '$renderer'"; exit 1
           fi
         env:
           ORG_GRADLE_PROJECT_mavenCentralUsername: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
@@ -149,20 +154,20 @@ jobs:
       - android-build-and-upload-release
     steps:
       - name: Publish release (remove draft)
-        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3.0.1
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         with:
           tag_name: ${{ needs.android-create-release.outputs.version_tag }}
           name: ${{ needs.android-create-release.outputs.version_tag }}
           draft: false
 
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: actions/setup-java@0f481fcb613427c0f801b606911222b5b6f3083a # v5.5.0
+      - uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5.7.0
         with:
           distribution: "temurin"
           java-version: "17"
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: ".nvmrc"
 

.github/workflows/android-testapp-release.yml

@@ -10,7 +10,7 @@ jobs:
   create-android-testapp-release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -30,7 +30,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        renderer: [opengl, vulkan]
+        renderer: [opengl, vulkan, multibackend]
     defaults:
       run:
         working-directory: platform/android
@@ -43,7 +43,7 @@ jobs:
       SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
       SENTRY_DSN: ${{ secrets.SENTRY_DSN_ANDROID }}
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -68,11 +68,11 @@ jobs:
     needs: [android-build-testapp]
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Finalize release (set draft=false)
         run: |

.github/workflows/cache-cleanup.yml

@@ -15,7 +15,7 @@ jobs:
       contents: read
     steps:
       - name: Check out code
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 

.github/workflows/core-release.yml

@@ -14,7 +14,7 @@ jobs:
   create-release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
 
@@ -46,13 +46,13 @@ jobs:
     needs: [create-release]
     runs-on: macos-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
 
-      - run: brew install webp libuv
+      - run: brew install webp libuv llvm
 
-      - uses: taiki-e/install-action@2ca9b94c269419b7b0c711c09d0b21c4e1d51145 # v2.83.1
+      - uses: taiki-e/install-action@ba47c86ac325773530516bb756137ac718732518 # v2.86.5
         with:
           tool: armerge@2
 
@@ -103,14 +103,14 @@ jobs:
           - renderer: vulkan
             runner: { os: ubuntu-24.04-arm, arch: arm64 }
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
 
       - name: Install dependencies
         run: .github/scripts/install-linux-deps
 
-      - uses: taiki-e/install-action@2ca9b94c269419b7b0c711c09d0b21c4e1d51145 # v2.83.1
+      - uses: taiki-e/install-action@ba47c86ac325773530516bb756137ac718732518 # v2.86.5
         with:
           tool: armerge@2
 
@@ -156,7 +156,7 @@ jobs:
       - run: |
           git config --system core.longpaths true
 
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
 

.github/workflows/gh-pages-android-api.yml

@@ -15,11 +15,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
-      - uses: actions/setup-java@0f481fcb613427c0f801b606911222b5b6f3083a # v5.5.0
+      - uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5.7.0
         with:
           distribution: "temurin"
           java-version: "17"
@@ -28,7 +28,7 @@ jobs:
         run: ./gradlew dokkaGenerate
 
       - name: Deploy 🚀
-        uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f # v4.8.0
+        uses: JamesIves/github-pages-deploy-action@fa24774553152dd7873cd16ebd8d959b010c5445 # v4.9.0
         with:
           branch: gh-pages
           folder: platform/android/MapLibreAndroid/build/dokka/html

.github/workflows/gh-pages-android-examples.yml

@@ -17,13 +17,13 @@ jobs:
         shell: bash
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Generate documentation
         run: make mkdocs-build
 
       - name: Deploy 🚀
-        uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f # v4.8.0
+        uses: JamesIves/github-pages-deploy-action@fa24774553152dd7873cd16ebd8d959b010c5445 # v4.9.0
         with:
           branch: gh-pages
           folder: platform/android/site

.github/workflows/gh-pages-cpp-api.yml

@@ -8,7 +8,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: true
 
@@ -20,7 +20,7 @@ jobs:
         run: doxygen
 
       - name: Deploy 🚀
-        uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f # v4.8.0
+        uses: JamesIves/github-pages-deploy-action@fa24774553152dd7873cd16ebd8d959b010c5445 # v4.9.0
         with:
           branch: gh-pages
           folder: docs/doxygen/html

.github/workflows/gh-pages-docc.yml

@@ -15,15 +15,17 @@ on:
 
 jobs:
   gh-pages-docc-build:
-    if: ${{ github.ref_name == 'main' }}
     name: Build DocC Docs
     runs-on: macos-latest
+    if: ${{ github.ref_name == 'main' }}
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          submodules: recursive
 
       - name: Configure AWS Credentials
-        uses: aws-actions/configure-aws-credentials@517a711dbcd0e402f90c77e7e2f81e849156e31d # v6.2.2
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
         with:
           aws-region: us-west-2
           role-to-assume: ${{ vars.OIDC_AWS_ROLE_TO_ASSUME }}
@@ -52,7 +54,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout 🛎️
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Download DocC docs artifacts
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
@@ -67,7 +69,7 @@ jobs:
           rm docs.zip
 
       - name: Deploy DocC documentation (main) 🚀
-        uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f # v4.8.0
+        uses: JamesIves/github-pages-deploy-action@fa24774553152dd7873cd16ebd8d959b010c5445 # v4.9.0
         with:
           branch: gh-pages
           folder: build/docs

.github/workflows/gh-pages-mdbook.yml

@@ -16,7 +16,7 @@ jobs:
     name: Build
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
       - name: Setup mdBook
         uses: peaceiris/actions-mdbook@ee69d230fe19748b7abf22df32acaa93833fad08 # v2.0.0
@@ -40,7 +40,7 @@ jobs:
     name: Deploy
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Download book
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
@@ -48,7 +48,7 @@ jobs:
           path: artifacts/book
 
       - name: Deploy
-        uses: JamesIves/github-pages-deploy-action@d92aa235d04922e8f08b40ce78cc5442fcfbfa2f # v4.8.0
+        uses: JamesIves/github-pages-deploy-action@fa24774553152dd7873cd16ebd8d959b010c5445 # v4.9.0
         with:
           branch: gh-pages
           folder: artifacts/book

.github/workflows/ios-ci.yml

@@ -22,7 +22,7 @@ jobs:
     outputs:
       should_skip: ${{ github.event_name != 'workflow_dispatch' && steps.changed-files-yaml.outputs.ios_any_modified != 'true' }}
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -58,7 +58,7 @@ jobs:
         working-directory: platform/ios
         shell: bash
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: false
           persist-credentials: false
@@ -211,7 +211,7 @@ jobs:
 
       - name: Configure AWS Credentials
         if: github.ref == 'refs/heads/main' && vars.OIDC_AWS_ROLE_TO_ASSUME
-        uses: aws-actions/configure-aws-credentials@517a711dbcd0e402f90c77e7e2f81e849156e31d # v6.2.2
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
         with:
           aws-region: us-west-2
           role-to-assume: ${{ vars.OIDC_AWS_ROLE_TO_ASSUME }}
@@ -236,7 +236,7 @@ jobs:
     runs-on: macos-14
     if: needs.pre_job.outputs.should_skip != 'true'
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
 
@@ -269,7 +269,7 @@ jobs:
     if: needs.pre_job.outputs.should_skip != 'true'
     runs-on: macos-26
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -304,7 +304,7 @@ jobs:
     if: needs.pre_job.outputs.should_skip != 'true'
     runs-on: macos-26
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -366,7 +366,7 @@ jobs:
 
       # Trigger release on main if VERSION file changed
 
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         if: github.ref == 'refs/heads/main'
         with:
           persist-credentials: false

.github/workflows/ios-device-test.yml

@@ -21,7 +21,7 @@ jobs:
     runs-on: ubuntu-24.04
     if: github.repository_owner == 'maplibre' && github.event.workflow_run.conclusion == 'success'
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -52,7 +52,7 @@ jobs:
           files: "${{ matrix.test.xcTestFile }}, ${{ matrix.test.ipaFile }}"
 
       - name: Configure AWS Credentials
-        uses: aws-actions/configure-aws-credentials@517a711dbcd0e402f90c77e7e2f81e849156e31d # v6.2.2
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
         with:
           aws-region: us-west-2
           role-to-assume: ${{ vars.OIDC_AWS_ROLE_TO_ASSUME }}

.github/workflows/ios-release-cocoapods.yml

@@ -14,7 +14,7 @@ jobs:
         working-directory: platform/ios
     runs-on: macos-14
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 

.github/workflows/ios-release.yml

@@ -23,7 +23,7 @@ jobs:
         working-directory: platform/ios
         shell: bash
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
 
@@ -65,7 +65,7 @@ jobs:
         working-directory: platform/ios
         shell: bash
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
 
@@ -104,13 +104,13 @@ jobs:
         working-directory: platform/ios
         shell: bash
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
 
       - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: ".nvmrc"
 
@@ -144,7 +144,7 @@ jobs:
           cat changelog_for_version.md
 
       - name: Configure AWS Credentials
-        uses: aws-actions/configure-aws-credentials@517a711dbcd0e402f90c77e7e2f81e849156e31d # v6.2.2
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
         with:
           aws-region: us-west-2
           role-to-assume: ${{ vars.OIDC_AWS_ROLE_TO_ASSUME }}
@@ -155,7 +155,7 @@ jobs:
 
       - name: Release (GitHub) - Create Draft
         id: github_release
-        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3.0.1
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         with:
           name: ios-v${{ env.version }}
           files: |
@@ -177,6 +177,22 @@ jobs:
           private-key: ${{ secrets.MAPLIBRE_NATIVE_BOT_PRIVATE_KEY }}
           owner: ${{ github.repository_owner }}
 
+      - run: npm install
+        working-directory: .
+
+      - name: Release (CocoaPods)
+        shell: bash -leo pipefail {0}  # so pod is found
+        run: gh workflow run ios-release-cocoapods.yml --field version=${{ env.version }}
+        env:
+         GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish release (remove draft)
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
+        with:
+          tag_name: ios-v${{ env.version }}
+          name: ios-v${{ env.version }}
+          draft: false
+
       - name: Release (Swift Package Index)
         run: |
           echo "::add-mask::${{ steps.generate_token.outputs.token }}"
@@ -192,22 +208,6 @@ jobs:
               "version":"${{ env.version }}",
               "download_url": "https://github.com/maplibre/maplibre-native/releases/download/ios-v${{ env.version }}/MapLibre.dynamic.xcframework.zip"}}'
 
-      - run: npm install
-        working-directory: .
-
-      - name: Release (CocoaPods)
-        shell: bash -leo pipefail {0}  # so pod is found
-        run: gh workflow run ios-release-cocoapods.yml --field version=${{ env.version }}
-        env:
-         GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Publish release (remove draft)
-        uses: softprops/action-gh-release@718ea10b132b3b2eba29c1007bb80653f286566b # v3.0.1
-        with:
-          tag_name: ios-v${{ env.version }}
-          name: ios-v${{ env.version }}
-          draft: false
-
       - name: Write release notifications
         if: github.repository_owner == 'maplibre'
         env:

.github/workflows/ios-testapp-release.yml

@@ -15,7 +15,7 @@ jobs:
     runs-on: macos-26
     timeout-minutes: 90
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -49,7 +49,7 @@ jobs:
           test -f bazel-bin/platform/ios/app-swift/MapLibreApp.ipa
 
       - name: Upload app to TestFlight
-        uses: apple-actions/upload-testflight-build@1ad58030672057aa084b4e96beb6f7a8c627f9e6 # v5.2.1
+        uses: apple-actions/upload-testflight-build@5e75ff58276689011512ba87a381d93dc67dbcf8 # v5.3.0
         with:
           app-path: bazel-bin/platform/ios/app-swift/MapLibreApp.ipa
           issuer-id: ${{ vars.APPSTORE_ISSUER_ID }}

.github/workflows/labeler.yml

@@ -9,4 +9,4 @@ jobs:
       pull-requests: write
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/labeler@b8dd2d9be0f68b860e7dae5dae7d772984eacd6d # v6.2.0
+    - uses: actions/labeler@bf12e9b00b37c5c0ca2b87b79b2daf7891dbda13 # v7.0.0

.github/workflows/linux-ci.yml

@@ -33,7 +33,7 @@ jobs:
     outputs:
       should_skip: ${{ github.event_name != 'workflow_dispatch' && steps.changed-files.outputs.linux_any_modified != 'true' }}
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -66,20 +66,20 @@ jobs:
             rust: true
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+        uses: github/codeql-action/init@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8
         with:
           languages: cpp
 
       - name: Install dependencies
         run: .github/scripts/install-linux-deps
 
-      - uses: taiki-e/install-action@2ca9b94c269419b7b0c711c09d0b21c4e1d51145 # v2.83.1
+      - uses: taiki-e/install-action@ba47c86ac325773530516bb756137ac718732518 # v2.86.5
         with:
           tool: armerge@2
 
@@ -156,7 +156,7 @@ jobs:
       # CodeQL
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+        uses: github/codeql-action/analyze@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8
         with:
           category: "/language:cpp"
 
@@ -199,7 +199,7 @@ jobs:
   linux-coverage:
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -215,7 +215,7 @@ jobs:
             ${{ runner.os }}-bazel-
           path: ~/.cache/bazel
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: '.nvmrc'
 
@@ -249,7 +249,7 @@ jobs:
       - linux-build-and-test
       - linux-coverage
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - if: github.event_name == 'pull_request'
         uses: ./.github/actions/save-pr-number

.github/workflows/macos-ci.yml

@@ -69,7 +69,7 @@ jobs:
         shell: bash
 
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           fetch-depth: 0
@@ -106,7 +106,7 @@ jobs:
             name: wgpu
 
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false

.github/workflows/macos-release.yml

@@ -23,7 +23,7 @@ jobs:
         working-directory: platform/macos
         shell: bash
     steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
         with:
           submodules: recursive
 
@@ -56,7 +56,7 @@ jobs:
         working-directory: .
 
       - name: Upload artifact
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: xcframework
           path: |
@@ -70,7 +70,7 @@ jobs:
         working-directory: platform/macos
         shell: bash
     steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
         with:
           submodules: recursive
 
@@ -92,7 +92,7 @@ jobs:
         working-directory: .
 
       - name: Upload artifact
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: xcframework-static
           path: |
@@ -111,13 +111,13 @@ jobs:
         working-directory: platform/macos
         shell: bash
     steps:
-      - uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v4
         with:
           submodules: recursive
 
       - uses: actions/download-artifact@v8
 
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v4
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v4
         with:
           node-version-file: ".nvmrc"
 
@@ -153,7 +153,7 @@ jobs:
           cat changelog_for_version.md
 
       - name: Release (GitHub) - Create Draft
-        uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2.6.1
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         with:
           name: macos-v${{ env.version }}
           files: |
@@ -167,7 +167,7 @@ jobs:
           draft: true
 
       - name: Publish release (remove draft)
-        uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2.6.1
+        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         with:
           tag_name: macos-v${{ env.version }}
           name: macos-v${{ env.version }}

.github/workflows/node-ci.yml

@@ -100,7 +100,7 @@ jobs:
         run: git config --global core.longpaths true
 
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -141,7 +141,7 @@ jobs:
           /usr/sbin/update-ccache-symlinks
 
       - name: Use Node.js from nvmrc
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: 'platform/node/.nvmrc'
 

.github/workflows/node-release.yml

@@ -17,12 +17,12 @@ jobs:
       run:
         shell: bash
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Use Node.js from nvmrc
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: 'platform/node/.nvmrc'
 
@@ -50,7 +50,7 @@ jobs:
       run:
         shell: bash
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -118,7 +118,7 @@ jobs:
         run: git config --global core.longpaths true
 
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -159,7 +159,7 @@ jobs:
           /usr/sbin/update-ccache-symlinks
 
       - name: Use Node.js from nvmrc
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: 'platform/node/.nvmrc'
 
@@ -297,12 +297,12 @@ jobs:
         shell: bash
 
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Use Node.js from nvmrc
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: 'platform/node/.nvmrc'
           registry-url: 'https://registry.npmjs.org'

.github/workflows/pr-bloaty-ios.yml

@@ -19,14 +19,14 @@ jobs:
     outputs:
       should_skip: ${{ steps.parent_workflow.outputs.was_skipped_or_cancelled }}
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           sparse-checkout: |
             .github
             .nvmrc
           persist-credentials: false
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: '.nvmrc'
 
@@ -45,7 +45,7 @@ jobs:
     if: needs.pre_job.outputs.should_skip == 'false'
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -85,7 +85,7 @@ jobs:
 
       - name: Configure AWS Credentials
         if: vars.OIDC_AWS_ROLE_TO_ASSUME
-        uses: aws-actions/configure-aws-credentials@517a711dbcd0e402f90c77e7e2f81e849156e31d # v6.2.2
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
         with:
           aws-region: us-west-2
           role-to-assume: ${{ vars.OIDC_AWS_ROLE_TO_ASSUME }}

.github/workflows/pr-linux-tests.yml

@@ -22,14 +22,14 @@ jobs:
     outputs:
       should_skip: ${{ steps.parent_workflow.outputs.was_skipped_or_cancelled }}
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           sparse-checkout: |
             .github
             .nvmrc
           persist-credentials: false
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: '.nvmrc'
 
@@ -48,7 +48,7 @@ jobs:
     if: needs.pre_job.outputs.should_skip == 'false'
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -95,7 +95,7 @@ jobs:
 
       - name: Configure AWS Credentials
         if: github.ref == 'refs/heads/main' && vars.OIDC_AWS_ROLE_TO_ASSUME
-        uses: aws-actions/configure-aws-credentials@517a711dbcd0e402f90c77e7e2f81e849156e31d # v6.2.2
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
         with:
           aws-region: us-west-2
           role-to-assume: ${{ vars.OIDC_AWS_ROLE_TO_ASSUME }}
@@ -139,7 +139,7 @@ jobs:
     if: needs.pre_job.outputs.should_skip == 'false'
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: true
           persist-credentials: false
@@ -170,7 +170,7 @@ jobs:
 
       - name: Configure AWS Credentials
         if: github.ref == 'refs/heads/main' && vars.OIDC_AWS_ROLE_TO_ASSUME
-        uses: aws-actions/configure-aws-credentials@517a711dbcd0e402f90c77e7e2f81e849156e31d # v6.2.2
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
         with:
           aws-region: us-west-2
           role-to-assume: ${{ vars.OIDC_AWS_ROLE_TO_ASSUME }}

.github/workflows/qt-ci.yml

@@ -104,7 +104,7 @@ jobs:
         run: git config --global core.longpaths true
 
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           path: source
           submodules: recursive

.github/workflows/rust-ci.yaml

@@ -7,6 +7,10 @@ on:
     branches: [ main ]
   workflow_dispatch:
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 defaults:
   run:
     working-directory: rustutils/
@@ -23,9 +27,9 @@ jobs:
           - os: windows-latest
           - os: ubuntu-latest
     steps:
-      - uses: taiki-e/install-action@2ca9b94c269419b7b0c711c09d0b21c4e1d51145 # v2.83.1
+      - uses: taiki-e/install-action@ba47c86ac325773530516bb756137ac718732518 # v2.86.5
         with: { tool: just }
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - run: just -v ci-test
@@ -34,9 +38,9 @@ jobs:
     name: Rust tests MSRV (Minimal Supported Rust Version)
     runs-on: ubuntu-latest
     steps:
-      - uses: taiki-e/install-action@2ca9b94c269419b7b0c711c09d0b21c4e1d51145 # v2.83.1
+      - uses: taiki-e/install-action@ba47c86ac325773530516bb756137ac718732518 # v2.86.5
         with: { tool: just }
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - name: Read crate metadata

.github/workflows/upload-coverage.yml

@@ -12,14 +12,14 @@ jobs:
     outputs:
       should_run: ${{ !steps.parent_workflow.outputs.was_skipped_or_cancelled }}
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           sparse-checkout: |
             .github
             .nvmrc
           persist-credentials: false
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: '.nvmrc'
 
@@ -38,7 +38,7 @@ jobs:
     if: needs.pre_job.outputs.should_run == 'true'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 

.github/workflows/validate-pr-title.yml

@@ -9,9 +9,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: ".nvmrc"
 

.github/workflows/validate-scripts.yml

@@ -9,11 +9,11 @@ jobs:
   validate-scripts:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version-file: ".nvmrc"
 

.github/workflows/windows-ci.yml

@@ -37,7 +37,7 @@ jobs:
       - run: |
           git config --system core.longpaths true
 
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -62,7 +62,7 @@ jobs:
       - run: |
           git config --system core.longpaths true
 
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           sparse-checkout: |
             platform/windows/vendor
@@ -118,19 +118,19 @@ jobs:
       - run: |
           git config --system core.longpaths true
 
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+        uses: github/codeql-action/init@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8
         with:
           languages: cpp
 
       - uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1.13.0
 
-      - uses: mozilla-actions/sccache-action@9e7fa8a12102821edf02ca5dbea1acd0f89a2696 # v0.0.10
+      - uses: mozilla-actions/sccache-action@fc920bf0ec8de6ee65d409111f7ec508035751ba # v0.0.11
 
       - name: Initialize sccache
         run: |
@@ -167,7 +167,7 @@ jobs:
       # CodeQL
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+        uses: github/codeql-action/analyze@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8
         with:
           category: "/language:cpp"
 
@@ -255,7 +255,7 @@ jobs:
           git config --system core.longpaths true
           git config --system core.autocrlf input
 
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           submodules: recursive
           persist-credentials: false
@@ -279,11 +279,11 @@ jobs:
             libuv:p
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+        uses: github/codeql-action/init@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8
         with:
           languages: cpp
 
-      - uses: mozilla-actions/sccache-action@9e7fa8a12102821edf02ca5dbea1acd0f89a2696 # v0.0.10
+      - uses: mozilla-actions/sccache-action@fc920bf0ec8de6ee65d409111f7ec508035751ba # v0.0.11
 
       - name: Initialize sccache
         run: |
@@ -308,7 +308,7 @@ jobs:
       # CodeQL
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@99df26d4f13ea111d4ec1a7dddef6063f76b97e9 # v4.37.0
+        uses: github/codeql-action/analyze@db488ddef3bf6cb639b32c2e9a7c0a7ea8271d28 # v4.37.8
         with:
           category: "/language:cpp"
 

ARCHITECTURE.md

@@ -10,7 +10,7 @@ MapLibre Native uses a monolithic repository that houses both core C++ code and
 
 ## Core cross-platform C++ code
 
-In the repository, core C++ code is contained in the `include` and `src` directories. The former includes headers that are considered to make up the "public" core C++ API, while the latter includes `.cpp` implementation files and headers that are private to the implementation. Within both directories, files are nested under an `mbgl` directory, which has various subdirectories based on areas of functionality. Both public and private headers therefore can (and should) always be included with the form `#include <mbgl/___/___.hpp>`.
+In the repository, core C++ code is contained in the `include` and `src` directories. The former includes headers that are considered to make up the "public" core C++ API, while the latter includes `.cpp` implementation files and headers that are private to the implementation. Within both directories, files are nested under an `mbgl` directory, which has various subdirectories based on areas of functionality. Both public and private headers therefore can (and should) always be included with the form `#include <mln/___/___.hpp>`.
 
 ## Platform specific code
 
@@ -24,7 +24,7 @@ Code and build scripts belonging to platform SDKs are contained in the `platform
 ## Other directories
 
 - `benchmark` contains the performance tests built using https://github.com/google/benchmark/. The code under this directory builds the `mbgl-benchmark-test` executable to execute the benchmark tests.
-  - The entry point of this executable is `platform/default/src/mbgl/benchmark/main.cpp -> benchmark/src/mbgl/benchmark/benchmark.cpp`.
+  - The entry point of this executable is `platform/default/src/mln/benchmark/main.cpp -> benchmark/src/mln/benchmark/benchmark.cpp`.
   - iOS SDK runs benchmark test through a separate app named `BenchmarkApp`.
   - Android SDK does not have benchmark test.
 - `bin` contains the code for tools like `mbgl-cache`, `mbgl-offline`, and `mbgl-render`.
@@ -142,4 +142,4 @@ To minimize data races and invalid memory access, we aim for zero shared memory
 
 Invoking a task on another thread itself creates an ownership obligation: the responsibility for the work happening on the other thread. This ownership is represented by the invocation method returning `std::unique_ptr<AsyncTask>`. Destroying this object indicates that the result of the task is no longer required: the callback is guaranteed not to be called, and the work on the other thread may be aborted (if doing so is convenient).
 
-All this is implemented by [Thread](https://github.com/mapbox/mapbox-gl-native/blob/master/src/mbgl/util/thread.hpp) and [RunLoop](https://github.com/mapbox/mapbox-gl-native/blob/master/include/mbgl/util/run_loop.hpp).
+All this is implemented by [Thread](https://github.com/mapbox/mapbox-gl-native/blob/master/src/mln/util/thread.hpp) and [RunLoop](https://github.com/mapbox/mapbox-gl-native/blob/master/include/mln/util/run_loop.hpp).

CHANGELOG.md

@@ -29,6 +29,10 @@
 ### 🐞 Bug fixes
 
 - *...Add new stuff here...*
+- [core] Draw numbers and short uppercase codes upright in vertical CJK line labels ([#4565](https://github.com/maplibre/maplibre-native/issues/4565)), compat to [maplibre-gl-js#8205](https://github.com/maplibre/maplibre-gl-js/pull/8205).
+- [core] Fix `ImageSource` not rendering across world copies ([#4508](https://github.com/maplibre/maplibre-native/issues/4508)).
+- [core] Repaint data-driven symbol paint properties after feature-state updates.
+- [core] Accept alpha values in legacy comma-separated `hsl()` colors ([#4434](https://github.com/maplibre/maplibre-native/issues/4434)).
 - [core] Fix thread-unsafe headless OpenGL display singleton initialization [#4332](https://github.com/maplibre/maplibre-native/pull/4332)
 - [macos] Fix `mlt-cpp` and `mbgl-vendor-icu` not being included in the amalgamation
 - [core] Fix memory access violation exception in vector_tile_data.cpp [#632](https://github.com/maplibre/maplibre-native/pull/632)
@@ -85,7 +89,7 @@
 
 - [ios, macos] Allow specifying multiple fonts or font families for local font rendering ([#16253](https://github.com/mapbox/mapbox-gl-native/pull/16253))
 
-  By default, CJK characters are now set in the font specified by the `text-font` layout property. If the named font is not installed on the device or bundled with the application, the characters are set in one of the fallback fonts passed into the `localFontFamily` parameter of `mbgl::Renderer::Renderer()` and `mbgl::MapSnapshotter::MapSnapshotter()`. This parameter can now contain a list of font family names, font display names, and font PostScript names, each name separated by a newline.
+  By default, CJK characters are now set in the font specified by the `text-font` layout property. If the named font is not installed on the device or bundled with the application, the characters are set in one of the fallback fonts passed into the `localFontFamily` parameter of `mln::Renderer::Renderer()` and `mln::MapSnapshotter::MapSnapshotter()`. This parameter can now contain a list of font family names, font display names, and font PostScript names, each name separated by a newline.
 
 ### 🐞 Bug fixes
 
@@ -139,7 +143,7 @@
 
 - [core][tile mode] Fix variable placement for labels with the `icon-text-fit` property set ([#16382](https://github.com/mapbox/mapbox-gl-native/pull/16382))
 
-  The `symbolIntersectsTileEdges()` util in `mbgl::TilePlacement` now considers icon shift for the variable symbols with enabled icon-text-fit setting, thus providing more accurate results.
+  The `symbolIntersectsTileEdges()` util in `mln::TilePlacement` now considers icon shift for the variable symbols with enabled icon-text-fit setting, thus providing more accurate results.
 
 - [core] Correctly log a warning instead of crashing when a non-existent image is attempted to be removed. ([#16391](https://github.com/mapbox/mapbox-gl-native/pull/16391))
 
@@ -170,7 +174,7 @@
 - [android] Add jni binding for styleable snapshotter ([#16286](https://github.com/mapbox/mapbox-gl-native/pull/16286))
 
 - [core] Ability to set generic layer properties using setProperty method ([#16324](https://github.com/mapbox/mapbox-gl-native/pull/16324))
-  This change enables the following new keys for the `mbgl::Layer::setProperty()` API:
+  This change enables the following new keys for the `mln::Layer::setProperty()` API:
   - "filter" invokes `setFilter()`
   - "minzoom" invokes `setMinZoom()`
   - "maxzoom" invokes `setMaxZoom()`
@@ -252,7 +256,7 @@
 
  - Fixed using of the `in` expression as a layer filter ([#16272](https://github.com/mapbox/mapbox-gl-native/pull/16272))
 
-  The bug was caused by `mbgl::style::conversion::isExpression()` always returning `false` for the `in` expression.
+  The bug was caused by `mln::style::conversion::isExpression()` always returning `false` for the `in` expression.
 
 ### 🧩  Architectural changes
 
@@ -296,9 +300,9 @@
 
 ##### ⚠️  Breaking changes
 
-- Changes to `mbgl::FileSourceManager::getFileSource()` ([#16238](https://github.com/mapbox/mapbox-gl-native/pull/16238))
+- Changes to `mln::FileSourceManager::getFileSource()` ([#16238](https://github.com/mapbox/mapbox-gl-native/pull/16238))
 
-  It returns now `mbgl::PassRefPtr<FileSource>` (previously was `std::shared_ptr<FileSource>`) in order to enforce keeping the strong reference to the returned object.
+  It returns now `mln::PassRefPtr<FileSource>` (previously was `std::shared_ptr<FileSource>`) in order to enforce keeping the strong reference to the returned object.
 
   Breaking code example:
   `auto fs = FileSourceManager::getFileSource(); fs->..`
@@ -306,9 +310,9 @@
   Possible fix:
   `std::shared_ptr<FileSource> fs = `;
 
-- The `mbgl::OnlineFileSource` class cannot be used directly ([#16238](https://github.com/mapbox/mapbox-gl-native/pull/16238))
+- The `mln::OnlineFileSource` class cannot be used directly ([#16238](https://github.com/mapbox/mapbox-gl-native/pull/16238))
 
-  Clients must use the parent `mbgl::FileSource` interface instead.
+  Clients must use the parent `mln::FileSource` interface instead.
 
   Breaking code example:
   `std::shared_ptr<OnlineFileSource> onlineSource = std::static_pointer_cast<OnlineFileSource>(FileSourceManager::get()->getFileSource(..));`

benchmark/CMakeLists.txt

@@ -9,7 +9,7 @@ add_library(
     ${PROJECT_SOURCE_DIR}/benchmark/parse/tile_mask.benchmark.cpp
     ${PROJECT_SOURCE_DIR}/benchmark/parse/vector_tile.benchmark.cpp
     ${PROJECT_SOURCE_DIR}/benchmark/renderer/group_layers.benchmark.cpp
-    ${PROJECT_SOURCE_DIR}/benchmark/src/mbgl/benchmark/benchmark.cpp
+    ${PROJECT_SOURCE_DIR}/benchmark/src/mln/benchmark/benchmark.cpp
     ${PROJECT_SOURCE_DIR}/benchmark/storage/offline_database.benchmark.cpp
     ${PROJECT_SOURCE_DIR}/benchmark/util/tilecover.benchmark.cpp
     ${PROJECT_SOURCE_DIR}/benchmark/util/color.benchmark.cpp

benchmark/api/query.benchmark.cpp

@@ -1,17 +1,17 @@
 #include <benchmark/benchmark.h>
 
-#include <mbgl/map/map.hpp>
-#include <mbgl/map/map_options.hpp>
-#include <mbgl/gfx/headless_frontend.hpp>
-#include <mbgl/renderer/renderer.hpp>
-#include <mbgl/style/style.hpp>
-#include <mbgl/style/image.hpp>
-#include <mbgl/storage/network_status.hpp>
-#include <mbgl/util/image.hpp>
-#include <mbgl/util/io.hpp>
-#include <mbgl/util/run_loop.hpp>
+#include <mln/map/map.hpp>
+#include <mln/map/map_options.hpp>
+#include <mln/gfx/headless_frontend.hpp>
+#include <mln/renderer/renderer.hpp>
+#include <mln/style/style.hpp>
+#include <mln/style/image.hpp>
+#include <mln/storage/network_status.hpp>
+#include <mln/util/image.hpp>
+#include <mln/util/io.hpp>
+#include <mln/util/run_loop.hpp>
 
-using namespace mbgl;
+using namespace mln;
 
 namespace {
 

benchmark/api/render.benchmark.cpp

@@ -1,24 +1,24 @@
 #include <benchmark/benchmark.h>
 
-#include <mbgl/gfx/headless_frontend.hpp>
-#include <mbgl/map/map.hpp>
-#include <mbgl/map/map_observer.hpp>
-#include <mbgl/map/map_options.hpp>
-#include <mbgl/renderer/renderer.hpp>
-#include <mbgl/storage/network_status.hpp>
-#include <mbgl/storage/resource_options.hpp>
-#include <mbgl/style/image.hpp>
-#include <mbgl/style/layers/symbol_layer.hpp>
-#include <mbgl/style/sources/geojson_source.hpp>
-#include <mbgl/style/style.hpp>
-#include <mbgl/util/image.hpp>
-#include <mbgl/util/io.hpp>
-#include <mbgl/util/run_loop.hpp>
+#include <mln/gfx/headless_frontend.hpp>
+#include <mln/map/map.hpp>
+#include <mln/map/map_observer.hpp>
+#include <mln/map/map_options.hpp>
+#include <mln/renderer/renderer.hpp>
+#include <mln/storage/network_status.hpp>
+#include <mln/storage/resource_options.hpp>
+#include <mln/style/image.hpp>
+#include <mln/style/layers/symbol_layer.hpp>
+#include <mln/style/sources/geojson_source.hpp>
+#include <mln/style/style.hpp>
+#include <mln/util/image.hpp>
+#include <mln/util/io.hpp>
+#include <mln/util/run_loop.hpp>
 
 #include <sstream>
 #include <optional>
 
-using namespace mbgl;
+using namespace mln;
 
 namespace {
 
@@ -124,7 +124,7 @@ static void API_renderStill_recreate_map_2(::benchmark::State& state) {
 }
 
 static void API_renderStill_multiple_sources(::benchmark::State& state) {
-    using namespace mbgl::style;
+    using namespace mln::style;
     RenderBenchmark bench;
     HeadlessFrontend frontend{size, pixelRatio};
     Map map{frontend,

benchmark/function/camera_function.benchmark.cpp

@@ -1,12 +1,12 @@
 #include <benchmark/benchmark.h>
 
-#include <mbgl/style/conversion/json.hpp>
-#include <mbgl/style/conversion/function.hpp>
-#include <mbgl/style/conversion/property_value.hpp>
-#include <mbgl/style/conversion_impl.hpp>
+#include <mln/style/conversion/json.hpp>
+#include <mln/style/conversion/function.hpp>
+#include <mln/style/conversion/property_value.hpp>
+#include <mln/style/conversion_impl.hpp>
 
-using namespace mbgl;
-using namespace mbgl::style;
+using namespace mln;
+using namespace mln::style;
 
 static std::string createFunctionJSON(size_t stopCount) {
     std::string stops = "[";

benchmark/function/composite_function.benchmark.cpp

@@ -1,14 +1,14 @@
 #include <benchmark/benchmark.h>
 
-#include <mbgl/benchmark/stub_geometry_tile_feature.hpp>
+#include <mln/benchmark/stub_geometry_tile_feature.hpp>
 
-#include <mbgl/style/conversion/json.hpp>
-#include <mbgl/style/conversion/function.hpp>
-#include <mbgl/style/conversion/property_value.hpp>
-#include <mbgl/style/conversion_impl.hpp>
+#include <mln/style/conversion/json.hpp>
+#include <mln/style/conversion/function.hpp>
+#include <mln/style/conversion/property_value.hpp>
+#include <mln/style/conversion_impl.hpp>
 
-using namespace mbgl;
-using namespace mbgl::style;
+using namespace mln;
+using namespace mln::style;
 
 static std::string createFunctionJSON(size_t stopCount) {
     std::string stops = "[";

benchmark/function/source_function.benchmark.cpp

@@ -1,13 +1,13 @@
 #include <benchmark/benchmark.h>
 
-#include <mbgl/benchmark/stub_geometry_tile_feature.hpp>
+#include <mln/benchmark/stub_geometry_tile_feature.hpp>
 
-#include <mbgl/style/conversion/json.hpp>
-#include <mbgl/style/conversion/property_value.hpp>
-#include <mbgl/style/conversion_impl.hpp>
+#include <mln/style/conversion/json.hpp>
+#include <mln/style/conversion/property_value.hpp>
+#include <mln/style/conversion_impl.hpp>
 
-using namespace mbgl;
-using namespace mbgl::style;
+using namespace mln;
+using namespace mln::style;
 
 static std::string createFunctionJSON(size_t stopCount) {
     std::string stops = "[";

benchmark/include/mln/benchmark.hpp

@@ -1,7 +1,7 @@
 #pragma once
 
-namespace mbgl {
+namespace mln {
 
 int runBenchmark(int argc, char* argv[]);
 
-} // namespace mbgl
+} // namespace mln

benchmark/ios/ios_test_runner.cpp

@@ -1,8 +1,8 @@
 #include <ios_test_runner.hpp>
 
-#include <mbgl/benchmark.hpp>
+#include <mln/benchmark.hpp>
 
-#include <mbgl/util/logging.hpp>
+#include <mln/util/logging.hpp>
 
 #include <unistd.h>
 #include <vector>
@@ -22,13 +22,13 @@ bool TestRunner::startTest(const std::string& basePath) {
     argv.push_back(nullptr);
 
     if (chdir(basePath.c_str())) {
-        mbgl::Log::Error(mbgl::Event::General, "Failed to change the directory to " + basePath);
+        mln::Log::Error(mln::Event::General, "Failed to change the directory to " + basePath);
         return false;
     }
 
-    mbgl::Log::Info(mbgl::Event::General, "Start BenchmarkRunner");
-    int status = mbgl::runBenchmark(static_cast<uint32_t>(argv.size()), argv.data());
-    mbgl::Log::Info(mbgl::Event::General, "BenchmarkRunner finished with status: '%d'", status);
+    mln::Log::Info(mln::Event::General, "Start BenchmarkRunner");
+    int status = mln::runBenchmark(static_cast<uint32_t>(argv.size()), argv.data());
+    mln::Log::Info(mln::Event::General, "BenchmarkRunner finished with status: '%d'", status);
 
     return status == 0;
 }

benchmark/parse/filter.benchmark.cpp

@@ -1,13 +1,13 @@
 #include <benchmark/benchmark.h>
 
-#include <mbgl/style/filter.hpp>
-#include <mbgl/style/conversion/json.hpp>
-#include <mbgl/style/conversion/filter.hpp>
-#include <mbgl/style/conversion_impl.hpp>
-#include <mbgl/tile/geometry_tile_data.hpp>
-#include <mbgl/benchmark/stub_geometry_tile_feature.hpp>
+#include <mln/style/filter.hpp>
+#include <mln/style/conversion/json.hpp>
+#include <mln/style/conversion/filter.hpp>
+#include <mln/style/conversion_impl.hpp>
+#include <mln/tile/geometry_tile_data.hpp>
+#include <mln/benchmark/stub_geometry_tile_feature.hpp>
 
-using namespace mbgl;
+using namespace mln;
 
 style::Filter parse(const char* expression) {
     style::conversion::Error error;

benchmark/parse/tile_mask.benchmark.cpp

@@ -1,8 +1,8 @@
 #include <benchmark/benchmark.h>
 
-#include <mbgl/algorithm/update_tile_masks.hpp>
+#include <mln/algorithm/update_tile_masks.hpp>
 
-using namespace mbgl;
+using namespace mln;
 
 class FakeTile {
 public:

benchmark/parse/vector_tile.benchmark.cpp

@@ -1,9 +1,9 @@
 #include <benchmark/benchmark.h>
 
-#include <mbgl/tile/vector_mvt_tile_data.hpp>
-#include <mbgl/util/io.hpp>
+#include <mln/tile/vector_mvt_tile_data.hpp>
+#include <mln/util/io.hpp>
 
-using namespace mbgl;
+using namespace mln;
 
 static void Parse_VectorTile(benchmark::State& state) {
     auto data = std::make_shared<std::string>(

benchmark/renderer/group_layers.benchmark.cpp

@@ -1,31 +1,31 @@
 #include <benchmark/benchmark.h>
 
 // Core function to benchmark
-#include <mbgl/renderer/group_by_layout.hpp>
+#include <mln/renderer/group_by_layout.hpp>
 
 // For mock layer properties
-#include <mbgl/style/layer_properties.hpp>
-#include <mbgl/style/layers/fill_layer_impl.hpp>
-#include <mbgl/style/layers/fill_layer_properties.hpp>
-#include <mbgl/style/layers/line_layer_impl.hpp>
-#include <mbgl/style/layers/line_layer_properties.hpp>
-#include <mbgl/style/layers/symbol_layer_impl.hpp>
-#include <mbgl/style/layers/symbol_layer_properties.hpp>
-#include <mbgl/style/layers/circle_layer_impl.hpp>
-#include <mbgl/style/layers/circle_layer_properties.hpp>
-#include <mbgl/util/immutable.hpp>
+#include <mln/style/layer_properties.hpp>
+#include <mln/style/layers/fill_layer_impl.hpp>
+#include <mln/style/layers/fill_layer_properties.hpp>
+#include <mln/style/layers/line_layer_impl.hpp>
+#include <mln/style/layers/line_layer_properties.hpp>
+#include <mln/style/layers/symbol_layer_impl.hpp>
+#include <mln/style/layers/symbol_layer_properties.hpp>
+#include <mln/style/layers/circle_layer_impl.hpp>
+#include <mln/style/layers/circle_layer_properties.hpp>
+#include <mln/util/immutable.hpp>
 
 // For real style loading
-#include <mbgl/style/style_impl.hpp>
-#include <mbgl/storage/file_source.hpp>
-#include <mbgl/util/io.hpp>
-#include <mbgl/util/run_loop.hpp>
-#include <mbgl/layermanager/layer_manager.hpp>
-#include <mbgl/renderer/render_layer.hpp>
-#include <mbgl/util/thread_pool.hpp>
+#include <mln/style/style_impl.hpp>
+#include <mln/storage/file_source.hpp>
+#include <mln/util/io.hpp>
+#include <mln/util/run_loop.hpp>
+#include <mln/layermanager/layer_manager.hpp>
+#include <mln/renderer/render_layer.hpp>
+#include <mln/util/thread_pool.hpp>
 
-using namespace mbgl;
-using namespace mbgl::style;
+using namespace mln;
+using namespace mln::style;
 
 // Minimal FileSource stub for benchmark (doesn't actually fetch resources)
 class StubFileSource : public FileSource {

benchmark/src/mln/benchmark/benchmark.cpp

@@ -1,8 +1,8 @@
-#include <mbgl/benchmark.hpp>
+#include <mln/benchmark.hpp>
 
 #include <benchmark/benchmark.h>
 
-namespace mbgl {
+namespace mln {
 
 int runBenchmark(int argc, char* argv[]) {
     ::benchmark::Initialize(&argc, argv);
@@ -10,4 +10,4 @@ int runBenchmark(int argc, char* argv[]) {
     return 0;
 }
 
-} // namespace mbgl
+} // namespace mln

benchmark/src/mln/benchmark/stub_geometry_tile_feature.hpp

@@ -1,9 +1,9 @@
 #pragma once
 
-#include <mbgl/tile/geometry_tile_data.hpp>
-#include <mbgl/util/feature.hpp>
+#include <mln/tile/geometry_tile_data.hpp>
+#include <mln/util/feature.hpp>
 
-using namespace mbgl;
+using namespace mln;
 
 class StubGeometryTileFeature : public GeometryTileFeature {
 public:

benchmark/storage/offline_database.benchmark.cpp

@@ -1,11 +1,11 @@
 #include <benchmark/benchmark.h>
 
-#include <mbgl/storage/offline_database.hpp>
-#include <mbgl/storage/resource.hpp>
-#include <mbgl/storage/response.hpp>
-#include <mbgl/storage/sqlite3.hpp>
-#include <mbgl/util/string.hpp>
-#include <mbgl/util/logging.hpp>
+#include <mln/storage/offline_database.hpp>
+#include <mln/storage/resource.hpp>
+#include <mln/storage/response.hpp>
+#include <mln/storage/sqlite3.hpp>
+#include <mln/util/string.hpp>
+#include <mln/util/logging.hpp>
 
 #include <random>
 
@@ -18,14 +18,14 @@ public:
 
         response.data = std::make_shared<std::string>(50 * 1024, 0);
         response.mustRevalidate = false;
-        response.expires = mbgl::util::now() + 1h;
+        response.expires = mln::util::now() + 1h;
 
         resetAmbientTiles();
         resetRegion();
     }
 
     void resetAmbientTiles() {
-        using namespace mbgl;
+        using namespace mln;
 
         db.clearAmbientCache();
 
@@ -37,7 +37,7 @@ public:
     }
 
     void resetRegion() {
-        using namespace mbgl;
+        using namespace mln;
 
         auto regions = db.listRegions().value();
         if (!regions.empty()) {
@@ -58,8 +58,8 @@ public:
         }
     }
 
-    mbgl::Response response;
-    mbgl::OfflineDatabase db{":memory:", mbgl::TileServerOptions::DefaultConfiguration()};
+    mln::Response response;
+    mln::OfflineDatabase db{":memory:", mln::TileServerOptions::DefaultConfiguration()};
 
     const unsigned tileCount = 100;
     int64_t regionID = 0;
@@ -78,7 +78,7 @@ BENCHMARK_F(OfflineDatabase, DeleteRegion)(benchmark::State& state) {
 }
 
 BENCHMARK_F(OfflineDatabase, InsertTileRegion)(benchmark::State& state) {
-    using namespace mbgl;
+    using namespace mln;
 
     while (state.KeepRunning()) {
         const Resource offline = Resource::tile(
@@ -99,7 +99,7 @@ BENCHMARK_F(OfflineDatabase, ClearAmbientCache)(benchmark::State& state) {
 }
 
 BENCHMARK_F(OfflineDatabase, InsertTileCache)(benchmark::State& state) {
-    using namespace mbgl;
+    using namespace mln;
 
     while (state.KeepRunning()) {
         const Resource ambient = Resource::tile(
@@ -109,7 +109,7 @@ BENCHMARK_F(OfflineDatabase, InsertTileCache)(benchmark::State& state) {
 }
 
 BENCHMARK_F(OfflineDatabase, InsertBigTileCache)(benchmark::State& state) {
-    using namespace mbgl;
+    using namespace mln;
 
     Response big;
     big.data = std::make_shared<std::string>(util::DEFAULT_MAX_CACHE_SIZE / 100, 0);
@@ -122,7 +122,7 @@ BENCHMARK_F(OfflineDatabase, InsertBigTileCache)(benchmark::State& state) {
 }
 
 BENCHMARK_F(OfflineDatabase, GetTile)(benchmark::State& state) {
-    using namespace mbgl;
+    using namespace mln;
 
     std::random_device rd;
     std::mt19937 gen(rd());
@@ -136,7 +136,7 @@ BENCHMARK_F(OfflineDatabase, GetTile)(benchmark::State& state) {
 }
 
 BENCHMARK_F(OfflineDatabase, AddTilesToFullDatabase)(benchmark::State& state) {
-    using namespace mbgl;
+    using namespace mln;
 
     Log::setObserver(std::make_unique<Log::NullObserver>());
     db.setMaximumAmbientCacheSize(50 * 1024 * 5);
@@ -152,7 +152,7 @@ BENCHMARK_F(OfflineDatabase, AddTilesToFullDatabase)(benchmark::State& state) {
 
 BENCHMARK_F(OfflineDatabase, AddTilesToDisabledDatabase)
 (benchmark::State& state) {
-    using namespace mbgl;
+    using namespace mln;
 
     auto regions = db.listRegions().value();
     if (!regions.empty()) {
@@ -171,7 +171,7 @@ BENCHMARK_F(OfflineDatabase, AddTilesToDisabledDatabase)
 
 BENCHMARK_F(OfflineDatabase, GetTileFromDisabledDatabase)
 (benchmark::State& state) {
-    using namespace mbgl;
+    using namespace mln;
 
     auto regions = db.listRegions().value();
     if (!regions.empty()) {

benchmark/util/color.benchmark.cpp

@@ -2,7 +2,7 @@
 
 #include <string>
 #include <vector>
-#include <mbgl/util/color.hpp>
+#include <mln/util/color.hpp>
 
 static const std::vector<std::string> testStrings = {"#000000",
                                                      "#FFFFFF",
@@ -20,7 +20,7 @@ namespace {
 void ColorParse(benchmark::State& state) {
     for (auto _ : state) {
         for (const auto& str : testStrings) {
-            auto result = mbgl::Color::parse(str);
+            auto result = mln::Color::parse(str);
             benchmark::DoNotOptimize(result);
         }
     }

benchmark/util/tilecover.benchmark.cpp

@@ -1,11 +1,11 @@
 #include <benchmark/benchmark.h>
-#include <mbgl/util/geo.hpp>
-#include <mbgl/util/geometry.hpp>
-#include <mbgl/util/tile_coordinate.hpp>
-#include <mbgl/util/tile_cover.hpp>
-#include <mbgl/map/transform.hpp>
+#include <mln/util/geo.hpp>
+#include <mln/util/geometry.hpp>
+#include <mln/util/tile_coordinate.hpp>
+#include <mln/util/tile_cover.hpp>
+#include <mln/map/transform.hpp>
 
-using namespace mbgl;
+using namespace mln;
 
 static const LatLngBounds sanFrancisco = LatLngBounds::hull({37.6609, -122.5744}, {37.8271, -122.3204});
 

bin/cache.cpp

@@ -1,8 +1,8 @@
-#include <mbgl/storage/file_source_manager.hpp>
-#include <mbgl/storage/resource.hpp>
-#include <mbgl/storage/resource_options.hpp>
-#include <mbgl/util/chrono.hpp>
-#include <mbgl/util/run_loop.hpp>
+#include <mln/storage/file_source_manager.hpp>
+#include <mln/storage/resource.hpp>
+#include <mln/storage/resource_options.hpp>
+#include <mln/util/chrono.hpp>
+#include <mln/util/run_loop.hpp>
 
 #include <args.hxx>
 #include <mapbox/io/io.hpp>
@@ -25,20 +25,20 @@ int main(int argc, char* argv[]) {
     args::ValueFlag<unsigned long> expiresValue(p, "expires", "Expires date, will use 'now' otherwise", {'e'});
     args::ValueFlag<unsigned long> modifiedValue(p, "modified", "Modified date, will use 'now' otherwise", {'m'});
 
-    std::unordered_map<std::string, mbgl::Resource::Kind> typeMap{{"glyphs", mbgl::Resource::Glyphs},
-                                                                  {"image", mbgl::Resource::Image},
-                                                                  {"source", mbgl::Resource::Source},
-                                                                  {"sprite-image", mbgl::Resource::SpriteImage},
-                                                                  {"sprite-json", mbgl::Resource::SpriteJSON},
-                                                                  {"style", mbgl::Resource::Style},
-                                                                  {"tile", mbgl::Resource::Tile}};
+    std::unordered_map<std::string, mln::Resource::Kind> typeMap{{"glyphs", mln::Resource::Glyphs},
+                                                                 {"image", mln::Resource::Image},
+                                                                 {"source", mln::Resource::Source},
+                                                                 {"sprite-image", mln::Resource::SpriteImage},
+                                                                 {"sprite-json", mln::Resource::SpriteJSON},
+                                                                 {"style", mln::Resource::Style},
+                                                                 {"tile", mln::Resource::Tile}};
 
     std::string typeHelp("One of the following (required):");
     for (const auto& key : typeMap) {
         typeHelp += " " + key.first;
     }
 
-    args::MapFlag<std::string, mbgl::Resource::Kind> typeFlag(
+    args::MapFlag<std::string, mln::Resource::Kind> typeFlag(
         p, "type", typeHelp, {"type"}, typeMap, args::Options::Required);
 
     args::Group tileIdGroup(p, "Coordinates (required for 'tile')", args::Group::Validators::AllOrNone);
@@ -67,15 +67,15 @@ int main(int argc, char* argv[]) {
         exit(3);
     }
 
-    mbgl::Response response;
+    mln::Response response;
     response.data = std::make_shared<std::string>(*file);
     response.etag = etagValue ? args::get(etagValue) : std::string();
-    response.expires = expiresValue ? mbgl::Timestamp(mbgl::Seconds(args::get(expiresValue))) : mbgl::util::now();
-    response.modified = modifiedValue ? mbgl::Timestamp(mbgl::Seconds(args::get(modifiedValue))) : mbgl::util::now();
+    response.expires = expiresValue ? mln::Timestamp(mln::Seconds(args::get(expiresValue))) : mln::util::now();
+    response.modified = modifiedValue ? mln::Timestamp(mln::Seconds(args::get(modifiedValue))) : mln::util::now();
 
-    mbgl::Resource resource(args::get(typeFlag), args::get(urlValue));
+    mln::Resource resource(args::get(typeFlag), args::get(urlValue));
 
-    if (args::get(typeFlag) == mbgl::Resource::Tile) {
+    if (args::get(typeFlag) == mln::Resource::Tile) {
         if (!xValueFlag || !yValueFlag || !zValueFlag) {
             std::cerr << "Error: -x, -y and -z must be provided for tiles" << '\n';
             exit(1);
@@ -88,9 +88,9 @@ int main(int argc, char* argv[]) {
                               .z = static_cast<int8_t>(args::get(zValueFlag))}};
     }
 
-    mbgl::util::RunLoop loop;
-    std::shared_ptr<mbgl::FileSource> dbfs = mbgl::FileSourceManager::get()->getFileSource(
-        mbgl::FileSourceType::Database, mbgl::ResourceOptions().withCachePath(args::get(cacheValue)));
+    mln::util::RunLoop loop;
+    std::shared_ptr<mln::FileSource> dbfs = mln::FileSourceManager::get()->getFileSource(
+        mln::FileSourceType::Database, mln::ResourceOptions().withCachePath(args::get(cacheValue)));
     dbfs->forward(resource, response, [&loop] { loop.stop(); });
     loop.run();
     return 0;

bin/offline.cpp

@@ -1,12 +1,12 @@
-#include <mbgl/util/run_loop.hpp>
-#include <mbgl/util/string.hpp>
-#include <mbgl/util/geojson.hpp>
+#include <mln/util/run_loop.hpp>
+#include <mln/util/string.hpp>
+#include <mln/util/geojson.hpp>
 
-#include <mbgl/storage/database_file_source.hpp>
-#include <mbgl/storage/file_source_manager.hpp>
-#include <mbgl/storage/resource_options.hpp>
-#include <mbgl/util/client_options.hpp>
-#include <mbgl/util/tile_server_options.hpp>
+#include <mln/storage/database_file_source.hpp>
+#include <mln/storage/file_source_manager.hpp>
+#include <mln/storage/resource_options.hpp>
+#include <mln/util/client_options.hpp>
+#include <mln/util/tile_server_options.hpp>
 
 #include <args.hxx>
 
@@ -51,19 +51,19 @@ mapbox::geometry::geometry<double> parseGeometry(const std::string& json) {
                          });
 }
 
-std::ostream& operator<<(std::ostream& os, mbgl::Response::Error::Reason r) {
+std::ostream& operator<<(std::ostream& os, mln::Response::Error::Reason r) {
     switch (r) {
-        case mbgl::Response::Error::Reason::Success:
+        case mln::Response::Error::Reason::Success:
             return os << "Response::Error::Reason::Success";
-        case mbgl::Response::Error::Reason::NotFound:
+        case mln::Response::Error::Reason::NotFound:
             return os << "Response::Error::Reason::NotFound";
-        case mbgl::Response::Error::Reason::Server:
+        case mln::Response::Error::Reason::Server:
             return os << "Response::Error::Reason::Server";
-        case mbgl::Response::Error::Reason::Connection:
+        case mln::Response::Error::Reason::Connection:
             return os << "Response::Error::Reason::Connection";
-        case mbgl::Response::Error::Reason::RateLimit:
+        case mln::Response::Error::Reason::RateLimit:
             return os << "Response::Error::Reason::RateLimit";
-        case mbgl::Response::Error::Reason::Other:
+        case mln::Response::Error::Reason::Other:
             return os << "Response::Error::Reason::Other";
     }
 
@@ -122,7 +122,7 @@ int main(int argc, char* argv[]) {
         exit(2);
     }
 
-    auto mapTilerConfiguration = mbgl::TileServerOptions::MapTilerConfiguration();
+    auto mapTilerConfiguration = mln::TileServerOptions::MapTilerConfiguration();
 
     std::string style = styleValue ? args::get(styleValue) : mapTilerConfiguration.defaultStyles().at(0).getUrl();
     std::cout << " Style: " << style << std::endl;
@@ -138,7 +138,7 @@ int main(int argc, char* argv[]) {
     const bool includeIdeographs = includeIdeographsValue ? args::get(includeIdeographsValue) : false;
     const std::string output = outputValue ? args::get(outputValue) : "offline.db";
 
-    using namespace mbgl;
+    using namespace mln;
 
     OfflineRegionDefinition definition = [&]() {
         if (geometryValue) {
@@ -185,7 +185,7 @@ int main(int argc, char* argv[]) {
         int retCode = 0;
         std::cout << "Start Merge" << std::endl;
         inputSource.mergeOfflineRegions(
-            *mergePath, [&](mbgl::expected<std::vector<OfflineRegion>, std::exception_ptr> result) {
+            *mergePath, [&](mln::expected<std::vector<OfflineRegion>, std::exception_ptr> result) {
                 if (!result) {
                     std::cerr << "Error merging database: " << util::toString(result.error()) << std::endl;
                     retCode = 1;
@@ -264,7 +264,7 @@ int main(int argc, char* argv[]) {
     std::signal(SIGINT, [](int) { stop(); });
 
     fileSource->createOfflineRegion(
-        definition, metadata, [&](mbgl::expected<OfflineRegion, std::exception_ptr> region_) {
+        definition, metadata, [&](mln::expected<OfflineRegion, std::exception_ptr> region_) {
             if (!region_) {
                 std::cerr << "Error creating region: " << util::toString(region_.error()) << std::endl;
                 loop.stop();

bin/render.cpp

@@ -1,11 +1,11 @@
-#include <mbgl/map/map.hpp>
-#include <mbgl/map/map_options.hpp>
-#include <mbgl/util/image.hpp>
-#include <mbgl/util/run_loop.hpp>
+#include <mln/map/map.hpp>
+#include <mln/map/map_options.hpp>
+#include <mln/util/image.hpp>
+#include <mln/util/run_loop.hpp>
 
-#include <mbgl/gfx/backend.hpp>
-#include <mbgl/gfx/headless_frontend.hpp>
-#include <mbgl/style/style.hpp>
+#include <mln/gfx/backend.hpp>
+#include <mln/gfx/headless_frontend.hpp>
+#include <mln/style/style.hpp>
 
 #include <args.hxx>
 
@@ -19,8 +19,10 @@ int main(int argc, char* argv[]) {
 
     args::ValueFlag<std::string> backendValue(argumentParser, "Backend", "Rendering backend", {"backend"});
     args::ValueFlag<std::string> apikeyValue(argumentParser, "key", "API key", {'t', "apikey"});
-    args::ValueFlag<std::string> styleValue(argumentParser, "URL", "Map stylesheet", {'s', "style"});
-    args::ValueFlag<std::string> outputValue(argumentParser, "file", "Output file name", {'o', "output"});
+    args::ValueFlag<std::string> styleValue(
+        argumentParser, "URL|file|-", "Map stylesheet (use '-' for stdin)", {'s', "style"});
+    args::ValueFlag<std::string> outputValue(
+        argumentParser, "file|-", "Output file name (use '-' for stdout)", {'o', "output"});
     args::ValueFlag<std::string> cacheValue(argumentParser, "file", "Cache database file name", {'c', "cache"});
     args::ValueFlag<std::string> assetsValue(
         argumentParser, "file", "Directory to which asset:// URLs will resolve", {'a', "assets"});
@@ -69,7 +71,7 @@ int main(int argc, char* argv[]) {
     const double lon = lonValue ? args::get(lonValue) : 0;
     const double alt = altValue ? args::get(altValue) : 0;
     const double zoom = zoomValue ? args::get(zoomValue) : 0;
-    const double fov = fovValue ? args::get(fovValue) : mbgl::util::rad2deg(mbgl::util::DEFAULT_FOV);
+    const double fov = fovValue ? args::get(fovValue) : mln::util::rad2deg(mln::util::DEFAULT_FOV);
     const double bearing = bearingValue ? args::get(bearingValue) : 0;
     const double pitch = pitchValue ? args::get(pitchValue) : 0;
     const double roll = rollValue ? args::get(rollValue) : 0;
@@ -87,9 +89,11 @@ int main(int argc, char* argv[]) {
 
     const bool debug = debugFlag ? args::get(debugFlag) : false;
 
-    using namespace mbgl;
+    using namespace mln;
 
-    auto mapTilerConfiguration = mbgl::TileServerOptions::MapTilerConfiguration();
+    auto mapTilerConfiguration = mln::TileServerOptions::MapTilerConfiguration();
+
+    std::string json;
     std::string style = styleValue ? args::get(styleValue) : mapTilerConfiguration.defaultStyles().at(0).getUrl();
 
     util::RunLoop loop;
@@ -115,11 +119,16 @@ int main(int argc, char* argv[]) {
             .withApiKey(apikey)
             .withTileServerOptions(mapTilerConfiguration));
 
-    if (style.find("://") == std::string::npos) {
-        style = std::string("file://") + style;
-    }
+    if (style == "-") {
+        json = std::string(std::istreambuf_iterator<char>(std::cin), std::istreambuf_iterator<char>());
+        map.getStyle().loadJSON(json);
+    } else {
+        if (style.find("://") == std::string::npos) {
+            style = std::string("file://") + style;
+        }
 
-    map.getStyle().loadURL(style);
+        map.getStyle().loadURL(style);
+    }
     std::vector<double> bounds = args::get(boundsValue);
     if (bounds.size() == 4) {
         LatLngBounds boundingBox = LatLngBounds::hull(LatLng(bounds[0], bounds[1]), LatLng(bounds[2], bounds[3]));
@@ -136,14 +145,19 @@ int main(int argc, char* argv[]) {
     }
 
     if (debug) {
-        map.setDebug(debug ? mbgl::MapDebugOptions::TileBorders | mbgl::MapDebugOptions::ParseStatus
-                           : mbgl::MapDebugOptions::NoDebug);
+        map.setDebug(debug ? mln::MapDebugOptions::TileBorders | mln::MapDebugOptions::ParseStatus
+                           : mln::MapDebugOptions::NoDebug);
     }
 
     try {
-        std::ofstream out(output, std::ios::binary);
-        out << encodePNG(frontend.render(map).image);
-        out.close();
+        std::string png = encodePNG(frontend.render(map).image);
+        if (output == "-") {
+            std::cout.write(png.data(), png.size());
+        } else {
+            std::ofstream out(output, std::ios::binary);
+            out << png;
+            out.close();
+        }
     } catch (std::exception& e) {
         std::cout << "Error: " << e.what() << std::endl;
         exit(1);

cmake/metal.cmake

@@ -11,96 +11,93 @@ target_compile_definitions(
 )
 list(APPEND
         INCLUDE_FILES
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/buffer_resource.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/command_encoder.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/context.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/drawable.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/drawable_builder.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/dynamic_texture.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/index_buffer_resource.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/layer_group.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/mtl_fwd.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/offscreen_texture.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/render_pass.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/renderer_backend.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/renderable_resource.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/texture2d.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/tile_layer_group.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/uniform_buffer.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/upload_pass.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/vertex_attribute.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/mtl/vertex_buffer_resource.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/background.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/circle.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/clipping_mask.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/common.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/collision.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/custom_geometry.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/custom_symbol_icon.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/debug.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/fill.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/fill_extrusion.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/heatmap.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/heatmap_texture.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/hillshade.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/hillshade_prepare.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/color_relief.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/line.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/location_indicator.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/particle_gpu_validation.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/retained_underlay_composite.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/raster.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/shader_group.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/shader_program.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/mtl/symbol.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/buffer_resource.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/command_encoder.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/context.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/drawable.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/drawable_builder.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/dynamic_texture.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/index_buffer_resource.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/layer_group.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/mtl_fwd.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/offscreen_texture.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/render_pass.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/renderer_backend.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/renderable_resource.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/texture2d.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/tile_layer_group.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/uniform_buffer.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/upload_pass.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/vertex_attribute.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/mtl/vertex_buffer_resource.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/background.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/circle.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/clipping_mask.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/common.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/collision.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/custom_geometry.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/custom_symbol_icon.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/debug.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/fill.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/fill_extrusion.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/heatmap.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/heatmap_texture.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/hillshade.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/hillshade_prepare.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/color_relief.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/line.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/location_indicator.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/particle_gpu_validation.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/retained_underlay_composite.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/raster.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/shader_group.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/shader_program.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/mtl/symbol.hpp
 )
 list(APPEND
         SRC_FILES
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/buffer_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/command_encoder.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/context.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/drawable.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/drawable_impl.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/drawable_builder.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/dynamic_texture.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/index_buffer_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/layer_group.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/mtl.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/offscreen_texture.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/renderer_backend.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/texture2d.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/render_pass.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/tile_layer_group.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/uniform_buffer.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/upload_pass.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/vertex_attribute.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/mtl/vertex_buffer_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/shader_program.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/background.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/circle.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/collision.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/clipping_mask.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/custom_geometry.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/custom_symbol_icon.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/debug.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/fill.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/fill_extrusion.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/heatmap.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/heatmap_texture.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/hillshade.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/hillshade_prepare.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/color_relief.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/line.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/location_indicator.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/particle_gpu_validation.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/retained_underlay_composite.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/raster.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/symbol.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/mtl/widevector.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/style/layers/mtl/custom_layer_render_parameters.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/buffer_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/command_encoder.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/context.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/drawable.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/drawable_impl.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/drawable_builder.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/dynamic_texture.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/index_buffer_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/layer_group.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/mtl.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/offscreen_texture.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/renderer_backend.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/texture2d.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/render_pass.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/tile_layer_group.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/uniform_buffer.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/upload_pass.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/vertex_attribute.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/mtl/vertex_buffer_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/shader_program.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/background.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/circle.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/collision.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/clipping_mask.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/custom_geometry.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/custom_symbol_icon.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/debug.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/fill.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/fill_extrusion.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/heatmap.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/heatmap_texture.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/hillshade.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/hillshade_prepare.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/color_relief.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/line.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/location_indicator.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/particle_gpu_validation.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/retained_underlay_composite.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/raster.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/symbol.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/mtl/widevector.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/style/layers/mtl/custom_layer_render_parameters.cpp
 )
 
-find_library(METAL_FRAMEWORK Metal)
-if (METAL_FRAMEWORK)
-    target_link_libraries(mbgl-core PRIVATE ${METAL_FRAMEWORK})
-endif()
+target_link_libraries(mbgl-core PRIVATE "-framework Metal")

cmake/opengl.cmake

@@ -11,143 +11,144 @@ target_compile_definitions(
 )
 list(APPEND
         INCLUDE_FILES
-        ${PROJECT_SOURCE_DIR}/include/mbgl/gl/renderable_resource.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/gl/renderer_backend.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/platform/gl_functions.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/shader_manifest.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/shader_group_gl.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/prelude.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/background.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/background_pattern.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/circle.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/clipping_mask.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/collision_box.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/collision_circle.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/custom_geometry.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/custom_symbol_icon.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/debug.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/fill.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/fill_outline.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/fill_pattern.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/fill_outline_pattern.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/fill_outline_triangulated.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/fill_extrusion.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/fill_extrusion_instanced.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/fill_extrusion_pattern.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/fill_extrusion_pattern_instanced.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/heatmap.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/heatmap_texture.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/retained_underlay_composite.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/hillshade_prepare.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/hillshade.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/color_relief.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/line.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/line_gradient.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/line_pattern.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/line_sdf.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/location_indicator.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/location_indicator_textured.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/raster.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/symbol_icon.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/symbol_sdf.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/symbol_text_and_icon.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/wide_vector.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/gl/renderable_resource.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/gl/renderer_backend.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/platform/gl_functions.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/shader_manifest.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/shader_group_gl.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/prelude.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/background.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/background_pattern.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/circle.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/clipping_mask.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/collision_box.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/collision_circle.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/custom_geometry.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/custom_symbol_icon.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/debug.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/fill.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/fill_outline.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/fill_pattern.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/fill_outline_pattern.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/fill_outline_triangulated.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/fill_extrusion.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/fill_extrusion_instanced.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/fill_extrusion_pattern.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/fill_extrusion_pattern_instanced.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/heatmap.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/heatmap_texture.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/particle_gpu_validation.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/retained_underlay_composite.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/hillshade_prepare.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/hillshade.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/color_relief.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/line.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/line_gradient.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/line_pattern.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/line_sdf.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/location_indicator.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/location_indicator_textured.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/raster.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/symbol_icon.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/symbol_sdf.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/symbol_text_and_icon.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/wide_vector.hpp
 )
 list(APPEND
         SRC_FILES
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/attribute.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/attribute.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/command_encoder.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/command_encoder.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/context.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/context.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/fence.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/fence.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/debugging_extension.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/debugging_extension.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/defines.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/draw_scope_resource.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/enum.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/enum.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/extension.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/framebuffer.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/index_buffer_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/index_buffer_resource.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/object.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/object.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/offscreen_texture.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/offscreen_texture.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/render_pass.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/render_pass.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/renderbuffer_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/renderbuffer_resource.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/renderer_backend.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/resource_pool.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/resource_pool.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/state.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/timestamp_query_extension.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/timestamp_query_extension.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/types.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/uniform.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/uniform.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/upload_pass.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/upload_pass.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/value.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/value.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/vertex_array.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/vertex_array.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/vertex_buffer_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/vertex_buffer_resource.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/platform/gl_functions.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/gl/legacy/clipping_mask_program.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/gl/legacy/program_base.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/gl/legacy/program.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/gl/legacy/programs.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/gl/legacy/programs.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/attribute.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/attribute.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/command_encoder.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/command_encoder.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/context.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/context.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/fence.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/fence.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/debugging_extension.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/debugging_extension.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/defines.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/draw_scope_resource.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/enum.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/enum.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/extension.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/framebuffer.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/index_buffer_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/index_buffer_resource.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/object.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/object.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/offscreen_texture.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/offscreen_texture.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/render_pass.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/render_pass.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/renderbuffer_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/renderbuffer_resource.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/renderer_backend.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/resource_pool.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/resource_pool.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/state.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/timestamp_query_extension.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/timestamp_query_extension.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/types.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/uniform.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/uniform.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/upload_pass.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/upload_pass.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/value.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/value.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/vertex_array.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/vertex_array.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/vertex_buffer_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/vertex_buffer_resource.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/platform/gl_functions.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/gl/legacy/clipping_mask_program.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/gl/legacy/program_base.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/gl/legacy/program.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/gl/legacy/programs.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/gl/legacy/programs.hpp
 )
 
 list(APPEND INCLUDE_FILES
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/background_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/circle_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/collision_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/custom_drawable_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/debug_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/fill_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/fill_extrusion_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/heatmap_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/heatmap_texture_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/hillshade_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/color_relief_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/hillshade_prepare_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/line_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/location_indicator_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/raster_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/shader_defines.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/symbol_layer_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/widevector_ubo.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/style/layers/custom_drawable_layer.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/layermanager/custom_drawable_layer_factory.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/gl/shader_program_gl.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/gl/buffer_allocator.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/gl/drawable_gl.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/gl/drawable_gl_builder.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/gl/dynamic_texture.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/gl/layer_group_gl.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/gl/texture2d.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/gl/uniform_buffer_gl.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/gl/vertex_attribute_gl.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/background_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/circle_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/collision_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/custom_drawable_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/debug_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/fill_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/fill_extrusion_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/heatmap_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/heatmap_texture_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/hillshade_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/color_relief_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/hillshade_prepare_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/line_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/location_indicator_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/raster_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/shader_defines.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/symbol_layer_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/widevector_ubo.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/style/layers/custom_drawable_layer.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/layermanager/custom_drawable_layer_factory.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/gl/shader_program_gl.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/gl/buffer_allocator.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/gl/drawable_gl.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/gl/drawable_gl_builder.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/gl/dynamic_texture.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/gl/layer_group_gl.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/gl/texture2d.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/gl/uniform_buffer_gl.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/gl/vertex_attribute_gl.hpp
 )
 list(APPEND SRC_FILES
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/gl/shader_info.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/gl/shader_program_gl.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/buffer_allocator.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/drawable_gl.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/drawable_gl_builder.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/drawable_gl_impl.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/dynamic_texture.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/layer_group_gl.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/texture2d.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/uniform_buffer_gl.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/gl/vertex_attribute_gl.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/gl/shader_info.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/gl/shader_program_gl.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/buffer_allocator.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/drawable_gl.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/drawable_gl_builder.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/drawable_gl_impl.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/dynamic_texture.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/layer_group_gl.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/texture2d.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/uniform_buffer_gl.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/gl/vertex_attribute_gl.cpp
 )

cmake/vulkan.cmake

@@ -12,93 +12,93 @@ target_compile_definitions(
 
 list(APPEND
         INCLUDE_FILES
-        ${PROJECT_SOURCE_DIR}/include/mbgl/style/layers/vulkan/custom_layer_init_parameters.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/style/layers/vulkan/custom_layer_render_parameters.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/buffer_resource.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/command_encoder.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/context.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/drawable.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/descriptor_set.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/drawable_builder.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/dynamic_texture.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/index_buffer_resource.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/layer_group.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/offscreen_texture.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/pipeline.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/renderer_backend.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/render_pass.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/renderable_resource.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/texture2d.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/tile_layer_group.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/uniform_buffer.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/upload_pass.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/vertex_attribute.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/vulkan/vertex_buffer_resource.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/shader_group.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/shader_program.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/background.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/circle.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/clipping_mask.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/collision.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/common.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/custom_geometry.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/custom_symbol_icon.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/fill.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/fill_extrusion.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/heatmap.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/heatmap_texture.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/hillshade.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/hillshade_prepare.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/color_relief.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/line.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/location_indicator.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/raster.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/symbol.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/vulkan/widevector.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/style/layers/vulkan/custom_layer_init_parameters.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/style/layers/vulkan/custom_layer_render_parameters.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/buffer_resource.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/command_encoder.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/context.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/drawable.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/descriptor_set.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/drawable_builder.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/dynamic_texture.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/index_buffer_resource.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/layer_group.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/offscreen_texture.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/pipeline.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/renderer_backend.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/render_pass.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/renderable_resource.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/texture2d.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/tile_layer_group.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/uniform_buffer.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/upload_pass.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/vertex_attribute.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/vulkan/vertex_buffer_resource.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/shader_group.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/shader_program.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/background.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/circle.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/clipping_mask.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/collision.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/common.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/custom_geometry.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/custom_symbol_icon.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/fill.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/fill_extrusion.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/heatmap.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/heatmap_texture.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/hillshade.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/hillshade_prepare.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/color_relief.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/line.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/location_indicator.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/raster.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/symbol.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/vulkan/widevector.hpp
 )
 
 list(APPEND
         SRC_FILES
-        ${PROJECT_SOURCE_DIR}/src/mbgl/style/layers/vulkan/custom_layer_render_parameters.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/buffer_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/command_encoder.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/context.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/descriptor_set.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/drawable.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/drawable_builder.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/drawable_impl.hpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/dynamic_texture.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/index_buffer_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/layer_group.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/offscreen_texture.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/pipeline.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/renderer_backend.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/render_pass.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/renderable_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/texture2d.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/tile_layer_group.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/uniform_buffer.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/upload_pass.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/vertex_attribute.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/vulkan/vertex_buffer_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/shader_program.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/background.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/circle.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/clipping_mask.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/collision.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/custom_geometry.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/custom_symbol_icon.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/debug.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/fill.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/fill_extrusion.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/heatmap.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/heatmap_texture.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/hillshade.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/hillshade_prepare.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/color_relief.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/line.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/location_indicator.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/raster.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/symbol.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/vulkan/widevector.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/style/layers/vulkan/custom_layer_render_parameters.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/buffer_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/command_encoder.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/context.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/descriptor_set.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/drawable.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/drawable_builder.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/drawable_impl.hpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/dynamic_texture.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/index_buffer_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/layer_group.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/offscreen_texture.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/pipeline.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/renderer_backend.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/render_pass.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/renderable_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/texture2d.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/tile_layer_group.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/uniform_buffer.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/upload_pass.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/vertex_attribute.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/vulkan/vertex_buffer_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/shader_program.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/background.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/circle.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/clipping_mask.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/collision.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/custom_geometry.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/custom_symbol_icon.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/debug.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/fill.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/fill_extrusion.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/heatmap.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/heatmap_texture.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/hillshade.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/hillshade_prepare.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/color_relief.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/line.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/location_indicator.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/raster.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/symbol.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/vulkan/widevector.cpp
 )

cmake/webgpu.cmake

@@ -17,99 +17,98 @@ target_include_directories(
 
 list(APPEND
         SRC_FILES
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/buffer_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/context.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/command_encoder.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/headless_backend.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/renderer_backend.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/drawable.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/drawable_builder.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/draw_scope_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/dynamic_texture.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/uniform_buffer.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/shader_program.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/wgsl_preprocessor.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/background.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/circle.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/clipping_mask.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/collision.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/custom_geometry.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/custom_symbol_icon.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/debug.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/fill.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/fill_extrusion.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/heatmap.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/heatmap_texture.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/hillshade.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/hillshade_prepare.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/color_relief.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/line.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/location_indicator.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/raster.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/symbol.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/widevector.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/vertex_buffer_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/vertex_attribute.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/texture2d.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/offscreen_texture.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/tile_layer_group.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/layer_group.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/buffer_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/context.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/command_encoder.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/renderer_backend.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/drawable.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/drawable_builder.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/draw_scope_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/dynamic_texture.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/uniform_buffer.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/shader_program.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/wgsl_preprocessor.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/background.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/circle.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/clipping_mask.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/collision.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/custom_geometry.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/custom_symbol_icon.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/debug.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/fill.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/fill_extrusion.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/heatmap.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/heatmap_texture.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/hillshade.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/hillshade_prepare.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/color_relief.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/line.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/location_indicator.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/raster.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/symbol.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/widevector.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/vertex_buffer_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/vertex_attribute.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/texture2d.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/offscreen_texture.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/tile_layer_group.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/layer_group.cpp
 )
 
 list(APPEND
         INCLUDE_FILES
-        ${PROJECT_SOURCE_DIR}/include/mbgl/webgpu/buffer_resource.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/webgpu/command_encoder.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/webgpu/context.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/webgpu/drawable.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/webgpu/drawable_builder.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/webgpu/dynamic_texture.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/webgpu/index_buffer_resource.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/webgpu/render_pass.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/webgpu/renderer_backend.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/shader_program.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/background.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/circle.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/clipping_mask.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/collision.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/common.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/custom_geometry.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/custom_symbol_icon.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/debug.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/fill.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/fill_extrusion.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/heatmap.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/heatmap_texture.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/hillshade.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/hillshade_prepare.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/color_relief.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/line.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/location_indicator.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/raster.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/symbol.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/shaders/webgpu/widevector.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/webgpu/texture2d.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/webgpu/uniform_buffer.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/webgpu/upload_pass.hpp
-        ${PROJECT_SOURCE_DIR}/include/mbgl/webgpu/vertex_buffer_resource.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/webgpu/buffer_resource.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/webgpu/command_encoder.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/webgpu/context.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/webgpu/drawable.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/webgpu/drawable_builder.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/webgpu/dynamic_texture.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/webgpu/index_buffer_resource.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/webgpu/render_pass.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/webgpu/renderer_backend.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/shader_program.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/background.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/circle.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/clipping_mask.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/collision.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/common.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/custom_geometry.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/custom_symbol_icon.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/debug.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/fill.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/fill_extrusion.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/heatmap.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/heatmap_texture.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/hillshade.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/hillshade_prepare.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/color_relief.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/line.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/location_indicator.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/raster.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/symbol.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/shaders/webgpu/widevector.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/webgpu/texture2d.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/webgpu/uniform_buffer.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/webgpu/upload_pass.hpp
+        ${PROJECT_SOURCE_DIR}/include/mln/webgpu/vertex_buffer_resource.hpp
 )
 
 list(APPEND
         SRC_FILES
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/buffer_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/command_encoder.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/context.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/drawable.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/drawable_builder.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/dynamic_texture.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/index_buffer_resource.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/render_pass.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/renderer_backend.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/shaders/webgpu/shader_program.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/texture2d.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/uniform_buffer.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/upload_pass.cpp
-        ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/vertex_buffer_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/buffer_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/command_encoder.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/context.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/drawable.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/drawable_builder.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/dynamic_texture.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/index_buffer_resource.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/render_pass.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/renderer_backend.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/shaders/webgpu/shader_program.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/texture2d.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/uniform_buffer.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/upload_pass.cpp
+        ${PROJECT_SOURCE_DIR}/src/mln/webgpu/vertex_buffer_resource.cpp
 )
 
 # Include WebGPU vendor configuration (Dawn or wgpu)
@@ -119,7 +118,13 @@ include(${PROJECT_SOURCE_DIR}/vendor/webgpu.cmake)
 if(MLN_WEBGPU_IMPL_DAWN)
     include(${PROJECT_SOURCE_DIR}/vendor/dawn.cmake)
     if(TARGET mbgl-vendor-dawn)
-        target_link_libraries(mbgl-core PRIVATE mbgl-vendor-dawn)
+        if(MLN_WEBGPU_EMDAWN)
+            # Emdawn is a compiler/linker port rather than a conventional
+            # library. Consumers must inherit its final-link options.
+            target_link_libraries(mbgl-core PUBLIC mbgl-vendor-dawn)
+        else()
+            target_link_libraries(mbgl-core PRIVATE mbgl-vendor-dawn)
+        endif()
     endif()
 elseif(MLN_WEBGPU_IMPL_WGPU OR MLN_WEBGPU_IMPL_FFI)
     # Include wgpu-native integration
@@ -127,6 +132,11 @@ elseif(MLN_WEBGPU_IMPL_WGPU OR MLN_WEBGPU_IMPL_FFI)
     if(TARGET mbgl-vendor-wgpu)
         target_link_libraries(mbgl-core PRIVATE mbgl-vendor-wgpu)
         # Add WebGPU-Cpp implementation file (required for wgpu-native backend)
-        list(APPEND SRC_FILES ${PROJECT_SOURCE_DIR}/src/mbgl/webgpu/webgpu_cpp_impl.cpp)
+        list(APPEND SRC_FILES ${PROJECT_SOURCE_DIR}/src/mln/webgpu/webgpu_cpp_impl.cpp)
     endif()
 endif()
+
+# Headless backend uses Dawn native / wgpu-native bootstrap; skip for emdawnwebgpu.
+if(NOT MLN_WEBGPU_EMDAWN)
+    list(APPEND SRC_FILES ${PROJECT_SOURCE_DIR}/src/mln/webgpu/headless_backend.cpp)
+endif()

design-proposals/2022-10-27-rendering-modularization.md

@@ -75,7 +75,7 @@ The shaders need a representation visible outside the toolkit and we need to cha
 
 Individual shaders are represented by an object class with massive amounts of template logic and a minimum of in-line comments.  They’re opaque from the outside and only controllable through vector tile data and styles.
 
-The [render_raster_layer](https://github.com/maplibre/maplibre-native/blob/main/src/mbgl/renderer/layers/render_raster_layer.cpp), as an example, asks for the instantiation of (eventually) RasterProgram.  Rather than having the source for the program, that then pokes into a compressed chunk of memory that contains the source, which is then uncompressed and fed into OpenGL for compilation.
+The [render_raster_layer](https://github.com/maplibre/maplibre-native/blob/main/src/mln/renderer/layers/render_raster_layer.cpp), as an example, asks for the instantiation of (eventually) RasterProgram.  Rather than having the source for the program, that then pokes into a compressed chunk of memory that contains the source, which is then uncompressed and fed into OpenGL for compilation.
 
 All of this makes sense in context, but is completely inaccessible outside the toolkit and rather incomprehensible when making changes.
 
@@ -134,9 +134,9 @@ Modern graphics pipelines use more than one pass to create a visual representati
 Without getting too deep into specifics, early rendering passes allow the developer to use the power of the rasterizer for their own data.  Later rendering passes are typically used to decorate the map with effects.
 
 #### The way it is now:
-The [low level rendering logic](https://github.com/maplibre/maplibre-native/blob/main/src/mbgl/renderer/renderer_impl.cpp) in the toolkit seems to only support one explicit rendering pass.
+The [low level rendering logic](https://github.com/maplibre/maplibre-native/blob/main/src/mln/renderer/renderer_impl.cpp) in the toolkit seems to only support one explicit rendering pass.
 
-However, there is the [RenderPass](https://github.com/maplibre/maplibre-native/blob/main/src/mbgl/gl/render_pass.hpp) so some notion of this exists in the toolkit, but it's not clear how complete that is.  It may depend on ordering to work things out, rather than the explicit command buffer filling and fences we would use in a more modern approach.
+However, there is the [RenderPass](https://github.com/maplibre/maplibre-native/blob/main/src/mln/gl/render_pass.hpp) so some notion of this exists in the toolkit, but it's not clear how complete that is.  It may depend on ordering to work things out, rather than the explicit command buffer filling and fences we would use in a more modern approach.
 
 In any case, we need this filled out more explicitly for the render targets.
 
@@ -205,7 +205,7 @@ In WhirlyGlobe we’ve always called out separate objects for drawing certain ki
 
 Which is to say that Drawable is a good concept which can encapsulate a lot of complexity.  So much so that it eventually encapsulates ALL the complexity, at least at that level of rendering.  It’s a good interface between the things that construct geometry and the things that render geometry.
 
-To keep the Drawable somewhat manageable, we added the concept of a Drawable Builder.  This is an object that you throw geometry at in a somewhat disordered way and it emits Drawables when you’re done.  MapLibre's [Buckets](https://github.com/maplibre/maplibre-native/blob/main/src/mbgl/renderer/bucket.hpp) are similar, but not quite the same.  Perhaps they'll be adaptable.  We'll see.
+To keep the Drawable somewhat manageable, we added the concept of a Drawable Builder.  This is an object that you throw geometry at in a somewhat disordered way and it emits Drawables when you’re done.  MapLibre's [Buckets](https://github.com/maplibre/maplibre-native/blob/main/src/mln/renderer/bucket.hpp) are similar, but not quite the same.  Perhaps they'll be adaptable.  We'll see.
 
 Drawables and Builders have a subclass for each supported rendering SDK.  One mistake we won’t bring over is using multiple inheritance for that.  You’re welcome.
 
@@ -221,7 +221,7 @@ Builders will be used primarily by Layers to emit Drawables for rendering.
 
 This is a big topic because it gets to the very heart of the critical changes we want to make to the toolkit.  There are a couple of different categories that are revealing and we'll use some examples.
 
-Most commonly there are *render layers*.  These are individual classes that know how to render, for instance, the [fill layer](https://github.com/maplibre/maplibre-native/blob/main/src/mbgl/renderer/layers/render_fill_layer.cpp).  You'll see a bunch of these that start with "render" and end with "layer".
+Most commonly there are *render layers*.  These are individual classes that know how to render, for instance, the [fill layer](https://github.com/maplibre/maplibre-native/blob/main/src/mln/renderer/layers/render_fill_layer.cpp).  You'll see a bunch of these that start with "render" and end with "layer".
 
 What's going on here is that the toolkit has broken out a bunch of features from a tile, consolidated them together in a Bucket and then handed them off to a Layer to render.  Sure enough, if you look in the render_*_layer you can see it doing just that.
 
@@ -230,7 +230,7 @@ Now it's not redoing the work of consolidation each frame, but it is doing a lot
 - This is more specific logic than we'd want to see in a rendering loop.  Remember, this runs every frame.
 - If your data is not in tile form, it's going to be hard to render.
 
-That last one is really interesting and we can find an example in MapLibre Native itself.  Look to the [Render Location Indicator Layer](https://github.com/maplibre/maplibre-native/blob/main/src/mbgl/renderer/layers/render_location_indicator_layer.cpp).  Here's where this approach trips up... rolls down the hill... into a pile of broken glass.  You can feel the developers' pain in this module.
+That last one is really interesting and we can find an example in MapLibre Native itself.  Look to the [Render Location Indicator Layer](https://github.com/maplibre/maplibre-native/blob/main/src/mln/renderer/layers/render_location_indicator_layer.cpp).  Here's where this approach trips up... rolls down the hill... into a pile of broken glass.  You can feel the developers' pain in this module.
 
 If you're not familiar with real time rendering toolkits, I'll put it this way.  Managing the logic for a location puck that updates every time the user moves should not involve direct OpenGL calls.  It should be abstracted, at least a little.
 
@@ -319,7 +319,7 @@ Every real time rendering toolkit has a main rendering loop or something like it
 
 On iOS this runs on the main thread and on Android this runs on its own separate thread.  You might think the latter is better, but it has its own problems (gesture lag).  In any case, MapLibre Native handles both just fine.
 
-The toolkit's main rendering "loop" lives in [renderer_impl](https://github.com/maplibre/maplibre-native/blob/main/src/mbgl/renderer/renderer_impl.cpp) and it's worth a look.  It serves as a central point to begin examining the real time rendering.
+The toolkit's main rendering "loop" lives in [renderer_impl](https://github.com/maplibre/maplibre-native/blob/main/src/mln/renderer/renderer_impl.cpp) and it's worth a look.  It serves as a central point to begin examining the real time rendering.
 
 As you might suspect, the rendering loop logic and implementation are heavily influenced by OpenGL.
 

design-proposals/2025-07-05-custom-vector-source.md

@@ -0,0 +1,184 @@
+# Custom Vector Source
+
+## Motivation
+
+MapLibre Native currently supports two ways to provide vector tile data:
+
+1. **URL-based sources** (`vector` source type) — tiles are fetched according to the protocol of the URL (`http://`,
+   `file://`, etc.).
+2. **CustomGeometrySource** — accepts GeoJSON features programmatically, but internally re-encodes them into vector
+   tiles, adding overhead and limiting control over the tile encoding.
+
+This proposal comes from the need for an efficient and kotlin native way to asynchronously connect a tile data source
+similar to vector tile.
+CustomGeometrySource was considered, but it has some obvious drawbacks:
+
+1. Tile requests are in the format of a bounding box — since it's not a tile X/Y/Z it is pretty unclear what logic it
+   conforms to.
+    1. Is it just a tile X/Y/Z but converted to geo bounds?
+    2. Can it ever request data in a bounding box that is bigger than just one X/Y/Z tile
+    3. Additional boilerplate of mapping geo bounds into tile X/Y/Z
+2. Internally CustomGeometrySource spawns a 4 thread threadpool and runs tasks one by one inside. It's a good old
+   technique
+   but Kotlin has things like coroutines which are a more ergonomic way to handle suspendable operations (like network
+   requests).
+3. CustomGeometrySource operates over GeoJSON. So in case of a vector tiles like format it needs to be converted to
+   GeoJSON and then internally it will be cut down into vector tile format back.
+
+## Proposed Change
+
+Introduce a new source type, `CustomVectorSource`, that lets the application deliver raw binary tile data (starting with
+MVT) directly to the rendering pipeline. The source participates in the standard tile loading lifecycle — the core
+requests tiles by `CanonicalTileID`, and the application responds asynchronously with encoded data or an error.
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Platform layer (Kotlin)                                    │
+│                                                             │
+│  CustomVectorTileProvider.fetchTile(z, x, y) → TileData     │
+│       ↕ (JNI / platform bridge)                             │
+├─────────────────────────────────────────────────────────────┤
+│  Core C++ layer                                             │
+│                                                             │
+│  CustomVectorSource                                         │
+│    ├── Options { fetchTileFunction, cancelTileFunction,     │
+│    │             zoomRange }                                │
+│    ├── setTileData(CanonicalTileID, shared_ptr<string>,     │
+│    │              TileDataFormat)                           │
+│    ├── setTileError(CanonicalTileID, exception_ptr)         │
+│    └── invalidateTile(CanonicalTileID)                      │
+│                                                             │
+│  CustomVectorTileLoader (Actor on Scheduler::GetBackground) │
+│    └── Receives fetch/cancel requests from tiles            │
+│                                                             │
+│  CustomVectorTile (extends Tile)                            │
+│    └── Parses MVT data via VectorTileData, delegates to     │
+│        standard GeometryTileWorker for symbol/line/fill     │
+│        layout                                               │
+│                                                             │
+│  RenderCustomVectorSource (extends RenderTileSetSource)     │
+│    └── Standard tile pyramid rendering                      │
+├─────────────────────────────────────────────────────────────┤
+│  Existing rendering pipeline (unchanged)                    │
+│    GeometryTileWorker → Buckets → Drawables → GPU           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Key Design Decisions
+
+1. **Binary data, not GeoJSON.** For the Kotlin layer to send data to C++, it needs to be marshaled into some
+   data format that can be passed across languages. One could come up with a new binary format, implement an encoder in
+   Kotlin and a decoder in C++. But it turns out MVT is already such a format — just a binary blob that can be passed
+   simply as a sized buffer. Existing infrastructure of `MVT` tile data is just reused as is.
+
+2. **Actor-based concurrency.** `CustomVectorTileLoader` runs on a background thread via MapLibre's Actor system. The
+   platform callback (fetch/cancel) is invoked on this thread; the platform layer is responsible for dispatching to its
+   own preferred context (e.g., coroutines on Android).
+
+3. **Cooperative cancellation.** When a tile is no longer needed (e.g., user panned away), the core calls
+   `cancelTileFunction`. The platform layer can abort in-flight work.
+
+4. **Standard tile pipeline reuse.** Once binary data arrives, it goes through the same `VectorTileData` →
+   `GeometryTileWorker` path as HTTP-fetched vector tiles. No custom rendering code is needed.
+
+5. **Extensible format enum.** `TileDataFormat` is an enum starting with `MVT`. Future formats (e.g., a hypothetical
+   compact binary format) can be added without API changes. And obvious next candidate is `MLT` format support in
+   CustomVectorSource.
+
+### Threading Model
+
+```
+Main thread:     Source::update() → tile needs data
+                         ↓
+Background Actor: CustomVectorTileLoader::fetchTile()
+                         ↓
+Platform bridge:  fetchTileFunction callback → platform code
+                         ↓ (async, any thread)
+                  setTileData() → mailbox → CustomVectorTile::setData()
+                         ↓
+GeometryTileWorker: parse MVT, create buckets (background pool)
+                         ↓
+Main thread:     Tile ready → render
+```
+
+## API Modifications
+
+### Core C++ (public header)
+
+```cpp
+namespace mln::style {
+
+enum class TileDataFormat : uint8_t { MVT = 0 };
+
+using TileFunction = std::function<void(const CanonicalTileID&)>;
+
+class CustomVectorSource final : public Source {
+public:
+    struct Options {
+        TileFunction fetchTileFunction;
+        TileFunction cancelTileFunction;
+        Range<uint8_t> zoomRange = {0, 18};
+    };
+
+    CustomVectorSource(std::string id, const Options& options);
+
+    void setTileData(const CanonicalTileID&,
+                     const std::shared_ptr<const std::string>& data,
+                     TileDataFormat format = TileDataFormat::MVT);
+    void setTileError(const CanonicalTileID&, std::exception_ptr error);
+    void invalidateTile(const CanonicalTileID&);
+};
+
+} // namespace mln::style
+```
+
+### Android (Kotlin)
+
+```kotlin
+interface CustomVectorTileProvider {
+    suspend fun fetchTile(z: Int, x: Int, y: Int): TileData
+}
+
+sealed class TileData {
+    class Mvt(val data: ByteArray) : TileData()
+}
+
+class CustomVectorSource(
+    id: String,
+    provider: CustomVectorTileProvider,
+    scope: CoroutineScope,
+    minZoom: Int = 0,
+    maxZoom: Int = 18
+) : Source()
+```
+
+The Android API uses Kotlin coroutines for async tile fetching. The `CoroutineScope` is caller-provided. Meaning
+`CustomVectorSource` can run on a threadpool but not limited to a threadpool. `CoroutineScope` abstracts it away.
+
+### iOS / macOS
+
+Not included in this initial implementation. The core C++ API is platform-agnostic and can be wrapped in Swift/Obj-C
+following the same pattern.
+
+## Migration Plan and Compatibility
+
+All changes are **additive**. No existing APIs are modified or removed. The new source type is opt-in — applications
+that don't use it are unaffected.
+
+- A new `SourceType::CustomMVTVector` enum value is added to the core.
+- Existing `CustomGeometrySource` remains unchanged and is not deprecated.
+
+## Rejected Alternatives
+
+### Extend CustomGeometrySource to accept binary data
+
+`CustomGeometrySource` is designed around GeoJSON features and internally manages geometry encoding. Bolting binary tile
+support onto it would conflate two different data models and complicate its already non-trivial implementation.
+
+### Use a local file source with a custom URL scheme
+
+This approach (e.g., `mbtiles://` or `custom://`) requires the application to write tile data to disk or implement a
+custom `FileSource`. It adds I/O overhead, doesn't support cooperative cancellation, and is harder to integrate with
+structured concurrency frameworks like Kotlin coroutines.

docs/20_调查/R0_Placement跨段归因与缓存安全边界调查_v1.md

@@ -0,0 +1,116 @@
+# R0 Placement 跨段归因与缓存安全边界调查 v1
+
+**STEP-110，2026-10-10；状态：PARTIAL（只读调查，非修复验收）。**
+
+**执行记录**：Codex CLI 0.161.0 实际会话模型 gpt-6-astra，推理 high，完成源码和历史证据审查；其报告写入阶段重复无响应，故本报告由 GPT 指挥 RDC 根据 Codex 调查结论独立回读关键源码后落盘。未运行测试、编译、ADB，也未修改业务实现。所有源码行号以调查起点 particle/main 2df504c 为准。
+
+## 1. 发行源码核对
+
+| 来源 | Git 提交 | 实际意义 |
+|---|---|---|
+| V23 GSRL Source Lock | 87f3d1c59a52581fb8339f0ea7d106b9f4b94fef | RN / Android Native 13.6.1-particle.23 构建源码 |
+| V23 Tag 剥离后提交 | a0a4787b4379ab2819943d20ce05a7ae760a88c3 | 构建提交之后的发行资料提交；注释 Tag 对象本身是 3ce42184… |
+| 当前 particle/main 和 origin/particle/main 调查起点 | 2df504cdc0403bdad85d3f31f16fd54a8744abac | 包含后续 STEP-109 尚未发行的 FieldSnapshot 比较优化 |
+
+Codex 通过 Git Blob 对照确认：src/mln/renderer/render_orchestrator.cpp、renderer_impl.cpp、src/mln/text/placement.cpp、include/mln/renderer/render_segment.hpp、src/mln/renderer/retained_underlay_cache.cpp 和 particle_fast_path.hpp 在上述三个提交完全相同。此范围内 main 的分析适用于 V23；不能反推 STEP-109 优化已在 V23 APK 生效。
+
+NavSea 输入冻结事实：Android 13 FZG1-2 V23，R0 [0,31) RETAINED 含地名 Symbol，C1 后续 82 层 CONTINUOUS。15.24 秒期间 placementChanged=true、R0 placementGatePassed=false、build/reuse=0、fallback/invalidation=453、fastPathHit Δ0、fastPathMiss Δ452，CPU 约 99%。**快照只能证实 Gate 未通过，不能证实 C1 引发 R0 Symbol 实际位置变化。**
+
+## 2. Q1：Placement 产生、传播、状态语义
+
+1. src/mln/renderer/renderer.cpp:53-65：先尝试 tryRenderParticleFastFrame；未命中即创建 RenderTree、prepare、完整 render，再缓存 prepared tree。
+2. src/mln/renderer/render_orchestrator.cpp:737-749：逐个 RenderLayer.prepare，依据动态 needsPlacement() 构建 layersNeedPlacement。该集合与 R0 的结构性 placementCapable 不是一回事。
+3. 同文件 :758-773：反向遍历整个 RenderTree 的需要 Placement 的图层，CrossTileSymbolIndex.addLayer 汇聚 Tile/Symbol 变化。该过程是整图范围，不按 Segment 独立产生。
+4. 同文件 :775-810：在 Continuous 模式，placementChanged = !placementController.placementIsRecent(now, zoom, override)。为 true 才调用 Placement::create、placeLayers、setPlacement；否则 setPlacementStale。随后取全局 symbolFadeChange，调用 hasTransitions 控制 needsRepaint。它表示**本轮要重新 Placement**，不表示 R0 最终视觉结果必然不同；为 false 也不保证新旧 R0 内容相等。
+5. 同文件 :811-823：非 Continuous 模式还有每次非空 Symbol Layers 就重算的特殊路径，不应混同天气播放运行态。
+6. 同文件 :840-848：全局 Placement、layersNeedPlacement、symbolBucketsChanged 进入 RenderTree。Renderer 再独立判断各 Retained Segment。
+
+src/mln/text/placement.cpp:45-59 CollisionGroups::get 在 crossSourceCollisions=false 时为不同 Source 创建隔离 collision group；开启时跨 Source Symbol 可以互相影响。**Source 不是 Segment**，同 Source 跨段仍存在相互影响，反之分段并不天然保证视觉隔离。
+
+src/mln/text/placement.cpp:688-748 根据新旧 placed icon/text 更新 opacity 与 fadeStartTime；:1282、:1319 提供 symbolFadeChange / hasTransitions。shaders/symbol_sdf.vertex.glsl:153-158 和 shaders/symbol_text_and_icon.vertex.glsl:153-158 表明 alpha 依赖 symbol fade uniform。即使符号几何未变，透明度也可能变化。symbolFadeChange、placementTransitionActive 是全局时间/过渡量，不是 R0 独立验收结果。
+
+Source layout/tile/visibility、Camera、Animation、Transition 均可能令 RenderTree prepare 或 Placement 状态变化；普通非 Symbol 粒子/颜色动画可以触发 repaint，但**不能单靠 repaint 来源判定 R0 新旧 placed 结果**。
+
+## 3. Q2：R0 Cache Gate 的真实数据流
+
+src/mln/renderer/renderer_impl.cpp:634-686 对每个 RETAINED Segment 分别取得：
+- retainedRangeContentFingerprint / layerContentChanged；
+- retainedSegmentSourceState 的 ready、stable、revision；
+- 组合的 segmentContentRevision；
+- retainedSegmentIsStable；
+- retainedRangeHasPlacementCapableLayer 结构性 placementCapable；
+- renderSegmentPlacementGatePassed 的结果。
+
+**确切 Gate**：include/mln/renderer/render_segment.hpp:85-90 规定：无 Placement 能力的段直接放行 Placement Gate；否则必须同时满足 placementChanged=false、symbolFadeChange=0、placementTransitionActive=false。它读取的后三者是全局状态，不读取“事件由 C1 发起”或 R0 实际视觉等价证明。
+
+src/mln/renderer/renderer_impl.cpp:661-686：Cache 支持还需要 Style/Sprite/global resources ready、Continuous 模式、没有 3D/debug、segmentStable、无 legacy/unsupported layer。Gate 失败可选择 static-placement 并传递给 cache.evaluate；:681-692 只有 Build/Reuse 才申请资源。:998-1028 先判断 global-live fallback，否则以 visitRenderSegmentExecution 顺序执行每段 composite/live，保持层序；actualExecution=live 不是证明 R0 Symbol 真变化，只表示本帧未从缓存 Composite。
+
+src/mln/renderer/renderer_impl.cpp:590-630 还保留聚合的 retainedPlacementStable 和 Fast Path 支持判定，说明每段 Gate 局部化**不等于**整个 Fast Path 可局部化。
+
+src/mln/renderer/retained_underlay_cache.cpp:85-105 将 camera/boundary、topology、content、tile、static-transition、static-placement 分别归类；:359-379 的 invalidate 更新 lastInvalidationReason，releaseResources 释放缓存，没有“每帧清零历史原因”的语义。因此早期快照当前 placementChanged=false 同时保留 lastInvalidationReason=static-placement **不是直接矛盾证据**；必须在同一帧比较 Gate、cacheSupported、decision、lastReason 的采样时序。
+
+STEP-102/STEP-106 的作用边界是 **placement-free Retained 的局部复用**。本机原始 Android 保存日志 artifacts/maplibre-particle/step106-t2-fix/runtime-T2/stream.log 末尾 tick130：placementChanged=true、crossSourceCollisions=true，但两个 placementCapable=false 的 Retained 段显示 actual=composite、decision=reuse、build=1、reuse=3878；内部 Annotation Symbol 被放入后续 Continuous。T1 的 Symbol-bearing Retained 未解除保守回退。**历史验收未证明含地名 Symbol 的 R0 可复用。**
+
+## 4. Q3：七种反事实场景
+
+| 场景 | Placement 事件来源能否定位 | R0 视觉是否可独立证明不变 | Reuse 必要安全条件 | V23 结论 |
+|---|---|---|---|---|
+| 1 R0 地名静态，C1 只更新非 Symbol 粒子/颜色 | 可按 Layer/Repaint 来源条件性追踪，Placement Controller 仍是全局 | 不能凭 C1 非 Symbol 就证明 | R0 Tile/layout/content/Camera、全部 Symbol placed/opacity/fade 与缓存时等价，无其他全局影响 | 无充分逐段证明；fail-closed |
+| 2 C1 Symbol 改动，不同 Source、crossSourceCollisions 关闭 | Source mutation 可区分 | 隔离碰撞降低风险，但仍不能独立证明 R0 Fade/Camera/其他 Source 状态不变 | 确认 Source 独立、Collision group 隔离、R0 自身配置、Tile、Fade 和层序均稳定 | 仅全局 Gate；fail-closed |
+| 3 C1 Symbol 改动且跨源碰撞开启 | 可以部分追踪事件 Source | **不能**；跨 Source Symbol 可能排斥 R0 地名 | 比较新旧全局 Collision 后 R0 每个文本/图标位置、显隐、Opacity、层序 | 无独立证明；fail-closed |
+| 4 R0 Symbol layout/tile/visibility/zoom 改动 | 局部 revision/fingerprint 可见 | 默认不能 | 重新 Placement / Build 缓存后验证 R0 版本和绘制结果 | 失效正确；fail-closed |
+| 5 Camera pan/zoom/rotation/pitch 改动 | Camera/signature/matrix 可识别 | 旧屏幕纹理通常不等价 | 新 Camera、projection、viewport 对应重新构建缓存并核对碰撞 | Camera/Boundary Gate；fail-closed |
+| 6 Fade/Placement Transition 活跃或刚结束 | Controller 可观察过渡 | 不能由几何稳定推出 opacity 稳定 | 所有 R0 Symbol opacity/fade、Transition 与缓存时等价，且状态稳定 | 只有全局 Fade/Transition Gate；fail-closed |
+| 7 C1 自动插入 Annotation Symbol | 验证场景的 Annotation layer 可追踪；NavSea 实际归段需运行证据 | 不能：跨段 Annotation 可能参与全局 Collision | 明确真实层序、Source/collision 关系，证明 R0 新旧 placed/fade 等价 | STEP-106 只覆盖 placement-free 段；fail-closed |
+
+重点：不同 Segment **不是** Collision 独立证据。仅识别“谁引起 Placement”并不足以让 R0 安全 Reuse；必须满足实际视觉、相机、图层顺序以及已缓存纹理的等价性。
+
+## 5. Q4：Fast Path 的其他独立必要 Gate
+
+Renderer 的 Fast Path 在完整 RenderTree 之前尝试。src/mln/renderer/renderer_impl.cpp:590-630 的 Retained eligibility/单 C 支持是前置条件；src/mln/renderer/particle_fast_path.hpp 的 Fast Path 判定还检查 boundary、topology、staticStable、hasPlacementTransition、pending changes、nonparticle transition/repaint、fading tiles、是否 Particle repaint、still image、continuous mode、debug、unsupported continuous layer、supported scene、annotation mutation 等。
+
+因此**R0 cache 有效是相关 Fast Path 的必要条件之一，绝不是充分条件**。当前 cache-invalid 说明首先在此受阻，不允许宣称修好 R0 就一定 hit，也不能在本 STEP 扩大调查到 C1 82 层所有性能开销或实施多 Continuous 优化。
+
+## 6. 数据流 / 状态流
+
+Host 更新 / Style / Source / Camera / 动画
+→ Renderer::update 尝试 Fast Path（未命中时）
+→ RenderOrchestrator.createRenderTree
+→ 全局 layer.prepare / needsPlacement / CrossTileIndex / PlacementController
+→ 全局 placementChanged / symbolFadeChange / hasTransitions
+→ 对各 Retained 段独立：Source ready/stable/revision + Fingerprint + structural placementCapable
+→ placement-free 段绕开全局 Placement Gate；Symbol-bearing 段使用全局三项严格 Gate
+→ Style/Resource/Camera/Revision 安全校验
+→ Cache Build / Reuse / Fallback
+→ 保序 RenderSegment Composite / Live
+→ Fast Path 另有单 C、pending、unsupported continuous 等 Gate。
+
+## 7. 确定事实、假设、证据不足
+
+| 确定事实 | 不能直接断言的假设 | 需要补的证据 |
+|---|---|---|
+| V23 核心 Placement/Cache 逻辑与当前 main 等价 | C1 变化直接导致 R0 视觉改变 | NavSea 同一帧事件来源、各 Source mutation、R0 全 Symbol 新旧结果 |
+| placementChanged 是全局计算触发量 | placementChanged=true 意味 R0 所有地名改变 | per-R0 placed/opacity/fade 结果签名 |
+| 含 Symbol 的 R0 使用 global conservative Gate | R0 453 次 fallback 是已证的性能 Bug | 既有语义被违反的状态不变量；当前并无证据 |
+| T2 实验 placement-free 段重复复用 | 现有 T2 足以支持含 Symbol R0 | NavSea 实际 Source/Annotation/跨源碰撞和真实设备对照 |
+| STEP-109 main 更改没有改 Gate | V23 已有 STEP-109 修复 | 需下一正式发行 GSRL 和设备验收（本 Step 禁止） |
+
+## 8. 必选结论矩阵
+
+| 维度 | 明确判定 |
+|---|---|
+| Placement 事件来源能否定位 | **条件性可区分**（Source/Layer 可追踪，global Placement 本身不标 per-Segment 责任） |
+| 能否证明 R0 视觉最终未变化 | **需扩展内部安全证据** |
+| 现有 Gate 性质 | **正确的设计保守限制**，不是已证明违反 STEP-102 语义的 Bug |
+| 缓存失效主要责任 | **多因素**：Native Placement 缺少 per-R0 结果证据 + Native 全局 Gate，受 Collision 语义和 Host Style/Annotation 组合影响 |
+| 下一步 | **Native 内部诊断补强 → 安全判据设计 → 另行授权真机对照**；若改公共接口/Host，则交 Integration 协商 |
+
+## 9. 依赖顺序与最小后续验证
+
+1. 在不影响生产安全和公开 API 的前提下，记录 placement 重算触发原因与时间，拆分 Source/Layer/Camera/Tile/transition 事件；
+2. 设计 per-R0 Placement **结果等价安全证据**，至少包含 R0 Symbol placed IDs、位置、可见性、text/icon opacity/fade、Collision group、Tile/glyph/source 版本、Camera 和合成顺序；先审查其不变量；
+3. 只有确证 R0 不受 C1 影响时，才另立有边界的 Native Gate 优化任务；不能先去掉 placementChanged；
+4. 再调查 Fast Path 单 C / unsupported / pending 等 Gate；进行等条件 V23 与后续版本 CPU/Frame/Visual A-B；
+5. 如需要 NavSea 配合改 Style/Annotation 或改公共 Contract/API，形成 Integration 阻塞请求，不在 STEP-110 擅自实施。
+
+**调查状态：PARTIAL。** 已完成静态因果审计、源码版本对照和 STEP-106 历史证据核对；缺少生产 R0 per-Symbol 等价、事件逐帧对应和 CPU 因果实测。这是安全证据边界，不是“R0 已修好”“缓存已命中”“CPU 已下降”。

docs/20_调查/STEP-111_R段Placement结果等价与独立刷新可行性调查_v1.md

@@ -0,0 +1,56 @@
+# STEP-111：R 段 Placement 结果等价与独立刷新可行性调查 v1
+
+**日期：2026-10-10｜状态：PARTIAL（初步可行性判断，不是 Codex 完整设计或运行验收）**
+
+## 1. 范围及真实证据
+- Mac `/Users/tei/dev/MapLibreParticleLab`，`particle/main`；调查时 HEAD `7ec9ac8c1635c7a3b607abc2ed4be4fd764e7b6d`。Integration `main` 与 `origin/main` 一致于 `80667d6c343411d03a760425438e3d292f452118`。
+- 使用可见 GNU Screen `7445.codex`，真实界面显示 **GPT-6 Astra high**；Codex 进行两轮源码浏览/调查后长期无新事件，第二轮缩窄至直接写报告仍无输出，随后终止会话；未生成任何要求的 STEP-111 正式调查文档。此文件由 GPT/RDC 对当下代码和既有 STEP-110 证据重新核对后撰写，**不冒称 Codex 已完成 STEP-111**。
+- 未改 C++/Swift/Kotlin/JS/测试代码，未编译、未测试、未跑设备；本文件是方案评估，不是新增 Native 功能。
+
+## 2. 现有实现的确定事实（RDC 逐行核验）
+1. `src/mln/renderer/render_orchestrator.cpp:775-810`：Continuous 渲染使用 `placementController.placementIsRecent` 得到全局 `placementChanged`，随后视情况新建 Placement、调用 `placeLayers(layersNeedPlacement)` 并更新 Controller；`symbolFadeChange` 和过渡也作为全局状态处理。这里的 `placementChanged` 表示重算触发，**不证明每一个 R 的最终输出改变**。
+2. `include/mln/renderer/render_segment.hpp:78-90`：R 中只要出现 `layerType == "symbol"` 就被标为 placementCapable；Gate 对这种 R 要求全局 `!placementChanged && symbolFadeChange==0 && !placementTransitionActive`。没有 per-R 最终 Symbol 结果比较。
+3. `src/mln/renderer/renderer_impl.cpp:638-686`：对每个 RETAINED 段已经独立计算内容 fingerprint、Source ready/stable/revision、segmentStable、placementCapable，并在 `cache->evaluate` 决定复用、构建或 fallback；`static-placement` 是 Gate 未通过时的失败原因。逐 R Cache 管理已存在，**缺的是含 Symbol 段的逐段结果等价证据**。
+4. STEP-110 已核对的 `src/mln/text/placement.cpp` CollisionGroups/opacity/fade 说明：Collision Domain 与 RenderSegment 边界不等价；跨 Source 碰撞开关、同 Source 跨段、text/icon Fade 等可能让别的段影响本段可见结果。STEP-102/106 仅能证明 placement-free 的安全复用，不直接证明含 Symbol R 的安全复用。
+
+## 3. 推荐的目标语义（待设计与实测）
+`R0-C0-R1-C1-R2-C2` 六段按图层顺序合成；若 R1 内 Symbol 的**最终绘制结果**与其上次成功 Build 的缓存版本等价，允许 R1 复用，而不因某个 R0/R2/C 段触发 global placementChanged 自动 Fallback。跨段碰撞真的改变 R1 Symbol 的显隐、锚点、位置、opacity 或其它绘制依赖时，R1 必须失效。
+
+**不等于**每个 R 拥有独立 Collision Index。第一阶段可以仍全图计算 Placement，之后对不同 R 的已完成结果分别判等，再控制各段纹理的 Build/Reuse；这只争取避免不必要的段重绘，不能自动省略全局 prepare/Placement、非 R 的 C 绘制或保证 Fast Path hit。
+
+### 待验证的候选签名（不是已实现结构）
+建议研究在 `placeLayers` 完毕之后、`renderer_impl.cpp:638-686` Cache 决定之前提供 `per-R PlacementResultRevision` 或严格结果比较，关联已缓存 Build 版本，而不只与上一帧比较。候选依赖包括：
+- 按层序可稳定归属到 R 的 text/icon 实例、Tile/Bucket/Source 世代与 placement/collision 可见性、锚点、偏移、实际绘制位置；
+- Fade/Opacity/Transition 的可绘制值或明确的“稳定可复用”条件；纹理/glyph/sprite/atlas 的有效世代；
+- Camera/projection/zoom/viewport/pixelRatio、Style 顺序与合成边界；这些可优先复用已有 Camera/Content/Resource Gate，不应盲目重复扫描；
+- 新旧结果缺失、ID 不稳定、资源生命周期不可证明、哈希碰撞或任意未知场景均 **fail-closed**。
+
+上述字段只是**候选调查清单**，现有代码尚未证明可以低开销取得稳定、完整的 per-R 视觉语义。简单“Symbol ID/位置没变”或单一 64-bit hash 相等都不足以证明最终像素安全等价。
+
+## 4. RCRCRC 反事实场景
+| 情况 | 希望达到的复用决策 | 当前证据边界 |
+|---|---|---|
+| C1 只有粒子/颜色更新，R0/R1/R2 视觉稳定 | R0/R1/R2 独立复用 | 当前 global Gate 可能挡住含 Symbol R；仍须取得最终结果不变证据 |
+| C1 Symbol 改变，仅使 R2 发生碰撞结果变化 | R2 重建；R0/R1 如证实未变可复用 | 事件来源不能替代逐 R 结果比较 |
+| C1 Symbol 改变，同时影响 R0 与 R1 | R0/R1 失效、不得复用旧遮挡 | 必须保留全局 Collision 正确性 |
+| R1 自身 Layer/Tile/Style 更改，R0/R2 不变 | R1 失效；其余分别判等 | 现有内容 revision 可局部区分，但 Symbol 仍有全局 Gate |
+| Camera/Zoom/Pitch、Annotation、Fade、Glyph 变化 | 受影响 R 失效；未知则全体安全回退 | 不得将各段等同独立碰撞域；须验证跨平台一致性 |
+
+## 5. 难度分级（GPT/RDC 初估，尚未经 Codex 最终复核）
+| 阶段 | 复杂度 1–5 | 输出与主要难点 |
+|---|---:|---|
+| A：只读设计 + 逐 R trace/reason | 2–3 | 诊断 event 来源与 per-R Cache 状态，不改变业务 |
+| B：Native per-R result fingerprint 的 shadow compare | 3 | 找齐最终 Placement 数据、稳定身份/世代、控制逐帧遍历成本；**只记录，不参与复用** |
+| C：用已验证等价结果替换含 Symbol R 的 global-only Gate | 4 | 与 Cache 生命周期/资源/层序/Fade 联动，必须零 false-reuse；Android OpenGL、iOS Metal 对照 |
+| D：真正把全图 Placement/Collision 改成分段增量计算 | 5 | 全局碰撞依赖与跨 Tile/Source 的更新传播，风险明显更高、不能简单按 R 切分 |
+
+工程周期目前**无法从静态代码得到可信承诺**。复杂度 3 表示可做有限验证原型；4 代表需多阶段视觉/性能门槛；5 代表核心架构重构，不能与缓存命中优化混为一谈。
+
+## 6. 后续建议及未完成项
+1. 下一次正式任务先补只读源码数据所有权审计：Placement 完成后在哪个对象/时间点能列出每 R 所属 symbol 的最终 placed/opacity，并确定 crossTileID、tile/glyph 资源失效契约。输出字段级“已有/缺失/必须新增”清单。
+2. 再授权仅做 **shadow-mode** 内部诊断：per-R `resultComparable/resultChanged/unknown` 与 global Gate 同步采样，**不改变 Gate**；采样成本与候选数量需量化，防止 O(N) 比较本身抵消收益。
+3. 真实 RCRCRC（每个 R 含 Symbol）覆盖同 Source/跨 Source 碰撞开关、Annotation、Fade、Camera、Tile、Layer 顺序及前后多帧；全缓存 ON/OFF 视觉一致，**false reuse 必须为零**。
+4. 通过后才另行授权 C 阶段优化，先看独立 R build/reuse/fallback 与 CPU/帧变化；Fast Path 对单 C、pending、non-particle repaint 等另有门槛，不作为此优化的当然收益。
+5. 若出现跨平台公共语义/公共接口改变，回 Integration RFC/ADR 处理；本阶段不得更改现有 API/Contract。
+
+**未完成：** Codex 未形成字段级可行性结论；无 per-R Placement 结果签名、运行对照、性能证据或真实 Native 修复。不可标“调查 PASS”或“独立刷新已实现”。

docs/20_调查/STEP-112_V23粒子FullRender循环与Symbol缓存准入全面源码调查_v1.md

@@ -0,0 +1,426 @@
+# STEP-112 V23 粒子 Full Render 循环与 Symbol 缓存准入全面源码调查 v1
+
+日期：2026-10-11（JST）。状态：本轮只读调查与文档交付完成；综合判定 **PARTIAL（现场逐帧归因及安全修复仍未验证）**。核心结论、证据等级和剩余事项见第11章。
+
+## 1. 调查基线与证据规则
+
+- 当前机器：Mac.lan，Darwin 24.6.0，x86_64；仓库 `/Users/tei/dev/MapLibreParticleLab`。
+- 分支 `particle/main`，起点 HEAD `41b416c261fa72bd21171328045036a124694f47`。
+- 实际模型 `gpt-6-astra`、推理 `high`：当前会话 `01a12686-49ee-70b1-953e-f95f8a4bd9ca` 的本地 rollout `turn_context.model/effort` 已核对。任务书建议模型由用户本轮明确要求覆盖。
+- 起点只有 STEP-110、STEP-111 两份任务书未跟踪，无 tracked diff；不改动它们。子模块状态均为空格前缀，无未初始化/偏移标记。
+- Integration `main=80667d6c` 使用用户提供的 RDC 核验事实，不重新同步或修改跨项目文件。
+- 已按顺序读取 AGENTS、PARTICLE_BASELINE、8 份项目规范、总则 README 与四份现行总则、STEP-112、STEP-102/106/109/110/111 的相关任务/记录/报告。初始化基线及现行路线 v2 中旧版本坐标不冒充当前 V23；后续按 Git 实际源码比对。
+- 证据分为 **源码证明**（指定基线静态控制流）、**FZG1 实测**（本任务引用历史现场输入，非本轮重测）、**条件推断**（前提明确的推演）、**仍需设备验证**（频率、真实配置、像素/性能）。
+- 只允许写本主报告、STEP-112 阶段记录、完成报告、开发记录追加。禁止源码/测试/Style/脚本/跨项目写入，禁止编译测试、设备操作、Git 提交推送及分支/worktree 变更。
+
+## 2. 已核实的入口事实
+
+**源码证明**：`src/mln/renderer/renderer.cpp:45-64` 先同步 retained 状态，再尝试 Fast；失败才清除旧 prepared tree、`createRenderTree`、`prepare`、Full render、保存新 prepared tree。Fast 失败与粒子请求下一帧属于不同决策。
+
+**源码证明**：`src/mln/renderer/particle_fast_path.hpp:99-126` 顺序短路。`cache-invalid` 在第 3 项返回，后续 revision、camera、staticStable、placement、pending、非粒子 repaint、C 层支持、scene 等条件没有因此得到通过证明。
+
+## 3. 核心发现：Symbol R 首次 Build 的控制流矛盾
+
+**源码证明（正常 Continuous Full 路径）**：含结构性 Symbol 的 R 没有通过当前逐段 Placement Gate 的窗口。这比“Fade 的 `==0` 可能太严格”更强，且不依赖 Source 变化或实际 Symbol 是否移动。
+
+1. `src/mln/renderer/render_orchestrator.cpp:792-807`：`placementChanged=true` 时执行 Placement；否则无条件 `setPlacementStale()`。
+2. `src/mln/text/placement.cpp:160-175`：旧 Placement 禁用 transitions 时 `placementIsRecent()` 必为 false，故必进入 changed=true 分支；若进入 changed=false 分支，旧 Placement 必启用 transitions，随后 stale=true，使 Controller `hasTransitions()` 必为 true。
+3. `src/mln/renderer/renderer_impl.cpp:593-594,655-659` 读取同一 Controller 的 transition；`include/mln/renderer/render_segment.hpp:85-90` 要求 `!changed && fade==0 && !transition`。
+4. 因而 changed=true 被第一项挡住；changed=false 被 stale→transition=true 挡住。对结构性 Symbol R，两个分支均 false。`RenderTreeImpl::prepare`（`render_orchestrator.cpp:133-138`）仅更新 buckets，不清 Controller stale；没有中间解除路径。
+
+此结论限定正常单线程 Renderer 调用链，不将任意人工注入/未来改动当作当前可达状态。隐藏/空 Symbol 仍按结构归为 capable（`render_segment.hpp:75-90`），所以也不能绕开这层保护。
+
+**源码证明**：原始 `Placement::symbolFadeChange` 是相对 commitTime 的归一化时间增量加 zoomAdjustment，而非“本帧是否改变”布尔量（`placement.cpp:1282-1289`）；transitions 关闭或 duration≤0 返回 **1**。正常 Full 的 `prepare()` 不改写它。只有已通过 Fast 的 `prepareParticleFastFrame()` 才把 RenderTree 字段设为 0（`render_tree.hpp:105-109`），不能反过来帮助首次 Build。
+
+**FZG1 实测（任务书输入）**：末态 true/0/false 与“transitions 开启、此次重新计算、静止 zoom、先前实际 Fade 已结束”的状态相容；与通常 transitions 关闭后的 true/1/false 不同。不能仅凭此末态推断每帧走默认 300ms 周期或 Host 确实关闭 transitions。
+
+**条件推断**：在 retained enabled、正常 Continuous Full、R2 含 Symbol 的前提下，逐帧 `segmentSupported=false` 可令 Build 始终为 0；`retained_underlay_cache.cpp:195-205,359-366` 即使此前没有有效纹理也每次记录 fallback/invalidation。故 1787 次 invalidation 不表示曾成功建成 1787 份纹理。
+
+以下第4—10章已补齐调度、全部 Gate、状态机、时间表、反事实和提案；运行时无新增证明，不能据此声称修复 PASS。
+
+## 4. 版本核验与 A：调度、Full、GPU 和 Idle
+
+### 4.1 当前 main 与发行 V23
+
+**源码证明**：执行只读 `git diff --name-only 87f3d1c59a52581fb8339f0ea7d106b9f4b94fef HEAD -- <相关路径>`，在 renderer/text/map、RasterArraySource、render_segment、TransitionOptions、Android WeatherRuntime/frontend、iOS FieldRuntime、GL/Metal shader 范围内，仅两份文件不同：`render_particle_validation_layer.cpp` 和 `render_weather_color_layer.cpp`。逐 hunk 核对为 STEP-109 的 immutable snapshot 身份快比较，未改变本调查的调度、Placement、Cache、Fast Gate。以下行号一律对应本轮 HEAD，不照搬 V23 两份 Layer 的旧行号。
+
+V23 Source Lock 为 `87f3d1c…`（既有 STEP-110/108 发行证据），Android/RN `13.6.1-particle.23`、iOS `6.29.0-particle.23`。当前 main 包含尚无实机性能验收的 STEP-109；不得称它已在 V23 APK 生效。本轮没有重新下载制品或核对设备内 binary。
+
+### 4.2 可核查调用图
+
+下图箭头“条件”都不是每次必然发生。路径简称只用于图；实际位置见后表。
+
+```mermaid
+flowchart TD
+  H[Host 数据/Style/Camera 更新] --> U[Map::Impl::onUpdate]
+  W[WeatherRuntime 定时唤醒：条件成立] --> T[Map::triggerRepaint]
+  T --> U
+  U --> F[RendererFrontend update / 平台 requestRender]
+  F --> R[Renderer::render]
+  R --> G[tryRenderParticleFastFrame：24 项 Gate]
+  G -->|通过| Q[复用 prepared tree / 更新粒子 / GPU render]
+  G -->|失败| C[createRenderTree / Layer prepare / 全局 Placement 判定]
+  C --> P[RenderTree prepare / bucket opacity 与动态属性]
+  P --> B[各 R evaluate：Build / Reuse / Fallback]
+  B --> D[离屏 Build 或保序 composite/live / GPU 粒子]
+  D --> O[onDidFinishRenderingFrame]
+  Q --> O
+  O -->|needsRepaint 或 camera transition| U
+  O -->|loaded 且无需 repaint/transition| IDLE[onDidBecomeIdle]
+```
+
+| 环节及证据强度 | 文件、函数、行号与条件 |
+|---|---|
+| **源码证明**：粒子是否活动 | `src/mln/renderer/layers/render_particle_validation_layer.cpp:1112-1127`，`isParticleAnimationActive` 检查 active、正式 Source 的 T0/T1、visibility；`needsRepaint` 再检查 V4 cadence 或旧 timeline。active=false、无双端点、visibility=None 不请求粒子 repaint。它不含“必须 Full”标志。单帧输入可投影成可用双端点，不能以业务仅一帧推断无数据。|
+| **源码证明**：粒子暂停和预报暂停不同 | 同上；`RasterArraySource::tickForecastClock`，`src/mln/style/sources/raster_array_source.cpp:487-510` 在 forecast 非 Playing 时不推进预报；这不把粒子 active 设 false。风场时间冻结仍可流动。无向量或语义不匹配另由 Layer `update:1247-1258` 拒绝 GPU 更新。|
+| **源码证明**：Core cadence | `raster_array_source.cpp:149-175,208-227,260-281,1237-1255`；非 AUTO 以 `1/fps` 检查，30 对应约 33.33ms；consume 才推进 cadence revision。AUTO 每次可 due，不等于固定 30。|
+| **源码证明**：Android SDK 唤醒 | `platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/WeatherRuntime.java:228-234,250-269`；有效可见粒子且非 AUTO，或 V4 forecast Playing 且已提交字段时，Handler 每次安排 34ms（60 为 17ms），调用 `map.triggerRepaint()`；disabled/disposed 停止，隐藏粒子但 forecast Playing 仍可唤醒。这里是 SDK Java 调度，不是 NavSea JS 每粒子循环。|
+| **源码证明**：iOS 对应唤醒 | `platform/ios/src/MLNParticleFieldRuntime.mm:173-193`；一次性 NSTimer 0.034/0.017s，触发 `triggerRepaint` 后重新调度。两端意图相同，调度抖动不保证相同。|
+| **源码证明**：进入地图更新 | `src/mln/map/map.cpp:93-95` 调 `Impl::onUpdate`；`src/mln/map/map_impl.cpp:108-153` tick forecast、更新 camera transition、装配 UpdateParameters、调用 frontend.update。非 Continuous 且无 still request 直接返回。|
+| **源码证明**：Android 跨线程链 | `android_renderer_frontend.cpp:118-133,149-152`（路径前缀 `platform/android/MapLibreAndroid/src/cpp/`）AsyncTask 保存最新 params，再 `MapRenderer.update/requestRender`；`map_renderer.cpp:127-149,153-157,221-247` 请求 Java 渲染、后端 scope 中调用 `Renderer::render`。多个 update 可能合并为一次实际 render。|
+| **源码证明**：iOS frontend | `platform/darwin/src/MLNRendererFrontend.h:28-54` 保存 params、setNeedsRerender，backend scope 中 render；不同于强制 Full 命令。|
+| **源码证明**：Fast/Full 分岔 | `src/mln/renderer/renderer.cpp:45-64`；Fast 成功直接 return；否则 create/prepare/render/commit tree。`renderer_impl.cpp:324-327` 只在 `!particleFastFrame` 增加 Full CPU 计数。`FullRendererFrame` 在 :323 两种路径都会计数，名称不能混用。|
+| **源码证明**：Full repaint 汇总 | `render_orchestrator.cpp:775-823,1107-1128`；light、Layer transition/repaint、Controller transition/stale、fading tiles 的 OR；Continuous 时赋 `RenderTreeParameters.needsRepaint`。|
+| **源码证明**：通知与 Idle | `renderer_impl.cpp:1070-1074` → Android forwarding `android_renderer_frontend.cpp:38-44` → `map_impl.cpp:259-288`；needsRepaint 或 transform transition 时 onUpdate，否则 loaded 时通知 Idle。Observer 的 RenderMode::Full 表示 loaded，不表示执行 Full CPU 路径。|
+| **源码证明**：GPU 推进 | Layer `update:1271-1283,1994-2055`；未到 cadence 可只重组 composite，不推进 state/trail；到期才准备 State/Trail pass。`renderer_impl.cpp:807-810,968-980,1047-1053` 执行 render targets 和 present。一次 repaint、一次 Full CPU、一次 simulation advance、一次成功呈现不是同一计数。|
+
+**仍需设备验证**：FZG1 约 30FPS 的真正限速因素是 targetFps=30、平台帧率限制、耗时瓶颈或组合，任务快照不能区分。源码支持“Core 33.33ms 阈值 + SDK 34ms 唤醒”的候选机制，不能把 34ms 直接换算为实测 1792 次 Full 的唯一原因。
+
+**源码证明**：所追踪的 PlacementController 仅在 render 链上比较时间，并无独立定时器调用强制 Full；stale/尚有 Fade 会通过 needsRepaint 延续正常地图帧。没有外部输入且粒子关、其它 transition 完成、资源 loaded 时可 Idle；WeatherRuntime 后续 wake 或 Tile 完成仍能再次唤醒，Idle 不是永久无任务保证。
+
+### 4.3 Full 与 Fast 工作比较
+
+| 工作 | Full | Fast | 证据 |
+|---|---|---|---|
+| diff Style/Source、prepare RenderLayer、CrossTile/Placement、新 RenderTree | 执行相应流程；不等于每帧都 placeLayers | 跳过，复用旧 tree | `renderer.cpp:53-61`；`render_orchestrator.cpp:445-539,737-848` |
+| Source/bucket/atlas upload | 遍历 | 跳过整批 | `renderer_impl.cpp:470-487` |
+| Layer update | 全部 render items | 仅 isParticleAnimationLayer | `renderer_impl.cpp:491-509`；`render_orchestrator.cpp:1458-1483` |
+| tweaker/upload/postRender | 全范围 | 单 C 范围；render targets 仍处理 | `renderer_impl.cpp:707-749,1031-1040` |
+| R GPU | 可 Build、Reuse composite 或 Live | 正常命中应复用；仍进入 cache evaluate/render | `renderer_impl.cpp:637-692,813-862,972-1028` |
+| C GPU、State/Trail、最终 framebuffer/present | 执行 | 仍执行 | 同上及 :1047-1053 |
+
+Fast 不是零 CPU 或零 GPU；Full 不是所有 R 从零重画。PREFIX 中 R0/R3 已复用而 Full CPU 仍增长，正与此结构相符。
+
+## 5. B：Fast 全 Gate 矩阵
+
+下面按 **实际首错顺序**列出全部 24 项。简称：`F=src/mln/renderer/particle_fast_path.hpp`；`I=src/mln/renderer/renderer_impl.cpp`；`O=src/mln/renderer/render_orchestrator.cpp`。表中“Tick”特指静态场、仅粒子 State/Trail 时间推进，不包括 forecast 播放导致新 Source impl；“Full恢复”是假定其它门槛已满足的一次新 Full 能否建立相应证据；FZG1 列区分输入实测与静态推断。
+
+| # / 条件与失败名（F 行） | 输入来源/通过条件 | Tick 本身改变？ | 一次新 Full 后可能恢复？ | FZG1 证据 |
+|---|---|---|---|---|
+| 1 prepared tree / no-prepared-tree (100) | I:247,290-302，tree 非空；reload/miss 清旧 :305-316 | 否 | 是，create 成功后保存 | **FZG1实测** cache-invalid 的那些判定已过此项 |
+| 2 retained enabled / retained-disabled (101) | I:207-208,248，runtime snapshot.enabled | 否 | 需控制面启用，Full 不自动开启 | **FZG1实测** 同上已通过 |
+| 3 所有 R valid / cache-invalid (102) | I:220-228,249，cache 容器与 plan 大小相同，每个 R cache 非空且 isValid | Tick 不改内容；Full Placement gate 可间接 invalidate | 无 Symbol 可建；当前含 Symbol 的 R 不可（第3章） | **FZG1实测** 首拒；R2 Build/Reuse=0 |
+| 4 Build/Static revision / revision-mismatch (103) | I:220-230,250，每 R buildRevision==observedStaticRevision，prepared aggregate static revision==tracker.current | 否；Full 稳定状态变化可推进 tracker | 通常可以，但缓存未建仍失败 | **未知**，被 #3 掩盖 |
+| 5 Content revision / content-mutation (104) | I:236-237,251，prepared 与 O 的 aggregate content revision 相等 | 固定场否；forecast/source 变化可改 | 是，Full 处理后 commit 新值，异步新变更再失效 | **未知**；有历史 Source Mutation 增量，无逐帧对应 |
+| 6 Viewport / viewport-changed (105) | I:214-216,253，Transform size 与 prepared 相等且 backend renderable size 未变 | 否 | resize 后重建可 | **未知**，静止场景不等于逐帧已核验 |
+| 7 Camera / camera-changed (106) | I:217,252，精确投影矩阵相等 | 否 | 新相机完成 Full 后可，持续交互继续失效 | **未知** |
+| 8 non-camera signature / update-parameters-changed (107) | I:151-196,218-219,254，完整签名相等，字段见下段 | timePoint 不入签名；forecast 可能更换 sources | 是，新 params 被 prepare/commit；源持续变则持续 miss | **未知** |
+| 9 Style loaded / style-not-loaded (108) | I:255，UpdateParameters.styleLoaded | 否 | 需真实加载完成 | **未知**（不能以段 ready 代替所有） |
+| 10 Boundary/RangeConfig / boundary-changed (109) | I:209-234,256，唯一 C 的 begin/end、configRevision 与 prepared 相等 | 否 | plan 有效时可；多 C 另被 #22 拦截 | **未知**，已知 PREFIX 数字来自现场 |
+| 11 Topology / topology-changed (110) | I:235,257，prepared topologyRevision==tracker.current；tracker I:542-563、cache.cpp:62-69 | 否 | Full 新拓扑和 cache 可重建 | **未知** |
+| 12 staticStable / static-unstable (111) | I:238-244,258；O:1156-1170，所有 R 稳定、无 light、R 动态 needsPlacement 时 Controller 无 transition、R 无 transition/repaint、**任一 Source** 无 fading tiles | 粒子不直接改 R；时间和 stale 可阻塞 | 取决于 Controller/资源，当前 Symbol 周期不保障恢复 | **条件推断** 部分帧会失败，实际序列未知 |
+| 13 Placement transition / placement-or-fade (112) | I:259-263；O:1281 → PlacementController::hasTransitions(now) 为 false；不读旧 tree 的 changed/fade 代替 | 仅时间推进可结束真实 Fade，但 stale 必须新 placement 清 | 稳定重算帧可清 stale；不重算会置 stale | **FZG1实测** 末态 false；不是所有 Fast 时刻都 false |
+| 14 Pending / pending-changes (113) | I:264；O:1285，pendingChanges.empty；O:1341-1344 入队、1486-1490 消费 | 正常粒子 changes 于 render 中生成/消费；非必然积压 | 通常可以，异步继续到来则不保证 | **未知** |
+| 15 non-particle transition / non-particle-transition (114) | I:265；O:1270-1273，无 light 或任意 Layer.hasTransition | 否；普通 Style transition 可活跃 | 等 transition 真结束再 Full | **未知** |
+| 16 non-particle repaint / non-particle-repaint (115) | I:266；O:1275-1278，非粒子 Layer 均不需 repaint | 固定 V4 场通常否；V3 WeatherColor 播放可 true（Layer :177-180） | 活跃动画不会因 Full 自行结束 | **未知** |
+| 17 fading tiles / fading-tiles (116) | I:267；O:1282-1284，所有 Source 无 fading tiles | 否 | fade 真结束且状态消费后可 | **未知**；与 #12 重复但诊断次序不同 |
+| 18 ParticleNeedsRepaint / no-particle-repaint (117) | I:268；O:1274，至少一个 renderable 且 isParticleAnimationActive；**这里不是 cadenceDue** | active 粒子满足；每次 advance 不取消 active | 数据就绪/显示后可；粒子关不能通过 | **条件推断** 风场活动大概率满足，未逐帧取证 |
+| 19 still image / still-image-request (118) | I:269，stillImageRequest=false | 否 | 请求消耗后可 | **未知** |
+| 20 MapMode / unsupported-mode (119) | I:270，Continuous | 否 | Static/Tile 不自动转换 | **条件推断** 现场连续地图符合，仍需记录 |
+| 21 Debug / debug-options (120) | I:271，NoDebug | 否 | 用户关闭后可 | **未知** |
+| 22 C 支持 / unsupported-continuous-layer (121-123) | I:272,624-627；O:1241-1250，有且仅一个 C、每层 startsRetainedDynamicRange、至少一个 particle | 否 | 固定含普通 Symbol/Line 的 C，多少次 Full 都不恢复 | **源码证明+现场布局前提** PREFIX C[13,33) 必失败 |
+| 23 scene / unsupported-scene (124) | I:273,619-630，preparedSceneSupported=true 且唯一 C；其内部含 loaded、无3D/debug、所有 R stable、aggregate Placement stable、无 legacy/custom、C 支持 | 否；Full 会重算并保存 false | 仅修 R2 局部 Gate 不够；需一致安全判据 | **条件推断** R 有活动 Symbol 或 C 普通层使其 false |
+| 24 Annotation / annotation-mutation (125) | I:202-205,274，AnnotationManager 无 pending changes（weak guard） | 否 | 正常更新消费后可；新 annotation 继续阻塞 | **未知**；不能把末尾 Symbol 存在等同 pending=true |
+
+#8 的逐字段完整范围（I:154-180,186-196）：pixelRatio、mode、debugOptions、styleLoaded、spriteLoaded、transformChanging、gestureInProgress；light/images/sources/layers/fontFaces/fileSource 对象身份；glyphURL；transition duration/delay/enablePlacementTransitions；prefetchZoomDelta、crossSourceCollisions、fastPFOREnabled；tileLodMinRadius/Scale/PitchThreshold/ZoomShift/Mode。viewport、camera 矩阵独立比较；timePoint 不在签名。**对象身份改变可触发 Full，即使负载内容相同；反过来单纯 triggerRepaint 且签名相同没有“必须 Full”语义。**
+
+所有输入在 I:246-275 装配，但 F:100-125 返回首错；现有记录 I:276-280 只有 candidate/reason。#3 的失败不能证明 #4—24 成功。修完 R2 仍会遇到 PREFIX 的 #22、prepared scene #23，以及真实资源/Source/Annotation 等独立门槛。
+
+### 5.1 第二重全局锁
+
+**源码证明**：Full 的 `retainedPlacementStable`（I:590-592）依据动态 `retainedRangeUsesPlacement`（O:1135-1141，即 needsPlacement），而逐 R gate 依据结构性 Symbol。活动 Symbol R 存在时：重算帧 aggregate placementStable=false；不重算帧 Controller stale=true，aggregate staticStable=false（O:1158）。二者分别让 `retainedSupported`（I:619-623）为 false，写入 `particlePreparedSceneSupported`（I:630）。这是独立于逐段 cache 的 **Fast scene 锁**，不是 main-buffer 的 global-live 判定；后者 I:998-1028 已不含 aggregate placement，允许无 Symbol R 继续 composite。
+
+假设以后仅让 R2 valid，旧 preparedSceneSupported=false 仍会在 #23 阻塞；不能等时间到就认为 prepared flag 自己恢复。Fast 的动态 transition 检查已避免直接沿用旧 tree changed/fade（I:259-263 注释），但没有解除 Full 产出的 scene 保守状态。隐藏 Symbol 可能使动态 usesPlacement=false、scene 不受它影响，结构性每段 gate 仍会拒绝首次 Build。
+
+## 6. C：R2 Build / Invalidate / Fallback 状态机
+
+### 6.1 从层结构到每段决策
+
+**源码证明**，按执行顺序：
+
+1. `include/mln/renderer/render_segment.hpp:48-90` 由 Style 元数据列举 Source 依赖与 Symbol 能力；type=symbol 就 capable，不看 visibility、当帧 bucket 或可见像素。越界 range 保守 capable；custom/custom-drawable 依赖 unknown。动态 `needsPlacement()` 则要求 CrossTileIndex::Required 且 placementData 非空（`src/mln/renderer/render_layer.cpp:30-32`），两者不等价。
+2. `render_orchestrator.cpp:1173-1202` 按段依赖查询 Source loaded/fading/revision，CustomMVTVector 暂无 revision contract 而 fail-closed；`retainedSegmentIsStable:1205-1216` 检查 light、相关 Placement transition 和本段 Layer transition/repaint，不再把无关 Source fade 当每段阻塞。对比 Fast 的 `retainedRangeIsStable:1156-1170` 仍检查所有 Source fade。
+3. `renderer_impl.cpp:516-535` 拓扑代际或 cache 数量变化时释放/重建每段 cache 容器；:558-559 的 key 为 viewport、begin/end、cameraMatrix。:641-652 组合 immutable layer impl+index fingerprint、source/global revision、pixelRatio。fingerprint 不是 Symbol 最终视觉签名。
+4. :653-666 将 segmentStable、结构性 placement gate、style/sprite/image ready、Continuous/no3D/noDebug/noLegacy/noCustom 合并为 segmentSupported。
+5. :668-680 首错优先级：source not ready → source unstable → style/sprite/global resource → placement → transition → legacy → unsupported → boundary → 3D → debug → mode。`static-placement` 是此处 gate 的名字，不是“R2 像素变了”的探测器，也不证明其它更后项通过。
+6. :681-691 调 evaluate；只有 Build/Reuse 才 prepareResources；失败改为 resource-or-compositor。所有 supported 条件通过仍不代表最终纹理已经绘制成功。
+
+### 6.2 状态转换和计数
+
+所有状态均据 `src/mln/renderer/retained_underlay_cache.cpp`；这是源码状态机，不是本轮运行截图。
+
+```mermaid
+stateDiagram-v2
+  [*] --> Invalid: 创建 / 资源释放
+  Invalid --> Fallback: supported=false
+  Ready --> Fallback: supported=false / invalidate
+  Fallback --> Fallback: 下帧仍不支持 / 再计 invalidation
+  Invalid --> BuildPending: enabled 且 key存在 且 supported
+  Fallback --> BuildPending: 准入恢复
+  Ready --> BuildPending: key或revision变化
+  BuildPending --> Ready: 资源准备 + 离屏绘制成功
+  BuildPending --> Fallback: resource或draw失败
+  Ready --> Reuse: valid 且 key/revision相同
+  Reuse --> Ready: 纹理保持有效
+  Ready --> Invalid: releaseResources
+```
+
+| 分支 | 行号及真实后果 |
+|---|---|
+| 无 key | :173-182，原来 valid/key 存在才 invalidate/release，返回 Disabled；与 R2 static-placement 不同 |
+| runtime disabled | :184-193，记 fallback；控制面同步 :129-163 另负责 invalidation/release |
+| supported=false | :195-205，**无条件** fallback++、invalidate；revisionChanged 才 release。即使 valid 本来 false，也再次 invalidation++。未走 first-frame 和 BuildPending 分支 |
+| revision 变化 | :171-172,207-213，invalidate/release、装新 key；这里 staticRevision 参数实际是每段 content 合成 revision，区别 aggregate tracker |
+| 初次无 key / key 改变 | :214-219，first-frame / viewport / camera-or-boundary；设 key。普通 key 变化未必释放同尺寸 GPU allocation，但 valid 失效 |
+| buildRevision 不一致 | :220-224，invalidate/release；不能复用旧代际 |
+| valid=true | :225-236，reuse++，返回 Reuse；不代表 main-buffer 必 composite，还要看全局 live gate |
+| invalid 且可支持 | :238-243，BuildPending，返回 Build；此时 buildCount 未增 |
+| GPU 资源 | :246-303，离屏 RGBA unsigned-byte texture（带 depth/stencil 参数）及 composite drawable；失败返回 false |
+| Build 真成功 | renderer_impl.cpp:813-862，beginBuild→R opaque/translucent→finishBuild→markBuildSucceeded；cache.cpp:332-345 设置 valid、buildRevision、build++、Ready |
+| Build 失败 | cache.cpp:347-356，fallback++、invalidate、release，reason=resource-or-compositor；需要该 reason/资源计数，不能从 Build=0 单独推断 GPU 坏了 |
+| invalidate / release | :359-380，前者 valid=false、记原因和计数；后者清 key/buildRevision/texture/compositor，不必增加同一种 invalidation 计数 |
+
+`lastInvalidationReason` 是最后一次记录，Reuse 或成功 Build 不在此函数中自动抹掉它；采样必须连同本帧 decision、gate、frameId 使用。`plan.valid=true` 也不等于 `cache.isValid=true`。
+
+### 6.3 FZG1 数字支持什么
+
+**FZG1 实测（任务书第二区，历史输入）**：PREFIX 约60秒，Full +1787，R0 reuse +1787，R2 build/reuse=0/0，fallback/invalidation≈1787，R3 reuse +1755，Fast=0，首拒 cache-invalid。
+
+**源码证明 + 条件推断**：每次 Full 的 R2 结构 capable → 第3章矛盾使 placement gate=false → supported=false → evaluate 直接 Fallback/invalidate → 正常 main-buffer live → 新 prepared tree 保存但 R2 invalid → 下一粒子帧 Fast #3 再失败。该闭环不需要假设 Source 每帧变化，也不需要假设 GPU 资源损坏。
+
+**仍需设备验证**：本轮没有60秒每帧原始 trace，不能把一次末态 static-placement 扩成每帧唯一首因；若某帧 Source not ready，:668-672 会先报 Source。提供的 build 是绝对值还是窗口增量、topology 重建是否清计数，也应在后续原始 diagnostics 中核对。若“Build=0”只表示窗口增量，不能排除窗口前构建过；当前源码正常含 Symbol Full 无准入窗口则给出更强的机制约束。
+
+Full 中 Symbol 正确显示，是 main buffer 的 live 绘制结果；cache Build 是单独离屏 render pass，:817 的 decision!=Build 会直接不画离屏纹理。没有自动把 main framebuffer 的 R2 像素拷贝成缓存的路径。R3 少于1787的32次复用差额可能来自资源/Source/全局条件，**没有足够逐帧证据归因**。
+
+### 6.4 Collision 与资源边界
+
+- **源码证明**：Placement::placeLayers 按完整 layer 列表逆序碰撞（`placement.cpp:201-206`）；CollisionGroups::get（:45-62）在 `crossSourceCollisions=false` 时才按 Source 隔离，开启时使用无过滤组。:46-48 的英文注释与实际 if 的开关文字不一致，本文依执行分支，不照抄注释。相同 Source 跨段仍同组；关闭跨源碰撞也不等于关闭段内碰撞。
+- **源码证明**：`Placement::commit:687-749` 内部同名局部变量 placementChanged 根据 text/icon placed 变化更新 fadeStartTime；外层 RenderTree.placementChanged 表示是否运行新计算。两个变量作用域和语义不同；全局 commit 也没有比较 R2 最终纹理。
+- **源码证明**：Source/Tile mutation 可按依赖映射每段，glyph/image/style/context 未能局部定位时推进 global epoch（`render_orchestrator.cpp:243-275,327-347,1519-1521,1555-1559,1582-1594`；`render_segment.hpp:114-133`）。Camera/viewport/pixelRatio/拓扑另有 key/revision 保护。Source ready 不等于每个 Symbol shader 输入稳定。
+- **条件推断**：别段符号或 Annotation 可能改变 R2 text/icon 可见性；同一位置/ID 也可能 opacity、variable anchor、orientation、line reprojection 改变。只有新一次完整 Placement 后证明最终有效输出及资源代际等价，才有候选复用条件。任何无法比较项必须 fail-closed。
+
+## 7. D：Placement/Fade 真语义与可达状态
+
+### 7.1 两个时钟、一个 stale 标记
+
+**源码证明**：TransitionOptions 默认 enablePlacementTransitions=true（`include/mln/style/transition_options.hpp:12-26`），默认 duration=300ms（`include/mln/util/constants.hpp:59`）。`Placement` 构造保存当次 options、commitTime、placementZoom（`placement.cpp:180-192`）。因此 UI 当前 option 与 Controller 中旧 Placement 的 option 在下一次新建前可能暂时不同，诊断必须同时记录。
+
+当 transitions 开启且 duration=D>0：
+
+- `symbolFadeChange(now) = (now - commitTime)/D + prevZoomAdjustment`（:1282-1289）；这是无 clamp 的增量，可能>1，零只说明刚 commit 且 zoomAdjustment 为零等特殊条件。
+- shader 使用 `clamp(baseOpacity ± symbolFadeChange,0,1)`，符号实际已终态时 uniform 仍能变化；Fade 终态不以 uniform==0 定义。
+- `Placement::hasTransitions` 用 **fadeStartTime** 而非 commitTime：`now-fadeStartTime < D`（:1319-1322）；commit 没有 text/icon placed 改变时继承旧 fadeStartTime（:748-749）。新计算与新的真实 Fade 不是同义词。
+- `placementIsRecent` 用 commitTime+updatePeriod>now（:160-167）；普通 period=`max(300ms,D)*(1-zoomAdjustment(currentZoom))`（:1307-1312）；zoomAdjustment=max(0,(oldZoom-newZoom)/1.5)（:1292-1298），zoom-out 可缩短到零甚至负值；此处没有下限 clamp。
+- 新 Symbol buckets 且非 tiltedView 才使用 30ms **periodOverride**（O:778-789），不是把 Fade duration 改成30ms，也不是所有 Source 变化都立即重算。
+- Controller `hasTransitions` 在 transitions 开启时 **stale 优先返回 true**（:170-175）。它含“需要重新评估”的语义，不能直接当作真实 opacity 正在变化的精确检测器。
+- delay 保存在 options/signature，但上述三个 Placement 时间公式没有读取 delay；不能将一般 Style paint transition 的 delay 机械套给 Symbol placement fade。
+
+### 7.2 transitions 开启的逐帧示意
+
+**条件推断（非 FZG1 实测时间线）**：固定 camera、无新 bucket、D=300ms、约33.33ms一帧，t0 首次 placement 后内容稳定。忽略调度抖动，t0+300ms 的边界实际取决于 Clock。
+
+| 时刻/情况 | RenderTree changed | fade increment | Controller transition | Symbol R gate | 解释 |
+|---|---:|---:|---:|---:|---|
+| t0 新可见 Symbol | true | 0（静止 zoom） | true，fadeStart=t0 | false | 真实淡入开始；base opacity 可能0 |
+| t0+33…267ms，不重算 | false | 约0.11…0.89 | **true，stale**（即使真实 Fade 早已结束也如此） | false | O:805-806 无条件 stale |
+| ≥t0+300ms，重新计算且显隐未变 | true | 重新归零 | false（旧 fadeStart 已到期、setPlacement 清 stale） | false | 可出现现场 true/0/false，但 changed 阻塞 |
+| 再下一帧，显隐仍未变 | false | >0 | true（重新置 stale） | false | 不是新像素变化的证据 |
+| 后续每到普通 period 重算 | true | 通常0 | 若无新显隐变化则false | false | 循环重复，未提供 Build 窗口 |
+| 新 bucket 触发30ms override | 到期时true | 新 commit 通常0 | 视 actual placed/Fade 而定 | false | 约30FPS时可能每次新增 bucket 帧均到期，需事件证据 |
+| zoom-out、period≤帧间隔 | 可每次true | prevZoomAdjustment≥0，可非0 | 取决于真实Fade | false | 不使用固定300ms频率推断 |
+
+### 7.3 transitions 关闭（及 duration=0 的区别）
+
+**源码证明**：已有 Placement.transitionsEnabled=false 后，`placementIsRecent` 总是 false（:163），所以**每次到达 Continuous Full 都新建并执行 placeLayers**，即便 layersNeedPlacement 为空也调用函数；Controller.hasTransitions=false（:171），`symbolFadeChange=1`（:1289）。因此正常关闭配置是 **true / 1 / false**，不是 true/0/false。这并不意味着有独立线程每帧强迫 Full：必须先有 render request 且 Fast 失败。
+
+若仅 duration=0 而 enablePlacementTransitions=true，recent 仍使用至少300ms（zoom/override 除外），fade=1；真实 Placement.hasTransitions 通常false，但 non-recompute Full 仍 stale=true。仍不能通过 Symbol gate。
+
+**源码证明**：Android JNI `platform/android/MapLibreAndroid/src/cpp/native_map_view.cpp:1012-1017` 明确传 duration、delay、enable；iOS `platform/darwin/src/MLNStyle.mm:521-539` 可分别设置 transition 和 performsPlacementTransitions。当前任务没有生产 Host 此项逐帧配置证据；不能拿 SDK 默认值替代 FZG1 实际值。Android getter :1000-1008 对 unset duration 返回0，若只记录 getter 值还需区分“未设置的默认300ms”和“明确设置0”。
+
+**对任务假设的明确判定**：`symbolFadeChange==0` 不能代表“Fade 已稳定”，此语义误读已被源码证伪；但缓存无窗口的充分原因是 changed/stale 的互斥准入，不是仅这个比较符。任务要求解释末态 true/0/false：该值与开启配置的稳态重算相容；在未改写字段的正常 Full 中，不支持直接解释为“关闭 transitions”。Fast 重置树字段为 false/0，而不是 true/0。若日志声称关闭且仍 true/0/false，应优先核对同帧采样、运行二进制/选项生命周期，不能改源码迎合假设。
+
+### 7.4 真值表：P=!changed && fade==0 && !transition
+
+下表针对 placementCapable=true；无 Symbol R 直接通过本 gate，但仍受其它保护。以 c=changed、z=(fade==0)、t=Controller transition：
+
+| c | z | t | P | 正常 Full 可达性/意义 |
+|---:|---:|---:|---:|---|
+| 0 | 0 | 0 | 0 | Continuous 正常 no-recompute 分支不可达：会 stale；抽象状态不足以证明安全 |
+| 0 | 0 | 1 | 0 | 开启且未重算、时间增量>0；Fade 活跃或已结束都可 |
+| 0 | 1 | 0 | **1** | 唯一逻辑通过组合；**正常 Continuous Full 不可达**。已命中 Fast 的树重置可有此形态，但不能自举 |
+| 0 | 1 | 1 | 0 | 同 timestamp 重复 render、增量仍0而 stale；可达也不通过 |
+| 1 | 0 | 0 | 0 | transitions关闭（fade=1）；或开启duration0/zoom修正且无实际Fade |
+| 1 | 0 | 1 | 0 | 新显隐变化伴随非零zoom修正等 |
+| 1 | 1 | 0 | 0 | 开启、静止zoom、重算但旧Fade结束；现场末态相容 |
+| 1 | 1 | 1 | 0 | 开启、新显隐/Fade、刚commit |
+
+Bucket 增减、跨段碰撞可能改变 `Placement::commit` 内部 placed 状态、重置 fadeStart；其是否真实改变 R2 需逐 Symbol 数据。即便完全不改变，也落入上述无窗口分支。没有 Source 变化也足以卡住；Source 变化不是这个机制的必要条件。
+
+### 7.5 Shader 与 Full 后安全 Build 的必要证据
+
+**源码证明**：`Placement::commit:694-724` 将上一 placement 的增量折入新的 OpacityState；`OpacityState:18-24` 保存 base opacity 和 placed 方向。`RenderTreeImpl::prepare`（O:133-138）→ `Placement::updateLayerBuckets:752-757` → `SymbolBucket::updateVertices`（`src/mln/renderer/buckets/symbol_bucket.cpp:346-366`）更新 opacity 与动态属性；`Placement::updateBucketOpacities:962-1029` 处理 duplicate、default、placed hidden 和属性编码。
+
+`renderer_impl.cpp:462,755-766` 把树的 fade 送入全局 shader uniform。OpenGL：`shaders/symbol_sdf.vertex.glsl:153-158`、`symbol_text_and_icon.vertex.glsl:152-158`、`symbol_icon.vertex.glsl:127-129`；Metal：`include/mln/shaders/mtl/symbol.hpp:157-164,372-374,644-646`，都将 opacity 基值加/减 fade 并 clamp。Metal fragment :257-263,495-530 再乘 paint opacity；GL `shaders/symbol_sdf.fragment.glsl:77` 和 `symbol_text_and_icon.fragment.glsl:53-57,94` 也乘 paint opacity。零 fade 可以对应 base=0 的新符号或 base=1 的已完成符号，数值自身不足以判稳。
+
+**条件推断（提案前提，尚非安全证明）**：可候选在完整 Placement 和 bucket 更新、shader 输入就绪后，使用一个与 Build 世代绑定的“输出已终态且不会仅随时间变化”证据，再建立 R2。必须同时覆盖 text/icon、duplicate、variable anchor/orientation、沿线重投影（placement.cpp:776-959）、paint opacity transition、glyph/image atlas、Tile/Source/camera/context、层序/深度/混合边界。仅 `!Controller.hasTransitions` 不足以替代这些证据，因 Controller 的 stale 是待重算语义；仅删除 changed 或把 ==0 改成≥1 也无法建立与缓存像素绑定的不变量。
+
+## 8. E：S1—S5 反事实与因果闭环
+
+### S1：仅粒子持续推进，所有静态输入就绪且不变
+
+**源码证明/条件推断**：以任务要求的“仍有含 Symbol 的 R2、粒子30FPS”为前提，而不是把“纯粒子”误解为地图根本没有 Symbol。
+
+- f0 无 prepared tree，必 Full；R2 gate 拒绝，R0/R3 若无 Symbol 且其余条件通过可 Build。
+- f1 Fast 首先看到 R2 invalid；Full 中要么 changed=true，要么 stale=true，再次拒绝 R2。R0/R3 可 Reuse。
+- f2…重复；启用 transitions 的重算频率由 period/zoom/bucket 决定，关闭时每次 Full 重算。**即使无任何外部 Source mutation，当前 Symbol R 仍无法从第一次正常 Full 自举。**
+- 反例边界：若全部 R 都无 Symbol，单 C 只包含受支持的 WeatherColor/Particle，所有 Gate 满足，正常 Full 能建缓存、随后 Fast 可以命中；Placement 不需每300ms独立强迫新 Full。若 f0 还有真实全局 Fade，则等待必要 Full 结束后才可能命中。
+- **仍需设备验证**：以上状态机不等于已测到30FPS、具体 CPU 成本或缓存最终像素正确。本轮未执行场景。
+
+### S2：粒子关闭，只剩偶尔地图刷新
+
+**源码证明/条件推断**：关闭 active/visibility 或清掉必要场数据会取消粒子 needsRepaint，#18 不能命中 Particle Fast。若同时停止 forecast、没有其它动画及 pending 资源，就失去高频 SDK wake/repaint 链；最终 loaded 且无 transition 可 Idle。期间每个真实 Full 仍进行 recent 判定，关闭 transitions 时每个 Full 都算 Placement，开启时仍可能用几帧完成 Fade/stale。
+
+**FZG1 实测**：关闭粒子对照约83次Full/分钟来自任务输入。**不能证明**这83次都由导航、Placement 或 Tile 任一单源造成；也不能证明 Placement 从不运行。若只隐藏粒子却仍 forecast Playing，WeatherRuntime :252 仍唤醒，因此“粒子关=无天气高频唤醒”必须同时核对预报状态。83次与1792次的差异支持高频粒子场景增加 render 请求，但不提供精确按来源分摊。
+
+### S3：真实 Host Source Mutation + Annotation + Tile 异步输入
+
+**源码证明**：Style Source 更新先由 `src/mln/style/style_impl.cpp:348-351` 通知 onUpdate；新 sources identity 会令 Fast #8 失败。Full 的 O:525-537 每批非空 sourceDiff 推进一次 aggregate content revision，并为每个增删改 Source 推进 local revision。Tile callback O:1555-1559 则每次推进 aggregate/local 并 invalidate；Glyph/Image 无明确 source 时推进 global。Annotation dirty（`annotation_manager.cpp:213-227`）使 #24 拒绝，Full O:360-363 消费 dirty。
+
+**理论量化（条件推断，非测量）**：
+
+- 一批 Full sourceDiff 含 m 个 Source 修改：aggregate 增1、local advance m 次；m 不等于 m 个 Full。
+- N 次独立 onTileChanged：当前实现 N 次 aggregate/local revision advance；若在下一 render 前合并，仅需要一次承载最新状态的 Full，若穿插 N 帧则可每帧拒 Fast。Fade、stale、继续到来的异步输入又可能延长 Full 序列，故不能用 N 推出总 Full=N 或每次 mutation 固定只需1帧。
+- 已 valid 的无 Symbol R，若仅依赖 Source S，S 的新 revision 使下一次可支持的 evaluate invalidate/build；其它无 Symbol R 可复用。global epoch 变化则所有段的新 revision 都不同。每段 Build次数≤它实际有资格 Build 且绘制成功的 Full 次数；当前 Symbol R 无资格，所以 Build仍0并非 mutation太频繁的唯一解释。
+- 只在 C 的 Source 变化可使整帧 Full，却不必令独立 R 的 local revision改变；碰撞关系仍可使 Symbol R 输出变化，不能以 source依赖表忽略跨段 Symbol。
+
+**重要独立来源**：V4 forecast Playing 时 `Map::onUpdate` → `tickForecastClock` → `refreshV4RendererState`；后者 `raster_array_source.cpp:569-608` 在投影 sampleState/端点变化时换 Source impl 并通知，即使 T0/T1 纹理可复用，也可能令 #8 每次失败。这是 Native forecast 的真实输入更新，不等于静态风场粒子 advection，也不能无证据统归 NavSea 导航 Mutation。S1 必须固定 forecast 时间；S3 诊断应分别计 external Source 和 forecast projection。
+
+### S4：布局对照，保留真实层序
+
+| 布局及证据 | 分段 | R 缓存 | C / Fast 独立门槛 |
+|---|---|---|---|
+| 原 RC（STEP-110 现场历史） | R[0,31)、C[31,113)，R含地名 Symbol | Symbol R当前无Build窗口 | 后段含大量普通业务层，若有普通 Symbol/Line，#22必拒；不能把 RC1/RC2 的所有字段与旧快照自动认作同一采样 |
+| 原 RCRR（四段的泛型/候选基准） | 若为 R[0,31)、C[31,33)、R[33,107)、R[107,113)，须由原始 plan 确认；**本轮任务未给该原配置完整边界，不将此数字当实测** | 首R和R2若含Symbol仍被阻塞 | 条件下 C仅 WeatherColor+Particle 则类型Gate可过，但 scene及所有R仍要过。泛型RCRR只说明策略排列，不保证边界和类型 |
+| **RCRR_PREFIX（任务书现场输入）** | R0[0,13)、C1[13,33)、R2[33,107)、R3[107,113) | R0复用1787、R2不建、R3复用1755；与Full mixed执行相容 | C1含普通Symbol/Line+WeatherColor31+Particle32；`O:1247` 遇普通层返回false，#22确定被#3掩盖 |
+| **理想保序反事实，未实施** | R[0,13)、R[13,32)、C[32,33)、R[33,107)、R[107,113) | 新R[13,32)及R2含Symbol，当前一样卡住；WeatherColor31也进入R | 恰好一个C且只有Particle可消除类型障碍；不消除Symbol Gate、scene、资源/source/annotation。若forecast/WeatherColor继续变化，新R必须重建/回退 |
+
+`singleContinuousSegment` 在 `renderer_impl.cpp:55-63` 限定唯一 C；`RenderLayer::startsRetainedDynamicRange` 默认false（`render_layer.hpp:113-120`），Particle/WeatherColor 才 override true（对应 layer头 :31-33/:27），普通 Symbol/Line 即便暂时隐藏也不会因不可见自动成为受支持 C。多 R 本身不是禁止项；多 C 是当前 Fast 的独立阻塞。STEP-106 的 R-C-R-C 是缓存局部性测试，不是生产 Fast 性能证明。
+
+**仍需设备验证**：补原始 RC1/RC2/RCRR plan JSON、113层完整 id/type/source/visibility/顺序，才能逐层定位实际布局；本轮没有跨项目改 Style。理想配置只做反事实，不能承诺 WeatherColor永远静态，更不能删海图Symbol或把普通层批量挪C作为优化。
+
+### S5：动态安全回退
+
+| 变化 | 必须处理的 R / Full 条件（源码证明+条件推断） | 不可盲复用的理由 |
+|---|---|---|
+| pan/zoom/rotate/pitch、viewport/pixelRatio | 屏幕缓存 key 改变的所有R重建；Fast camera/viewport/signature拒绝 | 旧屏幕纹理、anchor/reprojection不再对应当前相机；定图仍需碰撞正确 |
+| 相关 Tile/source更新、缺失/fading | 依赖段 Source gate/revision失效；Fast aggregate/content/fading可能整帧Full | 异步完成意味着可见内容改变；非依赖段只在全局证据允许时继续复用 |
+| Glyph/Sprite/Image/fontFace | 当前实现 global epoch及ready；通常所有R保守失效 | atlas/字形纹理可能变化，sourceReady不足以覆盖 |
+| text/icon opacity Fade或paint transition | 受影响Symbol R不能冻结随时间变化的像素；现有全局Controller/gate更保守 | uniform与base opacity共同决定alpha；不能从fade=0/Controller=false单独得出结果等价 |
+| 跨段Collision变化 | 所有碰撞影响到的Symbol R必须刷新；当前没有可靠per-R证据时保守回退 | source不等于segment；跨源关闭只隔离不同source，同source仍相互影响 |
+| Annotation插入/更新 | 拓扑/Source/pending及碰撞具体属性分别处理 | 自动 points Symbol由 `annotation_manager.cpp:176-192` 添加，默认iconAllowOverlap/iconIgnorePlacement=true，**不能断言它一定排斥R2**；结构gate照样capable，实际影响还看其它Symbol/配置 |
+| Style属性/顺序、Layer增删、Plan边界 | 本段fingerprint或全局topology变化；对应cache释放/重建 | 层序和混合语义不能被texture复用改变 |
+| context/resource/compositor失效 | 已损坏资源全部重建；失败保持live/fallback | valid标志不能替代真实资源准备和draw成功 |
+
+## 9. A—D 提案比较（均未实施）
+
+优先顺序：**A诊断补齐 → B建立严格生命周期准入原型并同步处理scene → C按需求扩展per-R等价；D先交Integration确认公共“强制Full”语义，再决定实现**。C范围布局问题与这些方案独立：保序单粒子C是候选配置，任何产品Style变更都另行授权。
+
+| 提案 | 首次Build / 全局scene / C Gate | 正确性与风险 | CPU / GPU / 内存代价 | 候选修改文件、复杂度、双平台与最小验证 |
+|---|---|---|---|---|
+| **A 全Gate+R2状态诊断，优先P0** | 不改变Build或scene/C结果；一次取齐被短路掩盖项 | 不改变fail-closed；读状态需同frame和phase，不能额外调用有计数副作用的needsRepaint造成伪观测 | CPU约O(现有gate数+R数)，复用已算结果；固定环形缓冲有界内存；GPU零额外工作。采样成本须实测 | `particle_fast_path.hpp`、`renderer_impl.cpp`、`render_orchestrator.cpp/.hpp`、`placement.hpp/.cpp`、现有diagnostics结构；**2/5**。Shared Core同字段，Android/iOS只分别接低频导出。最小验证见第10章，记录schema无需新增公共API即可先做Native内部诊断 |
+| **B Full后安全Build，优先P1** | **目标解决首次Build**；必须同时替换每段准入和prepared scene的旧证据，单改其中一处无效；不解决普通C层Gate | 保留全图Placement与全部资源保护，以已经完成的Symbol shader输入/终态证据授权。先shadow，不直接删除changed/stale/fade条件。危险为早冻结Fade、漏collision/atlas/paint状态、引用过期bucket | Full本来就做Placement，可在commit/bucket完成点记录代际，稳态尽量O(1)/段；首次离屏多一次R绘制，后续composite；每R现有全屏RGBA颜色约4WH字节，另depth/stencil和backend开销，更多R线性增加 | `placement.hpp/.cpp`、`symbol_bucket.cpp/.hpp`、`render_orchestrator.cpp/.hpp`、`renderer_impl.cpp`、`render_segment.hpp`、cache状态结构；按所需证据可缩减，非已定设计。**4/5**。GL/Metal shader不预设需要改；必须两后端同提交检查opacity精度和texture合成。最小：静止Symbol R开启/关闭transitions、首次可见、fade长尾、camera/context/资源失效，false-reuse=0 |
+| **C 更细per-R结果等价，优先P2** | 可以为B提供首建/重建的证据；单纯“新旧签名相等”没有旧Build时不能自举；scene也必须接纳相同证据；不解决C Gate | 与STEP-111一致，仍全图碰撞，再按R比较结果；stable ID、世代和实际GPU输入齐全才允许reuse。hash相等不是完整安全证明；未知必须回退 | 每次Full placement后O(受影响symbol数)，避免每粒子tick遍历；签名/版本及必要精确快照占O(symbol数)或O(段数+变化集)；降低R GPU重绘但不自动省CPU prepare | `placement.hpp/.cpp`、`cross_tile_symbol_index.cpp/.hpp`、`symbol_bucket`、`render_layer`、`render_orchestrator`、cache/renderer接口。**4/5**；深改分段Collision为**5/5且不推荐本轮**。双平台共用结果证据、验证shader差异。最小：同Source跨R、跨源开关、C1仅影响R2/影响多个R、duplicate/variable-anchor/沿线字/Annotation/重载；以缓存关对照 |
+| **D 外部Full与Particle Tick分流，Integration先行** | 单独不解决Symbol首次Build、scene或C类型；可明确某次更新必须Full，并在纯tick时优先Fast | 用户要求外部明确Full不能以数据相同去重/延迟；需明确序号、确认时点、合并规则、生命周期与平台一致性，禁止把重要资源更新当tick | 内部原因bit/epoch通常O(1)；若每个命令都必须独立一次Full会增加CPU/GPU，额外队列可能有界内存需求。收益取决于频率，不能承诺2 Full+28 Fast | `UpdateParameters`、`Map::Impl`、Renderer入口、Android frontend、Darwin frontend及必要RN公共层；**3/5**（跨项目/生命周期可到4）。现有triggerRepaint不是此契约。最小：相同数据两次明确Full、命令与tick/异步tile竞态、禁用销毁重建、Android异步合并和iOS，检查每个accepted序号按决议完成；不得私建API |
+
+### 9.1 B/C 的数据所有权与最轻量可行方向
+
+**源码证明**：`Placement` 持有 placements、opacities、variableOffsets、placedOrientations（`placement.hpp:184-201`），以 crossTileID 索引；`getSymbolPlacement`（`placement.cpp:1301-1304`）查具体Symbol。`placeLayers` 后 commit 已完成，但最终bucket opacity/duplicate和动态投影更新在 RenderTree.prepare，GPU drawable/tweaker又在之后。`Placement` 至多保留上一代（:190-192），cache可能跨更多代存在，因此只能与上次成功Build版本绑定，不能仅比较相邻两次Placement。
+
+`getPlacedSymbolsData` 对普通 Continuous Placement 返回静态空数组（:1325-1327），TilePlacement有专门实现（:1378-1387）；不能把现有public查询当完整R2结果快照。STEP-111的候选字段仍需要逐项实现与验证，本任务不宣称已设计出可直接上生产的签名。
+
+**候选轻量方案（条件推断）**：先争取“静态输入代际相同 + 完整Placement结束 + 所有目标symbol有效opacity已终态 + 无未消费资源/桶变更”的全局生命周期证书，授权该次Full离屏Build并保存buildEpoch；下次tick只比epoch和既有Gate。比每次tick全symbol hash轻。但必须证明碰撞/hidden/duplicate/variableOffset/paint动画均被证书覆盖；如不能低成本取得这一证明，继续fail-closed，退回shadow per-R比较，而非改用Controller.stale=false假装稳定。
+
+更细C候选字段分工：Source/tile/bucket generation、crossTileID及R归属、text/icon placed/hidden、实际anchor/orientation/动态顶点和编码opacity需要结果证据；Camera/viewport/pixelRatio、Style顺序、Source/global资源代际优先复用已有key/revision；paint opacity/transition必须覆盖时间依赖。首次帧没有参考就Build，未知或资源重建丢弃证书，真实结果变化则重建。内存与比较开销需要新增计数验证，不能从“理论可hash”推出安全或高性能。
+
+### 9.2 D 的 Interface Blocker
+
+**源码证明**：当前 `Map::triggerRepaint`（map.cpp:93-95）只调用onUpdate；`UpdateParameters`（`src/mln/renderer/update_parameters.hpp:25-61`）没有 externalFull/原因序号字段；Fast签名不比较timePoint，入口每次都先试Fast。`packages/maplibre-particle-rn/src/RendererRuntime.ts:12-27` 只有retained控制、continuous range/segment plan和diagnostics，未提供“外部指令强制Full并确认”的方法。Android frontend AsyncTask/最新params设计还有合并行为，不能自动保证每次命令一帧。
+
+**Interface Blocker（提案，不是当前调查阻塞）**：若用户希望公共Host“明确Full”命令具有不可被相同数据去重/延期的语义，Integration必须确认：完整更新是CPU prepare/全图Placement重新评估，还是强制所有R GPU重画；两个相邻命令能否同一Full满足、如何回执、如何与异步资源到达排序。既有C-001/C-002没有该公共语义。本轮仅只读 `/Users/tei/dev/navsea-particle-integration/contracts/PARTICLE_NAVSEA_BOUNDARY.md`、`CONTRACT_VERSION.md` 和COORD-005决议；C-001边界继续有效、C-002是QBIN窗口增补。不得通过Native私有通道绕过协调，未修改Integration，也未发送跨项目消息。
+
+纯内部性能优化可先留在Shared Core，不需要借口更改Host职责；明确Full请求一旦获授权，不能用“内容相同”跳过或推迟它，普通粒子tick则优先Fast并保留相机/资源/Placement等安全Full。**2 Full+28 Fast只是目标例子，非当前实现承诺或验收门槛。**
+
+## 10. 下一阶段最小诊断提案与独立验收证据
+
+**仅提案，未插桩、未执行、未创建下一Step。** 当前源码已能证明控制流矛盾；诊断用于确认FZG1实际选择的配置/路径、其它Gate和主要CPU成本，并为安全改造建立基线。
+
+### 10.1 同帧字段与采样点
+
+| 位置 | 最小字段 | 判别目的 |
+|---|---|---|
+| Map::onUpdate / SDK cadence wake | map generation、update/request序号、SDK wake/observer repaint/Host mutation/forecast tick来源、targetFps、active/visibility、forecastPlaying、sourceId、Clock时间 | 区分下一帧请求与外部数据更新；调度来源标识仅Native内部提案，不私建公共命令 |
+| I:199-278，Fast判定前 | frameId、UpdateParameters.timePoint、实际render时间、24项bitset、首错、changed signature字段mask、prepared tree/scene标志、所有R valid/buildRevision/staticRevision、config/topology/content revision | 一次记录所有Gate；多request合并和同一params重渲染可识别；避免只看cache-invalid |
+| O:778-810，Placement前后 | **当前options与旧Placement options** enable/duration是否unset/delay、commitTime、fadeStartTime、now、zoom/prevZoomAdjustment、override及原因、bucketAdded/Changed、recent、stale前后、outer changed、commit实际placed变化计数、raw fade和Controller/Placement各自hasTransitions | 验证开关分支、300/30ms和zoom影响；区分实际Fade与stale |
+| RenderTree.prepare后 / I:637-691 | tree fade、shader fade、每R capability、动态usesPlacement、placementGate、sourceReady/stable、fingerprint、content revision、supported、fallback各项bitset、cache前状态、evaluate decision | 确认是否Gate阻止首次Build、是否其它失败被placement reason遮蔽 |
+| cache Build/execute / I:813-862,998-1028 | BuildPending/成功/失败、valid/key/资源世代、texture/compositor create/release、build/reuse/invalidation/fallback累计及delta、actualExecution、globalLiveReason、GPU pass耗时（如平台已有可靠计时） | 拒绝Build与GPU失败分开；Reuse与实际composite分开 |
+| frame完成 | FullCPU/fast/simulationAdvance计数、createTree/placement/prepare/layerUpdate/encode耗时、repaint原因bits、loaded/Idle | 不能用Full计数代替Placement次数或simulation次数 |
+
+字段不存在时新增只读诊断accessor应另行授权；不可通过额外一次placeLayers获得“测量值”。重用本来算出的gate bool与needsRepaint值，避免观察过程增加计数或推进cadence。
+
+采样建议：每组先10秒预热、再60秒统计；前3秒及状态变化前后保留连续逐帧详情，60秒完整保留紧凑gate/段决策和计数；用固定容量Native环形缓冲、超限显式记录dropped计数。日志导出1Hz摘要或窗口结束统一写，不每帧JSON/JS bridge、不每Symbol默认打印。以实测结构大小和容量给出内存上限；对trace开/关同场景比较CPU/frame，目标开销预算先建议≤1%，达不到则缩减详细采样但保留全部gate bitset。这个预算不是当前已达到指标。
+
+### 10.2 最小场景与判断
+
+1. FZG1原V23、同场/同camera：粒子开/关，分别固定forecast暂停；保留原plan和所有113层元数据。复现计数只用于基线，不要求改变现有结果。
+2. 同输入分别enablePlacementTransitions=true/false；true下记录D=默认/显式值，false预期Full组合true/1/false。每个Symbol R应在每个Full看到gate=false；若有正常Full gate=true，是本报告不变量反例，应保留原始帧/版本并停止假设式修复。
+3. PREFIX，记录#22普通层第一个拒绝的id/type/index，同时#3失败；原RC和真实RCRR分别保留配置，不复用旧布局推断。
+4. 无外部Mutation的固定field、forecast暂停，与导航/Annotation更新、Tile完成、forecastPlaying分别对照，按来源和phase对齐revision。不得靠降低粒子FPS制造好看CPU。
+5. 后续B/C shadow原型才验证：首建可达、fade长尾/variable anchors/跨源碰撞/同源跨段/相机/Style/清场/context；缓存开关同帧结果对照，**false-reuse=0**，不能用总FPS掩盖陈旧字/图标、错层或缺字。Android OpenGL和iOS Metal同源码各跑，不能用一端替代另一端。
+
+独立验收需要：源码commit及制品SHA/实际SDK版本、plan JSON与Style层表、全部gate bitset、Placement两套配置和时间、R状态机计数、trace开关开销、CPU阶段耗时、同帧视觉/必要图像差异证据、原始日志路径。任何提升Fast命中/CPU降低数字必须来自新实验。本轮不提供尚不存在的诊断开关命令，也不执行构建、测试或设备动作。
+
+## 11. 最终结论、未确定事项与责任边界
+
+### 11.1 已证明
+
+1. **源码证明**：粒子/SDK只请求下一次正常地图渲染；每次先试Fast，没有粒子专属“必须Full”命令。当前Full CPU频率是请求频率与准入失败共同作用，不等于静态像素每帧变化。
+2. **源码证明**：正常Continuous Full对结构性Symbol R的三项gate无可达通过分支：changed或stale→transition二者必挡其一。它足以解释在静态输入下仍无法首次Build；不是仅仅“可能比较符用错”的猜测。
+3. **源码证明**：fade=0不是终态证明；关闭transitions正常返回1。FZG1 true/0/false快照不能用来断定关闭配置或每帧300ms周期。
+4. **源码证明**：还有prepared全局scene锁与C范围类型锁；PREFIX普通Symbol/Line C不支持Fast。仅修R2不能承诺Fast命中。
+5. **源码证明**：缓存invalidate计数不要求曾valid；Full可复用其它R并live画R2，正常主屏显示不等于离屏Build成功。
+6. **源码证明**：V23相关核心gate与本轮main一致；STEP-109仅改变两Layer的field深比较快路，不解除以上限制。
+
+### 11.2 假设判定与历史报告关系
+
+| 假设 | 判定与证据强度 |
+|---|---|
+| 粒子每次tick直接改变静态R内容 | **不成立为必然关系，源码证明**；纯simulation不改R，forecast/Host更新另算 |
+| C1每帧碰撞使R2符号真实变化，才导致Build0 | **未证实且非必要条件**；gate控制流在零mutation也不可达 |
+| `symbolFadeChange==0`等于Fade结束 | **源码证伪**；它是增量，不是稳定布尔量 |
+| FZG1 true/0/false证明关闭transitions | **源码不支持**；关闭的正常Full为true/1/false |
+| 删除placementChanged或改==0即可安全修复 | **不支持**；stale/scene/C/资源/碰撞/opacity仍独立存在 |
+| 现有Gate是合理保守且没有任何进展性问题 | **需细化**：fail-closed保护正确，但正常Symbol R Full首次Build不可达是可证的功能/性能准入限制；是否按产品契约命名为Bug由后续设计确认，不是视觉错误或可直接放宽安全的证据 |
+
+STEP-110/111保留原样。它们强调“来源不等于视觉影响、缺逐R安全证据”的结论仍成立；本轮新增的是 **changed/stale互斥导致准入不可达** 的完整控制流证据，不能把旧PARTIAL说成已实现修复，也不重写历史来伪装一致。
+
+### 11.3 尚不确定 / 仍需设备验证
+
+- FZG1每一帧enable/duration、bucket添加、zoom修正、调用来源和24项Gate真实值；末态仅一个快照。
+- 原RCRR完整边界和RC1/RC2精确同版Style列表；本报告不把推测布局写为实测。
+- 导航Source、Native forecast投影、Annotation、资源异步输入各自占多少Full/CPU；83与1792不是按来源归因数据。
+- R2每个Symbol实际最终输出是否与某个候选缓存时刻完全等价、可接受证书的充分字段及实现成本。
+- B/C实现后的首建、Fast hit、CPU/GPU/内存收益、GL/Metal像素一致性和安全回退；本轮都没有实现或运行结果。
+
+**交付判定：本轮A—E源码调查与提案已完成；综合结论保留PARTIAL（生产逐帧归因、完整原始布局及安全修复/性能未验证），不标实现/运行/性能PASS。** 已有决定性源码机制证据，不再以猜测“等Fade结束就可能Build”作为建议。下一阶段最小工作是A的同帧诊断和B的安全证据设计；维持现有fail-closed，不直接修Native。
+
+Codex调查阶段只交付四份文档，不承担Git操作；STEP-112任务书第十一节要求RDC独立进行仅文档scoped提交、推送和远端回读。Git最终状态以RDC收尾补记为准。

docs/20_调查/STEP-114_FastPath安全准入与闭环判定_v1.md

@@ -0,0 +1,78 @@
+# STEP-114 Fast Path 安全准入与闭环判定 v1
+
+日期：2026-10-11（JST）。结论：**PARTIAL；安全子集源码与独立最小场景已交付，真实 Fast 尚未验收。**
+
+## 1. 基线、证据等级与阅读
+
+Mac / Darwin 24.6.0 / x86_64，`/Users/tei/dev/MapLibreParticleLab`，`particle/main@b02e54de3d45fcf612126ae8f037cba204f590ea`。源码版本 `13.6.1-particle.23`，没有发行或改 Source Lock。实际模型 GPT-6.1-Sol / high 已从当前本地 rollout 的 `turn_context` 核实。
+
+已读根 AGENTS、PARTICLE_BASELINE、项目规范全部八份、项目总则 README 与四份有效总则、本任务、STEP-112 调查/完成报告、STEP-113 完成报告/Step（含两轮 RDC 追加）、实际 Shared Core 和 Test App 源码。Integration 只读 AGENTS、README、WORKFLOW、TEAM_MODEL、C-001/C-002、Contract 版本规则、RFC-001/002/004、ADR-001、COORD-005 决议；不写跨项目文件，不改 RN/JS API/ABI。
+
+SOURCE-PROVEN 表示本轮源码控制流；RETAINED-EVIDENCE 表示本机保留的旧 RDC JSON；IMPLEMENTED 表示已改源码；NOT RUN 表示未编译/运行。旧设备证据不是本轮改动的设备验收。
+
+## 2. R 的真实 SourceType 与初建失败点
+
+不能从 `unknown-dependency` 推断 source 一定是 CustomMVTVector：它还覆盖未知依赖、缺 revision 登记等情况。
+
+本轮只读 `artifacts/maplibre-particle/android-validation/step113/source-change-after-full.json`：Native source 表为 mapple/raster、navsea_delivery/vector、org.maplibre.annotations/annotations、rn-weather-fields/raster-array、step113-source-probe/geojson。R0 `[0,63)` 的依赖为 mapple、navsea_delivery、**tide**；第2层 `tide-spots` 是 `symbol`、sourceId=`tide`，source 表却没有 tide。R0 的 sourceRevision=0、sourceReady=false、Build=0、fallback=unknown-dependency。
+
+源码 `style/conversion/source.cpp::convertVectorSource` 创建 `VectorSource`；其构造函数指定 `SourceType::Vector`；`RenderSource::create` 创建 `RenderVectorSource`。因此该 Test App 的正式 PBF source **不是 CustomMVTVector**。任务书列出的 CustomMVTVector 限制是独立安全约束，本轮完整保留。没有改旧报告，也没有补造 tide 数据、删原正式 PBF 层或修改服务 Style。
+
+`retainedSegmentSourceState` 原先先读取 revisionFor，缺少 tide 的登记会返回 nullopt，从而提前返回默认 unknown-dependency。现在在读取 revision 前发现缺失 RenderSource 时明确返回 `missing-source`；本例的ready/stable=false、revision=0 不变。有旧tombstone记录的缺源也提前返回revision=0，而不暴露旧登记hash；它仍不得Build/Reuse，RevisionBook登记机制不变。这是诊断修正，**不改变缓存准入**。source 存在但无 revision、CustomMVTVector、未知 layer dependency 仍 fail-closed。
+
+后续即使 Host 合法补齐 tide，R 仍包含大量 Symbol，Placement 首建阻塞不会自动消失。缺源与 Placement 是不同失败点。
+
+## 3. 已支持的本地 GeoJSON/circle 子集
+
+FAST_SMOKE 选择本地 GeoJSON 非空点与 circle R，不新增 source 类型授权。其现有追踪链：
+
+| 输入或事件 | 源码链与保护 |
+|---|---|
+| GeoJSON setGeoJSON | `GeoJSONSource::setGeoJSONData` 替换 immutable Impl 并通知 SourceChanged；Fast non-camera signature 比较 sources；Full `diffSources` 推进全局 content 和本 source revision |
+| Source 增删/同ID重建 | `createRenderTree` 的 sourceDiff added/removed/changed 都 advanceSource；RevisionBook 保留 tombstone；PreparedTree 在 Full 更新对象前释放 |
+| 异步 GeoJSON 数据/布局 | `RenderGeoJSONSource::update` → GeoJSONTile::updateData；capturedData 和 weakPtr 防陈旧/销毁回调；GeometryTile correlationID 保护 pending；`onLayout` 每次更换 layoutResult 都 onTileChanged；RenderSource → orchestrator 推进 source-local revision 和全局 content，再 invalidate |
+| Tile 未就绪/淡入 | `isLoaded`、hasFadingTiles、source assessment、#17 与 R 稳定性检查继续保留 |
+| Layer paint/layout/顺序 | immutable layers signature、per-R content fingerprint、resolved plan/topology；有 transition/repaint 仍阻止 |
+| Camera/viewport/pixelRatio | #6/#7/#8、RetainedUnderlayKey 与 revision state；旧 texture 不能按新矩阵复用 |
+| Style reload | styleLoaded/signature、配置/层序/Source 新身份、PreparedTree 生命周期保护；trace 在实际看到 loaded→false 时重置 |
+| Image/Sprite | imageDiff、spriteLoaded、imageManager readiness、missing/unused image callbacks 推进全局 revision；#8 先捕获新 images 输入 |
+| Glyph/fontFaces/URL | non-camera signature、glyph URL/font identity 追踪、onGlyphsLoaded 推进全局 revision；不删除资源门禁 |
+| Annotation | #24 pending 检查、source/tile/图片变化与层表；实际 Symbol 继续纳入全场结构检查 |
+| context/reset/destroy | markContextLost、Renderer.clearData 清 PreparedTree/trace，orchestrator 推进 revision；析构 detach observer 前排空 source/tile 工作；Test App 取消 callback、dispose runtime、删除自有 marker，MapView 原生命周期仍由 Activity 执行 |
+
+这一闭环是现有实现的源码依据，**不是本轮已跑出的 Source mutation/GPU PASS**。异步过渡中 Full 也可能继续展示尚未更新的旧 bucket；要求 Fast 与同一时刻合法 Full 等价，而非承诺提交 API 后同步完成画面更新。成功布局后必须失效并正确重建；不可用两张稳定末态截图代替事件顺序证据。
+
+R source policy、RevisionBook、GPU Build/Reuse 算法本轮零语义修改。新增 C++ 用例验证既有 revision/cache 状态机组合；unit 中显式推进 epoch/标记构建只用于状态机测试，不是实际 Native 帧或 GPU 成功的证据。
+
+## 4. C、Annotation 与 Scene 聚合
+
+`continuousRangeSupportsParticleFastPath` 要求每个 C layer 都 startsRetainedDynamicRange，并至少有粒子动画层。WeatherColor 与 RasterParticle 符合；普通 circle、Symbol、内建 Annotation Symbol 不符合。`particlePreparedSceneSupported = retainedSupported && fastContinuousSupported`，并要求单一 C。#22/#23 可以共享 C 不支持根因。
+
+本轮没有修改 #22/#23、C GPU 复合流程、层序或 AnnotationManager。不能证明非粒子 C 与既有 Fast prepare/postRender 等价，故不放行。
+
+独立 FAST_SMOKE 在确认 `map.annotations.isEmpty()` 后，仅从本场景 Style 删除自动生成且空的 `org.maplibre.annotations.points` layer，保留内建 source；若缺层或 remove 失败则 BLOCKED。Native annotation 更新规则未变，正式 PBF 五场景不删除该层。baseline 层序应为 background、R circle、weather-color、raster-particle，实际 JSON 仍需 RDC 核对。
+
+ANNOTATION_BLOCKED 重新加载一个正常 Style，保留自动内建层并用现有 `map.addMarker` 加真实 marker；可单次修改其 position。内建 Symbol 位于 C，#22/#23 必须继续阻止 Fast。从该场景切回 baseline 时只删除本场景拥有的 marker，不能清除其他 Annotation。若存在其他 Annotation，baseline 拒绝启动。该场景转换含合法 Style reload，不是生产 Annotation 零重载支持的证明。
+
+## 5. Placement：安全局部修复与 BLOCKED
+
+正常 Continuous Full：placementIsRecent=false 则 placeLayers/commit，placementChanged=true；recent=true 则 setPlacementStale，controller.hasTransitions=true；关闭 transitions 时正常 Full changed=true、fade=1。含结构性 Symbol 的 R 无可证明的首次 Build 稳定窗口。
+
+本轮保持 Symbol R 的三项 gate、scene placementStable、全图碰撞、fade/transition 和跨 source 规则。完整 GPU symbol 输入、bucket/atlas/opacity/duplicate/anchor 的结果证书仍不存在；建立它需要独立结果签名或更大生命周期设计。**Symbol R 准入修复 BLOCKED，不能删除 changed/stale/fade 条件。**
+
+唯一行为修复限定于**完整非空层表没有任何结构性 Symbol**：此时 controller 的 stale/transition 没有 Symbol 像素消费者，单独阻止 #13 不代表画面可能变化。`particleFastPathHasPlacementTransition` 按完整 Style 表检查；隐藏/空数据的 Symbol 与 Annotation Symbol 一律保守保护。production 还核对层表数量与 renderLayers 数量，不一致保持原 transition；空表也保守保留。
+
+这是 Shared Core 内部实现优化，无 Android/iOS 分叉，不新增控制 API、不禁止正常 Full Placement、不修改原始 controller。其余23项 Gate、source/cache/scene 条件全部继续生效。新增 Symbol 尚未进入旧表时，immutable layers 的 non-camera signature 不相等，且 Annotation pending 单独阻止 Fast；Full 更新后表重新包含 Symbol。未取得新层表前不得只凭这个 helper 放行。
+
+反例边界：同场只要存在一个隐藏 Symbol、空 Symbol、C Annotation Symbol，仍使用原 controller transition；缺层表、source mutation、未完成 tile layout、image/glyph 更新、camera/viewport、style reload、debug/context 问题都不能被本修复抵消。未来若引入新的 Placement-capable layer 类型，应先扩展结构检测及测试；当前源码仅 Symbol 的 LayerTypeInfo 使用 CrossTileIndex::Required。
+
+## 6. 实施结果、验证方案和限制
+
+- IMPLEMENTED：缺源明确诊断、无 Symbol 场景的 #13 限定检查；3个非 Jest C++ 用例源码；独立4场景及 UI/Intent、真实 Native 快照与操作前后自动采样；中文文档和追加记录。
+- 保留 fail-closed：CustomMVTVector、未知 revision、缺源；非粒子 C；所有 Symbol R Build/Placement 保护。
+- NOT RUN：Native/Kotlin 编译、C++ 测试、Android build/设备/GPU/Fast 命中、像素对照、性能、iOS Metal 设备验证。
+- 保留：正式 STEP-113 五个 PBF 场景实现原样、STEP-102 fixture 原样、STEP-110/111 未跟踪文件原样。新增菜单明确标识独立 smoke，不冒充63/113层等价。
+
+验收步骤和命令见 `docs/60_测试/STEP-114_独立FastSmoke场景与RDC验收_v1.md`；Native 定向命令也直接写在本轮完成报告。baseline 必须取得真实 Native Full>0、Fast 增长、CacheBuild>0、Reuse 增长、completed fast-rendered、24 PASS/knownMask 完整/decisionMismatch=0；否则维持 PARTIAL，不能标 Fast Path 已修复。
+
+Source/Image/Camera/缓存禁用/Reload 的反向证据需保存事件前/提交后/100/500/1500ms 快照，必要时以更早的精确帧复核；未捕获瞬间 gate 不能用计数猜测。后台/恢复/Teardown、Symbol/Annotation 与原 PBF 回归、双平台共享源码独立检查仍为 RDC/用户待执行项。

docs/20_调查/STEP-116_STEP113原PBF_FastPath阻塞安全修复审查_v1.md

@@ -0,0 +1,73 @@
+# STEP-116 STEP-113 原 PBF Fast Path 阻塞安全修复审查 v1
+
+日期：2026-10-11（JST）。结论：**部分实现（PARTIAL）；空 Annotation 生命周期受控修复已落源码，缺源和 Symbol R 准入继续 BLOCKED。没有新的设备 Fast 证据。**
+
+## 1. 当前事实与范围
+
+仓库 `/Users/tei/dev/MapLibreParticleLab`，`particle/main@e2d202b560ad0165101546597c43f2ef0ccf4542`，Darwin 24.6.0 / x86_64。起点 tracked clean，只有 STEP-110/111 和本次 STEP-116 任务书未跟踪。版本仍 `13.6.1-particle.23`，不能用版本号相同推断 APK 源码相同。Integration main `80667d6c343411d03a760425438e3d292f452118` 为用户提供的 RDC 核验事实，本轮只读相关规范，没有 fetch 或跨仓写入。
+
+已读取 AGENTS、PARTICLE_BASELINE、项目规范全部八文件、总则 README 和四份有效总则、STEP-116 任务及 STEP-112/113/114/115 当前记录/报告和相关源码；Integration AGENTS、README、WORKFLOW、TEAM_MODEL、contracts、rfc、adr、instructions、status、compatibility 只读。本轮不使用子代理，不修改公开头文件、公开 API/ABI、Host/RN/JNI 控制协议、NavSea 或公网 Style。
+
+## 2. 缺源 R：证据成立，空依赖准入不实施
+
+保留文件 `artifacts/maplibre-particle/android-validation/step113/source-change-after-full.json`，SHA-256：
+
+`24a06fa1cb072a628c650723c58a880895ec656f4972fa55d3cb064bfb2aabda`
+
+Native 原层 index=2、ID=`tide-spots`、type=`symbol`、source=`tide`。R[0,63) 依赖 `mapple/navsea_delivery/tide`。Native 实际 Source 表是 `mapple:raster`、`navsea_delivery:vector`、`org.maplibre.annotations:annotations`、`rn-weather-fields:raster-array`、`step113-source-probe:geojson`；没有 tide。该文件属于旧 SOURCE_CHANGE 完整窗口，不冒充本次 STATIC_RC 实测。原记录中 fallback=unknown-dependency；当前 STEP-114 代码已提前报 missing-source。
+
+`RenderOrchestrator::retainedSegmentSourceState` 在查 revision 前先检查缺源及 CustomMVTVector；普通 Vector 不走 CustomMVTVector 拒绝分支。`renderSegmentDependencies` 不因隐藏或当前桶为空删依赖。`RenderSegmentRevisionBook::revisionFor` 对未登记来源返回空值，保留删除墓碑用于同名重建；墓碑存在不能代替当前 Source 的 readiness。
+
+源码链路审查：
+
+| 链路 | 当前实现与限制 |
+|---|---|
+| 零贡献候选 | createRenderTree 的 source/layer 匹配循环不会给缺源层生成 LayerRenderItem，updateList 默认 false；这支持“本轮没有对应新 RenderItem”，不等于全部旧 GPU 对象已完成禁用的证书 |
+| 旧 GPU 生命周期 | RenderLayer::markLayerRenderable 调用 activateLayerGroup 提交 ChangeRequest；Symbol 还处理 collisionTileLayerGroup，layerRemoved 停用两类 group。CPU 状态、待处理 requests、旧 buckets 与实际执行时点需要一起核验；无 source 的循环边界也不能只靠 bool 推断 |
+| Source 创建/删除/同名恢复 | createRenderTree 的 sourceDiff 递增全局内容及对应 source revision；prepare 输入的 immutable sources 身份变化使 NonCameraSignature 不匹配，必须先 Full |
+| 同名更新/异步完成 | changed sourceDiff、onTileChanged → TileMutation → 内容/source revision + observer invalidate；feature-state 同样走 source 变更，不能按 HTTP 下载或 loaded 时间代替 |
+| 全局输入 | layerDiff / 层序、imageDiff、Glyph URL/fontFaces、onGlyphsLoaded、Sprite/ImageMissing、context/style cleanup 保留原失效链 |
+
+因此本轮**没有把 missing-source 当 empty**，没有登记虚构 tide revision，没有补假源或删除 tide-spots。后续需要“该 R 在成功 Full 中实际参与 GPU 绘制的 group/碰撞 group 已排除、无待应用资源变化”的有界证据，以及 source 出现/恢复后下一次尝试必定 Full 的回归。当前仅 Source 表缺失不足以承担这项新准入契约。服务器正式 Style 缺源仍是 BLOCKED。
+
+本轮只在现有诊断 JSON 的每段增加可选 `missingSourceIds`，由同次 snapshot 的依赖和 Source 表计算，包含缺失来源的具体 ID。查询不写 revision、不构造缓存、不修改首错和 24 Gate。
+
+## 3. 空 Annotation C：局部修复与保护
+
+旧 STATIC_RC Native 66 层：原63层 + weather-color + raster-particle + 自动 points Symbol。C 从 rn-weather-color 开始，普通 Symbol 不支持 particle dynamic range，阻挡 #22，并影响聚合 #23。SOURCE_CHANGE 的额外 circle 也必须保留。
+
+仅在 Step113PbfGateScene 的 STATIC_RC 第二次 Style 加载完成时执行一次空层调整：
+
+1. 生产基础 ID 不含 points，生产Sources不得占用org.maplibre.annotations；SDK `map.annotations` 必须为空；实际层必须是 SymbolLayer、sourceId 为 org.maplibre.annotations，内部 Source 必须存在。来源由本次原始JSON无内部ID、Native加载路径与实际层共同核对，避免把生产同名Source误当空SDK来源。
+2. 使用 `Style.removeLayer(Layer)` 对象重载，保留可重加的 wrapper；Source 保留，原63层定义/顺序及生产 Sources 原样。
+3. 记录 `emptyBuiltinAnnotationLayerRemoved`、实例数0、Source保留、移除层ID/作用范围，保存 productionSources；poll/export 继续使用真实 Native 计数。静态预期正常 STATIC_RC 65 层，不能当实际计数。
+4. 不周期删除任何层。后续普通 Style.addLayer 保持原行为，native immutable layer/signature/topology 变化继续 Full；Style 更换后不对新 Style 再做移除。
+5. stop 在相同 Style 且该 ID 仍缺失时重加原 wrapper，已有同名层不覆盖。Style 身份改变或 Annotation/points 重新出现时，3秒 poll 撤销场景验收条件并报 BLOCKED；poll 是报告保护，不承担恢复可见内容的时序保证。
+
+关键修复位于内部 `src/mln/annotation/annotation_manager.cpp/.hpp`：原 updateStyle 只在 Source 不存在时创建 points，Source 保留而层被删除会让后续 Marker 无绘制层。提取私有 ensurePointLayer，独立检查 Source 和层；首次添加 SymbolAnnotation、更新已有 SymbolAnnotation、Style loaded 三个入口修复缺失层。更新没有 geometry/icon 变化时也把 dirty 置真。已有同名 Layer 不被覆盖。
+
+时序：Map::addAnnotation / updateAnnotation → AnnotationManager 修复 Style layer vector → Map::Impl::onUpdate 捕获新的 immutable layers → Fast NonCameraSignature/annotationMutation 拒绝旧树 → Full 执行正常 Annotation 渲染。恢复不依赖3秒poll，也没有在 renderer thread 的 updateData 内重写 Style。Shape Annotation 原接口/图层仍按原逻辑处理，碰撞、Fade、Glyph/Image 和 C 判断完全保留。
+
+风险：这是 Shared Core 内部生命周期修复，所有后端共用；需 RDC 编译并跑真实图像用例，确认无锁/重入问题及旧 Annotation 行为回归。用户主动提供同名层时尊重其语义；若其配置本身无法绘制，该情况不被当作 Test App 空层安全条件。恢复失败在日志保留，不写成功。
+
+## 4. Symbol R：首次 Build 仍 BLOCKED
+
+已读 PlacementController、Placement::placeLayers/commit/symbolFadeChange、RenderTreeImpl::prepare、SymbolBucket::updateVertices、renderer Full 准入和 scene 聚合。
+
+| Continuous Full 分支 | 当前 Symbol R gate |
+|---|---|
+| placement 不 recent | placementChanged=true；placeLayers 后 commit、setPlacement，changed 本身阻断 |
+| placement recent | setPlacementStale；hasTransitions 返回 true，阻断 |
+| transitions 关闭 | placementIsRecent=false，Full changed=true；symbolFadeChange 返回1，不是 settled=0 |
+
+RenderTreeImpl::prepare 在 bucket updateVertices 中更新 opacity/dynamic attributes，并置 uploaded/dynamicUploaded/placementChangesUploaded 等状态。Placement commit 只提交 CPU placement/opacity 结果，不证明当前 R 的最终 GPU 输入一致。per-R `renderSegmentPlacementGatePassed` 和 `retainedSegmentIsStable`，全局 retainedPlacementStable / retainedSupported / preparedSceneSupported 均保留。隐藏/缺源/当前 placementData 为空的 Symbol 仍结构上具备 Placement 能力。
+
+**需要的额外设计证据**：成功 Full 对应的 GPU 上传/绘制完成代次、R 使用的 bucket/tiles/跨瓦片ID与排序、跨Source碰撞与所有参与碰撞层的 Placement结果、text/icon opacity和dynamic vertices、atlas/glyph/image代次、Style/Source/layer identities与revision、camera/projection/viewport/pixelRatio、uniform fade及debug/3D条件、待处理requests/异步变更纪元。证书必须绑定一次成功 Cache Build，变化即 invalid/Full，并对 GL/Metal 验证等价及 shadow。现有代码没有完整证书，本轮不做跨层重写，不用毫秒阈值、loaded、无手势或counter装配代替。
+
+## 5. 测试源码与结论边界
+
+新增四个 `Step116Safety.*` C++ 用例：缺源/Source加入未loaded/异步revision/删除墓碑和恢复；JSON缺源审计与Placement并存、查询无副作用；Symbol两个Continuous分支及关闭transition保护、无变化/Source与全局资源revision；Annotation/层序/disable/reload多失败 shadow 全集。revision用例验证的是账本契约，不伪造实际 Glyph/Tile 回调或 GPU完成。
+
+新增三个 `Annotations.Step116*` 用例：空points移除后真实添加在render前恢复并比对既有point_annotation图像；已有Marker no-op update恢复且出图；已有同名层不覆盖、reload恢复且出图。这些是测试源码，全部 NOT RUN；设备的annotation/Style、async mutation、GL/Metal回退还须独立验收。
+
+本轮实现后预期消除原 STATIC_RC 的空内部 C Symbol；无法承诺 #23 清除，也无法承诺 R Build/Fast>0。旧快照、AST或diff检查均不构成新制品安全、像素或性能 PASS。

docs/20_调查/STEP-117_PBF_R首次缓存Build安全证据_v1.md

@@ -0,0 +1,137 @@
+# STEP-117 PBF R 首次缓存 Build 安全证据 v1
+
+日期：2026-10-11（JST）。结论：**安全准入 BLOCKED；本轮保持 missing-source 与 Symbol placement fail-closed，交付七项非 Jest C++ 回归源码。没有实现 R 零贡献准入或 Symbol 结果证书，没有新的 Native/Android PASS。**
+
+## 1. 工作区与证据等级
+
+Mac.lan / Darwin 24.6.0 / x86_64，仓库 `/Users/tei/dev/MapLibreParticleLab`，`particle/main@43e5f5b91598b9c3d3f1c788052d4bbd2d616668`。起点 tracked clean；STEP110/111 与 STEP117 任务书未跟踪。实际模型 GPT-6.1-Sol（gpt-6.1-sol）/ high，由当前 rollout `01a12912-9a0c-7712-9624-793f04b3f681` 的 `turn_context.model/effort` 核实。Integration 本地只读 HEAD 为 `80667d6c343411d03a760425438e3d292f452118`，没有跨仓写入或远端操作。Android VERSION 仍 `13.6.1-particle.23`。
+
+已读根 AGENTS、PARTICLE_BASELINE、全部项目规范、总则 README 与四份有效总则、STEP117 任务、STEP112–116 关键任务/调查/Step/完成报告/验收文件；Integration AGENTS、instructions、README、WORKFLOW、TEAM_MODEL、contracts/rfc/adr/status/compatibility。本报告用以下等级区分事实：
+
+- **源码事实**：当前 HEAD 的控制流和所有权；不等同运行安全证明。
+- **保留实测**：STEP116 原设备 JSON 与报告；不是 STEP117 新二进制。
+- **测试源码**：本轮已写、全部未编译和未运行。
+- **待证明设计**：尚未实现的证书、影子比较与平台验证。
+
+## 2. 原 120 帧重新核对
+
+原文件：`artifacts/maplibre-particle/android-validation/step113-retest-20261011_121308/static_rc/native-full.json`；274,693 字节；SHA-256：`cd491d2acca97119f1d4f2d6f77eb7b229c17b90d4be1181a59202308429b219`。本轮只读解析完整 JSON，逐帧复算 failMask，不修改或纳入 Git。
+
+实测源码 `c48a72a9d492ea0d05e4d58464f9643453158d50`，APK SHA `a8b7f4e0f8e026bde8835e18a04876062be84cce3a3749a511cb08605d9f8a35`，设备 FZG1-2 / `192.168.200.139:5555`。STEP116 报告记录安装 SHA 相同、90.008 秒 FastDelta=0 / FullDelta=920。本轮未接设备。
+
+原正式 63 基础层保留；Native 65 层，R[0,63)、C[63,65)；C 仅 `rn-weather-color`、`rn-weather-particles`。正式 Style fingerprint 为 `e0f9c2d1df38ae5d5953b561c52efe2f8590336de80b988e1d2935580d30b996`。生产 sources JSON 只有 mapple/raster 与 navsea_delivery/vector；Native 另有 org.maplibre.annotations/annotations、rn-weather-fields/raster-array。没有 tide。R index=2 的 `tide-spots` 为可见 Symbol，source/source-layer 均为 tide。
+
+| 实测项 | 复核结果 |
+|---|---|
+| 120 帧范围 | sequence 5631–5750；119 completed Full / 0 Fast / 1 pending |
+| 24 Gate | 120/120 knownMask=0xffffff、decisionConsistent=true；decisionMismatch=0 |
+| #3 / #4 / #23 | 各失败120帧 |
+| #12 / #13 | 各失败105帧 |
+| #22 | 最近窗口失败0；生命周期累计6，不称启动全程零失败 |
+| R cache | Build=0 / Reuse=0；textureCreate=0 / compositeCreate=0；fallback=missing-source |
+| R dependency | mapple、navsea_delivery、tide；missingSourceIds=[tide]；placementGatePassed=false |
+| pre Placement 状态 | 105帧 false/非零/true；15帧 true/0/false（changed/fade/transition） |
+| post Placement 状态 | 104帧 false/非零/true；15帧 true/0/false；pending 的 post=null |
+| fade 范围 | pre/post 均为0至0.9914085268974304 |
+
+这解释了一个容易误判的现象：15帧的 #12/#13 通过，并不建立 R cache；这些帧仍有 #3/#4/#23，且上一完成树的 changed=true。Fast #13 使用当前 controller transition，R 首建使用当前 Full 的三条件，二者取样点与职责不同。不得拼接 pre 与另一帧 post 来造出通过状态。
+
+## 3. 缺 tide：新 RenderItem 为零与 GPU 零贡献的区别
+
+### 3.1 Style 与 Source 创建
+
+`src/mln/style/style_impl.cpp::parse/addSource/addLayer` 先加入 parser.sources，再加入 layers。addLayer 在 source 存在时检查兼容性；source 不存在时仍保留原层（源码 TODO verify source）。这正是原 Style 能保留 tide-spots 而没有 tide 的路径。removeSource 会拒绝仍被 Layer 引用的 source；同名恢复不能依靠违法删除调用，合法整份 Style 更换及后续创建也必须覆盖。
+
+`RenderSource::create` 根据真实 SourceType 创建 RenderVectorSource、RenderRasterSource、RenderGeoJSONSource 等。原 navsea_delivery 是普通 Vector，不能将它归因为 CustomMVTVector；后者的未知 revision 准入限制继续保留。
+
+### 3.2 Full 的注册、停用和绘制时序
+
+| 环节 | 当前源码事实 | 能支持的结论 / 不能支持的结论 |
+|---|---|---|
+| createRenderTree source/layer 匹配 | `render_orchestrator.cpp` 在已有 sourceImpls 的外循环中收集 LayerRenderItem；缺源层不匹配，updateList 初始false | 本轮缺源层无新 RenderItem；不能单凭此证明旧 group 已移出 registry |
+| renderability 更新 | 每次 source 更新后比较 isLayerRenderable 与 updateList，调用 markLayerRenderable | 有 source 的正常 Full 能排队停用；所有 sources 为空时此循环不执行，不能推广为任意状态的清理保证 |
+| RenderLayer::markLayerRenderable | 更新 CPU bool；activateLayerGroup 创建 Add/RemoveLayerGroupRequest | bool=false 不是 request 已执行的证明；该方法没有清除 drawables、renderTilesOwner、placementData |
+| RenderSymbolLayer 停用 | 同时为普通 group 与 collisionTileLayerGroup 排队停用 | 需覆盖两类 group；不能仅数普通 RenderItems |
+| layerRemoved | RenderLayer 调用虚方法 removeAllDrawables；Symbol 的实现清除两类 group 的 drawable，然后停用 | 删除 Layer 与缺源导致不 renderable 的生命周期不同，不能互相替代 |
+| processChanges | 移动 pendingChanges 后逐个 execute，RemoveLayerGroupRequest 删除对应 registry entry | 删除 registry 不等于销毁 Layer 所持 group/bucket/atlas；指针仍可能持有旧数据 |
+| Renderer Full | tree.prepare → source/layer upload → updateLayers → processChanges → cache评估 → tweakers/group upload → Build/live draw → present/endFrame | Cache 评估位于处理 changes 之后，但此前没有生成覆盖旧数据与成功提交的零贡献证书 |
+| Cache Build | R 使用 orchestrator 的 layer group range 双 pass；没有只遍历新 LayerRenderItem | 缺源层无 RenderItem不等于range里无旧group；需要独立registry与层身份审计 |
+
+本轮实际读取 `render_layer.hpp/.cpp`、`render_symbol_layer.hpp/.cpp`、`change_request.cpp`、`render_orchestrator.hpp/.cpp`、`render_tree.hpp`、`renderer.cpp`、`renderer_impl.cpp`、`retained_underlay_cache.hpp/.cpp`。当前 src/include 中未找到名为 ResourceManager 的类；实际资源所有者是 gfx Context/backend、RetainedUnderlayCache 的 offscreen/composite、LayerGroup/Drawable 与 RenderTile bucket/atlas，以及 DynamicTextureAtlas/ImageManager/GlyphManager。GL 的 `Texture2DPool`（`src/mln/gl/resource_pool.hpp`）管理纹理复用，不提供“某个缺源层本帧零绘制”的语义证书。
+
+**限定的正向事实**：新加载且从未获得 source 的 tide-spots，没有匹配 RenderItem；新 RenderLayer 默认 isRenderable=false。**仍缺的事实**：原设备 JSON 没有 per-layer registry identity、两类 group 的已执行停用、旧 drawables/tiles/placementData 清空和成功 Full 提交代次。不能从其他 sources 已 Loaded、cache textureCreate=0 或 pending-changes Gate=PASS 推出这些条件全部成立。尤其 task 要求“无旧 Renderable 数据”，单纯停用并不满足它。
+
+### 3.3 失效链已存在，但不存在缺源的受控依赖状态
+
+`retainedSegmentSourceState` 在读 revision 前要求每个 sourceId 存在；缺失即返回 ready=false/stable=false/revision=0/reason=missing-source。renderSegmentDependencies 从完整层表收集 source 和 Symbol 全局前提，不因隐藏/空桶删依赖。RevisionBook 没有为从未出现的 tide 登记；删除墓碑可保留，但不代表当前 source 存在或 loaded。
+
+`sourceDiff.added/removed/changed` 增加 content revision 与对应 source revision，先删/建 RenderSource，再 update。同名同类型但 immutable Impl 改变属于 changed。Fast 的 non-camera signature 比较 immutable sources 身份，下一帧在 createRenderTree 之前拒绝旧输入；已有 PreparedTree 在 Full 创建前释放。异步 onTileChanged 增加全局 content 和局部 source revision并 invalidate。Image/Glyph/Style/Context 的全局 epoch、层身份 fingerprint、camera/viewport key也各自保留。
+
+因此“同名 source 出现后可拒绝旧 Fast”的机制已有源码依据；**不能由此反推不存在的 source 可合法登记成 loaded/stable/零 revision**。新的缺源状态需要绑定 source absent identity、完整层集合、应用后 registry/旧对象状态和成功绘制代次；source 出现、替换、异步 layout、context改变必须撤销它。当前没有这些存储和核验，不实施空依赖准入。
+
+## 4. Symbol 首次 Build 的安全根因
+
+### 4.1 两个 Full 分支和第二重 scene 锁
+
+`PlacementController::placementIsRecent` 按 commitTime+updatePeriod 判断；transitions关闭则总返回false。Continuous `createRenderTree`：
+
+1. 不 recent：placementChanged=true；Placement::create → placeLayers → commit；setPlacement 清 stale，CrossTileSymbolIndex prune 与 source fading 更新。
+2. recent：placementChanged=false；setPlacementStale；controller.hasTransitions 在 enabled 时优先因 stale 返回true。
+
+`renderSegmentPlacementGatePassed` 对结构性 Symbol 要求 `!changed && fade==0 && !controllerTransition`。每个分支至少违反一项。关闭 transitions 时 Full 为 true/1/false；duration=0但enable=true时fade=1，recent分支仍stale。等待更久、改300/30ms阈值或关闭fade无法提供证书。
+
+`renderer_impl.cpp` 还有独立保护：retainedPlacementStable、retainedStaticStable、retainedSupported，以及 `particlePreparedSceneSupported=retainedSupported && fastContinuousSupported`。只放宽 per-R Gate不会使 #23 安全通过；只放宽 #13也不能自举 Build。Fast 成功后 prepareParticleFastFrame 才重置树的 changed/fade；调用它来准备第一次 Build会循环假定尚不存在的安全证据。
+
+### 4.2 CPU 结果不等于最终 GPU 输入
+
+读 `placement.cpp::commit/updateLayerBuckets/updateBucketOpacities/updateBucketDynamicAttributeData`、CrossTileSymbolIndex、SymbolBucket::updateVertices、SymbolLayerTweaker 与 DrawableAtlasesTweaker，以及 GL/Metal symbol shader：
+
+- commit 以每个 crossTileID 的 text/icon placed 状态更新 opacity；显隐未变可继承旧 fadeStartTime。controller transition=false不等于所有桶在GPU中已上传或与旧帧等价。
+- RenderTreeImpl::prepare 更新 bucket opacity/dynamic data；SymbolBucket 将 uploaded、placementChangesUploaded、dynamicUploaded 标记为false。SymbolBucket::upload 的标记不是成功GPU Drawn R的证书。
+- opacity处理 duplicate、默认allow-overlap、justReloaded、variable anchors、orientation、text/icon配对；沿线重投影与camera相关。碰撞为全局 Placement，并可能跨 source/段产生依赖。
+- shader实际使用 `clamp(baseOpacity ± symbolFadeChange,0,1)`，再乘paint opacity。fade=0既可能为全透明新符号，也可能为已显示符号；fade非零也可能因clamp不再改变像素。用==0或>=1替代逐输入等价均不足。
+- LayerTweaker 还使用tile/label/coord矩阵、size binders、paint插值、纹理尺寸与shader变体；DrawableAtlasesTweaker绑定glyph/icon atlas和sampler。
+- retainedRangeContentFingerprint 只散列 layer.baseImpl 指针与index；它不包含 placement结果、opacity buffer、bucket身份、atlas纹理、uniform最终值。Source revision也不替代这些内容。
+- Build成功计数来自双pass编码无捕获异常、finishBuild与markBuildSucceeded；随后主buffer present提交。现有实现没有完整的 per-R GPU输入证书或设备completion fence记录。将编码成功说成GPU执行完毕属于证据越界。
+
+### 4.3 可继续的设计边界与反例
+
+| 候选条件 | 反例 / 缺少的证明 |
+|---|---|
+| source loaded、无手势、静止90秒 | changed/stale循环继续；异步glyph/tile/image可改变结果 |
+| Placement placed布尔相同 | opacity方向/基值、duplicate、anchor/orientation或dynamic vertices可不同 |
+| fade=0且controller=false | 实测15帧changed=true，Build仍拒绝；刚出现符号可能base opacity=0 |
+| 当前 RenderItems 为空 | 旧group可能仍在registry或旧数据留在RenderLayer；pending请求可能未执行 |
+| layer fingerprint/source revision相同 | 不能区分同桶的dynamic opacity/atlas/uniform变化 |
+| 两张末态截图看起来相同 | 未捕获变更瞬间、碰撞受害段及GPU提交代次，不能建立持续复用不变量 |
+
+待证明证书至少应覆盖：R层身份/层序和drawable集合；bucket/tiles/crossTileID及跨段碰撞结果；text/icon显隐、opacity方向/基值、dynamic vertices、沿线/variable placement；paint/layout revision；glyph/image/atlas/shader/uniform版本；projection/camera/viewport/pixelRatio；context generation；已应用ChangeRequests及异步content epoch。只能在正常Full完成prepare/upload/tweakers、真实Build成功提交且资源一致时绑定，任何不一致先Full+invalidate/rebuild。不能只加入一个“结果稳定”bool。
+
+这涉及 Placement→Bucket→Drawable/Atlas→Renderer提交生命周期的跨层实现，当前没有足够设备/图像证据保证安全。本轮停止该准入实现，不删或强制置假 placementChanged、symbolFadeChange、controllerTransition，不改24Gate。
+
+## 5. 七项测试源码及真实覆盖限制
+
+两个既有 test/CMakeLists.txt 已登记的测试文件内新增 `Step117Safety.*`，无需改构建表，全部 NOT RUN：
+
+| 用例 | 实际测试目标 | 不覆盖的事实 |
+|---|---|---|
+| RealPlacementControllerHasNoFirstSymbolBuildWindow | 用实际Controller/Placement::create/placeLayers/commit执行120个逻辑时刻；两个分支均fallback，Build/Reuse为0 | 空桶生命周期最小复现，无原PBF碰撞/GPU |
+| RealPlacementDisabledOrZeroDurationIsNotAResultCertificate | 实际enable=false与duration=0/enable=true，fade=1、stale行为继续保护 | 没有禁用生产fade |
+| MissingAndSameNameRestorationCannotReuseAnOldCache | 缺源→创建→状态机构建/复用→删除墓碑→同名恢复必须新Build | 模拟status与markBuildSucceeded仅为cache状态机，无GPU成功 |
+| CameraStyleAnnotationAndContextRequireRebuildBeforeReuse | camera/viewport/content/topology/config变化经过实际revision tracker和cache，使旧cache无效且#3/#4失败 | epoch输入是模拟，未触发真实Annotation/camera设备事件 |
+| RealMissingSourceTreeHasNoRenderItemButStillFailsClosed | 真实createRenderTree：缺源Symbol零RenderItem/零group仍missing-source；实际sourceDiff创建、同名替换、移除；layer fingerprint保持不变而revision变化 | 使用step117-source无数据GeoJSON测试对象，未改生产tide；无旧GPU对象场景 |
+| QueuedGroupRemovalIsNotAppliedUntilProcessChanges | 两个测试group实际进入registry，真实Remove请求入队前后遍历差异与pending变化 | 测试group代表两类生命周期，不是实际Symbol collision group或GPU Draw |
+| RealAsyncCallbacksAndContextStyleCleanupAdvanceContentEpoch | 实际Tile/Glyph/Image observer分派、markContextLost/clearData推进content epoch；旧content输入单独命中#5 | 事件在测试线程注入，无实际网络并发/完整Renderer/设备 |
+
+未新增Jest，未编译或运行这些测试。生产 src/include、所有Gate/计数、Android场景和63层零修改。既有Annotations.Step116图像用例保留；新测试不代替glyph/tile并发、跨段collision、old GPU drawable清理或Full/Fast像素验证。
+
+## 6. 具体阻塞与协调需求
+
+| 编号 | 无法继续的状态 | 应由谁处理 / 需要的产出 |
+|---|---|---|
+| B1 缺源零贡献 | 当前只有absent Source与新RenderItem缺席；无应用后双group/旧drawable数据/提交世代证书；revision=0不能登记为有效 | Shared Core制定absent依赖内部状态及销毁/禁用证书；Android/Metal分别验证初始缺源、曾有旧数据、合法Style替换、同名恢复 |
+| B2 Symbol首次Build | 重算changed、recent stale；所有可达Full状态都不满足现有准入；无最终GPU结果等价/时间不变证书 | Shared Core提供跨层结果证书设计与影子比较实现任务；先影子不放行，证明后才讨论受控准入；粒子负责人组织双平台审查 |
+| B3 正式tide语义 | 生产Style宣告tide-spots但sources不含tide；本仓库不能自行补业务数据、改服务器或删层 | Integration协调NavSea/Style所有者明确是否属于合法宿主动态注入、何时提供真实source及身份；改变公共缺源语义才走RFC/ADR，纯内部优化不强制新Contract |
+| B4 独立验证 | 本轮没有Native编译、测试或设备新证据；STEP116历史Mac配置缺libuv | RDC复核当前环境、执行定向测试，首错保留；用户明确授权后由RDC/普通Terminal集中Android验收 |
+
+B1/B2应形成具体设计/实现任务，不通过业务开关、假tide、删Symbol、改24Gate或STEP114烟测绕过。Integration是协调入口，本轮不向他人发消息、不写跨仓文件。当前代码阶段止于测试和证据交付；详见STEP117验收计划。原目标 Build>0、Reuse>0、FastDelta>0仍未完成。

docs/20_调查/STEP-119_Symbol结果证书与R缓存Build实现依据_v1.md

@@ -0,0 +1,77 @@
+# STEP-119 Symbol结果证书与R缓存Build实现依据 v1
+
+日期：2026-10-11（JST）。状态：IMPLEMENTED_WAITING_ANDROID；Shared Core已有实质实现，尚无本轮编译、GPU、Android或视觉验收结论。
+
+## 1. 基线与原证据
+
+仓库 `/Users/tei/dev/MapLibreParticleLab`，Mac.lan / Darwin24.6.0 / x86_64，particle/main@869930046b11dbeb3b147e3be952a2e847316292。Native版本13.6.1-particle.23。Integration本地只读HEAD=80667d6c343411d03a760425438e3d292f452118；已读取AGENTS、instructions、README、WORKFLOW、TEAM_MODEL和contracts/rfc/adr/status/compatibility，未写跨仓文件。纯Renderer内部优化，不新增公共接口、所有权或错误协议；C-001/C-002和Core-owned timeline/playback保持。
+
+STEP117揭示：Continuous重新计算令placementChanged=true；recent复用设置stale，hasTransitions=true。旧Symbol gate要求changed=false、fade=0、transition=false，两个分支都不能自举。global retainedPlacementStable、retainedStaticStable、retainedSupported、preparedSceneSupported还有独立阻断。
+
+STEP118保留原63基础层manifest，仅测试副本排除tide-spots：62基础层+2天气层，Native64，R[0,62)、C[62,64)，missingSourceIds=[]，static-placement、Build0/Reuse0。旧设备90.00806697399821秒FastDelta0/FullDelta942、decisionMismatch0，不是本轮结果。
+
+旧APK源码3051196054c7b69815c298040dae61d26499d9f2，SHA=44afcfabe0cf4f1ec93f35899241bd73093aa6db4b5cb82ca2120dd531b8f3e9。旧result.json SHA=d3d20fc35bbd17e9f0ea0dd014ca4af8e0c5c5284d9f0c009bc20981d876ff10；screen.png SHA=c8b57a8432626c9209ca9a614a747728d4256bd09273b28c26a793a75a6d44d4。本轮只读解析/核对，文件未修改。
+
+## 2. 实际渲染生命周期
+
+1. 正常Full先createRenderTree：Source/style差分、跨瓦片ID匹配、全场Placement碰撞与commit继续使用原实现，没有按R段拆碰撞或冻结新结果。
+2. RenderTreeImpl::prepare调用Placement::updateLayerBuckets，继续处理text/icon、重复符号、variable anchors、方向、opacity、动态顶点、沿线投影和排序。
+3. Renderer依次上传source/layer/atlas，updateLayers创建或更新Drawable，processChanges实际应用注册/移除队列。
+4. 所有正常Full LayerGroup先runTweakers并upload。SymbolLayerTweaker记录**同一份传给GPU的**evaluated props、drawable/tile UBO字段；记录frameCount，并确认evaluated/drawable/tile UBO存在和consolidated容量，未执行、出错、缺buffer或错误帧不能补证。
+5. 此后采集每R的原生Symbol绘制输入，与上一成功提交Full的证据精确比较。符合就准入首次Build，不依赖已有缓存。
+6. Build保持原双pass和原始全局ordinal；finishBuild后再检查输入未改变。资源/绘制错误走Fallback；实际主缓冲按原R/C层序composite或live绘制。
+7. present和endFrame成功返回之后再次检查输入、epoch及错误代次，才记录完成Full/Build证书。它证明成功编码和提交，不宣称GPU fence完成或像素等价已经测量。
+8. 后续一次正常Full Reuse成功提交后，才允许Fast。Fast使用相同证书版本、content/topology/config、相机、backend viewport、pixelRatio和crossSourceCollisions，并继续原24项Gate。
+
+普通Full替换旧prepared tree时只销毁引用式RenderItem；证据拥有复制的字节和必要资源引用，跨Full保留。style/context/显式prepared-tree reset仍清证书。symbolCompletedSignature独立保存上一Full的非相机输入，防止glyphURL/fontFaces/placement设置等在旧树销毁后丢失保护。
+
+## 3. 结果证据包含什么
+
+| 实际输入 | 采集与保护 |
+|---|---|
+| Symbol uniforms | 从SymbolLayerTweaker实际提交的CPU参数复制；包含paint颜色/透明度/halo、tile/label/coord矩阵、尺寸/插值、gamma、text/icon/halo标志；忽略SymbolDrawableUBO末尾12字节非shader padding |
+| 顶点与实例属性 | 对实际Drawable绑定的VertexAttributeArray/InstanceAttributeArray记录属性索引、类型、stride、offset、vertexOffset和共享原始字节；包含静态布局、动态位置/角度、opacity、data-driven paint、排序实例；共享属性必须已有GPU背板，索引必须已上传且非dirty |
+| 已释放的不可变buffer | 只在producer已release且存在GPU backing时用保持存活的对象/背板身份；不能读取的可变输入拒绝。不是把任意空数据当相等 |
+| text/icon/索引与排序 | 原生SymbolBucket对应text/icon/sdfIcon buffer、segment范围、instance/vertex/index长度、sortKey；两条路径均记录实际三角索引字节，release后必须保持不可变索引对象与GPU背板身份；instancing固定quad和segment仍核对 |
+| fade | 检查每个实际opacity顶点的packed值及当帧fade；必须在放置目标方向达到shader clamp终点，并且真实Placement fade已结束；非有限值、负值、非整数或越界packed值拒绝 |
+| atlas/texture/sampler | 保持atlas、glyph/icon及实际绑定纹理/原生atlas tweaker身份，核对尺寸/format、上传状态和实际绑定一致。原生tweaker的sampler策略由固定bucket/layout和相同camera/无手势状态决定；glyph/icon像素原地更新由既有全局epoch保护 |
+| shader | 独立provenance记录只在实际GL/Metal编译源码与原生Symbol源码完全相符、额外宏属于原生uniform白名单时登记；保留shader对象身份。名称相同的未知/替换shader不借用fade契约 |
+| LayerGroup/层序 | processChanges之后验证Symbol组确实注册，隐藏层无旧注册组，collision额外组或陌生组拒绝；记录全局group总数、原始ordinal、组身份/层索引/数量/enable，以及Drawable实际混合方程/因子/颜色mask、剔除/深度/3D状态。全局depth range与跨段排序因此参与证据 |
+| 版本与生命周期 | 精确结果revision、成功Build revision、成功Reuse状态；绑定content/topology/config、camera矩阵、viewport、pixelRatio、crossSourceCollisions；原update signature/SourceRevisionBook/Annotation Gate继续使用 |
+
+每个结果字节缓冲上限16MiB，超限拒绝证书；没有提高公共容量或假装完整证明。资源引用避免地址ABA；比较对象是字节序列而不是散列。既有segment cache revision组合仍保留，但Fast还直接核对证书状态，不能靠组合散列碰撞取得证书；Full Reuse也要求candidateHasBuild精确版本，缺匹配Build时显式invalidate旧Cache，再走Build。
+
+## 4. Placement与fade语义
+
+没有修改placementIsRecent、setPlacementStale、原hasTransitions、commit/fadeStartTime、updatePeriod或placement计算频率。原hasTransitions仍用于正常renderer请求刷新。新增内部hasActiveSymbolFade仅表示实际fade；retainedRangeIsStable、retainedSegmentIsStable、retainedPlacementTransitionActive和Fast动态输入改用它。
+
+GL三个原生Symbol vertex shader和Metal symbol.hpp三类shader均使用unpack后的base opacity加/减fadeChange并clamp到[0,1]。>=1在合法packed值上足以达到fade终点，但不能证明顶点、uniform、atlas或层序相同。因此没有单独用>=1放行，而是逐opacity检查+完整结果比较+提交代次。
+
+重算仍令placementChanged=true，诊断继续如实记录；它不再被当成最终GPU输入改变。recent/stale仍请求刷新，不能单独代表正在fade。Fast rebase保留被证书确认的Full fade值，不把它清为0来取得准入。
+
+## 5. 完整准入与失效
+
+首次Build路径：已完成Full证据 → 下一Full同绑定同输入且已settled → Build编码成功 → present/endFrame及复核 → Build证书。Reuse/Fast路径：同版本缓存 → 正常Full Reuse成功提交 → 原24Gate全部通过 → Fast。preparedSceneSupported与global/perSegment稳定性均使用同一结果证明，不存在只改perSegment条件的旁路。
+
+以下继续fail-closed：missing Source、CustomMVTVector未知revision、tile fading、未loaded style/sprite/image manager、paint/light transition、非粒子repaint、3D/debug/非continuous、不支持C、Annotation pending、相机/viewport/pixelRatio/非相机参数、异步content或pending changes、资源/编译/上传/绘制错误、未知placement-capable类型或shader（Symbol原生typeInfo指针必须匹配，名称相同不足以强制转换）、证据超限/不可读取。
+
+Glyph requested/error/loaded、Tile error/changed、Symbol error新增或保持epoch推进；Image missing/remove/update、Source差分、Context reset、Style clear沿用原保护。捕获到的renderer/registry错误推进错误代次与全局content epoch；逃出上传/编码/present的异常由Renderer外围捕获，清prepared/证书、失效所有旧Cache后原样抛出；证书不能使用失败更新的旧Drawables。Build前和成功提交后都有epoch复核，证据观察期间的变化拒绝完成证书。
+
+现有回调/registry操作运行在renderer调度线程；content revision是原有atomic。此优化不建立后台并发访问Drawable的通道，不改变callback线程合同。真正跨线程竞态仍需RDC平台实测。
+
+## 6. 反例与保守限制
+
+- 同placed布尔但variable anchor/角度/opacity不同：实际属性字节变化，revision递增，重新Full取证。
+- controller不fade但尚未上传/陌生shader/atlas未绑定：complete=false，拒绝证书。
+- glyph/icon纹理指针不变但内容更新：content epoch变化，旧Build/ReUse证书失配。
+- Source同名替换、原63层缺tide：SourceRevisionBook/loaded/缺源保护仍拒绝，不能借空RenderItem作零贡献证明。
+- 下方段删除group导致上方R ordinal/depth改变：全局group数量/ordinal证据变化，上方R不得复用旧结果。
+- Build存在但没有成功Full Reuse：canFast=false；失败/未完成的Full不能刷新成功提交证据。
+- Vulkan/WebGPU目前没有本轮原生shader provenance登记，Symbol结果证书保守拒绝；它们的普通Full渲染不变。本轮不宣称跨后端运行通过，也不以GL代替Metal验证。
+- 16MiB上限、非常大的PBF、持续Glyph/Tile更新、不同native实例buffer生命周期均可能继续阻止Build；须保留真实结果修复，不能提高测试阈值制造PASS。
+
+## 7. 测试与待证事实
+
+新增13项Step119SymbolResults，位于已登记的两个test/renderer文件。覆盖真实Controller lifecycle+SymbolBucket opacity/dynamic buffer、packed clamp反例、variable位置/角度、camera/viewport/pixelRatio、CollisionGroups、真实uniform/wrapped tile编码、未知shader、失败提交、Annotation与24Gate、真实Tile/Glyph/Image/Context/Style回调、Source同名替换/缺失和跨段registry移除。
+
+所有新增测试NOT COMPILED/NOT RUN。部分Build标记和字节payload是状态机fixture，绝不称真实GPU等价；现有CrossTileSymbolLayerIndex和Annotations图像测试必须由RDC一并验证。原PBF跨段collision、实际Glyph/Atlas延迟、Full/Fast图像、真实Build/Reuse/Fast和性能仍全部待独立验收。源码去除逻辑自举死锁，不承诺本机实机目标已实现。

docs/20_调查/iOS地图点击重叠Source触发MLNStyle空Peer崩溃调查_v1.md

@@ -0,0 +1,152 @@
+# iOS 地图点击重叠 Source 触发 MLNStyle 空 Peer 崩溃调查 v1
+
+- 日期：2026-10-09（Asia/Tokyo）
+- 状态：**问题已复现 / 原生崩溃堆栈已确认 / 修复与回归未执行**
+- 分类：Particle iOS Native / MapLibre Darwin Style API 与 maplibre-react-native 点击兼容
+- 严重程度：高；普通用户点击海图物体可使 NavSea 直接退出
+- 本文件性质：跨项目缺陷移交与定位证据，**不是已实施修复、测试 PASS 或新版本发行结论**。
+
+## 1. 用户复现现象
+
+在 iOS NavSea 正常启动并显示地图后：
+
+1. 直接点击地图上的「唐津ヨット ハーバ」位置点，App 异常退出。
+2. 点击其他普通地图物体，未观察到同样问题。
+3. 打开「+键盘」（十字光标）后，将光标移动到该港湾位置，查询/选取正常，不退出。
+
+因此该问题优先定位 **地图直接 Tap 的原生可点击 Source 命中/图层排序链路**，而不是仅根据地点名称推断港湾数据损坏、JS 详情渲染异常或粒子 GPU 绘制故障。
+
+## 2. 实际环境与 Git 事实
+
+| 项目 | 本次调查事实 |
+| --- | --- |
+| iOS 设备 | Pleiades，iPad mini（第 5 代，iPad11,2） |
+| iOS 崩溃日志声明的系统 | iPhone OS 26.5.2 (23F84) |
+| App | NavSea，bundleID `com.navsea.app` |
+| App 调查工作树 | `/Users/tei/dev/NavSea-release-v22` |
+| App 调查 HEAD | `4bfe5257`（`release/particle-v22-android-debug-20261009`） |
+| Particle 本次核对仓库 | `/Users/tei/dev/MapLibreParticleLab`，`particle/main` |
+| Particle 调查起点 HEAD | `6df21dac38f072c5ad35b8dfc7ec5217509602bc` |
+| 崩溃时间 | 2026-10-09 20:22:40 +0900 |
+| 崩溃日志 | 设备端 `NavSea-2026-10-09-202240.ips`（调查时只读复制到 Mac `/tmp/`） |
+
+设备还存在多份同日晚间 NavSea 崩溃报告，本次详细分析的证据为上述 **20:22:40** 报告。请不要把其余报告自动认定为相同堆栈，除非逐份核查。
+
+Particle 工作区在调查前已有其他未跟踪文档，均不属于本问题，不得顺手删除、覆盖或纳入本次提交。
+
+## 3. 崩溃证据（直接来自 iPad .ips）
+
+```text
+exception: EXC_CRASH / SIGABRT
+exceptionReason.name: NSInvalidArgumentException
+exceptionReason.composed_message:
+  *** -[__NSArrayM insertObject:atIndex:]: object cannot be nil
+faultingThread: 0 (com.apple.main-thread)
+
+-[MLRNMapView didTapMap:]
+  -> -[MLRNMapView handleTapAtPoint:]
+    -> -[MLRNMapView getTouchableSourceWithHighestZIndex:]
+      -> -[MLNStyle layers]
+        -> -[__NSArrayM insertObject:atIndex:]
+          -> NSInvalidArgumentException / abort()
+```
+
+上述调用栈直接证明 **崩溃发生在地图原生 Tap 处理访问 Style Layer 列表时，且 Objective-C 数组插入了 `nil`**。它并不证明具体是哪一个 Style Layer 的 Peer 为 `nil`；这一点需要后续补充定位日志或调试证据。
+
+## 4. 已核实的对应代码
+
+### 4.1 Darwin Style 列表 getter：空对象缺少防护
+
+文件：`platform/darwin/src/MLNStyle.mm`，调查时约第 285–293 行。
+
+```objc
+- (NSArray<__kindof MLNStyleLayer *> *)layers {
+  auto layers = self.rawStyle->getLayers();
+  NSMutableArray<__kindof MLNStyleLayer *> *styleLayers =
+      [NSMutableArray arrayWithCapacity:layers.size()];
+  for (auto layer : layers) {
+    MLNStyleLayer *styleLayer = [self layerFromMBGLLayer:layer];
+    [styleLayers addObject:styleLayer];
+  }
+  return styleLayers;
+}
+```
+
+`layerFromMBGLLayer:` 位于同一文件约第 376 行。该方法在已有 Peer 缺失时调用 `LayerManagerDarwin::createPeer(rawLayer)`；若工厂无法产生 Objective-C Peer，返回值可能为 `nil`，随后无条件 `addObject` 会直接触发本次异常。
+
+### 4.2 部分 Particle/Weather Layer 仅注册为 CoreOnly
+
+文件：`platform/darwin/src/MLNStyleLayerManager.mm`。
+
+```cpp
+addLayerTypeCoreOnly(std::make_unique<ParticleValidationLayerFactory>());
+addLayerTypeCoreOnly(std::make_unique<RasterParticleLayerFactory>());
+addLayerTypeCoreOnly(std::make_unique<WeatherColorLayerFactory>());
+```
+
+同文件的 `LayerManagerDarwin::createPeer`：当 `getPeerFactory(layer->getTypeInfo())` 不存在时返回 `nullptr`。因此以上 CoreOnly Layer **是造成空 Peer 的高优先级怀疑对象**，但需要定位日志确认实际 layer id/type，不能将具体类型预写为已证实。
+
+### 4.3 RN MapView：多 Source 命中触发列表遍历
+
+NavSea 当前安装依赖源码：
+`node_modules/@maplibre/maplibre-react-native/ios/components/map-view/MLRNMapView.m`。
+
+- `handleTapAtPoint:` 查询所有可点击 Source 的命中；存在命中时调用 `getTouchableSourceWithHighestZIndex:`。
+- `getTouchableSourceWithHighestZIndex:` 在 `touchableSources.count == 1` 时直接返回唯一 Source。
+- 在 **同时命中两个或更多可点击 Source** 时，方法读取 `self.style.layers` 并逆序遍历，决定顶部 Source；因此会进入第 4.1 节的危险路径。
+
+崩溃堆栈已进入 `getTouchableSourceWithHighestZIndex:` 的 `self.style.layers`，符合多 Source 命中逻辑。需要现场记录所命中的具体 Source / layer IDs，以确认唐津位置的重叠对象组成。
+
+### 4.4 NavSea 点击与十字光标是不同路径
+
+- 直接点击地图：`src/map/MapScreen.tsx` 的 `MapLibreMap onPress`，以及 `src/map/layers/MooringSource.tsx` 的 `GeoJSONSource onPress`。
+- 港湾点直点 Host 回调：`src/map/cursor/crossCursorEngine.ts` 的 `handleMooringPress`。
+- 「+键盘」选取：`crossCursorEngine.ts` 中的 `queryRenderedFeaturesAtPointCompat` / `queryRenderedFeaturesInRectCompat` 查询。
+
+本次异常在原生触摸处理阶段已发生；**即使 JS 侧在 `onPress` 增加 try/catch，也无法覆盖此 Objective-C SIGABRT**。
+
+## 5. 修复方向（待 Particle iOS 实施者决定）
+
+1. **首先精确定位**：在不改变业务和地图 Style 行为的前提下，记录 `layerFromMBGLLayer:` 转换失败的 raw layer id/type、Peer Factory 类型及命中 Source / Layer 列表，确认 CoreOnly Layer 是否为实际来源。
+2. **修复 Darwin 公共访问契约**：`MLNStyle.layers` 不得把 `nil` 加入 `NSMutableArray`；优先设计与现有 CoreOnly Layer 共存的稳定方案。可评估安全过滤不可桥接 Layer，或补齐对应的 Peer/排序能力，但不可仅凭猜测引入无意义的 ObjC wrapper。
+3. **保持集合访问一致性**：若采取过滤不可桥接 Layer 的方式，须同时检查 `countOfLayers`、`objectInLayersAtIndex:`、`getLayers:range:`、KVC/KVO 以及插入/移除行为，避免 getter 屏蔽后出现数量/索引语义不一致或再次写入 `nil`。
+4. **保持点击 z-order 正确性**：RN 的多 Source 命中不能因为跳过 CoreOnly Layer 而改变真实可点击 Layer 的前后顺序；必要时直接在 Native 查询层顺序而不是依赖不完整 ObjC Peer 列表。
+5. **限定修改范围**：优先在 Particle iOS Native / MapLibre 层完成，不通过 NavSea JS 屏蔽唐津地点、删除天气层或建立私有桥接来回避崩溃。若确实需要改 RN 公共接口或跨项目契约，应返回 Integration 项目协调。
+
+**切勿直接删除 Particle、WeatherColor 或 Validation 的 Core Layer 来“消除异常”**；它们是正式渲染能力。
+
+## 6. 修复后必须验证的场景
+
+| 场景 | 期望 |
+| --- | --- |
+| 同位置只命中一个可点击 Source | 正常选取，无崩溃 |
+| 两个及以上可点击 Source 重叠（重点复现） | 正确选中 z-order 最高且有效的 Source，无崩溃 |
+| 唐津ヨット ハーバ 直接点击 | 不退出，港湾选取/摘要功能正常 |
+| 「+键盘」移动到同一港湾 | 行为与修复前保持一致 |
+| 其他海图对象直接点击 | 继续正常，无点击回归 |
+| Style 含 RasterParticleLayer / WeatherColorLayer / ParticleValidationLayer 组合 | Style introspection 稳定，不向数组插入 nil |
+| 天气/粒子图层启用与关闭后重复点击 | 无崩溃、无源层级混乱、无隐藏的点击遮挡 |
+| `layers` getter、KVC 索引 getter、层增删 | 不出现 nil/越界，计数与索引契约保持一致 |
+
+最少应使用 **Mac 构建出的实际 iOS Native 二进制 + iPad 真机** 做点击复现/回归。仅能编译或仅有单元测试通过，不等于用户场景已修复。
+
+## 7. 责任、验收与完成条件
+
+- **Particle iOS**：调查具体 nil layer、修复 Darwin Style API/多 Source 点击兼容、实施 iOS 构建与真机验证。
+- **Particle Shared Core**：仅在确认是通用 Layer/Peer 协议缺陷时参与；不得未经证据改变 Android 行为。
+- **NavSea**：在收到经过验证的新 iOS 发行后进行最小消费端验收；业务层不承担原生崩溃掩盖责任。
+- **Integration 项目**：若涉及公共 API、跨平台协议、消费版本协调，则在现有 COORD/RFC/ADR/Contract/Status 框架内正式记录。
+
+修复完成报告应写明：引发空 Peer 的真实 layer id/type、实际改动文件、验证命令及结果、真机版本和复现结果、Git commit/分支，以及正式发行时遵照 GSRL 的 Source Lock/获取方式/校验材料。**本调查报告本身不构成新发行，也不授权覆盖现有版本。**
+
+## 8. 当前未完成事项
+
+- [x] 找到 iPad NavSea 原生崩溃日志，确认主线程异常及调用栈
+- [x] 核对 Particle `MLNStyle.mm`、`MLNStyleLayerManager.mm` 与 RN `MLRNMapView.m` 源码
+- [x] 说明直接点击与十字光标查询的不同调用路径
+- [ ] 获取本次返回 `nil` 的具体 Style Layer id/type
+- [ ] 编写并执行 Native 修复及目标回归
+- [ ] 重新构建 iOS、在实际 iPad 复现原场景并确认不再退出
+- [ ] 按 GSRL 验证新版本消费与正式发行（如进入发行）
+
+**结论：高可信度机制为 Native Style CoreOnly/缺失 Peer 与 RN 多 Source hit-test 排序不兼容；异常位置已由 .ips 确认，具体 nil Layer 身份与最终修复仍待 Particle iOS 验证。**

docs/40_任务/STEP-104_官方Native13.6.1升级阶段A_Codex任务_v1.md

@@ -0,0 +1,43 @@
+# STEP-104 官方 MapLibre Native Android 13.6.1 迁移：第一阶段 Codex 任务 v1
+
+## 1. 基线与职责
+- 用户授权 **GPT-6.1 Sol / High** 实施官方跟进，使用 Mac 固定 GNU Screen 会话 `20825.7445.codex`，不要自行切换模型和推理档位。
+- 项目独立 worktree：`/Users/tei/dev/MapLibreParticleLab-upgrade-android-1361`，分支 `upgrade/android-native-13.6.1-20261009`。
+- 当前第一父基线：**官方 Android Native 13.6.1** peeled commit `c7506d6aff3800e946f89e1a51432fc22d1a6534`；原有自研稳定版本（.21）HEAD `630ec657687bad4200c059bbccbb950d9c6f7ce9`，审计与报告闭环 HEAD `b433775348373b10fba02dc0e1f728bacd72f9e7`。
+- Integrated repo Linux 远端 `main` 已同步至 `80667d6c343411d03a760425438e3d292f452118`；当前遵守 C-001/C-002、RFC-004、ADR-001，不得擅自改公开 API 或将 Android 新行为写进跨平台 contract。
+- 先读原工作树 `/Users/tei/dev/MapLibreParticleLab/AGENTS.md`、`PARTICLE_BASELINE.md`、`docs/00_项目规范/`、`docs/00_项目总则/README.md` 与四份有效总则，再读现有审计报告 `/Users/tei/dev/MapLibreParticleLab-upstream-audit-20261009/docs/报告/UPSTREAM-001_MapLibre官方升级兼容性架构审计_Codex完成报告_v1.md`、近期 STEP-100/101/102 记录以及本任务。
+- 另一个 Mac `particle/main` 工作树有用户未跟踪文件且落后远端，禁止修改；历史 release/STEP-103 工作树均不可改。
+
+## 2. 本轮的工程目标和停点
+目标是形成一个**可测试的 Android Native 13.6.1 官方底座候选**，继续保留自研 Field/QBIN/Particle/WeatherColor/RenderSegment/Retained 功能，不重写、不扩大功能。当前不是新版发行。
+- A：在本分支以官方 13.6.1 为第一父，安全合入 `b433775348...` 自研历史的有效差异。优先使用 `git merge --no-commit --no-ff b433775348...`；解决全部 rename/content/modify-delete 冲突，不允许选择整文件 `ours/theirs` 丢失官方修复或自己的功能。核实 `git diff --check`、冲突标记和完整树，再创建明确 merge commit。可启用 rerere。
+- B：适配官方 `mbgl→mln` 命名空间、include、Layer/Source/Shader factory、`RenderLayer::update(PaintParameters)`、`RenderStaticData::backendSize` 移除、Renderer lifecycle、RenderSegment 和 GL 粒子后端。只修改当前升级必要的官方接入点，保留现有 fail-closed、source/placement/revision/fast-path gate、map Style 顺序、stencil/target 安全。
+- C：源码修改完成后，列出**精确可执行**的 Android Native C++/OpenGL 编译与定向测试命令，让 RDC 在 Mac 或 Linux 执行；Codex 自身不得进行耗时 build、link、codegen、打包或 Jest。可以执行 `git diff --check`、少量静态检查。
+- D：若完整迁移无法在本轮完成，优先形成单独的、可复现且可回退的 Git checkpoint、明确残留冲突/失败清单；未清除 Git 冲突不得提交伪造的成功 merge。发生公共 API/Contract 变化或 iOS 专属需求立即停下来报告，不自行扩大跨团队范围。
+
+## 3. 必须保留的现有行为
+- C-002 QBIN V4 单帧 exact match、双帧合法插值、每 fieldKey 八帧和原子拒绝语义不变；不同 reference/dataset/profile 不混用；RN Host 负责加载、requestedForecastTime，Native submit 不调整时间。
+- WeatherColorLayer 与 RasterParticleLayer 独立；粒子 GPU ping-pong、trail 和 RenderSegment 局部缓存存在；不允许用 CPU 动画替代、不允许关闭关键保护逻辑使其编译通过。
+- Retained 保留 Z-order、opaque/translucent 绘制语义与 segment 索引；Source/layer/style/context/placement 变更失效安全、销毁不泄漏或使用陈旧 texture。
+- 官方新版 Feature State 接口不得被自研逻辑覆盖或静默禁用；只记录 Native 后续 RN 11.5 测试 Gate，不升级 RN 包本轮版本锁。
+
+## 4. 范围
+- 允许：升级分支中的官方 Native Core/Shader/CMake、必要的 Android Native/JNI 接入、粒子模块源码、测试代码的机械迁移与必要接口适配，以及必要记录。
+- 禁止：修改 `particle/main`、`release/particle.21`、STEP-103 工作树、NavSea、Integration 合同、iOS 专属 Metal/Bridge 功能实现、官方仓库、Node/Gradle/NDK 工具链；禁止发布 AAR/npm、build APK、改 public API/ABI 语义。
+- 旧 .21 所有发布坐标保持冻结。iOS 旧实现应尽可能保留源码，但本轮只允许写 **NOT VERIFIED**，不允许声称 Metal/Swift/XCFramework PASS。
+
+## 5. 记录和 Git：强制多次小提交
+- 在仓库**根目录的 `recoder_step.md`** 追加每项实质进展，简明中文且 append-only，记录日期、基线、当前变化、已完成、剩余问题、下一步、关联 commit。还需追加 `粒子开发记录.md`（合入后存在），同步更新 `docs/50_Step记录/STEP-104_官方Native13.6.1升级阶段A_v1.md`。
+- 本任务已有独立启动 checkpoint 提交。后续**至少尝试**按合并/结构迁移/接口修复/文档三个功能批次提交。每次提交限定本主题的文件并有清晰中英 commit message。不允许为了凑提交提交空文件或破坏历史；若阻塞，就如实说明只完成哪些。
+- **仅 push 本次升级分支**到 `origin/upgrade/android-native-13.6.1-20261009`；切勿 push `particle/main`、force push、合并回主线、push upstream。需等 RDC 独立编译验收后再由 RDC 最终执行 push；Codex 此轮只 commit，不负责最终远端验收。
+- 用户正式要求阶段记录必须叫 `recoder_step.md`，**不可擅自纠正拼写或用其它文件代替**。
+- 工作期间若发现现存不相关改动，不能纳入任何提交。
+
+## 6. 完成报告与检查
+- 完成报告固定 `docs/报告/STEP-104_官方Native13.6.1升级阶段A_Codex完成报告_v1.md`，必须记录：实际模型与推理档位、原始 SHA 和候选 SHA、每个 commit 与变更范围、merge 冲突解决的准确状态、迁移清单、具体核心 API/行为检查、无 build 时 NOT RUN、给 RDC 的精确构建命令、剩余问题、Android/iOS/RN 明确边界、下一 Gate。
+- 命名绝对不能自称正式 SDK PASS；如只完成局部迁移标 PARTIAL / BLOCKED。Codex 结束前检查 `git status --short`、`git diff --check`、阶段日志存在，任务范围与 commit 对得上。
+- 对用户的最终下一停点是 Android 官方 13.6.1 候选的 Core/Android OpenGL 精确编译 Gate；RN 11.5/iOS/发布留后续。
+- 若需要新增跨平台语义/接口必须暂停并记录 Integration 协调所需证据，而不是自行做新合同。
+
+## 7. 本阶段特殊实施规则
+按现有项目 `AGENTS.md`：**Codex 写代码，RDC 负责独立编译和验收**。仅在完成局部代码和提交后提供精确编译命令，等待 RDC 结果，如失败再进入下一轮修复。不要自行执行长时间构建。

docs/40_任务/STEP-110_R0_Placement跨段归因只读调查_Codex任务_v1.md

@@ -0,0 +1,161 @@
+# STEP-110 R0 Placement 跨段归因与缓存安全边界只读调查 — Codex 任务 v1
+
+## 一、任务性质与核心问题
+
+**性质：Particle Native / Shared Core 专项，只读调查；不实现、不修复、不编译、不上机。**
+
+用户要求粒子项目独立回答：
+
+> Native 能否区分“R0 自己的 Placement 变化”和“其他 RenderSegment 引起的 Placement 变化”？如果能区分，是否足以在**不破坏 Symbol 碰撞、文字/图标位置及图层顺序**的条件下让未变化的 R0 复用缓存？
+
+必须把以下不同概念分开审查：
+1. **事件来源**：哪个 source/layer/segment 引发了 placement/repaint/revision；
+2. **实际影响范围**：全局碰撞计算是否使 R0 的 Symbol 位置、可见性、fade 或绘制结果改变；
+3. **缓存安全判据**：能否证明 R0 内容/Placement 仍与已缓存画面等价；
+4. **当前实现**：上述信息目前是否已有、是否按 Segment 使用、还是仅采用全局保守 Gate。
+
+禁止预设“全局 Placement 变化一定是 Bug”，也禁止以“R0 自己没有提交数据”直接推导“R0 视觉必然没有变化”。
+
+## 二、仓库、版本与事实优先级
+
+- 项目：`/Users/tei/dev/MapLibreParticleLab`，正式分支 `particle/main`、远端 `origin/particle/main`。
+- 创建任务时只读确认：`particle/main` HEAD `2df504cdc0403bdad85d3f31f16fd54a8744abac`、干净工作树。执行时必须**重新读取 Git 实际状态**，不得把此 HEAD 当作永恒基线。
+- NavSea 产品实机所用 APK 内 `assets/component-manifest.json` 记录：RN / Android Native AAR `13.6.1-particle.23`。V23 正式来源对应 `refs/tags/maplibre-particle/rn/13.6.1-particle.23`、GSRL Git commit `87f3d1c59a52581fb8339f0ea7d106b9f4b94fef`。
+- **必须分别标明 V23 发布源码与当前 `particle/main` 的事实**。如当前 main 有未发行后续改动，不能以 main 代替 V23，不能以 V23 APK 推断未发行修复已经生效。
+- 跨项目事实遵循 `D:\React\navsea-particle-integration\instructions\NAVSEA_PROJECT_INSTRUCTIONS.md` 及最新 COORD / RFC / ADR / Contract / Status；当前既有外部契约 C-001。此任务不新增/更改公共 API 或契约。
+- 粒子项目根 `AGENTS.md`、`PARTICLE_BASELINE.md`、`docs/00_项目规范/`、`docs/00_项目总则/README.md` 与四份有效总则必须先读，按当前项目事实处理过时的历史环境/发布坐标。
+- 必读既有证据：STEP-088、089、090、092、094、099、100、102、106、108、109；重点对比 STEP-090 早期缓存/快路成功条件、STEP-102 placement-free 分段隔离范围、STEP-106 T1/T2 Symbol 与 Annotation 边界的真实验收。
+
+## 三、来自 NavSea 的问题证据（仅作为输入，不由本任务修改 NavSea）
+
+FZG1-2 / Android 13 / V23 当前 APK，NavSea 采用**两段 R-C**：
+
+- R0：RETAINED，31 层，`background` 至 `place-labels-land-ja`，包含有 Placement 能力的 Symbol；
+- C1：CONTINUOUS，82 层，`rn-weather-color` 至 `chartDangerScanCenterLineLayer`，包含天气/粒子和其他业务层。
+
+固定同一风场、同一 map 生命周期，连续约 15.24 秒，`mapReactTag=864`、`generation=4`、`configRevision=1`、`topologyRevision=8`、113 层均不变：
+- 风场期间进程 CPU 样本均值约 98.6% / 99.1%，关闭天气后约 4%～8%；
+- `fastPathHit Δ0`、`fastPathMiss Δ452`、`fullCpuFrame Δ453`；
+- R0 `build Δ0`、`reuse Δ0`、`invalidation Δ453`、`fallbackCount Δ453`、texture/composite create `Δ0`；
+- 两端 `valid=true`、`fallback=false`、`sourceReady=true`、`sourceStable=true`、`placementChanged=true`、`placementGatePassed=false`、`cache.supported=false`、`cacheState=fallback`、`lastInvalidationReason=static-placement`；
+- `mainBufferExecutionMode=mixed`、`globalLiveFallbackReason=none`、`fastPathFallbackReason=cache-invalid`。
+
+**这些是症状，不代表已证明 C1 导致 R0 Placement 改变。** 此外，历史较早的 V23 短时快照曾观察到 `placementChanged=false` 但 R0 记录仍为 `static-placement`，需要区分“当前门槛值”和“上次失效原因/诊断时序”，避免误读。
+
+Mac 粒子团队如无法访问 Windows 原始快照，可依据上述冻结事实做 Native 只读审计；缺失证据须列为“需要后续验证”，不得自行编造 NavSea 图层或运行结果。
+
+## 四、必须回答的调查问题
+
+### Q1：Placement 的产生与传播
+
+从真实 V23 Native 代码绘制完整的因果链：
+- 触发 RenderTree / Placement 计算的入口与时机是什么？
+- `placementChanged`、`symbolFadeChange`、`placementTransitionActive`、`crossSourceCollisions` 分别表示**当前帧/上帧/全局/局部**的什么事实？何时清零或稳定？
+- Source/Layer 的 layout、tile、visibility、camera、animation 等变化，分别可能影响哪些 Placement 状态？
+- R0 以外的 C1 Symbol/Annotation/业务层变化，**在哪些条件下**可能影响 R0 的符号碰撞与最终视觉？
+- 如果 RenderTree 每次都重新算 Placement 但画面没有变化，如何区分“执行过计算”和“R0 最终结果发生变化”？
+
+### Q2：现有 R0 Gate 的作用域
+
+调查 V23 实际调用链及数据结构，至少解释：
+- R0 结构性 `placementCapable` 如何判定，与动态 `needsPlacement()` 有何区别；
+- R0 `placementGatePassed` 如何使用全局 `placementChanged`、fade、transition；
+- R0 `cache.supported`、`static-placement`、`actualExecution=live` 的完整因果关系；
+- R0 的 source-local mutation、segment fingerprint、retained revision 与 placement gate 是否真正各自独立；
+- STEP-102 对 **placement-free** R 的隔离已解决什么、**placement-bearing** R 仍未解决什么；
+- `lastInvalidationReason` 与当前失败条件是否可能属于不同采样/缓存生命周期。
+
+### Q3：能否证明“R0 不受 C1 变化影响”
+
+针对以下反事实场景逐项作出有证据的判断：
+1. R0 含静态地名，C1 只有普通非 Symbol 动画/颜色/粒子更新；
+2. R0 含静态地名，C1 的 Symbol 内容变化，但不同 Source 且跨源碰撞关闭；
+3. R0 含静态地名，C1 的 Symbol 内容变化且跨源碰撞开启；
+4. R0 Symbol 自身 layout/tile/visibility/zoom 发生变化；
+5. Camera/pan/zoom/rotation/pitch 变化；
+6. Symbol Fade/Placement Transition 活跃或刚结束；
+7. C1 有内部自动插入的 Annotation Symbol（参照 STEP-106）。
+
+每行必须分别给出：
+- “谁触发 Placement”能否识别；
+- “R0 最终 Placement/可见性是否改变”能否独立证明；
+- **允许 R0 Reuse 的必要安全条件**；
+- 当前 V23 是否具备这种判定能力及证据来源；
+- 无法证明时为什么必须继续 fail-closed。
+
+严禁把“不同 Segment”简单等同于“碰撞和 Placement 相互独立”。
+
+### Q4：对 Fast Path 的影响（仅限前置依赖）
+
+解释“R0 缓存有效”是否为 Fast Path 的必要条件但**非充分条件**。只读标出 R0 Gate 与单 C / unsupported continuous layer / revision / pending changes 等后续 Gate 的先后关系。不要扩大成 C1 全图层性能调查，不实施多 C 优化。
+
+## 五、只读检查范围与方法
+
+允许读取：
+- 当前 Particle Core 的 Renderer、RenderOrchestrator、PlacementController、RenderTree、Symbol/Collision、Retained Cache、RenderSegment Plan、Diagnostics 与 Fast Path 相关源码；
+- V23 tag 与当前 `particle/main` 的只读 `git show`、`git diff`、`git log`；
+- STEP-090/102/106 等历史设计、报告、设备验证结果；
+- 现有 C++ 定向测试源码与 Validation 场景源码（只读，不执行、不修改）。
+
+建议从当前实际路径 `src/mln/renderer/` 与相关 Shared Core 源码定位，**不得沿用旧 STEP 中过时的路径假设**。
+
+每一条重要结论必须给出：**文件路径 + 类/函数或结构名称 + 适当行范围或 commit + 相关调用顺序**。核心论断不得只引用历史文档或本任务描述。
+
+允许纯只读 Git/文本搜索，不要求也不允许额外建立实验分支、修改 Native/JS/Kotlin/测试代码、插桩、添加日志、运行 Jest、运行测试、Gradle、CMake/Ninja/Bazel、ADB 或重新安装 App。不得改 NavSea、Integration 或正式 release/tag。
+
+## 六、最终必须提供的结论矩阵
+
+**每个问题必须选择明确判定**，而不是只罗列建议：
+
+| 维度 | 可选结论 |
+|---|---|
+| 能否定位 Placement 事件来源 | 现有数据可区分 / 现有数据不足 / 条件性可区分 |
+| 能否证明 R0 的实际视觉结果未变化 | 已能证明 / 需扩展内部安全证据 / 不能按段安全证明 |
+| 现有 Gate 是什么性质 | 正确的设计保守限制 / 明确可证的过度阻塞 Bug / 混合 / 证据不足 |
+| 缓存失效的主要责任边界 | Native Placement 数据模型 / Native Gate 判定 / 当前跨段碰撞语义 / Host Style 组合 / 多因素 / 未确定 |
+| 可选后续方向 | 无需代码调整 / Native 内部诊断补强 / Native 内部安全判据设计 / 宿主层序方案需协调 / 需真机对照实验 |
+
+如果判断是 Bug，必须指出**违背了哪项既有语义/可复现的状态不变量**；如果判断是安全限制，必须指出**缺少何种证明才不能放宽**。如有多个阻塞项，按必要性和因果顺序排序，避免“修第一个之后才继续猜下一个”。
+
+## 七、报告与交接产物
+
+只允许新建/更新以下本 Step 文档（不改现有源码）：
+
+1. `docs/20_调查/R0_Placement跨段归因与缓存安全边界调查_v1.md`（主报告）；
+2. `docs/50_Step记录/STEP-110_R0_Placement跨段归因只读调查_v1.md`（状态及完成项）；
+3. `docs/报告/STEP-110_R0_Placement跨段归因只读调查_Codex完成报告_v1.md`（执行报告）；
+4. `粒子开发记录.md`（简短追加式记录）。
+
+调查主报告必备章节：
+- V23 tag / 当前 main 基线对照，说明是否有相关行为变化；
+- Q1～Q4 的逐条答案及代码证据；
+- **数据流/状态流**：Placement 事件 → 全局/局部状态 → R0 安全判定 → Cache Build/Reuse/Fallback → Fast Path；
+- 七类反事实场景矩阵，明确跨源碰撞、Fade、Annotation 的影响；
+- 已确定事实、假设、证据不足之处三栏；
+- 结论矩阵、根因优先级、最小下一步验证建议；
+- 若需调整公共 Contract / API，则仅提出 Integration 阻塞，不自行实施。
+
+完成报告必须逐项按“**已完成 / 未完成 / 无法验证**”回答任务项并说明原因；记录实际检查范围、当前 branch/HEAD、Git 提交及推送信息。不得用“源码已读”代替代码证据。
+
+**状态判定**：只读因果审计证据完整才可标为 `调查 PASS（不等于修复 PASS）`；否则 `PARTIAL/BLOCKED` 并列出缺失项。严禁声称“Native 已修复”、“R0 已缓存”或“CPU 已下降”。
+
+## 八、Git 收尾与执行界限
+
+- 本任务**只负责调查**。Codex/粒子项目未经用户后续明确授权，不得实施任何缓存、Placement、Fast Path 逻辑修改。
+- 完成相关文档后，仅提交本 Step 新增报告、Step 记录及追加的开发记录；保留所有无关 dirty/untracked 文件，不得强制清理。
+- 将本任务相关文档 scoped commit 到正式主线 `particle/main` 并 push 到公开远端 `origin/particle/main`。禁止 force push、改写历史、推送 upstream 或增加无关文件。
+- 完成报告必须给出**实际 commit hash、commit message、push 结果、远端分支**；push 失败不得宣称完成，应明确报告阻塞。
+- 本 MD 是交给粒子项目执行的**待办合同**。写入任务书本身不代表调查已执行、已验证或已得出结论。
+- 本任务不包含 Jest，不涉及原生编译、测试执行或 Android 设备操作。
+
+## 九、停止条件
+
+遇到以下情形须停留在调查层，提交 PARTIAL/BLOCKED 事实，不得扩大实现：
+1. V23 tag 与当前代码差异导致无法确认实际执行版本；
+2. Placement 影响关系必须依赖运行时数据，静态源码无法证明；
+3. 证明缓存安全需新增 per-segment collision/placement fingerprint 或改写 Core 算法；
+4. 需要改变对外 Native/RN 公共接口或跨项目责任；
+5. 需要 NavSea 配合修改 Style、增加调试或重新编译/测试；
+6. 所需证据缺失或与 STEP-090/102/106 的历史结论相冲突。
+
+出现以上情况，在报告中给出**最小下一步任务建议**，等待用户/Integration 决定；不得在本任务中直接实施。

docs/40_任务/STEP-111_R段Placement结果等价与独立刷新可行性只读调查_Codex任务_v1.md

@@ -0,0 +1,41 @@
+# STEP-111 R 段 Placement 结果等价与独立刷新可行性只读调查 — Codex 任务 v1
+
+## 一、用户目标
+用户希望 Native 对 R-C-R-C-R-C（简称 RCRCRC）中的每一个 RETAINED R 段单独决定是否更新。若该段本身最终视觉输出未变化，不应仅因另一段 Symbol/Placement/Fade 全局状态更新而被动重建；确实受跨段碰撞影响的 R 段必须正确更新，不能破坏文字、图标或层序。此任务是下一步架构/可实现性调查，不是授权实施优化。
+
+**核心区别**：A. 哪个 Layer/Source/Segment 触发重新计算；B. 全图 Placement 后每一个 R 段的最终 Symbol 视觉结果是否改变；C. Retained R 段缓存能否安全复用；D. 是否可进一步省略 R 段 prepare/placement 计算。A≠B、B≠C、C≠D。不要把各 R 分段直接当作 Collision Domain，也不要承诺每段无需参与全图 Placement 计算。
+
+## 二、正式边界与必读
+- Mac /Users/tei/dev/MapLibreParticleLab，particle/main，origin/particle/main；执行时重新记录 HEAD、branch、dirty、远端基线；保留未跟踪 STEP-110 任务书。
+- 先读仓库 AGENTS.md、PARTICLE_BASELINE.md、docs/00_项目规范/、docs/00_项目总则/README.md 和全部现行总则；读 STEP-110 主报告和 Codex 完成报告，以及 STEP-102、106、109、Fast Path 相关历史证据；以当前源码事实为准。
+- 先检查 /Users/tei/dev/navsea-particle-integration 的 main 与 origin/main 同步状态，读取其 README、WORKFLOW、TEAM_MODEL、contracts、rfc、adr、status、compatibility；已有跨项目结论优先。本 Step 只讨论 Shared Core Native，不直接修改 Integration/NavSea/Android/iOS。
+- STEP-110 已证明：PlacementController 仍是整图语义；R 的 placementCapable=true 时 Gate 消费 global placementChanged、symbolFadeChange、placementTransitionActive；跨 Source Collision 可能影响 R0，source≠segment。STEP-102/106 只验收过 placement-free R 的安全复用。本 Step 不能简单重复这些事实，重点给出**新增的判等/判无变化能力**具体可行性。
+
+## 三、只读调查工作项
+1. **从源码定位可实现性**：追踪 CrossTileSymbolIndex、Placement::placeLayers/commit、CollisionIndex/CollisionGroups、symbol buckets、placed icon/text、opacity/fade、RenderTree、RenderLayer、RenderSegment/Retained Cache 的真实控制与数据所有权。指出计算结束何处可以读取每一个 R 的最终 Placement 输出，是否已有稳定 ID、可见性/位置/opacity；写明路径、函数、行号和生命周期。辨别层间/Source 间/段间影响。
+2. **定义每段结果等价契约候选**：提出具体 per-R PlacementResultKey/Signature/Revision 候选字段（Symbol 实例稳定 ID、tile/source/bucket generation、placement result、collision visible/hidden、text/icon anchor/offset、paint opacity/fade/transition、zoom/camera、glyph/image atlas、style/layer order、render target boundary 等）。逐项解释哪些是 Placement 专属，哪些已有其他 cache gate 覆盖，哪些必须动态比较，哪些不需要加入，避免对每个 Symbol 每帧做过度 O(N) 或漏比较；比较发生于何时、如何处理首次帧、transition、reset、missing data。
+3. **RCRCRC 示例与判定表**：至少 R0/C0/R1/C1/R2/C2，其中 R0/R1/R2 都有 Symbol。分别分析：
+   - C1 仅粒子/颜色动画，R 均无可见变化；
+   - C1 Symbol 变动且只影响 R2；
+   - C1 Symbol 变动，碰撞也影响 R0/R1；
+   - R1 自己改变但 R0/R2 不变；
+   - 同一 Source 跨段、不同 Source 且 crossSourceCollisions=true/false；
+   - Annotation Symbol 自动插入，layer 顺序、camera/zoom/pitch、tile/glyph fade/opacity transition；
+   - 不能证明者 fail-closed。
+   结论表需区分“依然执行全局 Placement”、“该段仅避免 cache rebuild/composite 是否可复用”、“能否避免 render/prepare”、“Fast Path 仍被哪些其它 Gate 阻断”。
+4. **方案对比与难度**：对 A 只加 tracing/per-R 指标（不改变判定）、B 新增 per-R result fingerprint 但 shadow compare（仅记录真假）、C 利用已证明等价替换 global-only Symbol Gate 允许单段 Reuse、D 深改 Placement/Collision 成分段增量计算，逐一评估前提、复杂度（1-5）、改动范围、CPU/GPU/内存开销、风险、能否只改 Shared Core、对 Android OpenGL/iOS Metal 的影响。不能因为理论上可 hash 就声称 hash 一定安全。
+5. **执行与验收计划**：给出最小分阶段实现建议和真实可验证指标，包括 per-R signature stable/change、false invalidation、false reuse（严格 0）、build/reuse/fallback、视觉 A/B、Fade 长尾、CPU/frame、same frame draw ordering；指出先做诊断或原型是否需要新 Native 内部接口，哪些行为必须同时覆盖 Android/iOS。分别评估改善 retained cache 命中与改善整帧 CPU/Fast Path 的边界。
+6. **明确推荐结论**：回答每个 R 段可否“自身未变就不刷新”、可做到的最小粒度、不能保证的情形、最佳第一阶段（原型）与中长期方案，给出具体源码位置和工程量区间；区分源码已证实 vs 推断 vs 必须运行时验证。
+
+## 四、禁止项
+调查只允许读取 Native/历史 Git/本机历史实验文件以及新增本 Step 文档。禁止修改任何 C++/JS/Kotlin/Swift/编译脚本/测试代码；禁止执行编译、链接、测试、Jest、Gradle、ADB、Bazel、CMake、设备操作；禁止更改 NavSea、Integration、公用 Contract/API、GSRL、release/Source Lock、发行 Tag；禁止放宽当前 fail-closed Gate。禁止重置/清除现有 dirty、禁止 force push。除非明确用户授权，不执行后续实施。
+
+## 五、必做输出（实际生成）
+1. docs/20_调查/STEP-111_R段Placement结果等价与独立刷新可行性调查_v1.md — 主报告：代码路径/行号、RCRCRC 场景矩阵、Signature 草案字段逐项依据与生命周期、可行方案 A-D 对比、复杂度与工程量估计、风险、可执行的后续 Step 拆分、源码已证/待验证标识。
+2. docs/50_Step记录/STEP-111_R段Placement结果等价调查_v1.md — 简短中文 Step 记录，状态 PASS（调查完整）/PARTIAL/BLOCKED，记录未验证项与下一步。
+3. docs/报告/STEP-111_R段Placement结果等价调查_Codex完成报告_v1.md — 完成报告：实际模型与 reasoning effort（仅凭运行会话证据）、读取资料、逐任务结果、调查起/终 HEAD、branch、dirty、文件修改、未运行构建和测试、检查命令、限制、Git/Push 状态如实记录。
+4. 粒子开发记录.md — 本阶段简短追加（不要重写历史）。
+Codex 仅负责内容调查和上述报告落盘，Git scoped commit/push/远端验证由 GPT 指挥 RDC 独立负责，完成报告不得预报未执行 Git 结果。原有未跟踪 STEP-110 任务文件不纳入提交。本任务书自身保持未跟踪，避免误提交。
+
+## 六、验收与停止
+只在调查结果有对应源码位置/函数/调用顺序，明确安全条件、未证实风险、工程阶段与复杂度对比时，记“调查 PASS”；如生产实际视觉等价无法仅通过源码证明，可记“调查 PASS / 运行验证未执行”，不得声称优化已通过。必要的实机状态/插桩超出只读范围时明确给出下一阶段最小需求，不得扩大当前范围。不得把历史 STEP-110 的 PARTIAL 当成本次已经实现结果。任务退出前向 GPT 汇报生成文件、最后状态和未完事项。

docs/40_任务/STEP-112_V23粒子FullRender循环与Symbol缓存准入全面源码调查_Codex任务_v1.md

@@ -0,0 +1,138 @@
+# STEP-112：V23 粒子 Full Render 循环与 Symbol 缓存准入全面源码调查 — Codex 任务 v1
+
+**状态：待执行｜类型：全面只读源码调查｜编写日期：2026-10-10**
+
+## 一、用户目标与必须回答的问题
+
+NavSea 的 FZG1 连续风场场景中，粒子约 30 FPS，Native Particle Fast Path 持续 0 hit，约 1,787～1,796 次 Full CPU Frame/分钟；粒子关闭对照约 83 次 Full CPU Frame/分钟。含 Symbol 的 R2 缓存长期失效，理由为 static-placement。用户要求由粒子系统全面分析 Native 源码，找出导致“粒子 Tick → Fast Path 失败 → Full Render → R2 仍无法建立缓存 → 下一次继续失败”的真实原因，并提出安全修复方向。本任务**不授权修复**。
+
+必须明确回答：
+1. 谁请求每帧重绘？粒子是否只是要求下一帧，而非要求 Full Render？什么时候 MapLibre 能进入 Idle？
+2. Fast Path 全部准入条件的实际来源与执行顺序是什么？为什么 FZG1 的首个拒绝原因是 cache-invalid？
+3. R2 为什么 Build=0，而不是建好后偶尔失效？static-placement 实际检查了什么？
+4. placementChanged、symbolFadeChange、placementTransitionActive 是否在正常连续运行下形成难以通过的组合？原因来自时间机制、Transition 配置、Source，还是其它条件？
+5. Full Frame 已经正确绘制 Symbol 时，什么条件下可以安全地建立缓存供后续 Particle Tick 复用？修复 R2 后还会遇到哪些独立阻塞？
+
+**假设不是结论**：此前讨论认为 symbolFadeChange == 0 可能被误用为“Fade 已稳定”，这只是必须严谨验证或推翻的假设；不得直接断言为 Bug。
+
+## 二、环境、权威文档和既有事实
+
+- Particle 源码：Mac /Users/tei/dev/MapLibreParticleLab；执行时记录实际 branch/HEAD/dirty。编写时 branch=particle/main，HEAD=50ae48ad70，不能把该 HEAD 当执行时已固定版本。
+- 按 AGENTS.md 顺序先读 PARTICLE_BASELINE.md、docs/00_项目规范/、docs/00_项目总则/README.md 及现行总则、本任务、STEP-102/106/109/110/111 相关调查与报告；以执行时源码事实为优先。
+- 跨项目事实依照 /Users/tei/dev/navsea-particle-integration 的最新 COORD/RFC/ADR/Contract/Status。公共 API、Host/Native 职责改变只写提案，跨项目协调另立事项。
+- 现有未跟踪 STEP-110 与 STEP-111 任务书不得移动、覆盖、代为提交。现有 STEP-110/111 调查属于 PARTIAL，不表示 per-R 安全复用已经实现。
+- 执行模型建议 GPT-6 Sol Medium，实际完整模型与 reasoning effort 在开始前核实并报告；MD 不负责自动切换。提高推理档位须先停止说明理由、由用户确认。
+
+### FZG1 现场证据（不等于逐帧因果证明）
+
+| 指标（约 60 秒连续风场） | RC1 | RCRR_PREFIX | RC2 |
+|---|---:|---:|---:|
+| Full CPU Frame 增量 | 1792 | 1787 | 1796 |
+| Fast Path Hit | 0 | 0 | 0 |
+| R0 Reuse | 0 | 1787 | 0 |
+| R2 Build/Reuse | — | 0/0 | — |
+| R2 Invalidation/Fallback | — | 1787/1787 | — |
+| R3 Reuse | — | 1755 | — |
+| Fast 首个拒绝 | cache-invalid | cache-invalid | cache-invalid |
+
+RCRR_PREFIX 分段：[0,13) R0；[13,33) C1；[33,107) R2；[107,113) R3。C1 **含普通 Symbol/Line，以及 index31 WeatherColor 与 index32 Particle**，并非纯粒子段。R2 含大量 Symbol。FZG1 末态记录 placementChanged=true、symbolFadeChange=0、placementTransitionActive=false，**只是快照不是每帧时间序列**。此前也观察到导航 Source Mutation 计数增长，不能未经证据归咎于它。Full CPU Frame 不等于所有 Layer 重绘，不等于 Placement 实际重算次数。
+
+## 三、必须完成的源码分析 A：从粒子请求到 Full Render 的调度链
+
+逐级核查：
+- RenderRasterParticleLayer::isParticleAnimationActive / needsRepaint，SourceTimeline / V4Cadence / cadenceDue，粒子启动、暂停、无数据、隐藏时的返回条件。
+- RenderOrchestrator::hasTransitions，RenderTreeParameters::needsRepaint，Map::Impl::onDidFinishRenderingFrame / onUpdate，RendererObserver、RendererFrontend/Backend、Renderer::render / tryRenderParticleFastFrame。
+- 明确粒子 Tick、下一帧调度、Native Full 准备、GPU 粒子更新及 MapLibre Idle 的不同概念。检查 30 FPS 来自哪个实际 cadence，以及是否存在独立的 Placement 定时器强制 Full。
+- 输出**可核查调用图**，带文件路径、函数、行号及关键条件；区别“必然调用”“在特定配置调用”和“只是假设”。
+
+## 四、必须完成的源码分析 B：Fast Path 全条件审计
+
+检查 src/mln/renderer/particle_fast_path.hpp 的 evaluateParticleFastPath 与 renderer_impl.cpp 的 tryRenderParticleFastFrame：
+- Prepared RenderTree、Retained enabled、**所有 R 段** Cache valid、Build/Static Revision、Content Revision、Camera/Viewport、non-camera update signature、Style、Boundary/Topology/RangeConfig。
+- staticStable、Placement transition、pending changes、non-particle transition/repaint、fading tiles、ParticleNeedsRepaint、still image、MapMode、Debug、Continuous 支持层、scene support、annotation mutation。
+- **必须产生全 Gate 矩阵**：条件/来源函数与行号/通过条件/失败原因/是否被粒子 Tick 本身改变/是否在一次新 Full 后可能恢复/FZG1 已证实或未知。
+- 确认短路返回首个错误是否掩盖 unsupported-continuous-layer、unsupported-scene 等后续失败；不得因只看见 cache-invalid 就宣布其他条件已通过。
+- 比较 Full 与 Fast 路径的 CPU Prepare、RenderTree、GPU 绘制工作，避免将 Fast 解释成零 GPU render。
+
+## 五、必须完成的源码分析 C：R2 缓存 Build/Invalidate 状态机
+
+从图层结构到 GPU 缓存逐级核查：
+- render_segment.hpp 的 renderSegmentHasPlacementCapableLayer / renderSegmentPlacementGatePassed；隐藏 Symbol 是否同样触发结构级保护。
+- render_orchestrator.cpp 的 retainedRangeUsesPlacement / retainedRangeIsStable、Source/Tile/Glyph/Sprite/Annotation 的有效性及跨段 Collision 依赖。
+- renderer_impl.cpp 的 retainedPlacementStable 全局 Scene Gate、每段 segmentPlacementGatePassed、segmentSupported、Segment fingerprint/source revision、segmentFallbackReason、缓存 evaluate 与合成控制。
+- retained_underlay_cache.cpp 的 RetainedUnderlayCache::evaluate / invalidate / BuildPending / markBuildSucceeded / markBuildFailed / releaseResources；区分“首次未建立”“有效缓存因 Gate 被主动 invalidated”“底层资源损坏”“revision 变化”。
+- 以 FZG1 的 R2 Build=0、Reuse=0、Fallback/Invalidation≈1787 为约束，写出完整状态转换和所有可支持或反驳的来源；解释为什么 Full 的正常绘制不自动等于缓存离屏纹理 Build 成功。
+- 对 placementChanged=true 分清“发生 Placement 计算”与“R2 Symbol 最终可见性/位置/像素变化”。还须分析跨 Source/跨段 Collision、Fade、Shader opacity、Camera、异步资源所需安全边界。
+
+## 六、必须完成的源码分析 D：Placement 和 Fade 真正语义
+
+逐函数追踪 PlacementController::placementIsRecent / setPlacementStale / hasTransitions；Placement::getUpdatePeriod / commit / symbolFadeChange / hasTransitions；Style TransitionOptions；Symbol 在 OpenGL/Metal Shader 中如何消费 symbol_fade_change、opacity。
+
+**必须分别分析两种运行配置**：
+1. enablePlacementTransitions=true：默认 300ms 更新间隔、Symbol Bucket Added 可能导致 30ms override、Zoom 修正、Fade 从 0 到终态的数值变化、hasTransitions 与 setPlacementStale 的交互。
+2. enablePlacementTransitions=false：placementIsRecent() 为什么可能持续返回 false、Placement 是否每次 Full 都重算、symbolFadeChange 实际取值、为何末态可能为 true/0/false。
+
+针对 Gate **!placementChanged && symbolFadeChange == 0 && !placementTransitionActive**，逐行给出真值表与相应真实可达时刻：
+- Placement 刚计算后；
+- Placement 未重算但仍有淡入淡出；
+- Fade 完全结束后；
+- 关闭 Transitions；
+- Symbol Bucket 增减、跨段碰撞等变化；
+- Camera/Style/Source 不变、只有粒子的稳态。
+
+回答：在正常运行下是否存在可用于 Build 的安全窗口？如果不存在，是哪一条造成的？全局 Scene Gate 与每段 Placement Gate 是否构成第二重锁死？FZG1 末态数据不能被机械套进默认 300ms 时间表。**绝不通过直接删除 Gate 或仅更改 ==0 比较符来宣布安全修复。**
+
+## 七、必须完成的源码分析 E：反事实场景与因果闭环
+
+对下列情况分别输出逐帧状态推演与 Fast Gate 判定（明确“已证明/条件推断/需设备验证”）：
+
+- **S1 纯粒子稳态**：Camera 不动、所有 Source/Tile/Style/Glyph/Sprite ready 且不变、无外部 Full 指令、粒子 30 FPS。能否从第一次正常 Full 构建 R2 缓存并进入 Fast？何时会卡死？
+- **S2 粒子关闭**：没有粒子连续重绘，仅偶尔正常地图刷新。分析为何 Full CPU Frame 频率低，不能误判 Placement 从不执行。
+- **S3 真实 Host Source Mutation**：导航相关 Source/Annotation 更新与 Tile 异步输入同时存在，量化其对 Revision、Cache Build、Full Frame 的理论影响；不能假定所有变化都来自粒子。
+- **S4 不同布局**：原 RC/RCRR、实验 RCRR_PREFIX、理想保留图层顺序的 [0,13) R / [13,32) R / [32,33) C / [33,107) R / [107,113) R。检查 C 范围有普通 Symbol/Line 是否会触发 unsupported-continuous-layer；不能将最后一个仅为反事实的配置写成已实现。
+- **S5 动态安全回退**：相机缩放/旋转、Tile/Glyph/Sprite 完成加载、Opacity Fade、跨段 Collision、Style/Layer 改变时，哪些 R 必须重建，哪些状态不能盲目复用。
+
+务必清楚界定：“粒子导致下一帧”与“粒子本身让静态 R 内容变了”不等价；“需要 Full 准备”与“所有图层从零画一次”也不等价。
+
+## 八、方案对比与建议（仅提交提案）
+
+至少比较四类选项并给优先级：
+- **A 全 Gate 与 R2 状态诊断**：一帧内采集所有 Gate 状态，而不是仅返回第一个 Miss；记录 Placement 配置、计算原因、Fade 值、各 R 的 Build/Reuse/Fallback/Invalidate，控制 tracing CPU 开销。
+- **B Full Frame 后安全建立 Symbol R 缓存**：寻找 Placement、Opacity、GPU Shader、资源与 RenderTree 都满足安全条件的 Build 时机，打破可能的“永远无法首次 Build”自举问题。
+- **C 更细粒度 per-R 结果等价**：与 STEP-111 对照，是否有必要做 per-R Signature/Revision 或可采用更轻量的生命周期证据；跨段 Collision 不能被忽略。
+- **D 外部 Full 更新与 Particle Tick 分流**：用户要求外部明确 Full 指令到来即完整更新，不因数据相同去重/延迟；无外部指令时粒子优先 Fast，仍保留 Native 必要安全 Full 回退。核对目前内部/公共接口是否支持；涉及责任或公共语义必须由 Integration 正式协调，本任务不得私建 API。
+
+每项必须列：是否解决首次 Build、是否能解决全局 Scene Gate 和 C 段 Gate、数据正确性、GPU/CPU/内存代价、需改文件、风险、复杂度 1～5、Android OpenGL / iOS Metal 一致性、最小验证方案。
+
+**性能目标是 30 FPS 粒子与低频外部 Full 更新各司其职；2 Full + 28 Fast 是理想例子，不是当前 V23 已实现或零安全回退的承诺。** 不以降低粒子 FPS、删除海图 Symbol、移动一批普通静态 Layer 到 C、放宽 fail-closed 或忽略外部指令作为优化手段。
+
+## 九、本轮权限、限制与停止条件
+
+**仅执行全面只读调查**，允许阅读本仓库源码、历史 Git、已有 FZG1 数据、现有调研报告；允许写入本任务要求的调查文档、Step 记录、Codex 完成报告与对粒子开发记录的短条追加。不得修改 Native、Android/iOS、Shader、JS/TS、构建脚本、测试源码、Host/NavSea、Integration 契约、Style、Renderer Gate 或公共 API。
+
+不执行编译、链接、打包、设备操作、发布或新的性能测试。本轮如无法通过源码证实最终触发频率，必须给出下一阶段**最小诊断插桩提案**，记录字段、调用点、采样窗口、FZG1 验收场景与预期判断方法；不可未经授权直接实施插桩。严禁清理其他 dirty/untracked、变更上游、强推、改历史 Step。无法证明安全则维持 fail-closed。
+
+需要涉及跨项目职责/API 调整的提案，先输出 Interface Blocker，返回 Integration 决策。遇到重大事实冲突时报告并停止冲突部分，不得自行扩大修改范围。
+
+## 十、必做输出（调查完成时必须真实落盘）
+
+1. **主报告**：docs/20_调查/STEP-112_V23粒子FullRender循环与Symbol缓存准入全面源码调查_v1.md。必须包含：
+   - 完整粒子调度→Fast→Full 调用图、源码路径/函数/行号；
+   - Fast Path **全部 Gate** 对照矩阵（含短路掩盖条件）；
+   - R2 Cache 的首次 Build、Invalidate、Fallback 状态机与实际决策链；
+   - enablePlacementTransitions 开/关及 Fade 时间/数值状态表；
+   - 原始、PREFIX 和理想单粒子 C 的分段对照；
+   - S1～S5 反事实和证据强度；
+   - A～D 方案风险/成本/工程改动/优先级及推荐的下一步；
+   - 不同问题分别标注“**源码证明** / **FZG1 实测** / **条件推断** / **仍需设备验证**”。
+2. **阶段记录**：docs/50_Step记录/STEP-112_V23粒子FullRender与Symbol缓存调查_v1.md。写状态、目标、完成项、未完成、阻塞与下一步。
+3. **Codex 完成报告**：docs/报告/STEP-112_V23粒子FullRender与Symbol缓存调查_Codex完成报告_v1.md。逐项按“已完成 / 未完成 / 无法验证”报告，必须解释未完成原因；记录实际模型/推理档位、Git 起终 HEAD、branch、dirty、变更文件、检查结果、未做构建/运行的事实、Git/Push 实际结果。
+4. **粒子开发记录.md**：本阶段追加简短事实记录，不能更改历史。
+
+## 十一、验收与 Git 收尾
+
+只有 A～E 的关键问题有源码级证据、全部 Gate 有出处、root-cause 假设被验证或明确证伪、方案风险和最小验证路径充分时，才能写“源码调查 PASS”；**运行时未验证、Native 未修复、Fast Hit 未改善**必须明确列出，不能写实现/性能 PASS。没有决定性证据，结论应 PARTIAL，明确下一轮需要的最小运行时信息。
+
+本任务研究完成后，对**本任务范围的文档变更**进行 scoped Git 提交并 push 到 origin/particle/main，核对远端 HEAD；不得纳入现有未跟踪 STEP-110/STEP-111 任务书或无关修改。依 AGENTS.md 的 Codex→RDC 职责分工，Codex 交付调查结果，RDC/获授权操作方独立完成 Git/Push 与核验；Push 未确认不得冒称 Git 收尾完成。记录真实 commit hash、message、远端分支与 push 结果。禁止 force push、upstream push。
+
+**本任务结束条件：调研证据、报告与 Git 收尾；不得继续直接实施 Native 修复。**

docs/40_任务/STEP-113_FZG1_PBF_Layer与FastGate诊断_Codex任务_v1.md

@@ -0,0 +1,41 @@
+# STEP-113 — NavSea FZG1 PBF/Layer 等价测试 App 与逐帧 Fast Gate 诊断
+
+## 授权与范围
+用户明确授权：在 Particle Android 测试 App 接入与 NavSea 相同的正式 PBF 与图层分段，找到每帧阻止 Particle Fast Path 的所有 Gate；RDC 可以编译 APK、使用已连接 FZG1-2 的 ADB 测试。使用 Codex **GPT-6.1-Sol High** 实施源码，RDC 独立编译/设备验收。不得把调研中的假设冒充真机结果。
+
+## 项目与协作
+- Particle repo: /Users/tei/dev/MapLibreParticleLab, `particle/main`; NavSea **只读**: /Users/tei/dev/NavSea-Build。Integration **只读**: /Users/tei/dev/navsea-particle-integration；已 fetch 核实 Integration main 80667d6c。
+- 先完整阅读 Particle `AGENTS.md`、`PARTICLE_BASELINE.md`、`docs/00_项目规范/`、`docs/00_项目总则/README.md` 和其四份有效总则，以及 STEP-112 源码调查、上一步报告。
+- Native/Shared Core 仅增加诊断，Android Test App 增加测试 UI/场景。**禁止**改变现有 Fast Path Gate 准入逻辑、Placement/Fade、安全回退、公开 RN API、NavSea 源码、Cache 等价安全判定。Common Core 诊断数据不能含 Android 专有语义。
+- 仓库中两个已有未跟踪 STEP-110/111 任务 MD 必须原样保留，不得 add/reset/clean；禁止新分支或工作树。
+- Codex 不编译、不执行 Android Gradle/ADB、不执行 Jest（用户没有要求），不做正式发行、Git commit/push；由 RDC 负责这些步骤。
+
+## 目标 A：准确复制生产 Style、场景与真实 R/C 分层
+现有测试 App 已支持 `NAVSEA PBF`，使用生产 URL `https://pbf.jpcn.ccwu.cc/style/style.navsea-delivery-full-semantic-extentfix.json`，但仅有 **63** 个基础图层；它与 NavSea FZG1 实测 **113** 个最终渲染图层尚未等价。NavSea 源码 `src/config/builtinRuntimeUrlConfig.ts` 是 URL 事实源；`src/map/particle/RenderSegmentHost.tsx` 是宿主分段控制。STEP-112 用户 FZG1 的 RCRR_PREFIX 诊断：R0 [0,13), C1 [13,33), R2 [33,107), R3 [107,113)。注意 NavSea 当前源码 R/C 初始 plan 可能与运行诊断不一致，必须记录版本/选择器，不得当作同一事实。
+
+- 基于现有 `platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt`/fixture 增加独立 **STEP-113 FZG1-PBF Gate** 测试场景。真正加载生产 Style、Sprite、Glyph、VectorTile URI；原有场景全部保留，且不得改为假矢量地图。
+- 与 NavSea 对齐层顺序、类型、Source ID 和显隐规则：优先从 NavSea 实际源码、已有 FZG1 快照/资料得到完整清单，至少能证明原始63层一致；对于 RN 额外动态层，若没有真实 Source/图层定义，不得将同名假图层宣称为“同等画面”，应分别标注原样/结构仿真/缺失。严格实现全113层和所述四分段如能力允许；若其余层无法准确复制，仍完成可运行的 **真实 PBF 63 层模式 + 明示的部分等价模式**，并记录阻塞原因，不要卡死整个任务。
+- 每个场景导出/Logcat：实际 styleLayers (index/id/type/source/visibility)、总层数、每段 [begin,end)/类型与层名、分段配置接受/拒绝原因、当前 Style URL/版本/fingerprint、预报时间和 Particle Tick 状态；严格用实际 Layer ID 定义分段，不假定第13/33/107的 ID 永远不变。
+- 支持至少静态30fps粒子且 camera/forecast fixed、粒子关闭、Source 变化、场景对照。静态场景不可每500ms自行修改 Symbol；原 STEP-102 的动态 fixture 保持原样。
+
+## 目标 B：逐帧 24 Gate 完整诊断
+- 阅读 `src/mln/renderer/particle_fast_path.hpp` 的 `ParticleFastPathGateInput` (24 条固定顺序) 与 `src/mln/renderer/renderer_impl.cpp::tryRenderParticleFastFrame`；每次真实 Fast 尝试，记录统一 frame/sequence、所有 24 条 Gate 的 **PASS/FAIL** 或明确不可观测的 UNKNOWN，并保存首个实际短路 Gate 与同帧失败全集。不得通过二次调用有副作用的函数来获取字段；优先使用现成的已计算 `ParticleFastPathGateInput` 在单次调用无副作用完成独立掩码计算，并确保首错与 `evaluateParticleFastPath` 决定一致。
+- 对于 CacheInvalid 等早期阻断，也能看出后面的 `unsupported-continuous-layer` / `unsupported-scene` 是否同帧成立。记录 per-R cache state/build/reuse/invalidation/fallback, Placement changed/transition/fade、原因分类、FullFrame count。不要把 Full 绘制导致的 post frame Placement 数据冒充 pre-fast 原子时刻；必要时为 pre/post 两种 phase 分离记录。
+- 诊断必须为有界环形缓冲/低开销低频导出（例如保留最近120或256帧，另聚合失败计数），不得每 33ms 从 JS/Android UI Logcat 输出大 JSON。沿用已存在的 Android `getRenderSegmentDiagnostics` Native JSON 出口，新增 `fastGateTrace` 可选诊断字段，避免新 RN API/ABI；必要时增加手动/低频截图/Logcat 导出入口。控制每分钟几条摘要而非每帧 log。
+- 同一渲染生命周期 reset 要有清晰逻辑；不引入 data race，遵循现有 shared snapshot/atomic/锁语义，避免在 map UI 线程操作 Native mutable renderer state。
+
+## 目标 C：可验收性
+- Test App UI 能切换 STEP-113 场景、查看 Gate 首错/失败排名与各段状态；可用 Logcat 定向标签稳定抽取机器可读 JSON (包含 schema/version, style parity summary, frame window计数, gate-failure聚合, R状态摘要)。不要让 UI 实时多次 Native 查询产生额外帧，使用约2至5秒刷新。
+- 提供实际验证步骤（Mac PowerShell不要，macOS shell可用），基于标准 `tools/particle_android_validation/build_validation_apk.sh` 构建，确认设备 ABI 与脚本默认 ABI一致后交 RDC 运行。ADB 必须明确 `-s 192.168.200.139:5555`（这个设备本轮是 FZG1-2），不可无参数误操作其他设备。
+- 文字报告区分：SOURCE-PROVEN / TEST-APP-STRUCTURAL / DEVICE-MEASURED / NOT-VERIFIED。成功构建 APK 不表示真机性能验证通过。
+
+## 必做输出与收尾
+1. 所需 Shared Core / Android Test App 源码实现（尽量只局部变更）。
+2. `docs/50_Step记录/STEP-113_FZG1_PBF_Layer与FastGate诊断_v1.md`：实际状态、设备验收填写栏、剩余风险。
+3. `docs/报告/STEP-113_FZG1_PBF_Layer与FastGate诊断_Codex完成报告_v1.md`：改动文件列表、与 NavSea 样式/层等价度证据、24 Gate 定义、精确构建/ADB/场景命令、产物/日志预期、静态检查事实、未做项。
+4. `粒子开发记录.md` 中文末尾追加少量本次进展（append-only）。
+5. Codex 最终回报真实 model=GPT-6.1-Sol / high，以及剩余需要 RDC 独立验证事项。
+6. 文件变更仅 scoped；`git diff --check`，不提交不 push；避免 Jest 和 Native/Android 长时编译。任何公共跨项目 API 变更先停、写明需要 Integration RFC。
+
+## 优先次序
+优先先完成 **B 24Gate真正可靠同帧采集**，再实现已有 PBF Mode 的专项布局与 UI；不允许因为“113层不能精确复刻”就省略实际可交付的完整 Gate 诊断。

docs/40_任务/STEP-114_FastPath安全准入与TestApp闭环_Codex任务_v1.md

@@ -0,0 +1,41 @@
+# STEP-114：Fast Path 安全准入受控修复与 Test App 闭环（Codex 任务 v1）
+
+## 执行授权与基线
+- 用户明确同意继续受控修复，不要求完全复刻 NavSea 113 层。
+- Mac 仓库 /Users/tei/dev/MapLibreParticleLab，particle/main 起点 b02e54de3d45fcf612126ae8f037cba204f590ea。Integration 最新 main 80667d6c343411d03a760425438e3d292f452118 经 RDC 验证。
+- Codex 固定 GPT-6.1-Sol High (gpt-6.1-sol / high)。先读 AGENTS.md、PARTICLE_BASELINE.md、docs/00_项目规范、docs/00_项目总则/README.md 及四份有效总则、STEP-112/113 报告、Integration 的正式 Contracts/RFC/ADR，严格遵守项目边界。
+- 本轮 Codex 只改代码与文档；不能运行 Android Gradle、ADB、Jest、CMake/Ninja/Bazel 大编译或正式打包；Native 定向验证由 RDC 另行执行，Android 编译由用户在授权条件下手工统一验收。
+- 不碰原有两份未跟踪 STEP-110/111 文件、无关文件、NavSea 源码和 Integration；禁止 git add -A / reset --hard / clean；不得变更 RN/JS 公共 ABI/API、发行版本或 Source Lock。
+
+## 根因事实
+- STEP-113 STATIC_RC 66 Native layers，R[0,63) Build=0、unknown-dependency；C[63,66) 含天气色场、粒子、内部 Annotation Symbol。Fast=0。
+- 119 个最新 completed Full 帧：24 Gate shadow mismatch=0；#3 cache invalid、#4 revision mismatch、#22 unsupported continuous layer、#23 unsupported scene 全部失败；#12/#13 placement 105 帧失败。
+- RenderOrchestrator::retainedSegmentSourceState 对 CustomMVTVector 明确 fail-closed，已有源码注释说明无 retained cache revision contract；不得删掉这个限制来伪造 Fast。
+- continuousRangeSupportsParticleFastPath 要求 C 全层以 Particle dynamic API 标记；内部 Annotation Symbol 不满足，且 #23 聚合依赖部分与 #22 重合。
+- STEP-112 证明含结构性 Symbol 的 R 在旧 Placement stale/changed/fade 时可能根本无法进入首次 Cache Build；禁止只删条件或假设视觉没变。
+
+## 实施步骤（依次、受控）
+1. 做当前源码静态闭环：明确 Test App 对应 SourceType、Source/Tile/Style/Glyph/Image/Annotation mutation 追踪、R 的初建失败点、C 准入及 Scene 复合条件、Placement 控制流。
+2. R 缓存：只对确有完整 Source revision 与异步失效追踪的类型建立安全准入；若 CustomMVTVector 无法严格证明，保留其 fail-closed。优先为已支持的保守 source 子集提供可用的独立 R-cache 正向测试。保留 Source mutation、Tile update、camera、style reload、image/glyph、destroy/reset 的反向用例。
+3. C 非粒子层：只有证明原有 GPU 复合内容/Source revision/Placement/Annotation 在静止场景与 Full 等价、变化时 Full 回退，才能受限放行。否则不可移除 Gate #22：可通过单独 Test App 最小场景或安全 Layer 拓扑证明能进入 Fast。不要丢失原始正式 PBF 5 场景。
+4. Symbol R Placement：基于已提交的真实 Placement/资源 revision 与 transition/fade 审核是否有安全稳定窗口；如须新增独立结果签名或其他跨平台设计，停止该项并在报告中写 BLOCKED，不做危险简化。
+5. 优先实现独立 Test App FAST_SMOKE 场景（如安全可行），按 UI 菜单明确区分正式 PBF 与独立最小场景。使用 Native 真实 Full/Fast/CacheBuild/Reuse 计数和24 Gate JSON，测试稳定、Source mutation、Annotation、Pan/Zoom、Reload、前后台/Teardown；不许伪造 Frame 结果或直接注入 candidate=true。
+6. 所有公共 Shared Core 代码仍跨 Android/iOS 共用，不得建立平台分叉。任何需要改公共语义/API的部分暂停，留给 Integration RFC。
+
+## 测试/运行要求
+- 可改/新增现有非 Jest C++ 相关测试源，但 Codex 不执行测试/编译。
+- 必须写出 RDC 可以执行的精确定向 Mac Native 检查命令；后续 Android 编译和设备 Gate 集中一次进行。
+- 只证明能证明的部分；可产出 PARTIAL / BLOCKED 与可用局部修复，不允许“关掉Gate提升Fast数字”。
+
+## 必做输出
+1. 本次实际修改的 C++、Android Test App 和非 Jest 测试源（不能安全改的部分写明零修改）。
+2. docs/20_调查/STEP-114_FastPath安全准入与闭环判定_v1.md：R/C/Placement 证据、可能的反例、实现范围、安全前提、实际测试方案。
+3. docs/50_Step记录/STEP-114_FastPath安全准入与TestApp闭环_v1.md：当轮修改、状态、验证事实及后续步骤。
+4. docs/报告/STEP-114_FastPath安全准入与TestApp闭环_Codex完成报告_v1.md：模型全名档位、改动文件、影响/兼容、RDC 具体命令、已做/未做的验收、Git check。
+5. 追加中文 粒子开发记录.md：当前改动、当前状态、下一步。
+6. 新增 Test App 入口时更新相关场景说明，清楚区分真实 PBF 与独立 smoke。
+7. 文档必须实际写入并保留，不能任务后要求用户补交。
+
+## Git 收尾
+- Codex 只能执行无构建型静态检查与 git diff --check，回报 git status 和必要的验证命令；禁止将未运行的测试写成 PASS。
+- Codex 完成后先停下由 RDC 独立审计/运行定向检查；阶段结果达到合理门槛后由 RDC scoped commit 到 particle/main 并 push origin，核验远端 SHA。若未达真实 Fast，不得标示 Fast Path 已修复。正式发行独立处理。

docs/40_任务/STEP-116_STEP113原PBF_FastPath实际阻塞修复_Codex任务_v1.md

@@ -0,0 +1,26 @@
+# STEP-116：STEP-113 原 PBF Fast Path 实际阻塞修复
+
+## 授权、当前基线与配置
+用户要求继续修复，并以原 STEP-113 专用 Android APP 的 STATIC_RC 真正进入 Fast 为目标，而非 STEP-114 简化 FAST_SMOKE。当前仓库 Mac /Users/tei/dev/MapLibreParticleLab，particle/main HEAD e2d202b560ad0165101546597c43f2ef0ccf4542。Integration 已由RDC fetch 并核实 main 80667d6c343411d03a760425438e3d292f452118。仅内部 Shared Core 安全修复与 Android 专用 Test App；不改跨平台公开 API/ABI/协议，不改 NavSea、不发行。
+
+Codex 模型必须为 GPT-6.1-Sol High (gpt-6.1-sol / model_reasoning_effort=high)。先读根AGENTS.md、PARTICLE_BASELINE.md、docs/00_项目规范、当前 docs/00_项目总则 README及四份有效总则，读 STEP-112/113/114/115、Integration instructions/README/WORKFLOW/TEAM_MODEL/contracts/rfc/adr/status/compatibility，按事实和边界执行。Codex只编辑、静态检查、中文报告；不可执行Native/Gradle大编译、ADB、安装、Jest、发版、commit/push。Native独立审计由RDC；Android编译安装由用户手工集中一次完成。
+
+## 已确定的真正阻塞
+STEP-113 STATIC_RC：正式63个PBF基础层，Test App Native实际66层；R[0,63) Build0、Fast0、Source fallback unknown-dependency，C[63,66)中有自动添加的 org.maplibre.annotations.points Symbol，#22/#23持续失败。后续 STEP-114 源码/快照发现R依赖mapple、navsea_delivery和tide，Native source表实际没有tide，tide-spots Symbol层引用它；navsea_delivery实际是Vector，不是CustomMVT。即使R的missing-source得到解决，Symbol R首次cache Build仍被Placement的changed/stale/fade保护阻挡。不可把去掉一个Gate误写为全套修好。
+
+## 工作：真正解决而非假通
+1. 通过静态源码和保留的 STEP-113完整JSON逐环确认R缺源的原层及fallback、真正的 SourceType、source/Style变化导致的revision与GPU生命周期。
+2. R的缺失源：只有能证明缺失源永远贡献零像素，且后续Source创建/恢复/同名更新强制缓存失效/Full重新处理时，才允许把它作为有界的empty依赖；否则保留fail-closed并明确报告服务器正式Style存在缺源而无法安全缓存。不能偷偷创建假的tide Source或删除原始tide-spots层。
+3. C的内部Annotation Symbol：可以在专用 Test App 确认地图无任何Annotation实例时，参照 STEP-114 仅移除 SDK 自动创建的空内部 Annotation 层，保留原正式63层定义、Source/Layer顺序不变；必须有代码防止遗留Annotation/Style添加时漏内容，并在日志、manifest明确记录原STYLE层原样、仅内部辅助层调整。其他已有原场景继续原语义，不为了Fast删除SOURCE_CHANGE中的测试circle。未经证明不能改Core C准入逻辑。
+4. Symbol R初建：必须读PlacementController、onRender、commit/fade、renderSegmentPlacementGatePassed、retainedRangeIsStable和full-frame时的状态。真正放宽必须有结果等价的Placement/atlas/glyph/tile/style/source/camera/opacity证据，并在变更时立即invalid/full；不能仅凭stable多少毫秒、场景没有手动操作、tile加载完成来放行。若现有Core没有可核实的已提交GPU结果签名，禁止危险跨层重写，列为BLOCKED并说明需要的精确额外数据/设计。
+5. 要保留24Gate shadow mismatch=0与实际Cache Build/Reuse/Full/Fast原生计数。可添加同帧诊断或快速失败细项，便于用户一次Android build后通过原STATIC_RC脚本迅速定位仍失败的Gate。保留PBF63、PARTICLE_OFF、PARTIAL_RCRR、SOURCE_CHANGE五场景、STEP114独立Smoke和STEP102原场景；不要改变公网PBF Style或NavSea，也不要求精确113层。
+6. 增加与安全修复对应的非Jest C++源码测试，含缺源/源加入/async mutation、Annotation、Symbol R /全局变化/无变化、Style/Source/Tile/Glyph/Image以及Layer顺序/disable/reload；不要假造rendered Fast、不要把不运行测试记PASS。
+
+## 交付文件，全部本轮必须实际生成
+- 本轮实际源码和适当非Jest测试源码；修改Test App后更新必要README。
+- docs/20_调查/STEP-116_STEP113原PBF_FastPath阻塞安全修复审查_v1.md：每条阻塞证据/解决方案/风险/未解项。
+- docs/50_Step记录/STEP-116_STEP113原PBF_FastPath实际修复_v1.md：真实完成度及未运行项目。
+- docs/60_测试/STEP-116_STEP113原PBF专用APP验收_v1.md：严格按最新HEAD一次用户手工Android build/install→STEP115 preflight→原STEP113 STATIC_RC 75s以上→完整120帧/24Gate/源码/设备SHA/用户画面；失败后如何判断R/C/Symbol，不得依赖旧APK。
+- docs/报告/STEP-116_STEP113原PBF_FastPath实际修复_Codex完成报告_v1.md：实际模型全名档位、改动清单、公共API（必须不变）、逐项Implemented/Blocked/Not Run、Git/源码证据、RDC具体命令及用户构建/设备步骤。
+- 粒子开发记录.md追加中文结果与下一步；必要README与相关已有文档说明保持一致。
+- Codex运行git diff --check、静态核查；不运行Native编译、Android编译、Jest、ADB、安装、Git commit/push；本轮用户原有两个未跟踪STEP-110/111 MD一律保护。禁止git add -A/.、reset --hard、clean。完成后停止由RDC独立审计并scoped提交推送；若Fast尚未实测只能PARTIAL归档，不写Closed/PASS。

docs/40_任务/STEP-117_原PBF_R段首次Build与Fast安全准入_Codex任务_v1.md

@@ -0,0 +1,26 @@
+# STEP-117 原STEP-113 PBF的R缓存首次Build与Fast安全准入
+
+## 用户目标、代码基线和约束
+2026-10-11 用户要求继续 STEP-116 实机之后的实际修复：原专用Android Test App STEP-113 STATIC_RC，保留所有正式PBF 63基础层，不代换成STEP114简化FAST_SMOKE。真正验收须Native Cache Build>0、Reuse>0、FastDelta>0，同时画面正确、24Gate mismatch=0、异步更新fail-closed。若现有证据不能安全准入，必须保留真实阻塞并如实标 PARTIAL/BLOCKED，禁止伪造Fast或PASS。
+
+Mac repo /Users/tei/dev/MapLibreParticleLab 当前particle/main起点43e5f5b91598b9c3d3f1c788052d4bbd2d616668。Integration /Users/tei/dev/navsea-particle-integration origin/main同步至80667d6c343411d03a760425438e3d292f452118。模型固定 GPT-6.1-Sol High (gpt-6.1-sol, model_reasoning_effort=high)，不得升级。先读AGENTS、PARTICLE_BASELINE、docs/00_项目规范、docs/00_项目总则README与全部4份当前总则、Integration instructions/README/WORKFLOW/TEAM_MODEL和contracts/rfc/adr/status/compatibility。阅读STEP112-116全部关键任务记录和实际源码。Shared Core代码仍同时服务Android/iOS，本次限平台中性的内实现与Test App诊断，不改跨平台公开API/ABI/RN/JNI合同、不改NavSea/iOS/外部PBF服务器。若改动需要新公共contract或跨项目决定必须停止该部分，并在报告中指出应由Integration协调RFC/ADR，不自行做新平台业务语义。
+
+## 已测事实，一定先读取实机JSON和报告
+docs/60_测试/STEP-116_FZG1_原PBF实机验收结果_20261011.md。原完整JSON：artifacts/maplibre-particle/android-validation/step113-retest-20261011_121308/static_rc/native-full.json，SHA=cd491d2acca97119f1d4f2d6f77eb7b229c17b90d4be1181a59202308429b219。
+
+STEP116新APK源码c48a72a9，设备192.168.200.139:5555：原STATIC_RC已65层，原正式63层保留，C[63,65)仅WeatherColor与RasterParticle，#22最近120帧失败0。R[0,63)缺Source=tide，原style tide-spots Symbol引用tide；真实sources只有mapple:raster、navsea_delivery:vector、org.maplibre.annotations、rn-weather-fields。R Cache Build0 Reuse0、fallback=missing-source、placementGatePassed=false；24Gate最近120帧 #3/#4/#23失败120、#12/#13失败105、mismatch0，119Full/0Fast/1pending。90秒FastDelta=0、FullDelta=920。STEP116修好的空SDK Annotation条件和原63层定义不许回退。
+
+## 必做实现/根因研究
+1. 读 Style/Source creation、RenderOrchestrator::createRenderTree及LayerRenderItem、RenderLayer group disable/activate/processChanges、ResourceManager、sourceDiff、retainedSegmentSourceState、RenderSegmentRevisionBook、contentFingerprint、GPU提交。缺tide只可在具有可检查的零实际GPU绘制/无旧Renderable数据且同名Source添加/重建时完整Full+invalidate证书时作为缓存零贡献依赖；不得补假tide、删tide-spots、通过忽略revision/ready来放宽。无法证明则保持missing-source fail-closed，报告具体证据。
+2. 读PlacementController::setPlacement/placementIsRecent/hasTransitions、Placement::placeLayers/commit/fade/opacities、RenderSymbolLayer/SymbolBucket::updateVertices、RenderTree::prepare、Renderer::render Full与Cache Build及particleFast path判定。当前全帧重算时placementChanged=true、不重算时stale=true，fade不断非零；使首Build一直0。若能建立与成功提交的GPU Drawn R精确等价的结果证书，才受控放宽首次缓存，包括crossTile collision/placement、glyph/image/atlas、dynamic opacity、tile/source/layout revision、projection/camera/viewport、GPU context、异步ChangeRequests；任何变更必须Full/rebuild。不能将任何placementChanged、symbolFadeChange或controllerTransition强制false或删除24Gate。若需跨层较大重写无法保证安全则保留Gate报告BLOCKED。
+3. 原STEP113的正式63基础层完全保留，C空Annotation受控修复保留；旧五场景及SOURCE_CHANGE的负例保留。必要最少的Native诊断/Android测试入口增强可以做，但不可改变真实Fast计数/24Gate判定或把FAST_SMOKE当PASS。
+4. 以一次未来Android用户授权的RDC标准完整build/install测试为目标批量实现可证明安全的改动；提供非Jest C++测试源码，覆盖缺源零绘制/新增同名Source后失效、Symbol placement/symbol fade、异步glyph/tile/style/annotation/camera/context改变时fallback。不能将没有运行的测试标PASS。Codex不要运行大编译/Gradle/ADB/CMake/Ninja/Bazel/Jest、安装、commit/push，由RDC独立执行。
+
+## 必做中文交付文件
+- 真正实施的源文件、非Jest测试源码；必要Test App README更新。
+- docs/20_调查/STEP-117_PBF_R首次缓存Build安全证据_v1.md：真实源码/原设备JSON，GPU生命周期与Source缺失和Symbol placement安全边界、各项状态、设计/反例。
+- docs/50_Step记录/STEP-117_原PBF_Fast缓存准入_v1.md：改变、阶段验收、未执行与下一步。
+- docs/60_测试/STEP-117_FZG1_原PBF真实Fast验收计划_v1.md：严格原STEP113 STATIC_RC >=90秒、新APK源码SHA/设备SHA、Cache Build/Reuse/Fast及120帧24Gate、原63层与C、Source/Style/CAMERA mutation和用户画面、失败停止。
+- docs/报告/STEP-117_原PBF_Fast缓存准入_Codex完成报告_v1.md：模型全名档位、源码文件/公共ABI不变、证据、静态检查、当前BLOCKED和RDC实际测试步骤，commit/hash留RDC回填。
+- 粒子开发记录.md 末尾中文追加，必要README/说明文档修正。
+- git diff --check、静态API一致性与中文交付核查。禁止git add -A/git add ./git reset --hard/git clean，不触碰用户两份保护未跟踪文件 docs/40_任务/STEP-110_...和STEP-111_...，保留原Git忽略设备JSON。未经RDC工具真实返回，不得自称Native/Android PASS。最后停止交RDC进行独立代码审计、scoped commit/push/remote verification及一次集中Android build/installation/test。

docs/40_任务/STEP-119_Symbol稳定结果证书与R首次Build_Fast准入_Codex任务_v1.md

@@ -0,0 +1,33 @@
+# STEP-119 Symbol稳定结果证书与R首次Build/Fast安全准入
+
+日期2026-10-11。用户批准立即继续实施上一轮讨论的Shared Core方案，不是只读调查。
+项目 /Users/tei/dev/MapLibreParticleLab，particle/main基线869930046b11dbeb3b147e3be952a2e847316292；Integration /Users/tei/dev/navsea-particle-integration已同步origin/main=80667d6c343411d03a760425438e3d292f452118。实际Codex须GPT-6.1-Sol High（gpt-6.1-sol，model_reasoning_effort=high）。
+Codex负责开发、定向非Jest测试源码、中文文档，不执行Gradle/ADB/Native大编译/Bazel/Jest/commit/push。RDC独立核验、限定Git收尾并按用户授权集中执行一次APK build、install和真实设备验证。
+
+## 优先读取
+根AGENTS.md、PARTICLE_BASELINE.md、docs/00_项目规范、docs/00_项目总则README和4份当前总则；Integration的instructions/PARTICLE_PROJECT_INSTRUCTIONS.md、README.md、WORKFLOW.md、coordination/TEAM_MODEL.md、contracts/、rfc/、adr/、status/、compatibility/。STEP117根因调查 docs/20_调查/STEP-117_PBF_R首次缓存Build安全证据_v1.md 与STEP118真机报告 docs/60_测试/STEP-118_潮汐清理新APK设备实测结果_20261011.md及STEP112-116关键报告。必须逐段核对src/mln/text/placement.cpp、render_orchestrator.cpp、renderer_impl.cpp、render_tree.cpp、retained_underlay_cache.cpp、include/mln/renderer/render_segment.hpp、RenderSymbolLayer/SymbolBucket/atlas/shader、24FastGate/RevisionBook及现有测试。
+
+## 已证实
+STEP118原生产63基础PBF图层测试副本只排除一条失效tide-spots（用户允许），保留其它62基础层、天气2层=Native64；R[0,62)、C[62,64)，missingSourceIds=[]、R fallback=static-placement、R Cache Build0/Reuse0；90.008s FastDelta0 FullDelta942；PlacementGatePassed=false，24Gate mismatch0。当前源码perSegment Gate对Symbol要求 !placementChanged && symbolFadeChange==0 && !placementTransitionActive；Full新排布置changed=true，recent复用设stale->hasTransitions=true，而Fade完全稳定时通常>=1而非0。独立global retainedPlacementStable/retainedStaticStable/retainedSupported/particlePreparedSceneSupported又阻断。首次Build与Fast复用需要分开。
+旧设备真实证据在Git忽略artifacts/maplibre-particle/android-validation/step113-retest-20261011_140448/static_rc_no_tide/result.json和screen.png。新测试APK源commit=3051196054c7b69815c298040dae61d26499d9f2、SHA=44afcfabe0cf4f1ec93f35899241bd73093aa6db4b5cb82ca2120dd531b8f3e9。现HEAD较新只包含报告。
+
+## 本次必须优先真正实施的内容
+1. 在平台无关的Shared Core内部区分Placement计算调用与最终Renderable Symbol结果变化，建立可检验稳定状态、revisions/epoch/证书。不能用单一布尔值代替真正GPU输入一致性，不能把placed结果布尔不变当成vertices/opacity/atlas全部一致。保留跨瓦片collision、text/icon、variable anchors/方向、fade、glyph/icon/atlas、shader uniform/tweaker及绘制层序语义。必须检查GL和Metal两侧shader的symbolFadeChange clamp行为。普通Full应完成placement、updateBuckets/vertices、processChanges、tweakers/uploads，才决定可安全建立R缓存（同次或下一帧）。Build/reuse需要匹配版本，任何可影响像素的异步状态立即invalid并走Full。
+2. 解决Placement::placementIsRecent / setPlacementStale / hasTransitions语义和symbolFadeChange的>=1状态对首次Build的逻辑死锁。重新计算 != 真正GPU结果变化；stale不是强制正在fade。fade未完成仍必须阻断，所有真实动态Symbol/tiles/glyphs/Source/style/camera/viewport/pixelRatio/context/Annotation更新都fail-closed。不得简单常置false或单改renderSegmentPlacementGatePassed、删除24Gate、修改计数或强行把其它Symbol放进C。
+3. 必须同时审查并修复global/perSegment稳定性、revision/state跟踪和preparedSceneSupported，让首次R在安全的Full后建立Build，Reuse后才能Fast。缺失证明的Symbol子类严格拒绝，不能用概括性稳定状态假设可缓存。尽可能真正做到原62基础层静止时Build>0、Reuse>0、FastDelta>0；若架构上无法证明，明示BLOCKED，安全停止危险路径，但应尽量完成有证明的实现。
+4. 非Jest C++定向测试（已登记test/renderer文件），覆盖真实PlacementController生命周期、fresh->settled->build->reuse、fade过程拒绝、相机/缩放/旋转、纹理字形异步、新Source/style、Annotation、Context、tile/wrap/crossTile collisions、跨段LayerGroup安全重建；不能把无GPU predicate当真正GPU等价。
+5. 不改RN/JNI/ObjC/Java/Kotlin公共API与ABI、正式PBF/Source/MapLibre外部URL或NavSea/iOS业务、不变更Core-owned timeline/playback、不能改天气层语义。跨项目公共接口新语义须Integration RFC/ADR授权，必要则只报告并保留旧合同。
+6. 保持原STEP113 63 PBF和新STEP118 STATIC_RC_NO_TIDE派生测试、原24Gate、现有真实version/SHA的严格核对。不能新增虚构tide数据。
+7. 不触碰用户两个未跟踪 docs/40_任务/STEP-110_...与STEP-111_...，不git add . / add -A / reset --hard / clean；不修改Git忽略旧真机证据。Codex不运行Gradle/ADB/Jest/Native大编译、也不commit/push，最后交RDC。
+
+## 必做中文输出文件（缺一不得完成）
+- 实际Core实现+必要非Jest C++测试源码及直接相关诊断/README改动。
+- docs/20_调查/STEP-119_Symbol结果证书与R缓存Build实现依据_v1.md：真实渲染生命周期、核心不变量、结果证书如何绑定真实GPU绘制、反例、风险。
+- docs/50_Step记录/STEP-119_Symbol缓存实际实现_v1.md：状态、变更、验证、下一步。
+- docs/60_测试/STEP-119_原PBF_FAST实机联合验收计划_v1.md：一次build/install，新STATIC_RC_NO_TIDE >=90秒真实Build/Reuse/Fast+24Gate mismatch0，原63负对照及source/style/camera/glyph/annotation/context负例，视觉核验与fail closed。
+- docs/报告/STEP-119_Symbol缓存_Codex完成报告_v1.md：真实模型档位、文件、已实施/未实施、清楚BLOCKED或IMPLEMENTED_WAITING_ANDROID、静态检查、RDC命令、git commit由RDC负责。
+- 粒子开发记录.md在末尾中文追加。
+Codex只跑轻量静态范围和git diff --check；不可宣称Native/Android/iOS/用户视觉PASS。
+
+## RDC严格实机目标
+有实质Shared Core行为修改且独立审计通过后，Mac标准 ./tools/particle_android_validation/build_validation_apk.sh 一次Android OpenGL x86_64 APK；设备FZG1-2 ADB serial 192.168.200.139:5555且全部命令显式-s；运行 python3 -B tools/particle_android_validation/verify_step113_fast_path.py --scenario STATIC_RC_NO_TIDE --seconds 90。必须真实R Build>0、Reuse>0、FastDelta>0、Symbol画面/24Gate一致、更新时缓存失效与Full正确。失败最多5轮当前步骤修复，不能跳过并声称通过。无行为改动则不重编毫无意义APK。

docs/50_Step记录/STEP-104_官方Native13.6.1升级阶段A_v1.md

@@ -0,0 +1,28 @@
+# STEP-104 官方 Native 13.6.1 升级阶段 A
+
+- 状态：进行中。
+- 当前基线：官方 Android Native `c7506d6aff3800e946f89e1a51432fc22d1a6534`；自研旧版本 .21 `630ec657687bad4200c059bbccbb950d9c6f7ce9`。
+- 目标：把现有 Particle、WeatherColor、RasterArray、RenderSegment/Retained 与 Android Native 接口移植到官方 13.6.1，保持原语义；形成能进行精确编译验证的候选代码。
+- 必做：合并/冲突、代码边界适配、append-only `recoder_step.md`、多提交、完成报告、RDC 静态及精确编译。
+- 允许：本分支 Core/Android Native/构建配置/必要测试/记录。
+- 禁止：NavSea、其他 worktree、主线和正式发行、未经协调的公共合同变化。
+- 构建与测试：暂未运行；由 RDC 独立执行，不因任务书生成而记 PASS。
+- 本轮输出：`docs/40_任务/STEP-104_官方Native13.6.1升级阶段A_Codex任务_v1.md`、`docs/报告/STEP-104_官方Native13.6.1升级阶段A_Codex完成报告_v1.md`、`recoder_step.md`、阶段代码 Git checkpoints。
+- 当前结果：Gate 0 官方第一父基线检出；自研合并未开始。
+- 阻塞：尚无；旧/新版差异已在 UPSTREAM-001 审计，需逐项移植。
+- 下一步：Codex 迁移，RDC 独立编译，失败反馈给 Codex；未获得真实编译/设备结果不得宣称发布成功。
+
+## Gate 1 实际进展（2026-10-09）
+
+- 官方为第一父的 Git merge commit：`f8378fd7113c4d230500f0b82902d2356907f4a9`。
+- 76 个冲突路径已处理、没有未合并 index 条目；RDC 已检查 Git history 和 Native 代码空白格式。
+- 与旧发布的 Particle/QBIN/RenderSegment 功能是否能够完整编译、正确渲染仍未验证。本任务目标保持进行中；下一 Gate 为 Android Native 精确编译。
+- 本检查点只能称为 `SOURCE_MERGED / BUILD_NOT_RUN`，不是 Android/iOS SDK PASS。
+
+## Gate 2 / 2026-10-09 / RDC Native 编译实际结果
+
+- 结果：Android x86_64 OpenGL Native **PASS**（Gradle `BUILD SUCCESSFUL in 22m 24s`；进程退出码 0），编译提交 `a4b5f4eaa0eccb734e00d67adb5e750bba320404`。
+- 产物：`MapLibreAndroid/build/intermediates/cmake/openglDebug/obj/x86_64/libmaplibre.so`，`377246848` bytes，SHA-256 `ff5a5eb45f84ff633a87fe385fb04ee39ba63ed3bc486003408e02cea78c8907`。
+- 已排除的构建阻塞：新 worktree 的 cheap-ruler-cpp、tile-spec/earcut、supercluster LICENSE 依赖检出缺失；按 Git 固定提交恢复，无需修改产品源码。
+- 未完成项：其余 ABI、Android 安装/真机 GPU、Vulkan、RN 11.5.0、iOS Metal、发布均 NOT RUN；STEP-104 为 **PARTIAL**（阶段 A Native 编译 Gate 通过，产品发行 Gate 未开始）。
+- 下一步：Android 多 ABI + 真实 GPU/Style/RenderSegment 功能验收，再进入 RN 11.5.0 公共桥接联调。

docs/50_Step记录/STEP-105_FZG1-2_MapLibre13.6.1打包安装记录_v1.md

@@ -0,0 +1,11 @@
+# STEP-105 FZG1-2 MapLibre Native 13.6.1 Validation APK 安装记录
+
+- 日期：2026-10-09（JST）
+- 代码来源：官方 Native Android 13.6.1 + Particle .21 迁移候选，分支 `upgrade/android-native-13.6.1-20261009`，构建源提交 `30d0e6665e`。
+- 构建与目标：Mac，`MapLibreAndroidTestApp`、OpenGL Debug、Native x86_64，Gradle 6m48s 初次完成；因 Sentry 辅助库多 ABI 被旧检查规则拒绝；修订验证规则后增量 Gradle 10s，ZIP/ABI/体积检查 PASS。
+- 脚本修改：`tools/particle_android_validation/build_validation_apk.sh` 仅允许非目标 ABI 中已确认的 Sentry 库；`libmaplibre.so` 与 Custom Layer 必须仍为 x86_64；独立提交 `73db0356ac5860366f314ddba23b716220e7c16a`。
+- APK：`artifacts/maplibre-particle/step105-native1361-fzg/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk`，66,505,502 字节，SHA-256 `77bc0b238fb476494410a603443030b104d78f97a737307be52460bf5a68f5aa`。
+- 设备：FZG1-2 / Android 13 / ADB `192.168.200.139:5555`。覆盖安装 `adb install -r` **Success**；设备实际版本 `13.6.1`，签名一致、首次安装日期不变，设备文件 SHA 与 Mac 完全一致。
+- NavSea 仍为前台 App，未主动启动测试 App；运行、GPU 绘制、RenderSegment 等仍 **NOT RUN**，不可写成已通过。
+- 回退：旧版 13.4.1-particle.21 APK 已独立保存于忽略目录 `artifacts/.../rollback/`，未纳入 Git。
+- Gate：本阶段 **APK_BUILD_AND_INSTALL_PASS**；下一阶段是 FZG 可视运行及完整功能回归。

docs/50_Step记录/STEP-105_FZG1-2_MapLibre13.6.1运行验收记录_v1.md

@@ -0,0 +1,13 @@
+# STEP-105 / FZG1-2 MapLibre Native 13.6.1 实机运行记录 v1
+
+- 日期：2026-10-09 JST。
+- 设备：FZG1-2 Android 13 x86_64，ADB 192.168.200.139:5555。源码：upgrade/android-native-13.6.1-20261009 / c30add4d335c5c02aadac5756c1606b5bc497269。
+- PASS：粒子页面启动和用户观察、Cache 开关、Pan/双击 Zoom 后存活与缓存边界失效、STEP-101 单次重建、STEP-101 流式 Logcat 20 次 Native reset 完整配对、STEP-099 R-C-R 底层复用、QBIN V4 Golden 时间控制六项、STEP-102 T1 Symbol 安全回退、默认界面恢复。
+- STEP-101 T2 证据：20 请求、20 Native reset enter/complete、40 Renderer reset enter/complete、21 ready、crash buffer 0；最初的环形缓冲被覆盖测试不计正式 PASS。
+- STEP-099 T4：动态 GeoJSON 71 次更新，R0 buildDelta=0、reuseDelta=3677、invalidationDelta=0。
+- STEP-102 T1：R0 buildDelta=0、reuseDelta=3683、invalidationDelta=0；R1 包含 Symbol，gate=false、Live/Fallback，符合预期。
+- FAIL：STEP-102 T2_TWO_FREE 的 R1 持续 placementCapable=true、gate=false、Live/Fallback，reuse=0、invalidation 增加 3682；按 fixture R1 为 Fill，理应支持 retained；R0 reuseDelta=3682、buildDelta=0、invalidationDelta=0。无 crash，不证明错绘或确定回归起点。
+- 疑点：运行时注入的 Annotation Symbol、真实 Style Layer Index 或 Segment 范围；应先提取完整诊断和旧 .21 对照，保留 fail-closed，不直接改 Core 公共语义。
+- 证据目录（不提交 Git）：artifacts/maplibre-particle/step105-fzg-runtime-20261009/。截图、UI XML、Logcat、crash buffer 齐备。
+- 恢复：ADB 冷启动默认粒子页 GLOBAL/ACTIVE/EAST/MIX0%/256，当前 FZG 前台 Test App 13.6.1，Crash Buffer 0。
+- 状态：PARTIAL / T2 EXPECTATION FAIL。未编译、未执行 Jest、未更改源码或 NavSea，下一 Gate 是 T2 定向调查修正后回归。

docs/50_Step记录/STEP-106_STEP102_T2_Placement边界修正_v1.md

@@ -0,0 +1,48 @@
+# STEP-106 STEP-102 T2 自动 Annotation 层边界修正记录 v1
+
+日期：2026-10-09（JST）
+
+**状态：SOURCE_FIXED / STATIC_PASS / ANDROID_BUILD_NOT_RUN / DEVICE_RETEST_NOT_RUN**
+
+## 事实
+
+- 旧版 13.4.1-particle.21 在 FZG 同样复现 T2 R1 placementCapable=true/gate=false/live/static-placement/reuse0，已保存同场景旧版日志。新版 13.6.1 在比较结束后成功恢复，设备 APK SHA 正确。
+- 两版 AnnotationManager 会自动在 Style 末尾插入 Symbol Layer org.maplibre.annotations.points。T2 测试 Fixture 的上层自身为 Fill，但原 R-C-R Plan 的 R1 从 step102-upper 延续至最后一层，把该内部 Symbol 也算进去。
+- 不允许修改或跳过 Shared Core/Renderer Placement 安全 Gate。此次只改两个 Android Test App Kotlin 文件；新增 C2 live 尾部区段，单独承载 MapLibre Annotation Symbol，从而使 T2 的 R1 仅含 Fill；T1 R1 仍含自身 Symbol。
+- 为 tick8 新增 STEP102_STYLE_LAYER_LAYOUT 日志，供下次实际 APK 验证真实 Style Layer 顺序、分段边界。
+- 代码 Git 提交：86906c8a6af474a8d064c6f6d7d431e2a7e3efe6；静态检查 PASS，没有执行 Gradle、ADB 修正版验证、Jest。
+
+## 需用户手工编译
+
+在 Mac 终端：
+
+```bash
+cd /Users/tei/dev/MapLibreParticleLab-upgrade-android-1361
+export JAVA_HOME=/usr/local/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home
+export ANDROID_HOME=/Users/tei/Library/Android/sdk
+export ANDROID_SDK_ROOT="$ANDROID_HOME"
+export PATH="$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$PATH"
+export MAPLIBRE_VALIDATION_OUT_DIR="$PWD/artifacts/maplibre-particle/step106-t2-fix"
+./tools/particle_android_validation/build_validation_apk.sh
+```
+
+脚本内部使用 Gradle `--console=plain`。请保留 BUILD SUCCESS 和 build-info.txt，APK 生成后再由 RDC 安装到 FZG。不得把目前设备上的 13.6.1 旧 APK 当成包含本修复的版本。
+
+## 复测门槛
+
+- APK 完整性、包名、版本、Native x86_64、哈希校验；签名不符禁止卸载重装。
+- 新版 STEP102_STYLE_LAYER_LAYOUT 必须显示自动 Annotation Symbol 在最后的独立 Continuous C2；Plan valid、segments=4。
+- T1_FREE_SYMBOL：R0 continued Composite/Reuse、R1 placementCapable=true 且需要时 Live、C2 包含 Annotation；不崩溃。
+- T2_TWO_FREE：R0 和 R1 均 placementCapable=false、gate=true、actualExecution=composite；tick8→130 的 buildDelta=0、invalidationDelta=0、reuseDelta>0；C2 Live；不崩溃。
+- 复测 STEP-099 T4 R-C-R R0 locality，STEP-101 单次/20次 Native Reset（日志须持续采集），V4 Golden 最小烟测。保留失败路径及原始日志。
+- 修正作用域限定 Test App 分段验证，不等同生产快帧性能达标。若仍 fallback，应保留 Placement fail-closed，重新诊断而非强制 PASS。
+
+## 2026-10-09 手工边界获用户明确授权后的 RDC 编译与 FZG 闭环
+
+- 本轮用户明确要求“你编译和验证吧”。在 Mac 执行 Android Test App Gradle，源码 HEAD 23f7b8a4d7、干净；Gradle/Validation PASS。新版 APK SHA256=0ef3b033cd33139db07258745e9cd9d023170ce69767e3f8a5159821776ec9ef，66,505,495 字节，x86_64 MapLibre Native。
+- FZG1-2 签名检查一致，adb install -r Success；设备 base.apk SHA 与 Mac 相同、versionName=13.6.1。
+- T1_FREE_SYMBOL（两窗口）：Style 实际 5 层/4 段；R0 reuseΔ+3682、buildΔ0、invalidΔ0；R1 Symbol 继续保守 live/static-placement，PASS。
+- T2_TWO_FREE（两窗口）：R0、R1 均 placementCapable=false/gate=true/composite；两段各 reuseΔ+3683、buildΔ0、invalidΔ0；尾部 Annotation Symbol C2 live，PASS，原 T2 阻塞正式解除。
+- STEP099 T4：R0 reuseΔ+3675、build/invalidΔ0，PASS。STEP101 T1：1 个 nativeReset 完成，PASS；T2：20 Native reset 完整配对、21 ready、40 Render reset enter/complete，PASS。
+- QBIN V4 Golden t0/t1 插入、Runtime V4 READY 最小烟测 PASS。Crash Buffer 均无故障记录。FZG 已恢复默认 GLOBAL/ACTIVE/EAST/MIX0%/256，修正版 APK 哈希再次核对一致。
+- 状态更新：**STEP-106 CLOSED/PASS（FZG Android x86_64/OpenGL 定向问题及回归）**。不代表 ARM64、RN、iOS、Vulkan、全链发行通过。原始日志保存在 Git 忽略的 artifacts/maplibre-particle/step106-t2-fix/。

docs/50_Step记录/STEP-107_iOS_StyleCoreOnlyPeer集合修复_v1.md

@@ -0,0 +1,48 @@
+# STEP-107 iOS Style CoreOnly Peer 集合一致性修复 v1
+
+- 日期：2026-10-09（JST）
+- 状态：**进行中 / iOS Native 构建 PASS / XCTest 与 iPad 实机回归未执行**
+- 机器：Mac.lan；源码：`/Users/tei/dev/MapLibreParticleLab`；分支：`particle/main`
+- 开工 HEAD：`24105b1be7a2c8bd3a547117a30887fbaa0a308b`
+- 对应调查：`docs/20_调查/iOS地图点击重叠Source触发MLNStyle空Peer崩溃调查_v1.md`
+- 涉及的已正式发行基线：`maplibre-particle/rn/13.6.1-particle.22`（不修改原 Tag / Source Lock）。
+
+## 目标与边界
+
+消除 Darwin `MLNStyle.layers` 因 CoreOnly Layer 没有 ObjC Peer 而插入 nil 引发的 NSInvalidArgumentException；统一 `layers`、KVC 数量/索引/区间访问与增删位置语义，保持 C++ 原始 Style 的 CoreOnly 渲染能力以及可点击 ObjC 层的可见 Z-order。
+
+只允许修复 Darwin `MLNStyle.mm`、对应 iOS XCTest、Step 与报告；不得修改 NavSea、RN 11.5.0 依赖、Android、Shared Core、粒子 Shader/Renderer、V22 已发布内容或已有工作树。不得新建 worktree，禁用 Jest；不把编译通过等同 iPad 修复验收。
+
+## 本轮实施
+
+- [x] 检查实际 Native `MLNStyle.layers` 中未判空的 `addObject:`，及 `LayerManagerDarwin::createPeer` 对 CoreOnly 类型返回空的现状。
+- [x] getter 仅暴露有效 ObjC Peer，跳过无 Peer CoreOnly Layer；DEBUG 日志包含不可桥接 Layer ID/类型，以便后续现场确认触发者。
+- [x] `countOfLayers`、`objectInLayersAtIndex:`、`getLayers:range:` 统一使用 ObjC 可见集；修正原区间 getter 的反向遍历顺序。
+- [x] ObjC 可见索引用于 `insertObject:inLayersAtIndex:`、`removeObjectFromLayersAtIndex:`；`insertLayer:aboveLayer:` 使用下一个可见 sibling，防止隐藏 CoreOnly 层造成 nil。
+- [x] 补充 `MLNStyleTests.mm` 定向 XCTest，构造 Native-only Layer 与普通 Layer 混合、索引/顺序/增删场景。
+- [x] `git diff --check` PASS。
+- [x] RDC 在 Mac 执行 `bazel build //platform/ios:MapLibre.dynamic --color=no --curses=no --show_progress_rate_limit=15`，exit 0，Build completed successfully（982.084 秒）。
+- [x] XCFramework ZIP 存在、`unzip -tqq` PASS，SHA-256：`f16b7f2be761a101bb4b906b900175b95412abfeef09d715e2c9321b300a7b8a`。
+- [ ] 运行新增 `MLNStyleTests` XCTest，包括 KVC 索引与 CoreOnly 层回归。
+- [ ] 使用实际 iPad 和此修复构建的 Native 验证「唐津ヨット ハーバ」直接点击、多 Source 重叠、十字光标、天气开关及粒子渲染。
+- [ ] 从真实日志确认当次缺失 Peer 的具体 Layer ID/type；若原因超出 CoreOnly 假设，应补充分析。
+- [ ] 如进入正式发行，按 GSRL 创建**新版本**、独立构建与 Source Lock，并做公网校验；不得改写 V22。
+
+## 事实与遗留
+
+新增 XCTest 源码已编写，但本轮 Bazel XCFramework 构建目标不包含 Darwin XCTest，故不能声称测试 PASS；实际 iPad 未测试。编译日志路径：`/tmp/maplibre_v22_ios_style_fix_bazel_20261009.log`。编译警告仅见无效搜索路径 `/opt/homebrew/lib`，不影响构建。构建产物为未发行验证 ZIP，不是 V22 原版或正式新版本。
+
+原本就存在的 `vendor/expected-lite` 子模块本地状态与两份未跟踪文档必须保持原状。
+
+## 下一步
+
+由 Particle-iOS 在 Mac 真正执行 Darwin XCTest，必要时改正测试编译接口，再由用户将包含本次修复的 iOS Native 安装到 iPad 重放现场；上述验收未完成前仅按 PARTIAL / 待实机验收处理。不得转 NavSea JS workaround 或修改跨平台业务契约。
+
+报告：`docs/报告/STEP-107_iOS_StyleCoreOnlyPeer集合修复_RDC实施报告_v1.md`。
+
+## 代码交付 Git 核验（2026-10-09）
+
+- Scoped 修复提交：`016bf5ad93e0fdd625034b29fedd150ea6af3943`，包含 iOS 实现、XCTest 源码、本 Step、实施报告和开发日志，共五个文件。
+- 已 push 至 `origin/particle/main`；远端 `refs/heads/particle/main` 回读等于提交完整 SHA。
+- 这是**尚未完成 XCTest / iPad 事故复测的代码交付**，不是 GSRL 正式发行；原 V22 Tag/Source Lock 不动。
+- 原有 `vendor/expected-lite` 本地状态与两份未跟踪文档未触碰；未创建新 worktree。

docs/50_Step记录/STEP-108_V23统一正式发行_v1.md

@@ -0,0 +1,31 @@
+# STEP-108 V23 同源统一正式发行 v1
+
+- 日期：2026-10-09（JST）
+- 状态：**CLOSED / GSRL PASS / RELEASED（设备验收独立进行）**
+- 冻结源码提交：`87f3d1c59a52581fb8339f0ea7d106b9f4b94fef`
+- 主目录：`/Users/tei/dev/MapLibreParticleLab`，分支 `particle/main`
+- 版本：Android/RN `13.6.1-particle.23`，iOS Metal `6.29.0-particle.23`
+- 前序修复：STEP-107 Darwin Style CoreOnly Peer 防崩溃代码已纳入。
+
+## 分阶段事实
+1. Prepare：冻结并 push 源码版本，commit `87f3d1c59a52581fb8339f0ea7d106b9f4b94fef`，版本互锁正确。
+2. Build：`tools/particle_release_pipeline/release.sh 23 build`，exit 0；Android OpenGL 四 ABI Release、Maven Local、iOS Metal Bazel opt 与 RN tgz 均 PASS。日志：`/tmp/maplibre_v23_unified_release_build_20261009.log`。
+3. Publish：`tools/particle_release_pipeline/release.sh 23 publish`，exit 0；六文件 NAS 公网逐字节回读 PASS，SwiftPM `6.29.0-particle.23` Tag 可取。日志：`/tmp/maplibre_v23_unified_release_publish_20261009.log`。
+4. GSRL：六项文件实际 SHA-256 与下载地址见 `release/maplibre-particle/13.6.1-particle.23/SOURCE_LOCK.json`。
+5. Finalize：release.sh 23 finalize exit 0；正式发行 Tag 已成功 push；远端 main 和 tag 回读验证通过。
+
+## 未验收及禁区
+- STEP-107 XCTest 与 iPad 直接点击崩溃场景尚未运行；不得宣称已实机修复。
+- V23 Android 实机、React Native 宿主整体集成、iOS Metal 真机 NOT_TESTED。
+- 原 V22 Tag/Source Lock 与发行制品不覆盖；禁止新建 worktree、擅自纳入无关 dirty 文件。
+
+
+## 最终发行验收证据
+
+- 实际构建源提交：87f3d1c59a52581fb8339f0ea7d106b9f4b94fef。
+- 发行清单提交：a0a4787b4379ab2819943d20ce05a7ae760a88c3，Tag maplibre-particle/rn/13.6.1-particle.23 指向该 Commit。
+- SwiftPM Tag 6.29.0-particle.23 公网可读，二进制 checksum 匹配。
+- 六个制品再次经 curl 公网下载，全部 HTTP 200，长度、SHA-256 与 GSRL Source Lock 全部一致，TASK_PASS_V23_GSRL_FINAL_VERIFY。
+- 最初独立 Python urllib 请求遇到 HTTP 403，改用正式发布脚本使用的 curl 请求后六项全部 PASS，文件没有被重新上传或修改。
+- V23 GSRL 发行 CLOSED / PASS，STEP-107 XCTest、iPad 事故重放、Android/RN/iOS 设备测试仍 NOT_TESTED。
+- 本补充属于发行 Tag 之后的审计提交，不更改发行 Tag、SOURCE_LOCK.json 或公开二进制。

docs/50_Step记录/STEP-109_V23_CPU_FieldSnapshot深比较快路_v1.md

@@ -0,0 +1,35 @@
+# STEP-109 V23 CPU FieldSnapshot 深比较快路 v1
+
+日期：2026-10-10（JST）
+状态：进行中（源码已改；Mac Native 编译及设备 CPU 对照待验）
+
+## 基线
+- 设备：Mac.lan，仓库 /Users/tei/dev/MapLibreParticleLab。
+- 分支：particle/main；起点 HEAD：5b8bdfbfbb4263fe12a060e77bc310cf77f27d61；起点工作区干净。
+- 已发布基线：Android / RN 13.6.1-particle.23，iOS 6.29.0-particle.23；正式 V23 Tag、Source Lock 及制品均保持不变。
+- V21 FZG1-2 曾有天气持续运行高 CPU 与疑似浮点数组比较样本；不是 V23 的测量结果。
+
+## 调查依据
+- render_particle_validation_layer.cpp 稳定每帧通过 sameFieldGpuEndpoint() 比较 T0/T1，比较包含整个 vector 与 valid。
+- render_weather_color_layer.cpp 稳定每帧通过 sameFieldGpuContent() 比较完整 scalar/vector/valid。
+- V23 源码中已保留 STEP-090 Fast Path；STEP-102/106 已处理部分 RenderSegment Placement 语义，不对 V23 再次假设 cache-invalid。
+
+## 本次非正式修改
+- [x] ParticleGpuResources 记录与真实 GPU T0/T1 槽位相应的 shared_ptr<const ParticleFieldSnapshot>。
+- [x] WeatherColor Resources 同样记录两帧快照身份。
+- [x] 相同不可变 shared_ptr 且资源代际未变时，跳过 O(N) 深比较。
+- [x] 新快照对象、窗口更换、旧资源不存在时保留严格内容/端点对比。
+- [x] 只有真实纹理安装成功或严格等价比较后更新资源绑定身份；clear、context loss 与资源重建自动丢弃旧身份。
+- [x] 保留 T0/T1、MIX、时间跳转、窗口重用、编码/内容身份、双平台 Renderer 语义。
+- [x] 未改公共 API、RN、JS/TS、RenderSegment 安全 Gate、任何发行制品。
+
+## 构建与验收
+- [x] git diff --check PASS；只修改 2 个 C++ 文件。
+- [ ] Mac Metal Native Core 编译：**NOT COMPLETED / 用户验收前主动中止**。`bazel build -c opt --//:renderer=metal //:mbgl-core` 因触发 649 个通用 Core actions 的大量重编译，尚未走到构建成功/失败结论；已中断 Bazel 客户端并核对其 PID 退出。日志 /tmp/maplibre_step109_cpu_field_identity_bazel_20261010.log。此项不能写为 PASS。
+- [ ] C++ directed regressions（snapshot identity、new-object differing payload、window shift、clear/reload）。
+- [ ] Android OpenGL / FZG1-2 同场景 V23 原版与修改版 CPU A/B：尚未执行。
+- [ ] iOS Metal iPad 实际天气场/时间窗回归：尚未执行。
+- [ ] 真实性能目标：至少比较相同场数据、帧率、图层与设备条件下的平均进程、RenderThread、JS CPU；同时检查 FieldTextureUpload / SimulationReset 计数无异常增加。
+
+## 交付边界
+本 Step 不创建新发行版本，不覆盖不可变 V23 产物。开发态代码已通过 scoped commit `2aae38f4023f2ef682c9039c93dfa1e96b0e6e1b` 并 push 到 origin/particle/main（远端 SHA 回读 PASS）；这不是 Native 编译、性能或正式版本验收。正式使用仍须完成编译/设备测试、另立版本并执行 GSRL Source Lock、SHA-256、接收验收。若编译失败，则先记录错误并修复，不得宣称优化 PASS。

docs/50_Step记录/STEP-110_R0_Placement跨段归因只读调查_v1.md

@@ -0,0 +1,31 @@
+# STEP-110 R0 Placement 跨段归因只读调查 v1
+
+- 日期：2026-10-10
+- 状态：**PARTIAL（调查性质；非修复/性能 PASS）**
+- 仓库：/Users/tei/dev/MapLibreParticleLab；分支 particle/main
+- 调查起点 HEAD：2df504cdc0403bdad85d3f31f16fd54a8744abac
+- V23 Source Lock：87f3d1c59a52581fb8339f0ea7d106b9f4b94fef；V23 tag peeled commit：a0a4787b4379ab2819943d20ce05a7ae760a88c3
+- Codex 实际模型：gpt-6-astra / high（CLI 启动日志确认），CLI 0.161.0；Codex 调查完成，文档交付会话多次卡住，之后由 RDC 整理、落盘并独立审查关键源码。
+- 主报告：docs/20_调查/R0_Placement跨段归因与缓存安全边界调查_v1.md
+
+## 已完成
+
+1. 读取 STEP-110 任务书、根 AGENTS/基线、项目总则，以及 STEP-088/089/090/092/094/099/100/102/106/108/109。
+2. 比较 V23 GSRL build Commit、Tag commit 和 main；核心六份 Renderer/Placement/Cache/Fast Path Git Blob 完全一致。
+3. 只读追踪 Renderer::update、RenderOrchestrator::createRenderTree、CrossTileSymbolIndex、PlacementController、RenderTree、per-segment Placement Gate、Retained Cache、Fast Path。
+4. 读取 STEP-106 本机既有 T1/T2 设备日志，确认 placement-free Retained 段复用，不推定含 Symbol R0 可复用。
+5. 回答 Q1–Q4、七个反事实场景、结论矩阵与风险优先级，并明示 cannot prove 的范围。
+6. 不涉及 Native/JS/Kotlin/测试代码修改；未运行测试、Jest、构建、Gradle、CMake、Bazel、ADB 或设备验证。
+
+## PARTIAL 原因
+
+- NavSea 生产 R0 逐 Symbol placement/fade/visibility 等价证据缺失；只读源码不足以证明 C1 的 Placement 变化完全不影响 R0。
+- 本次不允许插桩、修改 Core 算法、重测 NavSea 或新建安全机制。
+- 需要另行授权 Native 内部诊断/安全判据，再进行跨 Source 碰撞与真实 CPU/视觉 A-B。
+- 本地报告写入由 RDC 完成，不能误称 Codex 已直接交付文档。
+
+## 结论及停手范围
+
+R0 含地名 Symbol，V23 全局 Placement/Fade Gate 的保守失效与现有设计相容；**当前没有证据判定为既有不变量遭破坏的 Bug**。对 placement-free R 的 STEP-102 隔离已通过历史测试，不能直接解除 placement-bearing R0 的 Gate。
+
+Git 收尾证据以 STEP-110 完成报告和最终 RDC Git 验收为准；禁止提交原来未跟踪的 STEP-110 任务书或其他无关文件。本任务无正式 Binary/Source Lock 发行。

docs/50_Step记录/STEP-111_R段Placement结果等价调查_v1.md

@@ -0,0 +1,21 @@
+# STEP-111 R 段 Placement 结果等价调查 v1
+
+- 日期：2026-10-10
+- 状态：**PARTIAL；调查未完成，Native 未实施**
+- 仓库：Mac `/Users/tei/dev/MapLibreParticleLab`，`particle/main`
+- 任务起点 HEAD：`7ec9ac8c1635c7a3b607abc2ed4be4fd764e7b6d`
+- 模型：Codex CLI 0.161.0，实际可见 TUI `GPT-6 Astra high`。
+- 执行：Codex 两轮源码探索后停止新增事件；尝试同会话缩窄为直接出报告，仍无报告生成。会话已人工中断并退出，未取得可靠退出码，不能认定正常完成。
+- GPT/RDC 随后只读核验 `render_segment.hpp:85-90`、`render_orchestrator.cpp:775-810`、`renderer_impl.cpp:638-686` 与 STEP-110，并编写 PARTIAL 评估；不是 Codex 完整调查报告。
+
+## 有证据的阶段结论
+- Retained Cache 已逐 R 管理，但含 Symbol 的 R 使用全局 Placement/Fade Gate，未依据该 R 的最终 Symbol 结果判等。
+- 可以把“全图 Placement 后按 R 判断纹理是否复用”作为候选优化路线，不把 Segment 当作独立 Collision Domain。
+- 难度初估：诊断 2–3/5、shadow 比较 3/5、安全独立 Reuse 4/5、分段增量 Collision/Placement 5/5；数字仅为工程评估，未通过真实实现检验。
+
+## 未完成、禁止夸大
+- 未形成稳定/完整的 per-R 视觉等价签名设计或生命周期证明；无新 Native 插桩、运行数据、编译、测试、Jest 或设备 A/B。
+- Codex 未生成预定三份交付文件；由 GPT/RDC 记录 PARTIAL，不写“Codex PASS”。
+- 原有未跟踪 STEP-110 任务书和本次 STEP-111 任务书均保留，不参与文档 Git 提交。
+- 主报告：`docs/20_调查/STEP-111_R段Placement结果等价与独立刷新可行性调查_v1.md`。
+- 后续先审查稳定 ID、Fade 和 per-R 最终数据所有权，再考虑 shadow-mode 与缓存 Gate 改造。

docs/50_Step记录/STEP-112_V23粒子FullRender与Symbol缓存调查_v1.md

@@ -0,0 +1,56 @@
+# STEP-112 V23 粒子 Full Render 与 Symbol 缓存调查 v1
+
+日期：2026-10-11（JST）。状态：**完成（本轮只读调查交付）；综合判定 PARTIAL（生产逐帧归因、安全修复与性能未验证）**。
+
+## 目标与基线
+
+只读完成任务A—E、全Gate矩阵、R2状态机、Placement/Fade两种配置、S1—S5及A—D提案；不实施Native修复。
+
+- Mac.lan / Darwin 24.6.0 / x86_64；仓库 `/Users/tei/dev/MapLibreParticleLab`。
+- 起点及结束基线：`particle/main@41b416c261fa72bd21171328045036a124694f47`。
+- 模型已从本会话rollout确认 `gpt-6-astra/high`；无切换、无子代理。
+- Integration HEAD `80667d6c` 采用用户提供的RDC核实事实，只读相关契约/决议。
+- V23 Android/RN `13.6.1-particle.23`、iOS `6.29.0-particle.23`。对V23构建源码 `87f3d1c…` 的相关路径diff只有STEP-109两Layer快比较；本调查核心Gate保持一致。
+
+## 必做项与结果
+
+- [x] 按序阅读AGENTS、基线、8份规范、总则README和四份有效总则、当前任务与STEP-102/106/109/110/111。
+- [x] A：Core/Android/iOS请求→Fast/Full→GPU→Observer/Idle调用图，区分forecast与粒子cadence。
+- [x] B：24项Fast Gate，逐项来源、通过条件、首错、Tick影响、Full恢复与现场证据强度。
+- [x] C：R2结构能力、Source/local/global revision、evaluate/BuildPending/资源/成功/失败/合成状态机。
+- [x] D：transitions开关、300ms/30ms/zoom、fade公式、8组合真值表、GL/Metal opacity链。
+- [x] E：S1—S5逐帧/事件推演和布局对照；原RCRR完整边界缺失明确标未知。
+- [x] A—D提案：优先级、首建/scene/C覆盖、正确性、资源代价、候选文件、1—5复杂度、双平台最小验证；D列Interface Blocker。
+- [x] 先创建框架、分阶段追加证据，最终三份交付文档和开发记录追加已落盘。
+- [ ] FZG1同帧全Gate/配置/CPU归因、生产Symbol结果等价、GL/Metal运行验证：本轮禁止执行，留给另行授权阶段。
+- [ ] Native修复、插桩、性能改善：本轮明确未授权，未执行。
+- [x] 指定四文件scoped commit/push及远端HEAD：由RDC在Codex调查后执行，首次提交与Push已核验；实际记录见下文Git收尾补记。
+
+## 主要源码结论
+
+正常Continuous Full中，含结构性Symbol的R要求 `!changed && fade==0 && !transition`；重算分支changed=true，不重算分支setPlacementStale令transition=true，因此首次Build没有准入窗口。即使全体Source静态也成立。`fade==0`不是Fade终态；关闭transitions的正常Full为true/1/false，现场true/0/false与开启配置的稳定重算相容。
+
+R2 invalid令下一次Fast在cache-invalid返回；另有全局prepared scene及PREFIX中普通Symbol/Line C的独立阻塞。Full可以复用R0/R3，不等于全图全部重画。上述不证明安全放宽Gate，也不证明现场每次Placement都改变R2像素。
+
+## 允许范围与必做输出
+
+仅四文件：
+
+1. `docs/20_调查/STEP-112_V23粒子FullRender循环与Symbol缓存准入全面源码调查_v1.md`
+2. 本阶段记录。
+3. `docs/报告/STEP-112_V23粒子FullRender与Symbol缓存调查_Codex完成报告_v1.md`
+4. `粒子开发记录.md` 仅追加。
+
+两份未跟踪STEP-110/111任务书保持原样。未改源码、测试、Style、脚本、跨项目文件、版本或发行产物，未清理dirty或改变branch/worktree。
+
+## 检查、阻塞与下一步
+
+只执行只读源码/Git比较和文档范围、完整性、空白检查；实际结果详见完成报告。编译/链接/codegen/测试/Jest/Gradle/APK/ADB/设备操作全部未运行，无新制品。
+
+剩余证据：FZG1实际Placement options和24项Gate逐帧序列、原始完整plan、Source/forecast/Annotation来源分摊、Symbol最终GPU输出安全等价。下一步仅建议授权A低开销同帧诊断与B生命周期安全证据设计；不得先删Gate。公共明确Full命令语义由Integration决定。Codex不负责Git收尾；STEP-112任务书要求RDC独立完成仅文档scoped提交、推送和远端验收，结果以Git收尾补记为准。
+
+## RDC Git 收尾补记（2026-10-11）
+
+- RDC独立检查 branch=`particle/main`、起点 HEAD=`41b416c261fa72bd21171328045036a124694f47`；仅stage任务规定的三份STEP-112文档及`粒子开发记录.md`，`git diff --cached --check`通过，恰好四文件，原两份未跟踪STEP-110/111任务书不触碰。
+- 首次文档提交：`abc137ca9637abc18be8c64cd98f2c7f1ed68704`，message=`docs: investigate STEP-112 particle full render and symbol cache`；普通`git push origin particle/main`退出码0；`git ls-remote origin refs/heads/particle/main`返回相同SHA，首次远端验收PASS。
+- 本段是RDC在Codex完成后补写的Git事实；补记自身形成单独文档提交，最终HEAD与远端一致性以RDC最终回读为准，不影响源码调查PARTIAL或禁止运行的设备/构建项目。

docs/50_Step记录/STEP-113_FZG1_PBF_Layer与FastGate诊断_v1.md

@@ -0,0 +1,100 @@
+# STEP-113 FZG1 PBF Layer 与 Fast Gate 诊断 v1
+
+日期：2026-10-11（JST）。状态：**进行中；源码交付PARTIAL，等待RDC独立编译/设备验收，113层完整等价缺证据。**
+
+## 目标、基线与边界
+
+优先B：每次真实Fast尝试可靠保存24 Gate、首错及失败全集；再交付真PBF专项场景、低频UI和机器可读导出。
+
+- Mac `particle/main@c6d13e1059d464d312ac33acac87967300fa5dc4`，仓库 `/Users/tei/dev/MapLibreParticleLab`。
+- 已实际核实模型 `gpt-6.1-sol/high`；NavSea只读 `ad9aa043`，Integration本地 `80667d6c`。
+- 当前源码版本 `13.6.1-particle.23` 未改；本次修改未发行。
+- 只修改Shared Core诊断、Android Test App、相关C++测试源码、本Step/报告及开发记录追加。禁止改变Gate/Placement/Fade/Cache安全判定、公开RN方法、NavSea/Integration、构建基线、正式发行或Git提交推送。
+- 既有STEP-110/111/113未跟踪任务书原样保留，无branch/worktree变更。
+
+## 必做项与当前结果
+
+- [x] 同一次已计算input保存24项状态掩码与生产首错，一致性计数明确，不重复副作用函数。
+- [x] 120帧有界环形数据、生命周期及窗口聚合，所有Gate记录；pre/post明确分离。
+- [x] per-R实际pre cache validity/revision和两phase的cache build/reuse/invalidation/fallback/原因/执行状态；每phase最多16R，超限显式。
+- [x] 使用现有Native JSON出口追加可选fastGateTrace；共享锁快照，UI不访问Renderer mutable state。
+- [x] 明确reset位置；普通Full miss不清历史。新增4个C++回归用例，尚未运行。
+- [x] 正式URL专项PBF63/STATIC_RC/PARTICLE_OFF/PARTIAL_RCRR/SOURCE_CHANGE场景源码；保留原场景和STEP-102动态fixture。
+- [x] 运行时原63层完整定义/顺序保存检查，真实Sprite/Glyph/Tile URI检查、Style fingerprint/版本/Layer表/plan接受及最终解析原因导出。
+- [x] 固定camera/forecast请求、30fps目标；禁用手势；静态轮询不改Symbol/Source/forecast。
+- [x] UI每3秒单次query、30秒摘要、手动最近snapshot导出；Logcat标签STEP113Gate，Base64分块防截断。
+- [x] 中文完成报告、精确RDC命令、开发记录末尾追加与静态范围检查。
+- [ ] 113层全量生产Layer/Source/显隐/业务数据与现场四段数字边界：缺同版本完整快照，未复制。
+- [ ] Native/Kotlin编译、定向测试、APK、FZG1-2资源/层/逐帧/性能/开销验收：本轮Codex未执行。
+
+## 证据等级与剩余风险
+
+SOURCE-PROVEN：NavSea URL配置、当前源码RC选择器、shared天气片段ID/type/source。TEST-APP-STRUCTURAL：保序63层和部分RCRR检查代码、额外Source探针、既有canonical风场。DEVICE-MEASURED：本轮无结果。NOT-VERIFIED：正式服务回读（本机域名无法解析）、设备实际Layer表/113层全等价、构建与性能。
+
+原始JSON63层不包含SDK可能追加的Annotation等内部层；必须使用实际Native styleLayers总数与Layer ID解析边界。部分RCRR锚点不同于现场[0,13)/[13,33)/[33,107)/[107,113)，不能把结构测试说成同等画面。NavSea当前RenderSegmentHost源码RC与该历史现场RCRR_PREFIX分别记录。
+
+pre里的changed/fade是上一完成RenderTree快照；当前Controller transition另存preFastPlacementTransition。Fast post不是新Placement结果。Debug simulationAdvance是进程级计数；实际forecast时间未新增Native回读接口，导出null并保存accepted请求。环形覆盖会丢弃最早详情但保留聚合；内存字节/CPU开销未实测。不能从零Fast提升或APK编译成功直接判性能PASS。
+
+## 独立验收填写栏（由RDC追加真实结果）
+
+| 项目 | 本轮状态 / RDC证据待填 |
+|---|---|
+| 源码diff/hash、分支/HEAD/dirty | Codex交付未提交；RDC填写制品对应源码 |
+| 设备serial/主ABI/ABI list | 目标192.168.200.139:5555；未读取 |
+| Native配置/编译/4个新用例与相关回归 | NOT RUN；填写命令/exit/耗时/日志/首错 |
+| APK build-info/ZIP/ABI/字节/SHA/签名/安装 | NOT RUN；标准Validation脚本，禁止复用失败旧APK |
+| PBF63完整资源、实际Layer manifest | NOT VERIFIED；填写SDK回读fingerprint和原/实际层数 |
+| STATIC_RC首错/24Gate/window/mismatch | NOT VERIFIED；mismatch必须0，保存120帧详情 |
+| PARTICLE_OFF/固定预报/camera | NOT VERIFIED；保存对照窗口和请求接受结果 |
+| PARTIAL_RCRR实际四段/Layer ID/缓存状态 | NOT VERIFIED；明确部分等价，不能补写113层PASS |
+| SOURCE_CHANGE基线/单次变化/pre-post | NOT VERIFIED；记录Source mutation和两次导出 |
+| reset/前后台/退出/旧STEP-102回归 | NOT VERIFIED；不能以进程正常退出替代场景检查 |
+| 内存/trace开销/CPU/FPS/截图/crash | NOT VERIFIED；不能用单制品构建成功替代 |
+| 完整113层及原始现场selector | 缺证据；另需真实同版本快照 |
+
+## 构建、检查与必做输出
+
+Codex仅执行只读调查、文本一致性/范围检查、git diff --check与新增文件空白检查；无编译、C++运行、Jest、Gradle/APK、ADB、设备、发行或Git提交推送。
+
+精确macOS Shell构建/ADB/场景/Logcat/私有JSON回读及Native定向命令见：`docs/报告/STEP-113_FZG1_PBF_Layer与FastGate诊断_Codex完成报告_v1.md` 第5节。Android ABI先匹配标准脚本x86_64，所有设备命令固定 `-s 192.168.200.139:5555`，由RDC执行。
+
+交付源码/测试、本记录、上述完成报告、粒子开发记录追加已落盘。下一步仅由RDC独立验收；失败保留首个真实error及完整日志，再按本任务范围修复。不得借此放宽Fast/Placement/Cache安全判定或进入正式发行。
+
+
+## RDC 独立验收补记（2026-10-11，设备证据）
+
+以下是 Codex 退出后 RDC 新执行的证据，不修改上文 Codex 未构建/未实测的历史结论。本次阶段判定：**PARTIAL；Android 构建 PASS；五场景稳定基线采样 PASS；113 层等价与性能 NOT VERIFIED**。
+
+- 环境：Mac、particle/main；构建源码基于 c6d13e1059d464d312ac33acac87967300fa5dc4 加 STEP-113 未提交改动，build-info 明确 git_dirty=true。此 APK 不是 Source Lock / 正式发行。
+- 标准 build_validation_apk.sh 于 2026-10-11 08:35:08 JST 退出码 0；Gradle BUILD SUCCESSFUL in 19m 22s；Java 17.0.20.1；OpenGL/x86_64；ZIP/ABI/体积/SHA 自检通过。
+- APK：artifacts/maplibre-particle/android-validation/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk；66,587,454 bytes；libmaplibre.so 40,033,976 bytes；SHA-256 0054248bc3872e8670df4e9a10d11f1d65c0912a0482586cd7a247e880a6eaef。记录：同目录 build-info.txt、build.log。
+- 设备：FZG1-2，ADB 192.168.200.139:5555，主 ABI x86_64；明确 -s 的 adb install -r 返回 Success，未卸载数据；设备安装后版本 13.6.1-particle.23。正式 PBF Style 模式运行并加载。启动前数秒 sceneReady=true 但 Native Layer=0 / plan not-configured 是加载暂态；只接受之后的 Native Layers 非零、planValid=true 稳定记录。
+- 五个场景均由 ADB 明确 serial 启动；STEP113Gate Logcat Base64 summary 成功还原。每场景实际设备稳定状态的 decisionMismatch 都是 **0**。Full/Fast/Attempts 为生命周期累计，并非精确 60 秒窗口。
+
+| 场景 | Native Layers | Attempts | Full | Fast | Retained 及关键证据 |
+|---|---:|---:|---:|---:|---|
+| PBF63 | 64（63+内部层） | 106 | 106 | 0 | R[0,64) Build0，unknown-dependency；无粒子持续驱动 |
+| STATIC_RC | 66 | 876 | 875 | 0 | R[0,63) Build0，unknown-dependency；unsupported-continuous-layer、unsupported-scene 各876 |
+| PARTICLE_OFF | 66 | 70 | 70 | 0 | no-particle-repaint=70；非相等时长性能对照 |
+| PARTIAL_RCRR | 66 | 862 | 861 | 0 | R0[0,3) unknown-dependency；R2[39,64) 与 R3[64,66) Build0/static-placement；两个 unsupported Gate 各862 |
+| SOURCE_CHANGE | 67 | 888 | 888 | 0 | 基线已记录；**没有执行菜单手动 Source mutation** |
+
+- STATIC_RC 同帧失败全集汇总 CacheInvalid=870、revision-mismatch=871、placement-or-fade=780；PARTIAL_RCRR CacheInvalid=856。这些失败条件可能在**同一帧**并存，不能累加为帧数。即使修复缓存 Build，也还有 #22/#23 与其它独立 Gate。
+- 设备摘要 JSON（不纳入 Git）：artifacts/maplibre-particle/android-validation/step113/ 下的 pbf63-summary-ready.json、static-rc-summary.json、particle-off-summary.json、partial-rcrr-summary.json、source-change-baseline-summary.json。它们只是低频 summary，不是导出的完整 120 帧。
+- 仍 NOT VERIFIED：原 NavSea 113 层完整 Layer/Source/显隐及真实四段边界；实际 PBF/Sprite/Glyph 画面截图；Source 单次变更后前后对照；120帧手动详情导出；C++ GTest 运行；reset/后台、旧 STEP-102 场景回归；CPU/GPU/诊断开销；生产性能提升、正式发行。不得把部分结构等价当成现场复测或将 STEP-113 判为 CLOSED/PASS。
+- 下一阶段必须分别处理 retained first-build 的安全准入、unsupported continuous layer、unsupported scene；不能直接删除 Gate 放行。
+
+
+## RDC 第二轮设备验收（2026-10-11：完整窗口与Source变更）
+
+**本轮状态：设备逐帧诊断 PASS、单次Source变更链路 PASS，完整113层等价与生产优化仍 PARTIAL。** 本记录追加在原有RDC基线结果之后，旧内容中的“未执行单次Source mutation/120帧导出”是第一轮结束时的历史状态，不代表第二轮。
+
+1. 在设备 FZG1-2、ADB 192.168.200.139:5555、版本 13.6.1-particle.23 上运行 SOURCE_CHANGE；通过屏幕中的 STEP 093 → STEP-113 → EXPORT LAST SNAPSHOT，使用明确serial的 adb exec-out run-as 回读 App 私有JSON；文件字节分别为变更前 277980、变更后约272KiB。精确位置：artifacts/maplibre-particle/android-validation/step113/source-change-before-full.json 和 source-change-after-full.json，均保留在 Mac 本机、未纳入Git。
+2. 变更前 trace：lifecycle 1，attempts 13859，capacity/windowCount 120，最新119个完成的Full帧、0 Fast帧、最后1帧为pending、decisionMismatch=0；变更后 trace：同lifecycle，attempts 17476，windowCount=120，同样119个已完成Full、0 Fast、decisionMismatch=0。相同frame中前置状态 pre 的 placementBasis 标为上一完成RenderTree，post 完成Full才使用当前Full tree；knownMask覆盖24条Gate。
+3. 在 SOURCE_CHANGE 场景操作一次 MUTATE PROBE SOURCE ONCE。Logcat解码的 source-command：mutation=1；变更后导出 commands.sourceMutationCount=1；Native lastMutation.sourceId=step113-source-probe，affectedSegmentIndices=[1]，事件 TileMutation。变更前 lastMutation.sourceId=navsea_delivery，affectedSegmentIndices=[0]。累计 content-mutation Gate failure 从12变为14，但中间同时有正常瓦片更新，**不得把全部增量单独归因为这一次probe**。120帧环形窗口会覆盖发生瞬时变更时的精确帧，故本轮只确认命令/Native依赖定位，不声称捕获到单次Mutation帧的全部过渡时序。
+4. 从变更后120帧中统计119个 completed 样本：首错 cache-invalid=119/119；同一帧 Gate #3 cache-invalid=119、#4 revision-mismatch=119、#12 static-unstable=105、#13 placement-or-fade=105、#22 unsupported-continuous-layer=119、#23 unsupported-scene=119。24Gate shadow 对应生产首错持续吻合，decisionMismatch=0。该统计是窗口而非全应用时间的FPS度量。
+5. PBF同源核验：原始63层按SDK回读生产Style逐层定义保序、baseLayersPreserved=true；spec version=8，源Style名称 NavSea Delivery Full Semantic ExtentFix；productionFingerprintSha256=e0f9c2d1df38ae5d5953b561c52efe2f8590336de80b988e1d2935580d30b996（SDK回读序列化JSON，不是HTTP包字节）。SOURCE_CHANGE运行时67层，连续段[63,67)依次是 weather-color、raster-particle、测试circle、内建 org.maplibre.annotations.points symbol。STATIC_RC的连续段[63,66)同样包括内建annotation symbol。现有 continuousRangeSupportsParticleFastPath 要求其范围内**每一层**均支持 retained dynamic range；因此这些普通circle/symbol使Gate #22持续失败；这项结论为“源码判定+本机层清单”，未进行绕过Gate的运行实验。
+6. Gate #23 supportedScene 源码逻辑与 retainedSupported、fastContinuousSupported 及单C配置有关，**#22与#23不是根因完全独立的两次失败**；二者虽为不同Gate，却可能共享同一个不支持的C层根因。Retained R[0,63)仍持续 Build0、unknown-dependency；部分RCRR其它R也有static-placement。不能只消除C阻断就承诺Fast会成功。
+7. NavSea只读核对：当前src/map/particle/RenderSegmentHost.tsx 配置 R→C，从 rn-weather-color 开始；旧STEP-112的FZG1 113层RCRR_PREFIX属不同运行配置。同版本113个Layer的完整Source/ID/type/visibility/业务数据清单仍缺，不能把TEST-APP-STRUCTURAL的63/66/67层宣称为113层完整等价。FZG1-2存在debug NavSea安装，但**本轮未启动/修改NavSea用户数据**。
+8. Android设备截图已采集：artifacts/maplibre-particle/android-validation/step113/step113-source-change-screen.png（1920×1200），仅归档，未进行NavSea同版本逐像素比对。Mac Native GTest CMake配置尝试退出码1：缺少libuv（记录/tmp/particle-step113-macos-cmake.log）；未安装依赖，未进入GTest构建与运行，不记PASS。
+9. 后续受保护顺序：先由跨项目负责人获取NavSea同版本113层完整只读snapshot及真实selector；然后在Test App精准构造Layer/Source/顺序并获取120帧一对一同条件比较；分别建立R Build准入、C范围支持、Scene聚合依赖的源码及像素等价证明；通过后才能在Shared Core按受控范围修改Gate逻辑。禁止在证据不足时关闭 fail-closed Gate。RDC未在本轮运行新Android编译、改变渲染逻辑或做正式发行。

docs/50_Step记录/STEP-114_FastPath安全准入与TestApp闭环_v1.md

@@ -0,0 +1,77 @@
+# STEP-114 Fast Path 安全准入与 Test App 闭环 v1
+
+日期：2026-10-11（JST）。状态：**进行中；源码交付 PARTIAL，运行闭环待 RDC/用户，Symbol R 准入 BLOCKED。**
+
+## 目标、基线与范围
+
+- Mac / Darwin 24.6.0 / x86_64；`/Users/tei/dev/MapLibreParticleLab`；`particle/main@b02e54de3d45fcf612126ae8f037cba204f590ea`。
+- 实际 GPT-6.1-Sol（gpt-6.1-sol）/ high 已从本会话执行记录核实。没有模型升级、子代理或另一 Codex 实例。
+- Native/Test App 源码版本 `13.6.1-particle.23` 未改；Integration 契约仅只读，RN/JS公共API/ABI、Source Lock、正式发行不变。
+- 只修改 Shared Core 内部安全子集判定/缺源诊断、现有非 Jest 测试、Android Test App、本Step中文文档和开发记录追加。
+- 禁止 Codex 执行编译/测试/Gradle/ADB/Jest/CMake/Ninja/Bazel、commit/push、发行、跨项目写入或触碰原有 STEP-110/111 文件。
+
+## 按顺序完成的源码工作
+
+- [x] 静态闭环：Test App source类型、R初建失败、mutation/异步布局/资源/Annotation追踪、C/scene复合条件、Placement两分支。
+- [x] 本机旧STEP-113完整JSON回读发现：navsea_delivery是Vector；R依赖tide但Native source表缺tide。缺revision默认unknown-dependency不能作为CustomMVT已出现的证据。
+- [x] R缺失 RenderSource 提前返回missing-source，仍ready/stable=false、revision0；不补假数据，不放行CustomMVT/未知revision。
+- [x] 保守GeoJSON/circle R正向独立场景；source admission/cache GPU算法不改，3个C++用例源码补充结构保护与revision/cache状态机覆盖。
+- [x] 非粒子C继续fail-closed；独立scene只在确认没有Annotation实例时移除空内建层，正式PBF五场景原样保留。
+- [x] 无Symbol全场的controller stale不影响Symbol像素消费者；限定#13只在完整层表有结构性Symbol时阻止。空表/数量不一致仍保守，隐藏或空Symbol不豁免。
+- [x] Symbol R真稳定窗口审查：现有commit/fade证据不足，保留全部Build/scene条件；停止更大结果签名设计，明确BLOCKED。
+- [x] 独立FAST_SMOKE、CIRCLE_C_BLOCKED、ANNOTATION_BLOCKED、SYMBOL_R_BLOCKED；菜单/Intent、低频真实Native UI、单次Source/Image/Camera/Annotation/Cache命令与操作前后文件、Reload/前后台/Teardown取证入口。
+- [x] 调查、场景/定向验收说明、Step、中文完成报告、粒子开发记录实际落盘。
+- [ ] Mac Native配置/编译和3个新用例及指定回归实际运行。
+- [ ] Kotlin/Android一次手工编译、真实NativeFast>0、视觉与反向/生命周期设备闭环。
+- [ ] Symbol R结果证书、CustomMVT完整revision契约、非粒子C复合等价证明：未实现，维持BLOCKED/fail-closed。
+- [ ] iOS Metal实机/性能与生产Fast：NOT VERIFIED，不能由smoke替代。
+
+## 当前结果与限制
+
+没有新的编译、测试、APK、设备、GPU计数或性能结果。SOURCE-PROVEN/IMPLEMENTED与旧RETAINED-EVIDENCE分开；整体PARTIAL，不标Fast Path已修复。旧PBF缺tide诊断修正不代表该R可以Build；即使补源仍受SymbolPlacement保护。
+
+预期FAST_SMOKE的真实Native层序4层、R[0,2)/C[2,4)，必须取得Build/Reuse/Full/Fast与24Gate同帧证据。UIsceneReady只代表加载/命令成功，实际Native结构由导出JSON检查。三个负场景继续阻止Fast。Source等操作自动100/500/1500ms取证仍可能错过瞬态，缺证据如实记NOT VERIFIED。
+
+## 已做检查与精确验收入口
+
+Codex仅源码/文档阅读、已有JSON解析、Git只读状态、静态函数/范围/哈希核对、git diff --check和新增文件空白核对。未执行任何构建/测试/设备/Git写操作。
+
+精确命令：`docs/60_测试/STEP-114_独立FastSmoke场景与RDC验收_v1.md` 第2节Mac Native配置/target/过滤器/日志/失败停止；第3—5节用户后续手工Android/ADB、JSON检查和反向/生命周期矩阵。完成报告也列出Native最小命令。配置失败保留现场，不能使用旧runner或自行安装依赖伪造通过。
+
+## 独立验收待填写
+
+| 项目 | 当前事实 / RDC或用户证据待填 |
+|---|---|
+| 源码baseline/diff/hash与制品版本 | 未提交工作区源码；用户构建前保存明确diff/hash与dirty状态 |
+| Mac configure/build/新用例3个与回归 | NOT RUN；记录exit/耗时/真实测试数/skipped/日志/首错 |
+| APK/ZIP/ABI/大小/SHA/签名 | NOT RUN；唯一现有Validation脚本由用户手工 |
+| FAST_SMOKE真实层表/plan/cache/Fast | NOT RUN；4层R[0,2)/C[2,4)，decisionMismatch=0，Fast/Reuse delta>0 |
+| Source异步失效/Tile/Image/Camera/Cache恢复 | NOT RUN；保存五phase文件与精确变化帧，不从末态猜Gate |
+| Circle C/Annotation/Symbol R负场景 | NOT RUN；保持阻止并具备可见内容与真实更新 |
+| Reload/前后台/Teardown/重新进入 | NOT RUN；销毁前文件不是销毁完成证据 |
+| 原STEP-113五场景与STEP-102回归 | NOT RUN；保留正式PBF全部定义，缺源改报missing-source |
+| iOS Metal设备/像素/CPU/GPU性能 | NOT VERIFIED；不以Mac状态机测试替代 |
+| Git提交/推送/远端HEAD | NOT RUN且本轮禁止；后续另行授权RDCscoped收尾 |
+
+## 必做输出与下一步
+
+调查：`docs/20_调查/STEP-114_FastPath安全准入与闭环判定_v1.md`。
+
+验收：`docs/60_测试/STEP-114_独立FastSmoke场景与RDC验收_v1.md`。
+
+报告：`docs/报告/STEP-114_FastPath安全准入与TestApp闭环_Codex完成报告_v1.md`。
+
+以上及本记录、源文件、开发记录已由Codex实际生成。接下来由RDC独立审计并执行MacNative定向验证；用户一次手工Android/设备闭环。若缺libuv、编译失败或真实Fast仍为0，保留首错/24Gate再回交修复；不得继续扩大Symbol/CustomMVT/C放行或进入发行。
+
+
+## RDC 独立审核追加（2026-10-11）
+
+**结论：源码/差异/接口静态审核 PASS；Native 与 Android 编译、Fast 帧 NOT VERIFIED；整体 STEP-114 PARTIAL。**
+
+- RDC 独立阅读本轮 Native diff、C++ 新用例、STEP-114 Android Test App 新场景与菜单、生命周期接线；git diff --check 退出码 0。本轮只有范围内的五个 tracked 改动和新增 Kotlin/中文文档；原 STEP-110/111 未跟踪任务书不修改、不暂存。
+- 新增三项 Step114FastPathSafety 用例存在，覆盖无 Symbol、隐藏/Annotation Symbol 和 Source revision/cache 状态机，但**没有实际运行**。
+- Step113PbfGateScene.kt SHA-256 为 6e7befeb90ae172aaeff4b636a7640274dfb1065d8c97744cbc6af8d22b4ccae，Step102PlacementFixture.kt SHA-256 为 e44912970dd6353787be7a3e5f9924fe1249e2305d495f1e25e707352c97d3c7，均未变化。
+- Java SDK 只读核对实际提供 Style.removeLayer(String) 与 MapLibreMap.getAnnotations()。Kotlin/Gradle 编译未执行。
+- Mac 预检：pkg-config --exists libuv 返回 1，与先前 macos-metal CMake required libuv 失败一致。独立 C++ header -fsyntax-only 试验退出码 1，首错为 Xcode AppleClang 找不到标准 C++ 头文件 array，实际在进入项目源码检查前终止。日志存于 Mac /tmp/step114-header-check.log。两项均是环境阻塞，不是本轮 Native 测试 PASS 或已证明代码错误；未安装/修改依赖。
+- 实际 Fast Path 命中、正反 GPU 渲染、Android 设备、性能、iOS 均未验证。正式 PBF 仍有 tide 缺源、Symbol R Placement、内建 Annotation C 的阻断。STEP-114 独立最小场景属于待用户一次 Android 手工构建集中验收内容，不能用旧 APK。
+- 后续 scoped Git 收尾若执行仅表示 PARTIAL 源码及测试入口已归档，**不代表正式发布或 Fast Path 修复完成**，不打 Tag/Source Lock。

docs/50_Step记录/STEP-115_STEP113原PBF专用App复测准备_v1.md

@@ -0,0 +1,22 @@
+# STEP-115：STEP-113 原 PBF 专用 APP Fast Path 复测准备 v1
+
+日期：2026-10-11（JST）。状态：TEST-PREPARATION COMPLETE / MANUAL ANDROID BUILD REQUIRED / FAST NOT VERIFIED。
+
+## 任务意图
+
+原 STEP-113 专用 Android Test App 的 PBF STATIC_RC 是 Fast Path 正式验证主体，不以 STEP-114 FAST_SMOKE 或删掉原正式图层的测试代替。STEP-113 的五个场景不修改，不要求 NavSea 113 层完整复刻，但每个结果必须基于真实 Native 的 Fast/Full、缓存 Build/Reuse 以及 Gate 记录。
+
+## 本次已核实事实
+
+1. Integration main 已 fetch 并确认 80667d6c343411d03a760425438e3d292f452118。Particle 当前 main 为 21a10816435a82de3471bdb55ed83223101f5689。
+2. 现有 APK 的 build-info 显示构建源码 c6d13e1059d464d312ac33acac87967300fa5dc4；APK SHA-256 为 0054248bc3872e8670df4e9a10d11f1d65c0912a0482586cd7a247e880a6eaef，与设备 192.168.200.139:5555 的当前安装包 SHA 一致。这是 STEP-114 修改以前的旧 APK，不能拿来验收新修复。
+3. STEP-114 未解决原 PBF 缺 tide Source、R Symbol Placement 首次 Build 及 C 内建 Annotation Symbol 拒绝，因此不能提前承诺原 STATIC_RC 会进入 Fast。
+4. 新增工具 tools/particle_android_validation/verify_step113_fast_path.py；不修改原 STEP-113 Test App、Native 渲染逻辑、RN 公共 API。工具对版本/安装包 SHA fail-closed，按当前进程 PID 解码现有 STEP113Gate Base64 低频摘要并比较帧计数。
+5. 使用 python3 -B 解码旧设备 Logcat 的 STEP113 SOURCE_CHANGE 摘要成功，历史累计 Fast=0、decisionMismatch=0。旧 APK 执行 --preflight-only 返回 STALE_APK，exit=3，属于**预期的旧包拒绝**，不是“修复后测试失败”。
+6. 没有执行 Android 编译、安装、启动新 APK、完整 120 帧采集、真实 Fast/性能/像素验收。用户需手工完成最新源码的唯一 Validation APK Pipeline，并手工 install -r，之后才能进行新二进制测试。
+
+## 通过准则与下一步
+
+实际源提交与安装 APK 完全匹配、原 STATIC_RC Native Plan valid、场景 READY、同一进程和场景内 Full/Fast 计数真实变化，FastDelta > 0 方可称 Fast observed。需另外核对 cache Build/Reuse 和 decisionMismatch=0、24 Gate、影像等价及 Source mutation/Annotation fail-closed。若 FastDelta=0，记录具体 Gate/R fallback 后停止将其宣称为 PASS，回到源码定位。原五场景以及 STEP-102 维持保护，非正式发行，不改 Source Lock。
+
+步骤见 tools/particle_android_validation/README.md。没有修复完成或新的 APK 时，保持 STEP-114 PARTIAL，本 STEP 仅测试工具准备完成。

docs/50_Step记录/STEP-116_STEP113原PBF_FastPath实际修复_v1.md

@@ -0,0 +1,57 @@
+# STEP-116 STEP-113 原 PBF Fast Path 实际修复 v1
+
+日期：2026-10-11（JST）。状态：**部分实现（PARTIAL），停止于源码交付，待 RDC 独立审计。**
+
+## 当前基线
+
+- Mac / Darwin 24.6.0 / x86_64；`/Users/tei/dev/MapLibreParticleLab`。
+- branch `particle/main`，起点 HEAD `e2d202b560ad0165101546597c43f2ef0ccf4542`，本轮不提交，HEAD 不变。
+- 实际模型 GPT-6.1-Sol（gpt-6.1-sol）/ high，从当前 rollout 的 turn_context 核实；没有切换或第二实例。
+- Native Android 版本 `13.6.1-particle.23`，没有发版；Integration main 80667d6c 为用户给定 RDC 核验，相关文档只读。
+
+## 交付与未完成
+
+| 工作 | 状态 | 事实 |
+|---|---|---|
+| 强制前置/实际代码/旧完整JSON调查 | 已完成 | 原R缺 tide，navsea_delivery 为 Vector；GPU/source生命周期见审查文档 |
+| 空Annotation生命周期 | 已实现，未验收 | Native add/update/style-loaded 恢复缺失points；Test App仅STATIC_RC一次移除空辅助层，保留Source，退出恢复，后续变更撤销验收条件 |
+| 原63层/PBF资源/五场景 | 已保留源码语义 | 不改公网或tide-spots；SOURCE_CHANGE circle保留；STEP114/102源码冻结 |
+| 缺源empty准入 | BLOCKED | 缺GPU零贡献证书；继续missing-source，不补假源 |
+| Symbol首次Cache Build | BLOCKED | 无绑定成功Build的Placement/GPU最终输入证书，现有Gate全部保留 |
+| 诊断与复测工具 | 已实现，未运行 | JSON缺源ID +独立Placement摘要；75秒实际等待、源码锁定/生命周期/blocked/24Gate拒绝条件 |
+| 非Jest C++测试源码 | 已实现，NOT RUN | 四个Step116Safety、三个Annotations.Step116；真实图像检查交RDC |
+| 四份中文文档/README/开发记录 | 已生成 | 具体路径见完成报告 |
+| 真正Fast/像素/性能 | NOT VERIFIED | 没有新APK、设备计数、截图或FPS/CPU结论 |
+
+## 检查与收尾
+
+Codex仅执行阅读、Git只读状态/diff、旧JSON与冻结文件SHA、Python AST解析、git diff --check及文档静态检查。无 CMake/Ninja/Bazel/Native编译或测试、Gradle/ADB/安装/Jest、commit/push/发布；没有改构建流水线、公开头文件/API/ABI/Host控制协议。
+
+保护 STEP-110/111 未跟踪任务书。下一步 RDC 按 `docs/60_测试/STEP-116_STEP113原PBF专用APP验收_v1.md` 独立审计并锁定提交后的源码，用户集中一次手工 build/install，再执行 STEP115 preflight、原 STATIC_RC ≥75秒、完整120帧和24Gate、SHA及画面。不得使用旧APK或旧测试runner给本轮记PASS。
+
+## RDC 后续结果填写（本轮尚未执行）
+
+- 审计后的源码HEAD/精确diff/SHA：待填写。
+- Native配置/编译/定向测试及首错/日志：NOT RUN。
+- 最新用户构建APK SHA、build-info、设备安装SHA：NOT RUN。
+- STATIC_RC实际层数/空层调整/原63层manifest/Source：NOT VERIFIED。
+- Cache Build/Reuse、Full/Fast增量、120帧/24Gate/mismatch：NOT VERIFIED。
+- Annotation恢复、Source/async/Style/资源/层序/disable/reload回退及用户画面：NOT VERIFIED。
+- 最终阶段结论：当前PARTIAL；缺源与Symbol仍BLOCKED。
+
+
+## RDC 独立核验追加（2026-10-11）
+
+**本轮结论：限定范围源码/接口及操作说明静态审查完成；Mac Native配置 BLOCKED；Android APK/设备Fast NOT RUN，整体PARTIAL。**
+
+- 起点粒子仓库 particle/main=e2d202b560ad0165101546597c43f2ef0ccf4542；Integration origin/main已由RDC fetch并与本地main同步，HEAD=80667d6c343411d03a760425438e3d292f452118。未接触NavSea与Integration正式文件。
+- Codex实际模型 gpt-6.1-sol/high；本轮实现仅原STEP-113 STATIC_RC 的 SDK 空Annotation辅助层、Native AnnotationManager缺层恢复、缺源只读JSON诊断和测试验证器，不改变正式63个PBF layer、原五场景其他分支、Fast Gate/caching的准入或公开控制面。新增7项非Jest C++用例源码，尚未执行。
+- RDC直接核对 Android Style.java 对象removeLayer(Layer)文档明确注明被移除Layer可以重新添加；与STEP116在stop中恢复原wrapper的目的相符。Native AnnotationManager恢复与事件生命周期仍须编译、图像和设备验证，不凭静态阅读标PASS。
+- RDC核对旧SOURCE_CHANGE实际完整JSON：Native FastGate gates每项有order，firstFrame的knownMask等字段存在；STEP116验收脚本的原JSON结构检查有数据来源，但并非本轮运行证据。
+- Mac shell当前无rg可执行，RDC将STEP116手动导出命令中的rg替换为标准grep -E，保留同样的文件筛选表达式。Python验收器ast.parse通过，git diff --check通过。
+- Mac Native按当前标准命令重新执行真正的cmake --preset macos-metal配置（使用/Users/tei/Library/Android/sdk/cmake/3.31.6/bin/cmake），退出码1：Required package libuv缺失，日志保存artifacts/maplibre-particle/step116-native/configure.log。严格串行停止，未执行构建目标、未运行7项C++测试。失败是环境依赖，不应改写成代码编译通过/失败或跳过继续。
+- 未执行Android Gradle、APK安装、ADB启动STEP113、新Fast计数、逐帧画面、iOS Metal回归、发行/tag/Source Lock。正式PBF缺tide以及Symbol R Placement仍保留fail-closed；此任务只是安全部分实现，并不解决原STATIC_RC无法进入Fast的全部原因。
+- 用户在本轮源码scoped Git锁定且push远端核验后，需手工一次集中Android编译与install -r，再执行STEP115同HEAD/安装SHA预检、原STATIC_RC 90秒、完整120帧+24Gate+截图与其它负场景验收。新APK前禁止把旧c6d13e1产物Fast0作为本轮修复验收。若仍Fast0，必须保留缺源、Placement和C实际结果并交跨平台Core负责人确定GPU结果证书。
+
+## RDC实际Android APK/设备验收追记（2026-10-11）
+用户明确授权本次由RDC完成Android编译、安装、测试。源码提交c48a72a9d492ea0d05e4d58464f9643453158d50，标准APK构建PASS，APK SHA=a8b7f4e0f8e026bde8835e18a04876062be84cce3a3749a511cb08605d9f8a35；ADB serial192.168.200.139:5555安装Success，设备SHA相同，预检PASS。原STEP113 STATIC_RC真实90秒FastDelta=0、FullDelta=920，脚本退出2 NO_FAST_OBSERVED。Native65层、C仅WeatherColor+Particle，原63层保留，#22在最后120帧失败数0，说明空Annotation修复局部有效。R[0,63)缺tide Source，Cache Build/Reuse=0、PlacementGate=false；120帧119Full/0Fast/1Pending，#3/#4/#23失败120帧、#12/#13失败105帧，decisionMismatch0。总体Fast目标FAIL，本Step继续PARTIAL。完整报告及证据路径参见docs/60_测试/STEP-116_FZG1_原PBF实机验收结果_20261011.md。

docs/50_Step记录/STEP-117_原PBF_Fast缓存准入_v1.md

@@ -0,0 +1,58 @@
+# STEP-117 原 PBF Fast 缓存准入 v1
+
+日期：2026-10-11（JST）。状态：**阻塞**。调查与七项非Jest C++回归源码已交付；安全准入、真实Build/Reuse/Fast仍未完成。
+
+## 目标与基线
+
+原STEP113 STATIC_RC完整63基础层保持不变，以成功提交的GPU R结果证据解决缺tide和Symbol首次Build，达到Build>0、Reuse>0、FastDelta>0；证据不足保持fail-closed。
+
+Mac.lan，`/Users/tei/dev/MapLibreParticleLab`，`particle/main@43e5f5b91598b9c3d3f1c788052d4bbd2d616668`；实际GPT-6.1-Sol（gpt-6.1-sol）/high已核实。Integration只读HEAD `80667d6c343411d03a760425438e3d292f452118`。VERSION `13.6.1-particle.23`，未改发行坐标。起点tracked clean，STEP110/111及117任务书未跟踪。
+
+## 必做项与结果
+
+- [x] 读取规则、当前任务/基线、STEP112–116关键资料与相关实际依赖源码。
+- [x] 回读原274,693字节JSON并验证SHA，逐帧复算120帧24Gate与Placement状态。
+- [x] 审查sourceDiff/revision/fingerprint、双group注册/停用、prepare/upload/Build/提交生命周期。
+- [x] 分别说明缺源零贡献与Symbol最终GPU结果证书的缺口、反例及协调责任。
+- [x] 保留fail-closed、原63层、STEP116空Annotation修复、原五场景及SOURCE_CHANGE负例。
+- [x] 新增七项Step117Safety C++测试源码，复用已有构建登记。
+- [x] 落盘调查、验收计划、完成报告，末尾追加开发记录。
+- [ ] 建立可核验的缺源零GPU贡献与无旧Renderable数据证书，准入缓存。
+- [ ] 建立Symbol最终GPU结果等价证书，解决首次Build。
+- [ ] RDC独立编译并运行定向C++测试。
+- [ ] 原STATIC_RC新制品≥90秒，Build/Reuse/Fast增长、完整120帧、Mutation回退与用户画面验收。
+
+## 允许与禁止范围
+
+本轮实际只改两个既有C++测试文件，新增四份中文文件并追加开发记录。未改生产src/include、公开API/ABI/RN/JNI/合同、Shader、Android场景、Style/服务器、NavSea、iOS、版本/Source Lock；没有放宽Source readiness/revision、Placement或24Gate，没有造Fast计数。STEP110/111原未跟踪MD保留，不暂存；原设备JSON保持Git忽略。
+
+按用户当前禁止项，没有运行Gradle/ADB/Native编译/CMake/Ninja/Bazel/Jest、安装、commit/push。未启动后台编译或第二Codex，没有子代理。
+
+## 阶段验收与当前结果
+
+保留实测（STEP116，非STEP117）：原STATIC_RC 90秒FastDelta=0、FullDelta=920；Native65层R[0,63)、C[63,65)；R缺tide、Build/Reuse=0；最近120帧119Full/0Fast/1pending，#3/#4/#23失败120、#12/#13失败105、#22失败0、mismatch0。
+
+本轮复算pre为105帧false/非零/true、15帧true/0/false；post为104+15，末帧pending。源码证明：缺源没有新RenderItem不等于无旧GPU数据；停用request未执行前registry仍可遍历旧group；停用不清旧drawables。Symbol重算changed与recent stale使首建条件不可达；layer fingerprint不包含最终GPU opacity/atlas/vertices。
+
+因此两项准入均BLOCKED。七项测试只是可运行源码：真实controller/sourceDiff/registry/observer路径与状态机组合；没有GPU像素等价证据，不能称Native或全任务PASS。静态检查的实际结果在完成报告中记录。
+
+## 构建测试、输出与下一步
+
+RDC命令及失败停止、源/APK/设备SHA、完整JSON/画面、负例矩阵详见 `docs/60_测试/STEP-117_FZG1_原PBF真实Fast验收计划_v1.md`。本轮仅测试代码，Android生产行为无变化，重复构建不能解决B1/B2；先进行独立审计与Shared Core证书设计协调，形成受控实现后再安排一次用户授权的集中Android闭环。
+
+必做输出：`docs/20_调查/STEP-117_PBF_R首次缓存Build安全证据_v1.md`、本文件、验收计划、`docs/报告/STEP-117_原PBF_Fast缓存准入_Codex完成报告_v1.md`、开发记录末尾追加。Git提交/hash、远端HEAD、Native/设备验收均留RDC在后续授权下回填，本轮未执行。
+
+
+## RDC独立核验附录（2026-10-11）
+
+- RDC先核对Integration main=80667d6c343411d03a760425438e3d292f452118、Particle当前particle/main=43e5f5b91598b9c3d3f1c788052d4bbd2d616668；源码与git已跟踪改动起点为空，仅两个用户保护未跟踪任务书。
+- 用户本轮要求继续真实STEP113 PBF Fast优化，Codex实际GPT-6.1-Sol High。调查原STEP116实机120帧JSON，缺tide Source以及Symbol placement重算/stale循环仍无法安全创建首次GPU缓存；已有证据只能证明无新的LayerRenderItem，不能证明旧GPU drawables/已经应用的双LayerGroup删除。保留既有24Gate/生产Core，安全准入BLOCKED。
+- Codex新增7个Step117Safety C++测试源码，分布于两个既有登记的test/renderer文件；RDC独立对两个最终文件以当前Android OpenGL/x86_64的NDK clang++、真实compile_commands.json C++20 flags和googletest头文件进行-fsyntax-only。retained_underlay_cache.test.cpp exit0（6.3s），render_orchestrator_error.test.cpp exit0（5.3s），RDC检查结果PASS。语法检查日志存Git忽略artifacts/maplibre-particle/step117-native-syntax/*.log。
+- RDC核查原生产src/include/Renderer/Placement/Fast Gate、Android STEP113/114及Source/style均无文件改动，git diff --check通过。故**没有新的运行时改动供Android APK验证**：重复编译/安装STEP116相同行为的APK不能使Build/Reuse/Fast改善，未触发第二次高成本Android周期。GTest链接运行、GPU像素等价、iOS/Metal、真实Fast目标仍NOT RUN/BLOCKED，不能将NDK语法退出0标为GTest PASS。
+- Integration正式现有RFC/ADR/Contract/status/coordination未包含所需R Symbol已提交GPU结果证书。B1缺源零贡献、B2 Symbol跨层结果证书与影子验收、B3真实tide Source身份/宿主动态注入语义须由粒子负责人/Integration按职责协调设计；本执行项目不得自行改变Shared Core公共契约或正式Style。
+- 七项测试当前仍是源码语法检查级别，不等于实测; 下一步应先由粒子负责人协调Shared Core结果证书及合法真实tide来源，受控实现后再使用原STEP113 STATIC_RC APK复测。任意无法安全证明的条件继续fail-closed。
+
+
+### RDC 严格 -Werror 编译参数复核修正（2026-10-11）
+
+第一次NDK -fsyntax-only按项目真实C++20参数编译两个测试文件均exit0，但测试辅助函数遗漏可选retainedUnderlayState字段初始化，产生一条 -Wmissing-designated-field-initializers 警告；第一次探测曾附加 -Wno-error，不能直接标作正式 -Werror 验收。RDC后续对 test/renderer/retained_underlay_cache.test.cpp 增加一行显式 retainedUnderlayState={}，保留原逻辑，然后从临时核验脚本中移除 -Wno-error，严格复用Android NDK OpenGL/x86_64真实compile_commands.json的 -Werror 及C++20参数重新执行两文件 -fsyntax-only：retained_underlay_cache.test.cpp退出0/5.3秒，render_orchestrator_error.test.cpp退出0/5.2秒；对应Git忽略日志均无警告输出。**严格语法检查PASS；GTest链接运行仍NOT RUN，Symbol GPU证书及Fast仍BLOCKED。**修正仅测试辅助字段初始化，不涉及生产src/renderer、Android APK和正式Gate。

docs/50_Step记录/STEP-118_tide失效引用受控排除与Fast真实验证_v1.md

@@ -0,0 +1,29 @@
+# STEP-118 tide 失效引用受控排除与Fast真实验证
+
+日期：2026-10-11 JST。用户授权：tide Source可以删除。最终状态依RDC的实际Android验收更新，不预先标PASS。
+
+## 基线与数据事实
+
+Integration最新已同步main=80667d6c343411d03a760425438e3d292f452118，Particle原main=fb8e78ac1ab65ccafa6fd2b181d038b90d9a00c3。STEP116旧实机原STATIC_RC：生产基础63层；Native65层、R[0,63)、C[63,65)、FastDelta0、FullDelta920，R Build/Reuse0、fallback=missing-source、missingSourceIds=[tide]、PlacementGate=false。STEP117生产Renderer/24Gate无改动，严格Android NDK C++20语法检查已通过。
+
+完整旧设备JSON显示生产sources只有mapple和navsea_delivery，根本没有tide；63基础Layer中只有index2的tide-spots Symbol依赖tide。故删除不存在的Source本身不会改变Fast。
+
+## 本轮受控实现
+
+不修改远端正式PBF服务器Style、不改NavSea、Shared Core、ABI/公共API、iOS或Native Fast Gate。保留原五个STEP113场景及原63层原始定义和productionFingerprint。新增独立STATIC_RC_NO_TIDE：加载同样远端Style，断言生产无tide Source、唯一引用它的Layer必须是tide-spots Symbol；在仅供本机Test App测试的JSON副本中移除这一Layer，保留其他62个原定义/顺序、同样两天气层及相机/30fps/Pause和STEP116空Annotation保护。预期Native总64、R[0,62)、C[62,64)（尚须实际设备确认）。
+
+Parity同时保留原production63清单/fingerprint与有效62清单/test fingerprint；明确baseLayersPreserved=false，删除唯一层id/source/count，禁止将修改后的场景宣称为原63场景。Python verifier新增场景，强制校验原63/有效62/Native64、tide-spots/tide唯一排除、原Source无tide、R[0,62)、空Annotation移除、24Gate和SHA；旧五场景仍严格要求basePreserved=true。
+
+## 验收与风险
+
+RDC先源码检查/scoped Git提交推送，再在用户既有授权下执行Mac标准OpenGL x86_64 Validation APK构建、设备192.168.200.139:5555安装、APK SHA与已安装base.apk SHA一致、preflight、派生场景连续90秒、真实Native Cache Build/Reuse、Fast/Full增量和24Gate及截图。无新设备结果前仅称IMPLEMENTED / WAITING_ANDROID_VALIDATION。
+
+即使消除missing-source，R Symbol Placement changed/stale与#23可能继续阻塞。Fast0仍为目标FAIL；不得通过删其它Symbol、造Source、禁用fade、修改Gate或放宽24Gate得到假Fast。后续正式PBF Style是否永久删除tide-spots由Style/NavSea负责人按跨项目协调确定，本Test App派生结果不能直接替代正式Style发行验收。
+
+## RDC Android 新APK实机验收追加（2026-10-11）
+
+Mac标准Test App build脚本于源码HEAD 3051196054c7b69815c298040dae61d26499d9f2 实际返回BUILD SUCCESS，Kotlin/Native OpenGL x86_64编译与ZIP/strip/ABI校验通过。APK大小66603850字节，SHA-256 44afcfabe0cf4f1ec93f35899241bd73093aa6db4b5cb82ca2120dd531b8f3e9；RDC adb -s 192.168.200.139:5555 install -r最终Success，设备base.apk SHA完全相同，Python preflight PASS。安装耗时约267秒，没有重入安装。
+
+原STEP113框架内独立STATIC_RC_NO_TIDE运行90.008秒，PID22825，实际2份同生命周期有效摘要：原正式基础63清单仍保留在manifest，仅测试副本移除唯一tide-spots引用，基础62、天气2、Native64，R[0,62)、planValid=true、decisionMismatch0。R missingSourceIds=[]且原缺源回退从missing-source变为static-placement，说明本项修复在真机真实生效。R Cache Build/Reuse仍为0/0，FastDelta=0、FullDelta=942；120帧窗口Fast0、Full119。PlacementGatePassed=false，24Gate的unsupported-scene等继续失败。验证脚本返回NO_FAST_OBSERVED/exit2；此为目标未达成的明确负结果而非运行器异常。
+
+结论：**tide孤立引用造成的缺源阻塞PASS；原Fast性能目标FAIL；STEP-118 PARTIAL**。剩余独立根因是Symbol Placement的GPU结果安全证书；不能通过放宽gate将其当作成功。完整量化数据、APK绑定和设备截图SHA见docs/60_测试/STEP-118_潮汐清理新APK设备实测结果_20261011.md。本次纯测试记录Git commit若晚于APK HEAD，不得将新文档HEAD冒充APK二进制源码。

docs/50_Step记录/STEP-119_SymbolRetained生命周期修复_v1.md

@@ -0,0 +1,41 @@
+# STEP-119 SymbolRetained 生命周期修复 v1
+
+日期：2026-10-12（JST）。Step 状态：进行中。代码交付：**IMPLEMENTED / WAITING_RDC_VALIDATION**。这是此前中断任务的续作；不关闭整体 STEP-119，不构成编译、GTest、GPU 或设备验收 PASS。
+
+## 目标与基线
+
+按照 `/tmp/fzg1_astra_guidance_20261012.md` 修复内部 Symbol Drawable 的 RenderTile 同源绑定、旧 Drawable 更新及 Bucket/Atlas 更换生命周期；保留原缓存、证书和 Full → Build → 成功 Full Reuse → Fast 顺序。
+
+- 机器：Mac.lan / Darwin 24.6.0 / x86_64；仓库：`/Users/tei/dev/MapLibreParticleLab`。
+- 开工及交付分支：`particle/main`；HEAD：`badb515d590fbdf221751b6677de3da0a5650d7e`。未切换分支/worktree，未提交或操作远端。
+- 接续已有四个源码修改；起点另有受保护 STEP-110/111 两份未跟踪任务书。
+- 用户本轮明确指定模型 `GPT-6.1 Sol High`（`gpt-6.1-sol / high`）。当前工具未提供执行器模型元数据，且本机当日 sessions 目录不存在，无法独立核验实际运行参数；不宣称已从日志核实，没有主动切换模型或启动子代理。
+- 当前发行锁为 Android/RN `13.6.1-particle.25`、iOS `6.29.0-particle.25`，构建冻结源 `f32f6f45fd359007e8b3c77911b66d9e7fc93848`；本修复不改 Source Lock/发行物，不声称已进入 v25 制品。
+
+## 必做项
+
+- [x] 读取 Astra 指导、AGENTS、PARTICLE_BASELINE、规范、四份当前总则、当前 STEP-119 任务/实现/测试资料，核对现有四文件 diff。
+- [x] 同次 source prepare 获取 raw owner 和 Y 排序引用列表；仅比较地址完成同源校验，再复制当前 ID/atlas。
+- [x] 同 Bucket/Atlas 的完整 tile/pass 组先检查，再全部重新绑定当前 owner/RenderTile；不逐帧重建 Drawable/tweaker。
+- [x] Bucket/Atlas/组内成员失配或缺 atlas 时移除整组，走原创建路径；Text/IconRGBA/IconSDF/Halo 使用同一 atlas 与实际 tweaker 配对。
+- [x] Retained 使用内部强引用 atlas 和当前地址映射，不沿旧 Drawable 裸指针读取 atlas/Tile；缺证立即 complete=false。
+- [x] 保活 RenderTile → renderData → LayoutResult 的证据资源，不把每次 prepare 的 owner 地址写入比较字节。
+- [x] 编写并静态核对 13 项 SymbolRetainedLifetime GTest 源码，修正 atlas-only TileRenderData 查询默认 assert 的测试替身缺口。
+- [x] 中文 Step、完成报告及开发记录末尾追加；四源码路径 scoped diff 空白检查 exit0。
+- [ ] RDC 实际编译/链接并发现、运行生命周期与 STEP-119 定向 GTest。
+- [ ] Android OpenGL、Metal 实际路径验证与 Vulkan 编译兼容性证据。
+- [ ] 新源码锁/APK/SO 身份闭环、FZ-G1 动态生命周期、原24Gate、Full/Fast 视觉及释放验收。
+
+## 修改范围与当前结果
+
+生产修改限 `src/mln/gfx/symbol_drawable_data.hpp`、`src/mln/renderer/layers/render_symbol_layer.cpp`、`src/mln/renderer/layers/render_symbol_layer.hpp`；测试限 `test/renderer/retained_underlay_cache.test.cpp`。沿用此前修改，续作只补未知 Symbol 类型拒绝、测试替身空查询覆盖、Text/Icon/SDF/Halo 连续 prepare 稳定性与证书资源释放检查。
+
+未改 RN/JNI 公共 API、原24Gate/证书判据、Placement、缓存开关、发行物、Integration、旧报告或两份保护任务书。未运行 CMake、编译/链接/语法编译、GTest、Gradle/APK、ADB/安装、Jest；没有新制品或设备数据。
+
+## 阻塞与下一步
+
+实现已落盘，可编译性与运行正确性仍待 RDC。现 verifier 会拒绝 tracked dirty，后续 Git 来源锁须在独立审计和另行授权后处理；本轮禁止 Git 收尾，不能绕过 verifier 或借旧 APK。历史 Metal/libuv 缺口未重新验证，不安装升级依赖。
+
+RenderTile 容器不拥有底层 `Tile&`；强引用 atlas/texture 也不能证明原地像素或槽位不变，继续依赖既有 content epoch 和真实绑定复核。原始寄存器 tombstone 缺失，不能断言 `0x8cdc7c` 唯一根因为本缺陷；保留原 SO Build ID `485459ba44f806ef0a0c08633c717bfd5d82ad8f` 与匹配符号交 RDC。
+
+准确命令、测试覆盖限制、停止门槛和交接证据见 [本轮完成报告](../报告/STEP-119_SymbolRetained生命周期修复_Codex完成报告_v1.md)。Codex 到此交接，RDC 独立审计后逐条验证；失败保留首错与现场，不放宽条件。

docs/50_Step记录/STEP-119_Symbol缓存实际实现_v1.md

@@ -0,0 +1,85 @@
+# STEP-119 Symbol缓存实际实现 v1
+
+日期：2026-10-11（JST）。状态：进行中；代码阶段IMPLEMENTED_WAITING_ANDROID，独立验收未完成。
+
+## 目标与基线
+
+实现Shared Core内部最终Symbol结果证书，解决静止真实PBF派生R首次Build逻辑自举死锁，支持后续Reuse/Fast，同时保护所有真实渲染失效与原24Gate。
+
+particle/main@869930046b11dbeb3b147e3be952a2e847316292；Mac.lan/Darwin24.6.0/x86_64。Native13.6.1-particle.23；Integration本地HEAD80667d6c343411d03a760425438e3d292f452118，只读。实际会话rollout 01a1299f-0c2b-78b0-8599-e50812c108dd的turn_context核实gpt-6.1-sol/high，未升级、未启动子代理。
+
+## 必做项
+
+- [x] 读取根规则、规范/总则、当前任务、Integration规则与STEP112–118关键证据，核对实际Renderer/Placement/Bucket/Atlas/GL/Metal。
+- [x] 实现真实上传输入证据、revision/epoch、完成Full/Build/Reuse绑定，global/perSegment/preparedScene同时接线。
+- [x] 分离stale刷新需求与真实fade；保留原Placement算法/原Style/Source/公开API/ABI。
+- [x] 完成13项非Jest C++针对性测试源码，两个文件均已登记。
+- [x] 中文调查、阶段记录、实机联合验收计划、完成报告与开发记录追加。
+- [x] 轻量静态范围/原证据哈希/git diff --check检查。
+- [ ] Native编译与13项GTest实际运行，GL/Metal真实代码路径独立验证。
+- [ ] 同源新APK/设备SHA与>=90秒真实Build>0、Reuse>0、FastDelta>0、24Gate mismatch0。
+- [ ] 原63缺tide负对照、全部失效矩阵、Full/Fast视觉与iOS/Metal独立验收。
+
+## 允许与禁止范围
+
+仅内部Shared Core/原生shader来源薄接入、已登记C++测试与本Step文档。未修改include公开头、RN/JNI/ObjC/Java/Kotlin、正式PBF/URL/Style、天气语义、Core-owned timeline/playback、发行版本或Integration协议。
+
+没有Gradle/ADB/Native构建/Bazel/Jest/codegen/commit/push；没有更改STEP110/111未跟踪任务书或Git忽略原设备证据。没有修改长期项目总则、RDC Runner或后台执行器。
+
+## 当前结果
+
+两次成功Full取证的同一settled GPU输入版本可建立R Build，成功Full Reuse后才允许Fast。真实opacity clamp、动态/paint属性、UBO、索引/排序/tiles、atlas/shader身份、registry ordinal/depth与异步epoch共同参与；缺失证明仍Full。
+
+普通Full销毁旧RenderTree时保留复制证据，真正reset时清理；否则两帧比较仍会自举失败。原24Gate evaluator/掩码/顺序/计数和公开诊断结构没有修改。STEP117历史保守helper与断言保留，生产接线改为最终结果证书。
+
+源码没有运行验证，不宣称当前设备已从STEP118的Build0/Reuse0/Fast0改善。证书明确绑定编码/提交成功，GPU完成与像素仍需独立验收。Vulkan/WebGPU无本轮原生shader来源登记，Symbol证书继续fail-closed，普通Full不变。
+
+## 阻塞与下一步
+
+本工作区未锁定源码；既有验证器会拒绝tracked dirty，不能绕过。历史Mac缺libuv，本轮没有重跑配置。新的Native可编译性、真实PBF输入是否低于16MiB、实际GPU等价、异步竞态与性能均待证。
+
+立即交RDC按本Step联合验收计划独立审计、在其授权范围完成源码锁/定向Native验证，并集中一次APK build/install/真实设备验收。失败保存证据，按固定Codex修复→RDC验证闭环；未通过不得标完成/冻结，不自行执行下一阶段。
+
+## RDC独立编译检查记录（2026-10-11 JST）
+
+用户明确要求编译然后测试，并要求不要因本次功能无新第三方依赖而破坏已存在原生环境。RDC先同步核实Integration origin/main=80667d6c343411d03a760425438e3d292f452118与Particle origin/particle/main=869930046b11dbeb3b147e3be952a2e847316292，且保护的两份STEP110/111未跟踪MD的SHA未变。
+
+Mac Metal原生CMake配置首次因PATH找不到cmake而失败，改用既有/usr/local/opt/cmake/bin/cmake后，配置因早已缺少的libuv失败（不是本轮代码引入的依赖）。Homebrew建议连带升级CMake、Python和OpenSSL，RDC及时中断该安装并复核原CMake仍存在、无libuv新依赖安装。**Mac Metal CMake/GTest仍未运行，不能记PASS。**
+
+改走原项目已存在 Android NDK OpenGL/x86_64 compile_commands.json，保持实际C++20警告/Werror、不加Wno-error、不切宏、不改源数据。编译实际Core生产7文件（placement.cpp、render_symbol_layer.cpp、symbol_layer_tweaker.cpp、render_orchestrator.cpp、renderer_impl.cpp、renderer.cpp、shader_program_gl.cpp）与两个非Jest已注册GTest源码，合计9个编译单元，经过本地定点修复后全部严格 -fsyntax-only exit0（每文件独立日志保存在Git忽略artifacts/maplibre-particle/step119-native-syntax/）。本轮修复3处小编译缺口：SymbolLayer及Retained test各一处toString补上util命名空间，Orchestrator error test将构造结果从const Mutable转换为Immutable，保留测试语义。该结果是**Android NDK语法/类型检查**，非真实链接、GTest运行或Metal构建。
+
+下一关：RDC scoped Git锁定源码后，基于新源码一次集中标准Android Gradle/OpenGL x86_64 APK构建；FZG1-2安装和STATIC_RC_NO_TIDE 90秒验证。任何编译/设备错误继续按原步修复，不能绕过24Gate或声称Fast已通过。
+
+## RDC Android原PBF实机正负对照（2026-10-11）
+
+本轮源码锁 3d989a00a822989339a6d7cb4d23acc04396670e、APK SHA 57d68800770d431a2ce9247406f636e7a01cc19fccaf4c59f5eb3a7c99128135，Mac标准Android OpenGL x86_64 APK真编译/链接/打包PASS；FZG1-2安装SHA一致、preflight PASS。新STATIC_RC_NO_TIDE 90.010秒：Native64/R[0,62)，missingSourceIds=[]，Cache Build=1 / Reuse=3276（累计）、FastDelta=1819 / FullDelta=0、24Gate mismatch=0。原STATIC_RC 90.010秒：原Native65/R[0,63)，missingSourceIds=[tide]，Build=0、Reuse=0、FastDelta=0、FullDelta=305，fail-closed仍正常。新13项GTest运行/Metal/iOS/动态源变更与像素对比均未完成，保持ANDROID_FAST_CORE_PASS/OVERALL_PARTIAL。详细原始数据和sha见 docs/60_测试/STEP-119_FZG1_原PBF真实Fast验收结果_20261011.md。
+
+- 2026-10-11 STEP119实机首次FAST_OBSERVED：APK源3d989a00a822989339a6d7cb4d23acc04396670e SHA=57d68800770d431a2ce9247406f636e7a01cc19fccaf4c59f5eb3a7c99128135，FZG1-2安装/preflight PASS；STATIC_RC_NO_TIDE 90秒 FastDelta1819/FullDelta0、R Build1/Reuse3276、24Gate mismatch0、Native64，missingSourceIds=[]。仅正向目标首次通过，负例/视觉/GTest/iOS未验，STEP119 PARTIAL。详见 docs/报告/STEP-119_Android真机Fast首次通过_阶段验收_v1.md。
+
+## RDC STEP-119 RCRR 多配置续验（2026-10-11 JST）
+
+- Integration origin/main 经 RDC 同步核验为 `80667d6c343411d03a760425438e3d292f452118`；Particle 起点 `46c88b0209474376225b54ae0ad701881673743d`，仍在 `particle/main`；两份 STEP110/111 未跟踪任务文档未触碰。
+- 同一已安装 APK 源 `3d989a00a822989339a6d7cb4d23acc04396670e`，SHA `57d68800770d431a2ce9247406f636e7a01cc19fccaf4c59f5eb3a7c99128135`，真机原 `PARTIAL_RCRR` 80秒：R0 Build0/Reuse0/missing tide；R2/R3 各 Build1/Reuse536；FastDelta0/FullDelta596、decisionMismatch0。即局部复用有效、全帧 Fast 安全拒绝。
+- 真机导出原63层 `styleParity.baseLayerManifest` 确认 tide=2、sea=3、clip-outline=31、special=37；天气实际在原宽 C 中，不在 R0。由此修正早期错误的分段位置推测。
+- Test App 增加三种 `RCRR_*_NO_TIDE` 场景，分别测试窄 C、宽 C 与错误动态 R；基于上述真实 Manifest 校准成 Native64 精确 R/C 区间，未修改正式 PBF/原场景/24 Gate。验证器精确验三段 R 边界；4项 Python unittest PASS、Style Manifest 静态索引核对 PASS、git diff --check PASS。
+- **尚未完成**：新 Kotlin Test App 的用户手工 APK 编译及三场景真机 90秒回归、图像目视、Camera/Source/Style/Tile/Annotation/Context 真机失效和恢复、STEP119 13项 GTest 真跑、Metal/iOS。Mac 原有 libuv 缺失限制保持，不擅自安装或升级工具链。STEP-119 **PARTIAL，不 CLOSED**。
+- 文档：`docs/60_测试/STEP-119_RCRR多配置验收矩阵_v1.md`、`docs/报告/STEP-119_RCRR多场景局限性_阶段验收_v1.md`。原始真机记录位于 ignored `artifacts/maplibre-particle/android-validation/step119-rcrr-observe-20261011_172720/partial_rcrr/`。
+
+## RDC STEP-119 粒子独占 C 与 CPU 效率收敛（2026-10-11 JST）
+
+- 用户确认：RCRR 正常运行的 `CONTINUOUS` 原则上**只含 `RasterParticleLayer`**，`WeatherColorLayer` 与其他非逐帧图层在 R；下一轮验收必须结合 CPU/帧、CPU/秒和实际 FPS，不只观察 FastDelta。
+- RDC 已同步 Integration `main`=`80667d6c343411d03a760425438e3d292f452118`；Particle 以 `1072816740fa69b7b23cd70602a402be19e5be2a` 为起点，现有 `particle/main` 与 STEP110/111 未跟踪文件不变。
+- Native 源码检查确认 `singleContinuousSegment(plan)` 是 Fast 准入条件，Fast 上传/绘制仅访问 C 范围，所有 R 需满足原24 Gate 与真实 Render/Symbol 缓存证书；WeatherColor 放 R 后是否能安全 Build/Reuse 尚待真机验证，不能提前 PASS。
+- 将 `RCRR_C_NARROW_NO_TIDE` 改为粒子独占 C[32,33)（WeatherColor 在 R[0,32)），新增 RCR 两 R、RCRRR 四 R，以及同 Style/Plan 关闭缓存的 Full 对照；保留旧 C 宽、粒子误入 R 两种负例和原63层 `PARTIAL_RCRR`。菜单 ID 改为100～102避免新增enum与操作冲突。
+- 新增严格 SHA/HEAD/设备锁的 CPU 采样器（App进程 utime+stime、6秒采样、35秒warmup、90秒观测）、A-B-A 对照比较器；对照同时列 CPU核秒/秒、CPU估算ms/完成帧、Native FPS、FastFraction≥95%、Build/Reuse/Invalidate。ADB实机只读确认 `CLK_TCK=100`，未以旧APK冒充新测试；未进行Android编译。
+- Python 非Jest结构+CPU测试 12项 PASS。正式测试矩阵 `docs/60_测试/STEP-119_RCRR多配置验收矩阵_v2.md`，本轮阶段报告 `docs/报告/STEP-119_粒子独占C与CPU效率_阶段验收_v1.md`。
+- **待验**：用户手工编译、安装新APK及Full-Fast-Full CPU实测，三种粒子独占C布局的Build/Reuse/Fast、视觉等价、变更后失效与恢复，13项GTest/Metal/iOS。STEP-119继续PARTIAL、不宣称CPU性能提升。
+
+## RDC 2026-10-11 STEP-119 粒子独占 C 与 CPU 实机综合验收（续）
+
+- 用户已明确授权 Mac RDC 执行 Android APK 编译/安装及综合测试。Integration main 已同步到 `80667d6c343411d03a760425438e3d292f452118`；APK 真机源码 Commit 为 `32ac795fc4abd04006673bf644f87a711329e78f`；x86_64 APK SHA-256 为 `2bbd1cb4dc9e03ec56d8404363970e56f76b03819f6f2b50c8aee6dbb6fa43d2`，Mac build exit0、设备压缩下载解压 SHA 同源、`pm install -r` Success exit0、安装 Base APK 同 SHA、严格 preflight exit0。
+- CPU 测量工具首次 `sh -c` 多参数读取阻塞 exit3；随后采用单个 ADB shell 命令并保存 warmup+末尾日志的临时修正测量，第一组 Full 不齐整 exit2排除。最终 9次Benchmark中8次有效：2×Full、3×RCRR（三R）、2×RCR（两R）、1×RCRRR（四R）。全部24 Gate完整、判定失配0、同 APK/Style指纹、固定相机与场、Native最后120帧窗口119 Fast/0 Full（正向组）。
+- 实测进程CPUms/完成帧中位：Full 60.67ms，RCR 3.50ms，RCRR 7.04ms，RCRRR 7.82ms；RCR两次3.30/3.70ms，RCRR三次6.96/7.04/7.37ms。RCRR Full-Fast-Full 基线漂移2.70%，中间 Fast约55FPS、CPUms/帧7.04，相对Full估算降低88.40%。RCR约59.4–59.7FPS、CPU占单核约19.7–22.0%，比RCRR在该固定场景更省 CPU。仅为进程级CPU近似，不证明GPU、耗电。
+- 两种负例独立90秒：宽 C 海图混入 `Fast0/Full+339`、Particle误入R `Fast0/Full+322`，两者均24 Gate完整、`decisionMismatch=0`、`unsupported-continuous-layer`安全拒绝；严格验证器返回2属于预期负例 PASS，并非进程崩溃。
+- 定向验证中每个正向 R 都曾 Build1，稳定采样窗口 BuildDelta/InvalidateDelta=0，Reuse持续增加。天气切换后的 R 刷新、相机/源/Tile/Annotation/Context生命周期、Full与Fast的视觉同等、GPU计时、iOS/Metal、13个GTest仍未证实；STEP119 **PARTIAL**，不将稳态验收写成CLOSED。
+- RDC 将临时已实际运行的 CPU 采样器 `sh -c` 与日志边界修正合入正式Python测试脚本，**不重新构建/修改当前已验APK**；Python 12项 PASS，Git收尾只包含此脚本、阶段报告、Step记录与开发记录。正式结果：`docs/报告/STEP-119_RCRR粒子独占C_CPU真机验证_阶段报告_v2.md`，综合数据 `artifacts/maplibre-particle/android-validation/step119-rcrr-cpu/compare-20261011_193724.json`（本地忽略目录）。

docs/60_测试/STEP-114_独立FastSmoke场景与RDC验收_v1.md

@@ -0,0 +1,172 @@
+# STEP-114 独立 Fast Smoke 场景与 RDC 验收 v1
+
+日期：2026-10-11。状态：**源码交付；下列编译、测试和设备操作全部 NOT RUN。** Codex 不执行本页命令。Mac Native 由 RDC/普通 Terminal 独立执行；Android 构建、安装、ADB 与实体机步骤由用户在后续授权条件下手工统一执行。
+
+## 1. 场景入口和范围
+
+Test App：`STEP 093 → STEP-114 独立 FAST_SMOKE（非正式 PBF）`。正式网络 PBF 仍在 `STEP 093 → STEP-113 FZG1-PBF GATE`，保留 PBF63、STATIC_RC、PARTICLE_OFF、PARTIAL_RCRR、SOURCE_CHANGE 原实现。
+
+| 独立场景 | 预期层序/保护 | 待验收结果 |
+|---|---|---|
+| FAST_SMOKE | R=background + 非空本地 GeoJSON/circle；C=WeatherColor + RasterParticle。无 Annotation 实例时删除空内建 Annotation layer，保留 source | Native 实际4层；R Build/Reuse 和 Full/Fast 必须真实增长 |
+| CIRCLE_C_BLOCKED | baseline 后追加普通 circle C；Annotation 层仍按独立空场景移除 | 实际5层，#22/#23 阻止 Fast；R 可正常 Build/Reuse，不等于整个 scene 可 Fast |
+| ANNOTATION_BLOCKED | baseline 加正常自动内建 Annotation Symbol C，并创建真实 marker；不删该层 | 实际5层；#22/#23 阻止 Fast；marker 可见、可单次 position 更新 |
+| SYMBOL_R_BLOCKED | baseline 的 R 内加本地16×16图标 Symbol；无需网络 glyph/sprite | 实际5层；Symbol R 首建仍被 Placement gate 阻止；不能把关闭 transitions 当修复 |
+
+全部使用既有离线 ECMWF canonical 双帧资产、固定预报 `1786060800000` ms、PAUSE、30fps目标和1024粒子，SDK camera 初始33.45/129.97、zoom10.5、bearing/pitch0；手势禁用且退出恢复。30fps目标不是实际帧率测量。actualForecastTimeObservedMs 保持 null，不能当成 Native 已回读请求时间。sceneReady 只表示加载回调与控制命令成功，不替代 Native 层表/valid/实际渲染核验。
+
+不要在旧正式 V23 APK 上验收本轮新入口；版本号未变，必须保存本轮源码 diff/hash、build-info 的 dirty 状态与 APK SHA。不得发行或覆盖已有版本。
+
+## 2. Mac Native 精确定向命令（仅 RDC 执行）
+
+基于现有 `macos-metal` preset 和实际 `mbgl-test-runner` target，无全仓测试、无 Jest。STEP-113 曾缺 libuv；本轮没有安装依赖。配置失败则停止，不运行旧 runner。
+
+```bash
+cd /Users/tei/dev/MapLibreParticleLab
+bash <<'SH'
+set -eu
+mkdir -p artifacts/maplibre-particle/step114-native
+if cmake --preset macos-metal > artifacts/maplibre-particle/step114-native/configure.log 2>&1; then
+  echo 'configure exit=0'
+else
+  step114_rc=$?
+  tail -n 80 artifacts/maplibre-particle/step114-native/configure.log
+  exit "$step114_rc"
+fi
+if cmake --build build-macos-metal --target mbgl-test-runner --parallel 3 > artifacts/maplibre-particle/step114-native/build.log 2>&1; then
+  echo 'build exit=0'
+else
+  step114_rc=$?
+  tail -n 80 artifacts/maplibre-particle/step114-native/build.log
+  exit "$step114_rc"
+fi
+if build-macos-metal/mbgl-test-runner --gtest_filter='Step114FastPathSafety.*:FastGateTrace.*:ParticleFastPath.*:RetainedUnderlayCache.*:RetainedUnderlayRevision.*:RenderSegmentPlacementFree.*:RenderSegmentLocality.*:RenderSegmentPlan.*:RenderSegmentDiagnostics.*:RenderOrchestratorError.*:RenderOrchestratorTeardown.*:ImageManager.*:GlyphPBF.*' --gtest_color=no --gtest_output=xml:artifacts/maplibre-particle/step114-native/tests.xml > artifacts/maplibre-particle/step114-native/tests.log 2>&1; then
+  tail -n 20 artifacts/maplibre-particle/step114-native/tests.log
+else
+  step114_rc=$?
+  tail -n 80 artifacts/maplibre-particle/step114-native/tests.log
+  exit "$step114_rc"
+fi
+SH
+```
+
+记录 configure/build/tests 各退出码、耗时、实际测试数量与是否 skipped；失败回传首个真实 error、target、必要上下文与日志路径。新增测试应实际发现3个 `Step114FastPathSafety` 用例，否则不能把空过滤器执行成功作为 PASS。这些主要是纯状态机/结构判定测试，**不能证明 Android GPU Fast 命中、帧像素一致或 iOS 设备通过**。
+
+## 3. Android 后续一次集中手工验收
+
+由用户手工，在设备 ABI=x86_64 且 Java17/SDK 环境满足现有规范时，运行唯一既有 Validation Pipeline；不自行改 ABI、build 参数或依赖，不全量 clean。
+
+```bash
+cd /Users/tei/dev/MapLibreParticleLab
+./tools/particle_android_validation/build_validation_apk.sh
+```
+
+失败保留 build.log，禁止复用旧 APK。用户手工核对同包签名和数据后再安装；本页不授权卸载用户数据。下面 ADB 全部固定既有 FZG1-2 serial，仅作为用户后续手工命令：
+
+```bash
+adb -s 192.168.200.139:5555 shell getprop ro.product.cpu.abi
+adb -s 192.168.200.139:5555 install -r artifacts/maplibre-particle/android-validation/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk
+adb -s 192.168.200.139:5555 shell am start -S -n org.maplibre.android.testapp/org.maplibre.android.testapp.activity.particle.ParticleCoreLayerValidationActivity --es step114_scenario FAST_SMOKE
+```
+
+启动后预热10秒，再观察60秒。在开始和结束分别点击“导出当前 Native 快照”。标签 `STEP114Gate` 每30秒只输出真实 Native 摘要，完整JSON写 App 私有 files。生命周期计数可以含预热，必须比较同 lifecycle/sceneGeneration 的两次计数 delta；不要称整个累计为60秒帧率。
+
+菜单“单次更新 R GeoJSON”“Pan/Zoom 往返”“单次 Image 变更”“禁用/恢复缓存”保存 before/submitted/100/500/1500ms 的5份快照。一次只做一项，等恢复稳定并手动导出后再做下一项。自动文件有 actionSequence 和 phase，不追加 candidate 输入或人工 frame 结果。
+
+每个负场景单独启动、预热、观察、导出，不把以下命令连续执行当验收：
+
+```bash
+adb -s 192.168.200.139:5555 shell am start -S -n org.maplibre.android.testapp/org.maplibre.android.testapp.activity.particle.ParticleCoreLayerValidationActivity --es step114_scenario CIRCLE_C_BLOCKED
+adb -s 192.168.200.139:5555 shell am start -S -n org.maplibre.android.testapp/org.maplibre.android.testapp.activity.particle.ParticleCoreLayerValidationActivity --es step114_scenario ANNOTATION_BLOCKED
+adb -s 192.168.200.139:5555 shell am start -S -n org.maplibre.android.testapp/org.maplibre.android.testapp.activity.particle.ParticleCoreLayerValidationActivity --es step114_scenario SYMBOL_R_BLOCKED
+```
+
+ANNOTATION_BLOCKED 点击“单次更新真实 Annotation”，截图应见位置变化，Native 保持 fail-closed。FAST_SMOKE 中点击该操作会明确 BLOCKED（没有 marker），不创建隐藏 Annotation 或假事件。
+
+## 4. 回读完整快照（用户手工）
+
+在普通 bash Terminal 保存全部 step114 JSON，不通过 Logcat 分块拼接。路径来自当前 Debug App：
+
+```bash
+cd /Users/tei/dev/MapLibreParticleLab
+bash <<'SH'
+set -eu
+mkdir -p artifacts/maplibre-particle/android-validation/step114
+adb -s 192.168.200.139:5555 shell run-as org.maplibre.android.testapp ls files > /tmp/step114-files.txt
+tr -d '\r' < /tmp/step114-files.txt > /tmp/step114-files-normalized.txt
+while IFS= read -r step114_file; do
+  case "$step114_file" in
+    step114-*.json)
+      adb -s 192.168.200.139:5555 exec-out run-as org.maplibre.android.testapp cat "files/$step114_file" > "artifacts/maplibre-particle/android-validation/step114/$step114_file"
+      ;;
+  esac
+done < /tmp/step114-files-normalized.txt
+SH
+adb -s 192.168.200.139:5555 logcat -d -v time -s STEP114Gate:I '*:S' > artifacts/maplibre-particle/android-validation/step114/device.log
+adb -s 192.168.200.139:5555 logcat -b crash -d > artifacts/maplibre-particle/android-validation/step114/crash.log
+adb -s 192.168.200.139:5555 exec-out screencap -p > artifacts/maplibre-particle/android-validation/step114/screen.png
+```
+
+每阶段独立命名截图/日志；同名覆盖前先归档。App files 自动快照只在显式操作和生命周期变化时创建，数量无硬上限；验收后由用户管理归档，Codex 不删文件。100ms采样也可能错过一帧的变更窗口，未捕获不能标反向 Gate PASS，需保留日志再复核。
+
+下面是读取**实际导出文件**的正向检查；把路径替换为稳定 FAST_SMOKE 手动快照的明确文件名（不要随意用最后的 teardown/旧场景文件）：
+
+```bash
+python3 - 'artifacts/maplibre-particle/android-validation/step114/替换为稳定FAST_SMOKE文件.json' <<'PY'
+import json, sys
+from pathlib import Path
+d = json.loads(Path(sys.argv[1]).read_text())
+assert d['scenario'] == 'FAST_SMOKE' and d['sceneReady'] and d['blockedReason'] is None
+n = d['native']; t = n['fastGateTrace']
+assert n['valid'] and n['styleLayerCount'] == 4
+assert [l['layerType'] for l in n['styleLayers']] == ['background', 'circle', 'weather-color', 'raster-particle']
+assert [s['strategy'] for s in n['segments']] == ['RETAINED', 'CONTINUOUS']
+r, c = n['segments']
+assert (r['beginIndex'], r['endExclusive'], c['beginIndex'], c['endExclusive']) == (0, 2, 2, 4)
+assert not r['placementCapable'] and r['placementGatePassed']
+assert r['cache']['sourceReady'] and r['cache']['sourceStable'] and r['cache']['supported']
+assert r['cache']['build'] > 0 and r['cache']['reuse'] > 0
+assert t['fullRendered'] > 0 and t['fastRendered'] > 0 and t['decisionMismatch'] == 0
+assert len(t['gates']) == 24
+fs = [f for f in t['frames'] if f['completed'] and f['outcome'] == 'fast-rendered'
+      and f['post']['configRevision'] == n['configRevision']
+      and f['post']['topologyRevision'] == n['topologyRevision']
+      and f['post']['contentRevision'] == n['contentRevision']]
+assert fs, '完整窗口没有真实完成的 Fast 帧'
+for f in fs:
+    assert f['candidate'] and f['decisionConsistent'] and f['knownMask'] == 0xffffff and f['failMask'] == 0
+    assert f['gateStatus'] == ['PASS'] * 24
+    assert not f['cacheInputsTruncated'] and f['cacheInputs']
+    assert all(x['valid'] and x['buildRevision'] == x['staticRevision'] for x in f['cacheInputs'])
+    assert f['post']['fullCpuFrame'] == f['pre']['fullCpuFrame']
+    assert any(x['actualExecution'] == 'composite' for x in f['post']['retained'])
+print('仅此快照 Native 正向证据通过；反向/生命周期/视觉/双平台仍需独立验收')
+PY
+```
+
+不能通过修改导出的 JSON、补造 frame、重命名旧文件或放宽断言制造结果。
+
+## 5. 定向反向、生命周期与回归矩阵
+
+| 项目 | 必需证据/接受条件 |
+|---|---|
+| 稳定 baseline | 两次同生命周期快照 Fast/Reuse delta>0；至少一个 completed Fast 的24 Gate全通过；Build>0；orange R circle可见，天气/粒子正常；decisionMismatch=0 |
+| Source mutation/异步 Tile | 单次sourceMutationCount增长；sources 表及 lastMutation 定位 step114-r-geojson；content/source revision变化；#8/#5/ready/pending 等真实拒绝证据、成功布局后 Full/Build 增长再恢复 Fast。tombstone/失败布局用Native状态机用例补充，不冒充GPU验证 |
+| Image 更新 | images signature/content/global revision 导致 Full；重建后恢复。baseline图标未引用也保守失效；不能宣称已验证 glyph atlas像素 |
+| Glyph | baseline完全无文字；本轮未新增 glyph mutation Test App控制。已有 GlyphPBF/ImageManager 测试仅资源回归；真实 Symbol glyph URL/font/atlas变化属于 Symbol结果证书阻塞，NOT VERIFIED，不能以image替代 |
+| Pan/Zoom 往返 | SDK cameraObservedFromSdk与Native gate/key对应，Full/Build增量；恢复相机后不能直接复用旧key；截图无陈旧circle/错位 |
+| 缓存禁用/恢复 | 禁用时#2失败、实际Full/live，无completed Fast增长；恢复后合法Build与Fast恢复；比较截图确认R内容/层序一致 |
+| Reload | 保存reload-before与加载后快照；sceneGeneration变更、Native当前层表/plan正确，重新Build；trace lifecycle仅在实际Native reset时变，不要求UI generation=Native lifecycle |
+| 非粒子C/真实Annotation | CIRCLE_C_BLOCKED/ANNOTATION_BLOCKED稳定窗口#22/#23失败、无completed Fast；真实marker可见/位置变化；#24是短暂pending保护，不要求在3秒末态仍FAIL |
+| Symbol R | 本地icon可见；R placementCapable=true，正常Full placementGatePassed=false/Build0或对应安全fallback；Fast不放行，scene #23可能另挡；无证书不改判定 |
+| 前后台 | baseline导出、手工Home后台10秒、回前台观察/导出；pause-before文件、恢复后Native增长、无死循环/错层/crash。此处未强制改变WeatherRuntime播放语义 |
+| Teardown/重建 | 退出场景/关闭Activity产生teardown-before，dispose与callback取消；用户确认MapView销毁返回/无crash，重新启动baseline。teardown-before不是销毁完成证明 |
+| 原PBF5场景 | 分别采集STEP-113五场景；仍保留全部基础63层定义/顺序及Annotation；缺tide时应明确missing-source，CustomMVT若实际出现仍unknown；不要求生产Fast>0、不篡改旧统计 |
+| 原STEP-102 | T1/T2/T3/T4 fixture和既有动态poll回归；尤其含Symbol路径不因本轮无Symbol优化被放行 |
+| iOS/Metal | 同Shared Core源码的Mac Metal定向测试先执行；iOS实机与GPU像素/性能未验收。Android Fast成功不能替代此项 |
+
+## 6. 收口规则
+
+记录各场景来源commit/dirty diff、APK SHA/版本、device serial/ABI、真实Native层表/plan、before/after文件与SHA、24Gate、Full/Fast/Build/Reuse增量、截图、首错及crash日志。processSimulationAdvance是进程级，不作为单Map Fast证据。post的原始 placementTransitionActive仍可能true，但无Symbol的preFastPlacementTransition=false是本轮受控变化，decisionMismatch应仍0。
+
+没有真实Fast或反向证据不足，保持 PARTIAL；Symbol证书/CustomMVT/C放行分别继续 BLOCKED/fail-closed。不得根据静态检查、runner退出0或APK成功宣称整个Fast Path修复/性能PASS。Codex未commit/push，RDC后续Git收尾另需明确授权与scoped路径，不包括STEP-110/111或正式发行。

docs/60_测试/STEP-116_FZG1_原PBF实机验收结果_20261011.md

@@ -0,0 +1,57 @@
+# STEP-116 原 STEP-113 PBF 专用 APP 实机测试报告
+
+日期：2026-10-11 JST；结论：**PARTIAL。空 Annotation / C 段结构修复确实有效；原 STATIC_RC 进入 Fast Path 的目标未达成（FAIL）。**
+
+## 1. 用户授权与源码/设备闭环
+
+用户明确授权本次由 RDC 执行标准 Android APK 编译、安装和专用 APP 测试。环境：Mac.lan，仓库 /Users/tei/dev/MapLibreParticleLab，Particle源码commit c48a72a9d492ea0d05e4d58464f9643453158d50；Integration main 80667d6c343411d03a760425438e3d292f452118。Git tracked clean；两个STEP110/111用户文件仍未跟踪且不改动。Android Test App版本字符串13.6.1-particle.23，本轮真实二进制以commit和SHA而不是版本名辨识。
+
+RDC执行标准 tools/particle_android_validation/build_validation_apk.sh，进程退出0，Gradle与APK pipeline回报BUILD SUCCESS，构建Native OpenGL/x86_64、Kotlin、ZIP/strip/体积检查通过。Java17；APK文件66,603,829字节，libmaplibre.so未压缩40,035,512字节。APK SHA-256：
+
+a8b7f4e0f8e026bde8835e18a04876062be84cce3a3749a511cb08605d9f8a35
+
+设备FZG1-2，ADB serial 192.168.200.139:5555。实际adb install -r返回Performing Streamed Install / Success，没有卸载应用或清空数据；pm path得到新安装base.apk，设备sha256sum与上述新APK完全一致。STEP115 Python工具的preflight-only返回PREFLIGHT_PASS，确认当前源HEAD、build-info、APK、设备ABI和安装包SHA完全匹配。build-info中的git_dirty=true来自构建前保护的两份未跟踪任务书，不是tracked源码变更。
+
+## 2. STEP-113原STATIC_RC的90秒结果
+
+RDC实际启动原 STEP-113 正式PBF STATIC_RC（非STEP114简化FAST_SMOKE），进程PID19771，同sceneGeneration=2/lifecycle=1，观察90.008秒。两份完整运行摘要一致且单调：
+
+- STATUS=NO_FAST_OBSERVED，工具exit=2（真实Fast目标未达成）
+- FastDelta=0，FullDelta=920
+- sceneReady=true，planValid=true，baseLayersPreserved=true
+- 原正式PBF基础63层定义/顺序保留；正式Style fingerprint e0f9c2d1df38ae5d5953b561c52efe2f8590336de80b988e1d2935580d30b996
+- Native实际层数65，R[0,63)、C[63,65)；C只包含rn-weather-color和rn-weather-particles
+- emptyBuiltinAnnotationLayerRemoved=true、annotationInstancesAtRemoval=0、annotationSourcePreserved=true；原内建Annotation Source仍在Native列表并Loaded
+- 实际Native Sources为mapple:raster、navsea_delivery:vector、org.maplibre.annotations:annotations、rn-weather-fields:raster-array；tide Source确实缺失
+- R Cache Build=0、Reuse=0；lastFallbackReason=missing-source、missingSourceIds包含tide；placementCapable=true、placementGatePassed=false
+
+RDC经设备菜单STEP093→STEP113→EXPORT LAST SNAPSHOT，回读真实Native完整JSON，大小274,693字节，SHA-256：
+
+cd491d2acca97119f1d4f2d6f77eb7b229c17b90d4be1181a59202308429b219
+
+完整120帧窗口验证：120帧、24项Gate、每帧knownMask=0xffffff、120/120 decisionConsistent=true、decisionMismatch=0；完成帧为119 Full、0 Fast；另1帧pending。
+
+| Gate | 最近120帧失败数 |
+|---|---:|
+| #3 cache-invalid | 120 |
+| #4 revision-mismatch | 120 |
+| #12 static-unstable | 105 |
+| #13 placement-or-fade | 105 |
+| #22 unsupported-continuous-layer | 0 |
+| #23 unsupported-scene | 120 |
+
+其他Gate当前窗口失败数为0。#22生命周期初期累计6次，不能称启动全程均无失败。#23仍因R不满足整体准入而持续失败。diagnostic decisionMismatch=0仅说明当前决策与trace一致，不代表Fast有效。
+
+## 3. 与旧STEP-113相对照及有效性判断
+
+原STEP-113旧APK的STATIC_RC Native层数66，多出内建org.maplibre.annotations.points Symbol落在C中，Gate #22/#23曾每帧失败，R Build=0、Fast=0。旧场景累计Full875，和新测试FullDelta920不是相同窗口/时长，不可据此计算帧率或性能提升。
+
+新APK实际65层、C仅两张天气层，最近120帧#22为零，证实STEP116针对空Annotation/C准入的**局部修复有效**。然而真实R中缺tide、Placement/Fade条件未稳定、R Build/Reuse仍为0，#3/#4/#12/#13/#23持续失败；**Fast仍为0，没有任何性能收益证据**。没有改动或删除原63层，不以STEP114烟测替代。
+
+## 4. 保存的证据和未覆盖的边界
+
+本机Git忽略路径：artifacts/maplibre-particle/android-validation/step113-retest-20261011_121308/static_rc/，包括result.json、launch.txt、logcat.txt、native-full.json、screen.png、ui.xml。本轮截图仅存档，尚未人工验收像素/航标显示；没有执行五场景全部回归、Annotation真实增删、缺源恢复、Camera/Tile/Image负例、iOS或Native GTest（Mac先前CMake缺libuv）。本轮当前正式PBF用户目标已获得明确失败结论，不得标CLOSED/PASS。
+
+后续必须由Particle Shared Core跨平台负责人确定R缺源零像素证明、Source同名重建的Full失效保证及Symbol Placement已提交GPU结果证书；不得伪造tide、删正式图层、禁用安全Gate或声称已有Fast性能改善。
+
+注意：若本结果文档随后产生新的纯文档Git commit，APK仍绑定上述c48a72a9源码。后续使用STEP115严格HEAD预检时，不能拿新文档HEAD冒充该APK源码，也不得为修改审计证据而重新标记APK编译来源。未执行GSRL正式发行、Source Lock或Tag。

docs/60_测试/STEP-116_STEP113原PBF专用APP验收_v1.md

@@ -0,0 +1,151 @@
+# STEP-116 STEP-113 原 PBF 专用 APP 验收 v1
+
+日期：2026-10-11（JST）。**以下命令交 RDC / 用户执行，Codex 本轮全部未运行。** 本轮源码状态 PARTIAL；缺 tide 与 Symbol R 准入仍阻塞，预期仍可能 Fast=0。不得拿 STEP114 Smoke 或旧 V23 APK 替代原 STATIC_RC。
+
+## 1. RDC 源码锁定和 Native 定向验证
+
+先重新读取 AGENTS、当前基线、STEP-116 审查/报告与 diff。审计包含 Native Annotation 修复的线程/生命周期、原63层逐层定义/顺序、移除对象重载、stop恢复、后续marker/style添加、五场景分支、生产Gate未变和七项新测试。执行只读命令：
+
+```bash
+cd /Users/tei/dev/MapLibreParticleLab
+git branch --show-current
+git rev-parse HEAD
+git status --short
+git diff --check
+git diff -- src/mln/annotation/annotation_manager.cpp src/mln/annotation/annotation_manager.hpp src/mln/renderer/render_segment_json.hpp test/api/annotations.test.cpp test/renderer/retained_underlay_cache.test.cpp platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/Step113PbfGateScene.kt tools/particle_android_validation/verify_step113_fast_path.py tools/particle_android_validation/README.md 粒子开发记录.md
+shasum -a 256 docs/40_任务/STEP-110_R0_Placement跨段归因只读调查_Codex任务_v1.md docs/40_任务/STEP-111_R段Placement结果等价与独立刷新可行性只读调查_Codex任务_v1.md
+```
+
+两任务书 SHA 应分别为 `33037df71b4b30aa7956d59f4b99f77af3085405b24111bc0fe11ec857a93db0`、`f3a5806f25384bf46055db2edfea0d21bfbc4124184bc813b46e38b8079c1ec4`。不要暂存它们。RDC按获授权的scoped流程收尾后，记录真正的最新HEAD；本报告起点 e2d202b 并不包含本轮修改。构建前 tracked 必须 clean；原未跟踪任务书可保留，build-info 的 git_dirty 不能单独用来推断源码不一致。
+
+Native 定向命令逐项执行，上一项失败立即停止，保存完整 stdout/stderr 与首个真实 error；历史缺 libuv 不当成新结果，不运行旧runner：
+
+```bash
+cmake --preset macos-metal
+```
+
+```bash
+cmake --build build-macos-metal --target mbgl-test-runner --parallel 3
+```
+
+```bash
+build-macos-metal/mbgl-test-runner --gtest_filter='Step116Safety.*:Annotations.*:FastGateTrace.*:ParticleFastPath.*:RenderSegmentDiagnostics.*:RenderSegmentPlacementFree.*:RenderSegmentLocality.*:RenderSegmentPlan.*' --gtest_color=no
+```
+
+Annotations.Step116 三用例使用现有 point_annotation 图像做实际渲染比较；不能仅检查 getLayer 指针就声称像素 PASS。账本/谓词用例不构成 GPU rendered Fast，Metal host 成功也不代替 Android OpenGL/设备回退。若依赖/编译阻塞，保持现场并在报告标 BLOCKED/NOT RUN，Android集中构建是否继续由用户安排。
+
+## 2. 用户一次手工 Android 构建与安装
+
+在锁定的最新 HEAD 上，用户手工依序执行，Codex/RDC不得代用户启动 Android 构建或安装：
+
+```bash
+cd /Users/tei/dev/MapLibreParticleLab
+git rev-parse HEAD
+git status --short
+./tools/particle_android_validation/build_validation_apk.sh
+```
+
+标准脚本使用 Java17、OpenGL/x86_64、strip native debug symbols，保存 build-info/build.log，检查 ZIP/ABI/体积/SHA。失败不得续用原路径旧 APK。
+
+```bash
+cat artifacts/maplibre-particle/android-validation/build-info.txt
+shasum -a 256 artifacts/maplibre-particle/android-validation/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk
+/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 install -r artifacts/maplibre-particle/android-validation/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk
+```
+
+记录源码HEAD、branch、精确修改文件/SHA、构建日志、APK大小/ABI/SHA、设备序号及型号。不能仅凭 `13.6.1-particle.23` 或安装 Success 认定是新源码。
+
+## 3. STEP115 preflight → 原 STATIC_RC ≥75秒
+
+用户安装成功后，由 RDC / 用户执行，serial/adb路径明确：
+
+```bash
+python3 -B tools/particle_android_validation/verify_step113_fast_path.py --adb /Users/tei/Library/Android/sdk/platform-tools/adb --serial 192.168.200.139:5555 --preflight-only
+```
+
+preflight 检查当前 tracked clean、build-info.commit==HEAD、APK SHA==build-info.sha256、设备 ABI x86_64、安装包 SHA==本地 APK。STALE_APK / SOURCE_NOT_LOCKED / SHA失败时停止，必须先纠正版本。PREFLIGHT_PASS只代表版本一致。
+
+```bash
+python3 -B tools/particle_android_validation/verify_step113_fast_path.py --adb /Users/tei/Library/Android/sdk/platform-tools/adb --serial 192.168.200.139:5555 --scenario STATIC_RC --seconds 90
+```
+
+使用90秒，脚本在取得 PID 后实际等待完整90秒（≥75秒）；加载太慢导致摘要不足则 INSUFFICIENT_SAMPLES / NO_READY_SUMMARY，不推断Fast。保留 result.json、logcat.txt、launch.txt、实际观察秒数。摘要须同sceneGeneration/lifecycle、planValid/basePreserved、24项、mismatch=0、累计计数单调；独立blocked日志和摘要撤销不能被早先Fast盖过。退出2为没有可接受Fast证据，退出3为版本/环境等阻塞，不能改成0制造PASS。
+
+`FAST_OBSERVED`仅指真实 Native fastRendered 增量>0，不是安全/像素/性能终验。要求原63层manifest、NavSea原PBF/Sprite/Glyph/Vector URI及定义/顺序不变，仅声明SDK空辅助层调整；正常静态预期Native65层/C仅weather-color和raster-particle，实际以新导出为准。PUBLIC PBF若变成非63层，场景保留现场并 BLOCKED，不更换简化Style来通过。
+
+## 4. 手动导出完整120帧及设备画面
+
+保持同次 STATIC_RC 运行，用户在 STEP093 → STEP113 菜单选择 EXPORT LAST SNAPSHOT。这是最近一次3秒共享采样，不额外渲染。以下由 RDC / 用户回读，必须核对所选文件确属本次新运行：
+
+```bash
+mkdir -p artifacts/maplibre-particle/android-validation/step116
+step116_file="$(/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 shell run-as org.maplibre.android.testapp ls -t files | tr -d '\r' | grep -E '^step113-STATIC_RC-.*[.]json$' | head -n 1)"
+test -n "$step116_file"
+/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 exec-out run-as org.maplibre.android.testapp cat "files/$step116_file" > artifacts/maplibre-particle/android-validation/step116/static-rc-full.json
+shasum -a 256 artifacts/maplibre-particle/android-validation/step116/static-rc-full.json
+/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 exec-out screencap -p > artifacts/maplibre-particle/android-validation/step116/static-rc-screen.png
+/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 logcat -b crash -d > artifacts/maplibre-particle/android-validation/step116/crash.log
+```
+
+`test -n`失败立即停止后续命令。同一个Full JSON先做离线证据结构检查（不是安全测试）：
+
+```bash
+python3 -B - <<'PY'
+import json
+from pathlib import Path
+p = Path('artifacts/maplibre-particle/android-validation/step116/static-rc-full.json')
+v = json.loads(p.read_text())
+assert v['scenario'] == 'STATIC_RC' and v['sceneReady'] and not v['blockedReason']
+assert v['commands']['emptyBuiltinAnnotationLayerRemoved'] is True
+assert v['commands']['annotationInstancesAtRemoval'] == 0
+assert v['commands']['annotationSourcePreserved'] is True
+assert v['styleParity']['baseLayerCount'] == 63 and v['styleParity']['baseLayersPreserved']
+assert not v['styleParity']['full113Equivalent']
+n = v['native']; t = n['fastGateTrace']; frames = t['frames']
+assert n['valid'] and len(frames) == t['windowCount'] == 120
+assert len(t['gates']) == 24 and t['decisionMismatch'] == 0
+assert [g['order'] for g in t['gates']] == list(range(1, 25))
+assert all(f['knownMask'] == 0xffffff and f['decisionConsistent'] and len(f['gateStatus']) == 24 for f in frames)
+assert all(a['sequence'] < b['sequence'] for a, b in zip(frames, frames[1:]))
+complete = [f for f in frames if f['completed']]
+assert complete and all(f['post'] is not None for f in complete)
+print('结构完整；仍须独立核对源码/制品SHA、同次generation/lifecycle及用户画面')
+print('生命周期 Full/Fast:', t['fullRendered'], t['fastRendered'])
+print('窗口 completed/Full/Fast:', len(complete), t['windowFullRendered'], t['windowFastRendered'])
+for s in n['segments']:
+    if s['strategy'] == 'RETAINED':
+        print('R', s['beginIndex'], s['endExclusive'], s['missingSourceIds'],
+              s['placementGatePassed'], s['cache'])
+print('窗口失败项:', [(g['order'], g['reason'], g['windowFailures']) for g in t['gates'] if g['windowFailures']])
+PY
+```
+
+允许最后一帧 pending，但不能把其post作为当前Full。pre为上次完成树、post/full为本次完成树，避免跨帧拼状态。环形窗口可能覆盖Mutation瞬间，必须变更前/后分别及时手动导出，若没捕获则如实 NOT VERIFIED。120条帧不等于120条completed。
+
+用户确认基础PBF/标注/天气色带/粒子可见、无漏内容/闪烁/层序错误；截图归档及用户判断不能代替同条件Full/Fast像素比较。当前缺源/Placement未解时应记录 Fast0 和每项失败，不宣布性能提升。
+
+## 5. 失败定位与受保护回归
+
+| 结果 | 判断与下一步 |
+|---|---|
+| missingSourceIds含tide，R Build0 | 正式Style缺源仍fail-closed；不补假源、不删tide-spots，记录Source类型/缺失层ID |
+| 缺源消失但Symbol placementGatePassed=false | 独立Symbol准入阻塞，检查Full changed/stale/fade与pre/post；不要用等候时间放行 |
+| #22仍失败 | 查Native C范围实际层清单；空层调整是否被撤销/失败，普通circle或真实Annotation仍应阻挡 |
+| #23仍失败 | 查retainedSupported和preparedScene聚合，消除#22不保证#23通过 |
+| mismatch>0 / unknown Gate /版本不符 | 停止记录通过，保留首错和完整证据 |
+| Fast>0 | 先核查没有缺源/场景撤销、原Style完整，继续资源变化/回退/画面对照；仅记FAST_OBSERVED |
+
+原五场景仍在。每项独立运行并保留导出，不连续启动冒充采样：
+
+```bash
+python3 -B tools/particle_android_validation/verify_step113_fast_path.py --scenario PBF63 --seconds 90
+python3 -B tools/particle_android_validation/verify_step113_fast_path.py --scenario PARTICLE_OFF --seconds 90
+python3 -B tools/particle_android_validation/verify_step113_fast_path.py --scenario PARTIAL_RCRR --seconds 90
+python3 -B tools/particle_android_validation/verify_step113_fast_path.py --scenario SOURCE_CHANGE --seconds 90
+```
+
+这些场景可能预期Fast0，脚本退出2是受保护负例结果，不自动视为回归失败或改预期。SOURCE_CHANGE保留circle与Annotation；用户执行一次原 MUTATE PROBE SOURCE ONCE，导出前后commands和native lastMutation/affectedSegmentIndices，区分同时发生的真实瓦片更新。
+
+Native七项新测试之外，还需 RDC/用户记录：遗留Annotation拒绝移除；STATIC_RC后添加真实Marker（同步恢复points再Full、像素可见），no-op更新；额外Style.addLayer/重排不删除新内容；disable、退出到STEP102、Style reload及后台恢复；Source创建/同名更新/async Tile、Glyph/Image变化必定invalid/Full。Test App没有新增自动Mutation来假装覆盖这些事件；若当前UI无法触发，标该项设备NOT VERIFIED并使用对应Native真实测试/另行授权的操作。STEP114四场景回归使用其既有命令；Smoke结果只归其独立场景。
+
+最终提交证据应包含最新HEAD/精确源码diff、Native日志/首错、用户build-info/build.log/APK及安装SHA、设备信息、原STATIC_RC摘要和完整JSON、manifest、24Gate/真实Build/Reuse/Full/Fast增量、回退与画面。编译成功、preflight成功或静态检查都不把STEP-116判为CLOSED/PASS。

docs/60_测试/STEP-117_FZG1_原PBF真实Fast验收计划_v1.md

@@ -0,0 +1,165 @@
+# STEP-117 FZG1 原 PBF 真实 Fast 验收计划 v1
+
+日期：2026-10-11（JST）。**本计划全部运行命令交RDC/普通Terminal；Codex本轮未执行。当前安全准入BLOCKED，测试源码交付不表示真实Fast已修复。**
+
+## 1. 执行顺序与停止条件
+
+先独立审计STEP117调查、diff和七项测试，确认B1缺源零贡献与B2 Symbol结果证书仍未实现。本轮只有测试/文档，不应期待重新打APK获得不同Fast行为。RDC可先验证C++回归；粒子负责人协调Shared Core证书设计及正式tide语义，再授权具体实现。完成可证明的实现并复核后，安排一次完整Android build/install/原STATIC_RC集中验收。
+
+本任务不授权Codex执行任何Native编译/测试、Gradle/ADB/安装、Jest、commit/push。RDC后续Git收尾须按独立授权scoped提交，核对origin远端HEAD，保护STEP110/111。Android与设备命令只能在用户明确授权的对应阶段执行。当前缺libuv历史记录只用于排查；不跳过失败、不改门槛、不运行旧runner、不改build-info使旧包冒充新源码。
+
+遇到编译/测试失败、Source/Style版本不符、mismatch>0、未知Gate、错误恢复/漏内容或Fast仍为0，保存首个真实error/target及完整日志路径，停止相应通过判定。不要换STEP114烟测、删原层或补假tide来继续。
+
+## 2. 独立源码与定向Native验收
+
+```bash
+cd /Users/tei/dev/MapLibreParticleLab
+git branch --show-current
+git rev-parse HEAD
+git status --short
+git diff --check
+git diff -- test/renderer/retained_underlay_cache.test.cpp test/renderer/render_orchestrator_error.test.cpp 粒子开发记录.md
+shasum -a 256 docs/40_任务/STEP-110_R0_Placement跨段归因只读调查_Codex任务_v1.md docs/40_任务/STEP-111_R段Placement结果等价与独立刷新可行性只读调查_Codex任务_v1.md
+```
+
+STEP110/111预期SHA分别为 `33037df71b4b30aa7956d59f4b99f77af3085405b24111bc0fe11ec857a93db0`、`f3a5806f25384bf46055db2edfea0d21bfbc4124184bc813b46e38b8079c1ec4`。查看新增四份文档及报告静态核查章节。生产src/include/Shader/TestApp/旧测试断言应与起点保持一致；不得把test fixture的markBuildSucceeded或测试线程注入事件当作实际GPU/并发完成。
+
+以下逐项串行运行，上一项失败立即停止。使用当前Mac配置的CMake；如果PATH没有cmake，可用已配置的 `/Users/tei/Library/Android/sdk/cmake/3.31.6/bin/cmake`，不得自行升级依赖。
+
+```bash
+cmake --preset macos-metal
+```
+
+```bash
+cmake --build build-macos-metal --target mbgl-test-runner --parallel 3
+```
+
+```bash
+build-macos-metal/mbgl-test-runner --gtest_filter='Step117Safety.*:Step116Safety.*:Annotations.*:RenderOrchestratorError.*:RenderOrchestratorTeardown.*:FastGateTrace.*:ParticleFastPath.*:RetainedUnderlayCache.*:RetainedUnderlayRevision.*:RenderSegmentDiagnostics.*:RenderSegmentPlacementFree.*:RenderSegmentLocality.*:RenderSegmentPlan.*' --gtest_color=no
+```
+
+新增Step117Safety必须实际运行7项，不能以filter未匹配的exit0通过。test/CMakeLists.txt已登记两个源文件，不需要绕过原target。记录当前HEAD、runner构建来源、命令、exit/耗时、用例数量、完整日志路径。Annotations.Step116是实际出图比较；其通过也不替代原PBF的Symbol结果证明。Mac Metal runner成功不代表Android OpenGL或iOS设备PASS。
+
+## 3. 一次未来授权的Android制品闭环
+
+在B1/B2受控实现完成、源码已锁定且tracked clean后，用户授权RDC/普通Terminal逐项执行标准Pipeline。保护未跟踪MD保留，git_dirty=true需结合tracked状态判断。记录真正的源HEAD，不能拿本轮起点43e5f5b当作包含未来实现的提交。
+
+```bash
+cd /Users/tei/dev/MapLibreParticleLab
+git rev-parse HEAD
+git status --short
+./tools/particle_android_validation/build_validation_apk.sh
+```
+
+Pipeline必须Java17、OpenGL/x86_64、strip，成功后核对ZIP、唯一ABI、libmaplibre.so、体积、完整build.log/build-info与SHA；失败不复用旧APK。版本名13.6.1-particle.23本身不能标识源码。
+
+```bash
+cat artifacts/maplibre-particle/android-validation/build-info.txt
+shasum -a 256 artifacts/maplibre-particle/android-validation/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk
+/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 install -r artifacts/maplibre-particle/android-validation/MapLibreAndroidTestApp-validation-opengl-debug-x86_64.apk
+```
+
+不得卸载/清数据。设备serial须重新核实为FZG1-2；变化时显式记录并修改后续参数。回读已安装base.apk SHA，由以下现有工具复核同HEAD/本地APK/设备安装包：
+
+```bash
+python3 -B tools/particle_android_validation/verify_step113_fast_path.py --adb /Users/tei/Library/Android/sdk/platform-tools/adb --serial 192.168.200.139:5555 --preflight-only
+```
+
+STALE_APK、SOURCE_NOT_LOCKED、ABI/SHA不符立即停止。PREFLIGHT_PASS仅说明版本闭环；旧c48a72a9 APK与本轮源码HEAD不同，即使生产文件未改也不能修改来源记录。
+
+## 4. 原STATIC_RC≥90秒正式验收
+
+```bash
+python3 -B tools/particle_android_validation/verify_step113_fast_path.py --adb /Users/tei/Library/Android/sdk/platform-tools/adb --serial 192.168.200.139:5555 --scenario STATIC_RC --seconds 90
+```
+
+从取得同PID起实际观察至少90秒，取得前后同sceneGeneration/lifecycle的摘要，计数单调、不撤销、不重置。保存result.json/logcat/launch、实际观察秒数。exit2/NO_FAST_OBSERVED如实失败；exit3为版本/环境阻塞。FAST_OBSERVED只是必要条件。
+
+正式通过同时要求：
+
+- 原Style的63基础层定义/顺序保留，记录productionFingerprint与baseLayerManifest、productionSources；原Style/Sprite/Glyph/Vector URI一致。若服务器内容改变导致fingerprint或层数不同，停止跨版本比较，交Style所有者协调。
+- STEP116空SDK Annotation规则保留：零实例后一次受控移除points，Source保留；原C正常只有WeatherColor+Particle，Native65层/R[0,63)/C[63,65)。后续真实Annotation/Style改变不得被再次删除。
+- 实际每个R Cache Build>0、Reuse>0，同生命周期FastDelta>0；completed fast-rendered帧必须cacheValid/revision一致、24Gate已知且全部PASS、mismatch=0。pending帧不计成功。
+- 缺源准入若未来获证书，必须能回读该absent source的零绘制/旧数据排除及同名恢复失效证据；missingSourceIds非空不能自动通过，也不能简单规定非空一律失败而回避新证书审查。
+- Symbol缓存绑定成功提交的R结果证书，列出受影响bucket/atlas/collision/opacity/动态属性/camera/context和变更代次；源码/设备证据中不得强制清三字段或改Gate。
+- 用户验收底图、海岸/等深线、航标、文字、天气色带与粒子，无漏内容/闪烁/层序错误；同条件Full/Fast像素对照及资源变化回退分别取证。性能提升需额外相同条件测量，不能从Full减少单独推断。
+
+## 5. 完整120帧与用户画面
+
+同次运行在STEP093→STEP113菜单手动EXPORT LAST SNAPSHOT。导出由用户触发，RDC回读同次generation/lifecycle的文件；确认文件名/时间不属于旧运行。以下shell命令逐项执行，任何失败立即停；变量只用于本次任务：
+
+```bash
+mkdir -p artifacts/maplibre-particle/android-validation/step117
+step117_file="$(/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 shell run-as org.maplibre.android.testapp ls -t files | tr -d '\r' | grep -E '^step113-STATIC_RC-.*[.]json$' | head -n 1)"
+test -n "$step117_file"
+/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 exec-out run-as org.maplibre.android.testapp cat "files/$step117_file" > artifacts/maplibre-particle/android-validation/step117/static-rc-full.json
+shasum -a 256 artifacts/maplibre-particle/android-validation/step117/static-rc-full.json
+/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 exec-out screencap -p > artifacts/maplibre-particle/android-validation/step117/static-rc-screen.png
+/Users/tei/Library/Android/sdk/platform-tools/adb -s 192.168.200.139:5555 logcat -b crash -d > artifacts/maplibre-particle/android-validation/step117/crash.log
+```
+
+完整JSON离线结构核对示例（不是新安全证书/性能验收）：
+
+```bash
+python3 -B - <<'PY'
+import json
+from pathlib import Path
+v = json.loads(Path('artifacts/maplibre-particle/android-validation/step117/static-rc-full.json').read_text())
+assert v['scenario'] == 'STATIC_RC' and v['sceneReady'] and not v['blockedReason']
+assert v['styleParity']['baseLayerCount'] == 63 and v['styleParity']['baseLayersPreserved']
+assert v['commands']['emptyBuiltinAnnotationLayerRemoved']
+assert v['commands']['annotationInstancesAtRemoval'] == 0
+assert v['commands']['annotationSourcePreserved']
+n = v['native']; t = n['fastGateTrace']; fs = t['frames']
+assert n['valid'] and n['styleLayerCount'] == 65
+assert len(fs) == t['windowCount'] == 120
+assert len(t['gates']) == 24 and t['decisionMismatch'] == 0
+assert [g['order'] for g in t['gates']] == list(range(1, 25))
+assert all(f['knownMask'] == 0xffffff and f['decisionConsistent'] and len(f['gateStatus']) == 24 for f in fs)
+assert all(a['sequence'] < b['sequence'] for a, b in zip(fs, fs[1:]))
+assert all(f['post'] is not None for f in fs if f['completed'])
+assert all(f['post'] is None for f in fs if not f['completed'])
+assert [(s['strategy'], s['beginIndex'], s['endExclusive']) for s in n['segments']] == [
+    ('RETAINED', 0, 63), ('CONTINUOUS', 63, 65)]
+fast = [f for f in fs if f['completed'] and f['outcome'] == 'fast-rendered']
+assert fast, '原PBF当前窗口没有完成Fast帧；保持FAIL/BLOCKED'
+assert all(f['failMask'] == 0 and all(c['exists'] and c['valid'] and
+    c['buildRevision'] == c['staticRevision'] for c in f['cacheInputs']) for f in fast)
+assert all(s['cache']['build'] > 0 and s['cache']['reuse'] > 0 for s in n['segments'] if s['strategy'] == 'RETAINED')
+print('必要结构/计数成立；继续检查证书、同次SHA/manifest、变更前后帧与用户画面')
+PY
+```
+
+在当前STEP117无准入实现的代码上，Fast/Build断言预期不能通过；不得删除这些断言制造PASS。pre为上一完成树，post/full为本次完成树；#13另取当前controller，不能混为同帧。环形窗口可能覆盖变更瞬间，必须每项操作前/后及时导出；未捕获则NOT VERIFIED。
+
+## 6. 安全反例与旧五场景
+
+| 操作 | 必须取证的正确行为 | 当前入口/限制 |
+|---|---|---|
+| 初始缺源 | 没有证书时missing-source、Build/Fast0；未来证书需证明双group零贡献和无旧数据 | 原STATIC_RC真实缺tide；不补造source |
+| 同名source创建/重建/数据到达 | 下一次尝试Full，旧证书和cache失效；真实内容可见后才重建 | 新C++真实sourceDiff用例及状态机；当前App没有生产tide注入入口，需Integration/真实来源协调，设备项NOT VERIFIED |
+| 已有旧Symbol后缺源/合法Style替换 | 两类group停用请求执行，旧drawables/buckets排除；不得复用旧R | 当前测试只有registry生命周期，无实际GPU旧数据证书；必须追加真正渲染用例后验收 |
+| Tile/Glyph/Image异步更新 | #5/#8/#14或对应稳定性Gate拒绝旧Fast，受影响R重建；未加载/fading继续fail-closed | C++回调注入不等同网络并发；实际资源延迟与事件顺序需独立工具/测试授权 |
+| Symbol collision/fade/anchor/orientation/沿线 | Full/Fast最终像素等价；所有碰撞受害R失效；时间相关opacity不能冻结 | 结果证书当前不存在；不能用默认空桶测试代替 |
+| Source mutation | 保留原SOURCE_CHANGE circle负例和手动MUTATE PROBE SOURCE ONCE；记录sourceId/affectedSegmentIndices与真实Full | 当前probe属C，不能冒充R的tide恢复 |
+| Style mutation/重排/添加 | non-camera/topology/fingerprint拒绝旧树；内容不删除 | 原入口无自动全矩阵；没有触发能力则NOT VERIFIED |
+| 真实Annotation add/no-op update/reload | STEP116同步恢复points并可见；#24/层表拒绝旧Fast；空层验收条件撤销 | Annotations.Step116图像回归和用户合法操作；不可周期删真实层 |
+| Camera/viewport/pixelRatio/projection | #6/#7/#8、cache key/context失效，Full后正确重建，无拖影或错位 | 用户pan/zoom/rotate/pitch/resize；逐事件导出 |
+| context/后台/恢复/disable/退出场景 | PreparedTree/资源正确失效释放，无旧GPU数据复活 | 用户设备生命周期及Native实际Renderer测试；现有callback用例不替代 |
+
+原五场景依次独立运行、分别保存日志/导出/画面。以下复测工具命令由RDC在同SHA预检后执行，SOURCE_CHANGE保留普通circle与Annotation负例：
+
+```bash
+python3 -B tools/particle_android_validation/verify_step113_fast_path.py --adb /Users/tei/Library/Android/sdk/platform-tools/adb --serial 192.168.200.139:5555 --scenario PBF63 --seconds 90
+python3 -B tools/particle_android_validation/verify_step113_fast_path.py --adb /Users/tei/Library/Android/sdk/platform-tools/adb --serial 192.168.200.139:5555 --scenario PARTICLE_OFF --seconds 90
+python3 -B tools/particle_android_validation/verify_step113_fast_path.py --adb /Users/tei/Library/Android/sdk/platform-tools/adb --serial 192.168.200.139:5555 --scenario PARTIAL_RCRR --seconds 90
+python3 -B tools/particle_android_validation/verify_step113_fast_path.py --adb /Users/tei/Library/Android/sdk/platform-tools/adb --serial 192.168.200.139:5555 --scenario SOURCE_CHANGE --seconds 90
+```
+
+受保护负例可能预期Fast0，exit2应按场景语义记录，不能调整工具返回码或删除负例。STATIC_RC正式正例仍要求真实Fast，不接受STEP114 FAST_SMOKE替代。
+
+## 7. 最终证据包
+
+RDC回填：锁定源HEAD与精确diff/相关源码SHA、scoped提交与远端HEAD（若获授权执行）、Native配置/构建/七测试日志、首错/阻塞；build-info/build.log/APK与安装包SHA、设备型号/serial；原Style fingerprint/63层manifest/C层表；同次90秒摘要、120帧完整JSON及SHA、每项24Gate/cache/Full/Fast/pre/post；Mutation前后/异步/碰撞/GPU生命周期证书；用户画面及同条件Full/Fast对照。
+
+没有证书保持BLOCKED；编译成功、静态检查、PREFLIGHT_PASS或测试进程exit0不能代替原PBF真实Fast安全验收。

docs/60_测试/STEP-118_tide移除Android实机验收_v1.md

@@ -0,0 +1,12 @@
+# STEP-118 FZG1-2 tide移除专用TestApp验收
+
+使用Mac仓库/现有标准build_validation_apk.sh和明确Android ADB serial 192.168.200.139:5555。严格串行，每一步退出值和实际产物均需PASS才能推进。完整证据存Git忽略artifacts目录。
+
+1. Git源HEAD锁/Integration当前main，确认只改TestApp Kotlin、Python verifier、说明及报告，两份STEP110/111未跟踪用户任务书不动。
+2. 标准 ./tools/particle_android_validation/build_validation_apk.sh。核验Gradle build SUCCESS、ZIP/strip/native x86_64、APK/source commit及sha256。
+3. ADB -s 192.168.200.139:5555 install -r新APK，Success后pm path/设备base.apk SHA与本地APK一致。
+4. python3 -B tools/particle_android_validation/verify_step113_fast_path.py --preflight-only。必须PREFLIGHT_PASS。
+5. python3 -B tools/particle_android_validation/verify_step113_fast_path.py --scenario STATIC_RC_NO_TIDE --seconds 90。验证新scene的实际Native Layer64、原生产63层manifest及同旧fingerprint、有效62基础层、C天气2层、R[0,62)、tide Source确实不存在、missingSourceIds不再包含tide。
+6. 读取result.json的真实FastDelta/FullDelta、R Build/Reuse/lastFallbackReason、Gate #3/#4/#12/#13/#22/#23、decisionMismatch。退出码2 NO_FAST_OBSERVED是负结论，不允许跳过。
+7. 必要时通过设备菜单EXPORT LAST SNAPSHOT并用ADB run-as取原生JSON、截屏；Native120帧24Gate的各窗口失败计数和原动画/像素效果分开验收。
+8. 新场景不等于原63层：原STATIC_RC仍保留严格basePreserved=true与真实missing-source负基线。若Fast仍为0且placementGatePassed=false，结论只能是缺源局部已解除、Fast仍BLOCKED；不能冒称已获得性能收益。真正Fast>0仍需要资源/Source/Style变更回退Full及用户实际画面验收。