knowledge: daily intake batch 13

knowledge/repos/vllm-omni/ci/rules.md

@@ -1,7 +1,7 @@
 ---
 title: "vLLM-Omni CI 规则"
 created: 2026-08-23
-updated: 2026-09-08
+updated: 2026-09-13
 type: rule
 tags: [vllm-omni, ci]
 sources: ["PR #3422", "PR #5074", "PR #5255", "PR #5310", "PR #5402", "PR #5524", "PR #5543", "PR #5670", "PR #5713", "PR #5780", "PR #5823", "PR #5836", "PR #5957", "PR #5976", docker/Dockerfile.ci, docker/Dockerfile.xpu, .buildkite/intel/scripts/run-xpu-test.sh, .buildkite/cuda/test-merge.yml, .buildkite/cuda/test-ready.yml, "PR #5845", "PR #5872", "PR #6008", "PR #6048", "PR #6056", "PR #6096", "PR #6102", "PR #6202", "PR #6208", "PR #6273", "PR #6293", "PR #6311", "PR #6339", "PR #6343", "PR #6468", "PR #6523", "PR #6613", "PR #6555", "PR #6650", .buildkite/common/scripts/run_cov_split.sh, pyproject.toml, tests/helpers/tests/test_mark.py, tools/pre_commit/check_test_marks.py, .buildkite/common/scripts/upload_pipeline.py, .buildkite/cuda/test-nightly.yml, .buildkite/cuda/test-weekly.yml, .buildkite/npu/test-npu-nightly.yml, .pre-commit-config.yaml, tests/helpers/clean.py, tests/helpers/client.py, tests/helpers/mark.py, tests/helpers/runtime.py, tests/helpers/stage_config.py, tests/buildkite/test_upload_pipeline.py, tests/dfx/perf/scripts/run_benchmark.py, tests/dfx/perf/tests/test_minicpmo_4_5.json, tests/dfx/perf/tests/test_minicpmo_4_5_duplex_seed_tts.json, tests/dfx/perf/tests/test_qwen_image_vllm_omni.json, tests/dfx/stability/, tests/e2e/accuracy/minicpmo_4_5/test_minicpmo_4_5.py, tests/e2e/online_serving/helpers/minicpmo_4_5_duplex.py, tests/e2e/online_serving/test_flux_kontext_expansion.py, tests/e2e/online_serving/test_minicpmo_4_5.py, tests/e2e/online_serving/test_minicpmo_4_5_duplex.py, tests/e2e/online_serving/test_minicpmo_4_5_expansion.py, tests/e2e/online_serving/test_qwen_image_expansion.py, tests/e2e/online_serving/test_minimax_h3_dlo_dp2_t2va.py, tests/model_tests/diffusion/diff_model_builders.py, tests/model_tests/diffusion/model_settings.py, tests/model_tests/diffusion/test_alignment.py, tools/nightly/run_nightly_jobs.sh, tools/pre_commit/check_tts_adapter.py, tests/tools/test_check_tts_adapter.py, .buildkite/amd/scripts/bootstrap-amd-omni.sh, .buildkite/amd/test-amd-merge.yml, .buildkite/amd/test-amd-ready.yml, tests/diffusion/distributed/test_tensor_parallel.py, tests/diffusion/offloader/test_diffusion_layerwise_offload.py, "PR #6704", tests/dfx/perf/tests/test_qwen3_omni_async_chunk.json, tests/dfx/perf/tests/test_qwen3_omni_no_async_chunk.json, "PR #6743", "PR #6696", vllm_omni/benchmarks/metrics/metrics.py, vllm_omni/benchmarks/patch/patch.py, tests/benchmarks/metrics/test_metrics.py, tests/benchmarks/patch/test_patch.py, "PR #6674", docker/Dockerfile.npu, docker/Dockerfile.npu.a3, docker/Dockerfile.npu.ci, docker/Dockerfile.npu.ci.a3, "PR #6818", "PR #6830", "PR #6884", tests/diffusion/conftest.py, tests/diffusion/attention/test_flash_attn.py, tests/buildkite/test_amd_pipeline.py, tests/e2e/offline_inference/test_qwen3_omni_colocate_async.py, "PR #6947", "PR #7118"]
@@ -271,3 +271,18 @@ PR 报告的 collection=1 和 local two-card B300 184.97 s 是该精确 workload
 - 强制：preset expansion tests 必须同时断言 pod env 中存在 alias、不再存在裸 `HF_TOKEN`，并验证 L4/H100/B200 全部 CUDA mirror preset 的 commands 都 prepend 同一恢复语句；非 CUDA preset 不得无故注入该 wrapper。
 - 禁止：依赖 Buildkite/Kubernetes 的 env merge 顺序碰巧正确；只修一个 GPU family；或把本地 shell/export 成功外推为 secret 已进入 pod env。
 - 验收：render 后的每个 CUDA mirror step 都保留 secret alias 和 runtime export，scheduled build 的同名 `HF_TOKEN` 不再导致 gated-model jobs 401；NPU steps 的 env 与 commands 保持不变。^[PR #7118]
+
+## OMNI-CI-1g — post-merge CUDA L3 必须按 commit diff 做 source 过滤
+
+- 触发：修改 `upload_pipeline.py` 的 `_changed_files_for_source_filter`、Upload Merge
+  Pipeline bootstrap、`test-merge.yml` 上传参数，或 `source_file_dependencies` /
+  `source_filter_fallback` 行为。
+- 强制：PR-label 与 post-merge `main` 的 L3（merge pipeline）都必须对 commit/PR diff 应用
+  `source_file_dependencies`；只有显式 `--all`（scheduled NIGHTLY 等）或 `--e2e`
+  （`main+WEEKLY`）才 keep-all。Upload Merge Pipeline 不得在普通 `main` 上默认传
+  `--all`。无 job-key 命中时，被上传的 pipeline YAML 或 `source_filter_fallback` 命中仍可
+  keep-all；一旦有 job-key 命中，正常过滤优先。
+- 禁止：仅因 `BUILDKITE_BRANCH=main` 就禁用 source 过滤；把 post-merge L3 跑成全量 E2E
+  却声称仍是 diff-aware；把 scheduled full upload 与 post-merge L3 混为同一策略。
+- 验收：单测断言 `main` 且 `force_all=False/e2e_only=False` 返回 diff；`force_all`/`e2e`
+  返回 `None`；bootstrap 在非 WEEKLY 的 main merge 上传不带 `--all`。^[PR #7371]

knowledge/repos/vllm-omni/components/diffusion/rules-lora.md

@@ -1,7 +1,7 @@
 ---
 title: "Diffusion LoRA 规则"
 created: 2026-09-02
-updated: 2026-09-09
+updated: 2026-09-13
 type: rule
 tags: [vllm-omni, components, diffusion]
 sources: ["PR #2783", docs/user_guide/diffusion/lora.md, vllm_omni/config/omni_config.py, vllm_omni/config/stage_config.py, vllm_omni/diffusion/data.py, vllm_omni/diffusion/lora/loader.py, vllm_omni/diffusion/lora/manager.py, vllm_omni/diffusion/lora/layers/base_linear.py, vllm_omni/diffusion/models/qwen_image/pipeline_qwen_image.py, vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2.py, vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_i2v.py, vllm_omni/diffusion/utils/tf_utils.py, vllm_omni/diffusion/worker/diffusion_worker.py, vllm_omni/engine/async_omni_engine.py, vllm_omni/entrypoints/cli/serve.py, tests/diffusion/lora/test_loader.py, tests/diffusion/lora/test_lora_manager.py, tests/entrypoints/test_async_omni_diffusion_config.py, "PR #5500", "vllm_omni/diffusion/models/ltx2/ltx2_adapter_parser.py", "vllm_omni/diffusion/models/ltx2/ltx2_phase_adapter.py", "PR #6070", "PR #6476", "PR #6550", vllm_omni/diffusion/models/minimax_h3/lora.py, "PR #6268", benchmarks/kernels/benchmark_diffusion_lora_expand.py, tests/diffusion/lora/test_base_linear.py, "PR #7195"]
@@ -137,3 +137,17 @@ confidence: high
 - 强制：deactivate 只 `suspend_lora()`（保存并清零 `_diffusion_lora_active_slices`），保留 stacked A/B；同一 adapter_id 与同一 rounded scale 再激活时 `resume_lora()` 复原掩码，禁止整层 `reset_lora`+rebind。`_suspended_adapter_id` 在真实 reset、rank 驱动的 `create_lora_weights`、新 bind 开始、以及 remove 被 suspend 的 adapter 时必须清空；不同 adapter 或不同 scale 仍走完整 rebind。
 - 禁止：把 suspend 当成可丢弃的 upload；resume 覆盖后注册的新 layer 的 inactive mask；在失败 bind 后仍保留旧 suspended 身份。
 - 验收：CPU 覆盖 suspend/resume、同 id+scale 不 re-upload、不同 scale/id 走 rebind、remove suspended 触发 reset、中途失败后 inactive，以及 add_adapter 后新 layer 不被错误 resume。^[PR #7195]
+
+## DIFF-2ag — 绑定零层的 diffusion LoRA adapter 必须失败而不是静默 no-op
+
+- 触发：修改 `DiffusionLoRAManager._bind_adapter_weights` / `_activate_adapter`、
+  binding 记账，或 pipeline 可选 `_validate_diffusion_lora_binding` hook。
+- 强制：无论 pipeline 是否提供 binding validator，绑定过程都必须无条件记录实际命中的
+  module 名；`bound_lora_names` 为空时立即 `ValueError`，错误信息同时列出 expected
+  target modules 与 adapter 收到的 module 名。既有 activate 的 try/except 必须 reset 全部
+  wrapper 并保持 inactive，不得留下“已激活但等于 base”的状态。
+- 禁止：仅在有 validator 时才记账；让零绑定激活返回成功或只打 DEBUG；把 diffusers 命名
+  checkpoint 对不上 engine layout 的情况当成有效 adapter。
+- 验收：CPU 回归用故意不匹配的 `target_modules` 断言激活抛错、消息含收到的模块名、
+  active id 仍为 `None` 且无 `set_lora`；有 validator 的模型路径仍覆盖完整 binding
+  completeness。^[PR #7349]

knowledge/repos/vllm-omni/components/diffusion/rules-output-lifecycle.md

@@ -1,7 +1,7 @@
 ---
 title: "Diffusion output 与 multiprocess runtime 规则"
 created: 2026-09-02
-updated: 2026-09-08
+updated: 2026-09-13
 type: rule
 tags: [vllm-omni, components, diffusion]
 sources: ["PR #5550", "PR #5864", "PR #5885", "PR #5978", "PR #6750", vllm_omni/diffusion/diffusion_engine.py, vllm_omni/diffusion/executor/multiproc_executor.py, vllm_omni/diffusion/inline_stage_diffusion_client.py, vllm_omni/diffusion/io_support.py, vllm_omni/diffusion/model_metadata.py, vllm_omni/diffusion/output_formatter.py, vllm_omni/diffusion/ipc.py, vllm_omni/diffusion/sched/request_scheduler.py, vllm_omni/diffusion/stage_diffusion_proc.py, vllm_omni/diffusion/utils/media_utils.py, vllm_omni/diffusion/worker/diffusion_worker.py, tests/diffusion/test_async_output_timeout.py, tests/diffusion/test_async_output_worker.py, tests/diffusion/test_diffusion_engine.py, tests/diffusion/test_diffusion_engine_cleanup.py, tests/diffusion/test_diffusion_ipc.py, tests/diffusion/test_inline_stage_diffusion_client.py, tests/diffusion/test_ipc_async.py, tests/diffusion/test_multiproc_engine_concurrency.py, tests/diffusion/test_result_pump.py, tests/diffusion/test_stage_diffusion_proc.py, tests/entrypoints/openai_api/test_video_server.py, "PR #6023", "PR #5983", "PR #4222", "PR #6094", "PR #6255", "PR #6288", "PR #6308", "PR #6499", "PR #6749", "PR #6847", "PR #6953", vllm_omni/diffusion/data.py, vllm_omni/diffusion/registry.py, vllm_omni/diffusion/models/diffusers_adapter/pipeline_utils.py, tests/diffusion/test_diffusion_output_formatter.py, tests/diffusion/test_diffusion_plugin_hooks.py, tests/entrypoints/openai_api/test_video_pipeline_capability.py, "PR #6294"]
@@ -176,3 +176,37 @@ confidence: high
 - 强制：runner 与 pipeline 共有同一 `InteractionCoordinator`；仅对已注册 modality 构造 handler；`enqueue` 按 modality 路由；`apply_at_chunk_boundary` 以稳定顺序推进（prompt 优先，再及其他 modality）；per-request session 落在 `StepRequestState.interaction_sessions`，chunk ACK 元数据写入 `interaction_chunk_metadata`。未注册 modality 必须 fail closed。当前公开行为保持 prompt-only，直到另有 PR 注册并验收非 prompt handler。
 - 禁止：在 denoise 中途旁路 coordinator 直接改 `prompt_embeds`；在非 chunk 边界静默应用 interaction；未注册就接受 camera/`multi_modal_data`；或把内部 handler 重构当成用户 API 已扩展。
 - 验收：覆盖 prompt enqueue→chunk-boundary apply→ACK event id、未注册 modality 拒绝，以及无 session 的 modality 跳过；不得用本框架落地证明 camera/MM 路径已可用。^[PR #6294]
+
+## DIFF-1ai — 迁移后的视频输出必须以 typed `media` 为唯一能力信号
+
+- 触发：修改 `DiffusionOutput`、device-side video postprocess、`video_output_transport`、
+  runner 预 D2H 准备、worker IPC media envelope 或 engine finalizer 路由。
+- 强制：迁移动画输出以 `DiffusionOutput.media`（`DiffusionMediaOutput`）为唯一能力信号，
+  与 legacy `output` 以及 model-specific `post_process_func` 互斥。runner 在 normalize/
+  request-split 之后、异步 D2H 之前完成 request-owned 准备：合格视频转 contiguous uint8
+  `BTHWC`，或按策略保留已标 transport-ready 的 float；IPC 只接受 transport-ready 的
+  版本化 `diffusion_media_v1` envelope；engine 走通用 media finalizer，绕过 legacy
+  model postprocessor。`to_cpu=True` 前 media 必须已 prepared。feature 默认关闭，经
+  `video_output_transport.enable_device_postprocess` 显式开启。合同违规 fail loud；
+  OOM 可回退到 owned float 并告警，其他 runtime 错误仍传播。未迁移模型保持 legacy path。
+- 禁止：对已迁移路径同时填充 `media` 与 legacy `output`；未准备就 D2H/to_cpu；把 HTTP
+  sink、codec 策略或未迁移模型静默当作同一 Phase-1 合同。
+- 验收：正负覆盖互斥字段、未 prepared `to_cpu`、IPC 拒收未就绪 media、opt-in 开关与
+  OOM float fallback；至少一条迁移模型（如 WAN2.2 非 latent）走 typed path，一条未迁移
+  模型仍走 legacy。^[PR #6615]
+
+## DIFF-1aj — multiproc worker shutdown 必须升至 SIGKILL 并保留幸存者供重试
+
+- 触发：修改 `_ExecutorShutdownCleaner`、diffusion worker process join/terminate/kill、
+  worker monitor 与显式 `shutdown()` 的竞态，或 cleaner 持有的 process 引用生命周期。
+- 强制：cleanup 按有界三阶段推进：cooperative join → `terminate`+join → `kill`+join；
+  信号/join 的 `OSError` 不得中断 peer cleanup。最终仍存活的进程必须记 error（含 name/pid）
+  并保留在 cleaner 上，供下一次显式 shutdown 重试，不得在第一次失败后丢弃引用。
+  cleaner 用非阻塞锁，防止 monitor 与显式 shutdown 并发操作同一批 `Process`；二次进入
+  直接返回。`broadcast_mq` 在 enqueue 成败后都要清空；result-pump/pending-future 清理
+  仍在 `finally`。
+- 禁止：只做 graceful+SIGTERM 后假定已退出；失败后清空 process 列表导致无法再 reap；
+  把存活进程当作 GPU 内存已回收或 HWR/服务自动重启已完成。
+- 验收：真实 CPU child（含忽略 SIGTERM）在 queue 失败时经 SIGKILL 退出并被 reap；合作
+  退出路径 exit 0；覆盖 shared deadline、signal/join OSError 续跑、幸存者保留与并发
+  cleaner。^[PR #7126]

knowledge/repos/vllm-omni/components/host-weight-runtime/rules.md

@@ -1,7 +1,7 @@
 ---
 title: "Host Weight Runtime 规则"
 created: 2026-08-23
-updated: 2026-09-04
+updated: 2026-09-13
 type: rule
 tags: [vllm-omni, components]
 sources: ["PR #6419", "PR #6427", "PR #6445", "PR #6486", "PR #6591", "PR #6692", vllm_omni/host_weight_runtime/]
@@ -124,3 +124,18 @@ confidence: high
   artifact miss。
 - 验收：覆盖 capability/budget gate、mid-registration rollback、PyTorch pinned-source verification、
   unregister retry 与 retained-owner GC，并断言 successful direct path 无 private staging allocation。^[PR #6591]
+
+## HWR-1f — domain-init 锁等待必须受 `WaitPolicy` 单调截止约束
+
+- 触发：修改 `FilesystemHostWeightStore` 构造、`domain-init.lock`、`WaitPolicy` 向 store
+  的传递，或 `HostWeightRuntime.from_config()` 的初始化路径。
+- 强制：store 构造必须把 runtime `WaitPolicy` 传入，并用 `time.monotonic() +
+  coordination_timeout_seconds` 作为 `domain-init.lock` 的 deadline；超时转为 retryable
+  `DOMAIN_UNAVAILABLE`，preferred 可 fallback，required 失败。超时 waiter 不得解锁 owner，
+  也不得改写 owner 的 domain metadata。初始化预算与 resolve/publish 协调预算分开；这不是
+  硬启动 deadline，也不取消进行中的 filesystem I/O/production。争用结束后新 runtime 可重试。
+- 禁止：构造期 `FileLock(..., deadline=None)` 无限阻塞，使 preferred 也无法 fallback；把
+  coordination timeout 说成可取消的同步 producer 总时限。
+- 验收：外部持锁下分别覆盖 preferred fallback 与 required failure、typed
+  `DOMAIN_UNAVAILABLE`、owner 锁与 metadata 保持、deadline 前释放可成功，以及释放后新
+  runtime 的 `LOCAL_HIT` 恢复。^[PR #7128]

knowledge/repos/vllm-omni/components/serving/rules-metrics.md

@@ -1,7 +1,7 @@
 ---
 title: "Serving metrics 生命周期规则"
 created: 2026-09-05
-updated: 2026-09-05
+updated: 2026-09-13
 type: rule
 tags: [vllm-omni, components, serving]
 sources: ["PR #3576", "PR #4755", "PR #6549", vllm_omni/engine/async_omni_engine.py, vllm_omni/engine/orchestrator.py, vllm_omni/entrypoints/async_omni.py, vllm_omni/entrypoints/omni_base.py, tests/metrics/test_prometheus.py]
@@ -38,3 +38,19 @@ confidence: high
 - 禁止：把 orchestrator 已 dispatch、但仍在 stage scheduler queue 的请求报作 running；分散复制公式；让负值、过期/竞态 snapshot 或 engine waiting 大于 dispatched 产生负 gauge；在 final request 仍在 `request_states` 时丢掉既有 `total - 1` 防止 waiting 卡为 1 的语义。
 - 限制：该实现求的是各 `(stage, replica)` 最新 waiting snapshot 的**和**，并不按 request ID 去重；代码和 PR #6549 的 3-dispatched/2-queued 测试只证明单一 queue 的拆分，未证明同一 pipeline request 不会同时落在多个 snapshot。因此该值是受 clamp 保护的 scheduler-queue occupancy，不应声称是精确的全局唯一请求数。PR #6549 唯一 review thread 仅确认 `engines_` 名称用于区分 frontend 与 engine waiting，未处理该 cardinality 问题。
 - 验收：用真实 Prometheus scrape 覆盖 3 个已 dispatch、其中 2 个 engine scheduler waiting，精确断言 running=1、waiting=2；同时覆盖 arrival、普通/最终 stage result、cleanup、replica removal 和 snapshot 的负值/超 dispatched 值，确认既有 finalization race 语义不变。^[PR #6549]
+
+## SERV-2g — metrics 去重集合必须挂在请求 state 并随其释放
+
+- 触发：修改 `OmniBase` 的 result/message metrics 去重、`ClientRequestState`、abort 后
+  request state 保留，或 `_log_summary_and_cleanup`。
+- 强制：`id(msg)` / `id(result)` 去重集合必须是每个 `ClientRequestState` 上的
+  `consumed_metric_message_ids`，由 `_handle_output_message` / `_process_single_result`
+  写入；不得再维护与 request 并行的实例级 `dict[request_id, set]`。abort 可按既有合同
+  暂时保留 `request_states`，但去重集合只能活在该 state 上，并由 `generate()` 正常
+  cleanup / `_log_summary_and_cleanup` 与 state 一并释放。
+- 禁止：在 `OmniBase` 上保留 request-keyed metrics 旁路 map；abort 路径留下跨请求生命周期
+  的去重条目；让同一 message 在 abort-then-cleanup 前后被累计两次，或 cleanup 后实例上仍
+  能按 request_id 读到残留 map。
+- 验收：生产 handler 写入 state 集合后 abort，断言实例属性无独立 request-keyed metrics
+  map；cleanup 后 `request_states` 与任何 request-keyed map 均无该 id；同一 message 重放
+  只累计一次。^[PR #6561]

knowledge/repos/vllm-omni/components/serving/rules-session-lifecycle.md

@@ -1,7 +1,7 @@
 ---
 title: "Serving session lifecycle 规则"
 created: 2026-09-05
-updated: 2026-09-06
+updated: 2026-09-13
 type: rule
 tags: [vllm-omni, components, serving]
 sources: ["PR #6537", "PR #6354", vllm_omni/config/stage_config.py, vllm_omni/entrypoints/openai/api_server.py, vllm_omni/engine/duplex/adapter.py, vllm_omni/engine/duplex/runtime.py, vllm_omni/experimental/fullduplex/mage_vl/adapter.py, vllm_omni/experimental/fullduplex/mage_vl/serving/backend.py, vllm_omni/experimental/fullduplex/mage_vl/serving/server.py, tests/e2e/features/fullduplex/test_mage_vl_adapter.py, tests/e2e/features/fullduplex/test_mage_vl_serving.py, tests/e2e/online_serving/nemotron_voicechat_realtime_duplex.py]
@@ -44,3 +44,17 @@ confidence: high
   slot；因 warmup failure 拒绝服务或永久阻塞 real client；或在 shutdown 遗留 background warmup task。
 - 验收：覆盖 disabled、health-then-self-WS ordering、warmup tag 绕过 admission gate、explicit close、
   success/failure 均 set event、real-client 120-second escape hatch，以及 shutdown cancellation。^[PR #6354]
+
+## SERV-6j — 视频预热缓存不得在帧被逐出后回写，取消重启不得插入固定延迟
+
+- 触发：修改 streaming video WebSocket 的 `frame_pil_cache` / prewarm decode、有界
+  `frame_buffer` 逐出，或 cancel-then-restart 上一 query 后的等待逻辑。
+- 强制：prewarm 完成（成功 PIL 或 `_BAD_FRAME`）写入缓存前，必须再次确认该 b64 仍在
+  当前 `frame_buffer`；已逐出则丢弃结果，不得把帧重新插入 cache。取消上一 query 并
+  await task/`abort()` 后，不得再 `asyncio.sleep(0.1)`；Orchestrator abort ACK 已是完成
+  信号，墙钟等待不是额外 completion 证明。
+- 禁止：让 decode 竞态把已逐出帧钉回 cache 造成会话期泄漏；用固定 sleep 冒充 abort
+  排空；把去掉 sleep 说成已消除更深的 EngineCore GPU race。
+- 验收：`max_frames=1` 下延迟 decode 时，被逐出帧的 PIL 在会话仍打开时可被回收；
+  `max_frames=2` 时仍缓存到 teardown。中断连续 query 时记录的 sleep 请求为空，且旧
+  generator 关闭与 abort 完成发生在下一次 generate 之前。^[PR #7363]