[manager] bound P2P host cache queries

.github/workflows/build-dev-image.yml

@@ -1,9 +1,17 @@
 #
-name: Create and publish a develop Docker image
+name: Create and publish a KVCM Docker image
 
 # Configures this workflow to run every time a change is pushed to the branch called `release`.
 on:
   workflow_dispatch:
+    inputs:
+      flavor:
+        description: Image flavor
+        type: choice
+        options:
+          - dev
+          - integration
+        default: dev
 
 # Defines two custom environment variables for the workflow. These are used for the Container registry domain, and a name for the Docker image that this workflow builds.
 env:
@@ -12,7 +20,60 @@ env:
 
 # There is a single job in this workflow. It's configured to run on the latest available version of Ubuntu.
 jobs:
+  integration:
+    if: ${{ inputs.flavor == 'integration' }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Build server package
+        env:
+          BUILD_IMAGE: ghcr.io/alibaba/tair-kvcache-kvcm-dev:2026_02_13_12_03_24230b1
+        run: |
+          docker run --rm --privileged \
+            -v "${GITHUB_WORKSPACE}:/workspace" \
+            -w /workspace \
+            "${BUILD_IMAGE}" \
+            bash -lc '
+              git config --global --add safe.directory /workspace &&
+              bazelisk build //package:kv_cache_manager_server --config=ci_fast &&
+              cp bazel-bin/package/kv_cache_manager_server.tar.gz open_source/docker/ &&
+              chown "$(stat -c %u /workspace):$(stat -c %g /workspace)" \
+                open_source/docker/kv_cache_manager_server.tar.gz
+            '
+
+      - name: Prepare image tag and context
+        id: integration_image
+        run: |
+          VERSION="integration-$(date -u '+%Y_%m_%d_%H_%M')-${GITHUB_SHA::7}"
+          IMAGE="${REGISTRY}/${IMAGE_NAME}:${VERSION}"
+          test -r open_source/docker/kv_cache_manager_server.tar.gz
+          echo "image=${IMAGE}" >> "$GITHUB_OUTPUT"
+          echo "KVCM integration image: ${IMAGE}" >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Log in to the Container registry
+        uses: docker/login-action@65b78e6e13532edd9afa3aa52ac7964289d1a9c1
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and publish integration image
+        uses: docker/build-push-action@f2a1d5e99d037542a71f64918e516c093c6f3fc4
+        with:
+          context: open_source/docker
+          file: open_source/docker/Dockerfile.prod
+          platforms: linux/amd64
+          push: true
+          tags: ${{ steps.integration_image.outputs.image }}
+          build-args: BINARY_PACKAGE_TAR=kv_cache_manager_server.tar.gz
+
   build:
+    if: ${{ inputs.flavor != 'integration' }}
     strategy:
       fail-fast: false
       matrix:
@@ -97,6 +158,7 @@ jobs:
           retention-days: 1
 
   merge:
+    if: ${{ inputs.flavor != 'integration' }}
     runs-on: ubuntu-latest
     needs:
       - build

docs/README.md

@@ -4,6 +4,7 @@
 - [模块架构与关联关系](design/module_architecture.md) - 各模块职责、依赖方向、控制流与数据流，附 Mermaid 图
 - [基本概念](design/basic_concepts.md) - Storage、Instance Group、Instance、Block、CacheLocation 等核心概念
 - [ReportEvent 增量上报与权威快照设计](design/report_event_snapshot_uri_version.md) - 增量/快照协同、提交屏障、故障恢复、性能取舍与 Subscriber 集成
+- [ReportEvent / GetHostCacheState 小 block 性能记录](design/report_event_performance.md) - local/Redis 指标解释、锁与可见性语义、有界并发、容量基准及后续优化边界
 - [高可用与选主机制](design/ha_leader_elector.md) - HA 架构、LeaderElector 状态机、CoordinationBackend、Leader 发现
 - [CacheReclaimer 异步删除与过度逐出优化](design/cache_reclaimer_async_delete.md) - 异步删除生命周期、in-flight credit、反压与无进展退避
 - [后台扫描 GC](design/cache_garbage_collector.md) - 基于 authoritative cursor 的后台全量巡检；V1 清理长期 orphan WRITING 和普通 SERVING storage-missing，并提供无副作用读取、精确值条件 CAS 与 HA 生命周期

docs/configuration.md

@@ -99,6 +99,16 @@ kvcm.schedule_plan_executor_thread_count=8
 # 0 < migration_worker_budget < executor_thread_count
 kvcm.schedule_plan_migration_worker_budget=3
 
+# GetHostCacheState 大请求使用的独立有界 metadata query executor。
+# worker_count 包含当前 RPC caller；默认 4 表示 caller + 3 个后台线程，设为 1 可禁用并行。
+kvcm.meta_query.worker_count=4
+
+# key/投影元素数达到该阈值才进入并行路径；小请求保持串行。
+kvcm.meta_query.parallel_threshold=256
+
+# 每个并行任务一次领取的连续元素数，必须不大于 parallel_threshold。
+kvcm.meta_query.chunk_size=128
+
 # CacheReclaimer 删除 Future 在 delay 结束后可继续抵扣水位的最长时间；到期只关闭 credit，
 # 不取消底层删除。默认 60000ms。
 kvcm.cache_reclaimer.inflight_delete_timeout_ms=60000
@@ -167,6 +177,25 @@ executor_thread_count > 1
 新增迁移策略，因此不能根据启动时的策略状态放宽校验。`2/1`、`8/3` 是合法配置，`1/1`、`8/8` 和 `8/0`
 会导致 `ServerConfig::Check` 或 `CacheManager::Init` 失败。已有单线程自定义配置需要至少调整为 `2/1`。
 
+### GetHostCacheState metadata query executor
+
+`kvcm.meta_query.*` 控制独立于 `SchedulePlanExecutor` 的进程级有界查询池，仅服务大规模
+GetHostCacheState metadata read 和 host 投影/归约。线程不会按 instance 或请求创建：所有 MetaIndexer
+共享一个 executor，RPC caller 始终参与工作，因此 `worker_count=4` 只创建 3 个后台线程。队列饱和时
+请求由 caller 继续执行，不会无限堆积任务。
+
+只有单一 `local` metadata backend 的大批 key 读取会并发；`redis`、`cached` 和其他 backend 保持原有
+batch 调用。CPU 投影使用同一有界池。参数约束为：
+
+```TEXT
+1 <= worker_count <= 64
+0 < chunk_size <= parallel_threshold
+```
+
+默认值是 `4/256/128`。`worker_count=1` 是线上回退开关；调大 worker 前应同时对比单请求和并发请求
+p99、CPU 与 ReportEvent RT。设计、指标含义、测试命令见
+[`design/report_event_performance.md`](design/report_event_performance.md)。
+
 同一个 `migration_config` 中，`strategies` 的 `(source_storage_name, target_storage_name)` 组合必须唯一。
 相同 source 迁移到不同 target、不同 source 迁移到相同 target，以及 `hot -> warm -> cold` 级联均可配置；只有
 完全相同的 source/target route 会被拒绝。重复 route 无法明确选择各自的 threshold、method、retention 和 Mark

docs/design/cache_reclaimer_async_delete.md

@@ -221,6 +221,14 @@ size 的 Location 按 0 bytes 记账，但仍加入 pending 并受数量上限
 只有本次请求覆盖某个 block 的全部有效 Location 时，才增加一个 `predicted_deleted_keys`。V1 不跨
 多个 `DeleteHandler` 合并推断，允许保守少计。
 
+EventReport Location 由外部 reporter 拥有，只能由 ReportEvent snapshot、delta 或 host lifecycle 清理，不能进入
+通用物理存储回收请求。它仍然是 metadata key 上的有效 Location：若一个 block 同时包含 EventReport 与普通
+Location，删除全部普通 Location 后 key 仍然存在，因此不得产生 `predicted_deleted_keys` credit。EventReport usage
+不参与按 storage type 的水位，但仍计入 group 总 byte 水位；通用 Reclaimer 即使因此触发，也只能选择普通
+Location，EventReport-only 场景会按 no-progress 退避，不能进入物理删除。EventReport Location 也不能作为
+migration cold-tier spec coverage。key-count 水位继续使用 MetaIndexer 的官方总 key 数，无法证明可删除时保持
+fail-closed、允许保守多触发而不能提前抵扣。
+
 水位判断改为：
 
 ```text
@@ -362,6 +370,10 @@ V1 提供以下指标：
     有效 Location。
 15. Meta 异步请求跳过 `CLS_DELETING`，重复提交不会再次安排物理删除。
 16. Admission 已进入队列但尚未执行时停止 Executor，cancel callback 使 Future 以错误终态完成。
+17. EventReport Location 不进入物理删除请求，但与普通 Location 共存时仍阻止错误的
+    `predicted_deleted_keys` credit。
+18. EventReport usage 仍可触发 group 总 byte 水位，但不触发 EventReport storage-type 水位。
+19. reporter URI host 即使与 migration target storage 同名，也不能补齐 cold-tier spec coverage。
 
 ### 8.2 集成测试关注点