Learn rules from the full vLLM-Omni human review audit

knowledge/repos/vllm-omni/_index.md

@@ -1,7 +1,7 @@
 ---
 title: "vLLM-Omni 入口"
 created: 2026-07-10
-updated: 2026-07-31
+updated: 2026-08-23
 type: index
 tags: [vllm-omni]
 sources: []
@@ -23,6 +23,8 @@ PR title/body 先选择 owner；changed files 只校验实际范围。Direct 已
 | HTTP/OpenAI request、response、endpoint、engine lifecycle | [serving rules](components/serving/rules.md) |
 | checkpoint、tokenizer、processor、stage input/handoff | [model-executor rules](components/model-executor/rules.md) |
 | diffusion pipeline、denoise、VAE/DiT、图像生成 | [diffusion rules](components/diffusion/rules.md) |
+| host-weight artifact、lease、filesystem store、restore transaction | [host-weight rules](components/host-weight-runtime/rules.md) |
+| Buildkite、硬件 lane、CI guard、xdist/shared fixture | [CI rules](ci/rules.md) |
 | connector、collective、跨 stage 通信 | [distributed](components/distributed/_index.md) |
 | queue、token budget、prefix cache、调度 | [scheduler rules](components/scheduler/rules.md) |
 | 明确模型名或 registry key | 直接查看 [models 目录](models/_index.md) |

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

@@ -1,7 +1,7 @@
 ---
 title: "vLLM-Omni CI"
 created: 2026-07-10
-updated: 2026-07-10
+updated: 2026-08-23
 type: index
 tags: [vllm-omni, ci]
 sources: []
@@ -21,5 +21,6 @@ sources: []
 
 | 遇到什么 | 查看哪里 |
 |---|---|
+| 审查硬件 lane、回归 fence、CI 工具供应链或 xdist/shared fixture | [CI rules](rules.md) |
 | 查看仓库特有 CI 陷阱 | [CI guides](guides/_index.md) |
 | 调查历史 CI 失败 | [CI incidents](incidents/_index.md) |

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

@@ -0,0 +1,65 @@
+---
+title: "vLLM-Omni CI 规则"
+created: 2026-08-23
+updated: 2026-08-23
+type: rule
+tags: [vllm-omni, ci]
+sources: ["PR #3422", "PR #5074", "PR #5524", "PR #5543", "PR #5670", "PR #5872", "PR #6048", "PR #6096", "PR #6102", "PR #6202", "PR #6208", "PR #6273", "PR #6293", "PR #6339", "PR #6343"]
+confidence: high
+---
+
+# vLLM-Omni CI 规则
+
+只有 `OMNI-CI-数字字母` 是可审计规则 ID。
+
+## Direct 代码快速入口
+
+| PR 描述信号 | 规则 | 第一批源码 |
+|---|---|---|
+| 新模型、nightly、CUDA/NPU、硬件 marker、镜像升级 | `OMNI-CI-1a` | `.buildkite/**` → `pyproject.toml` markers → 目标 e2e/accuracy test |
+| regression/guard、route census、middleware、mutation test | `OMNI-CI-1b` | 公开 app/handler → guard test；先证明旧实现会失败 |
+| pre-commit、SPDX、shellcheck、stability marker | `OMNI-CI-2a` | `.pre-commit-config.yaml`、`.buildkite/**`、`tools/**` |
+| xdist、共享 worker、下载 fixture、进程池 | `OMNI-CI-2b` | `tests/conftest.py`、`tests/helpers/**`、`tests/model_tests/**` |
+
+## OMNI-CI-1a — 硬件 lane 必须真实收集并执行目标路径
+
+- 触发：增加模型、硬件路径、nightly/ready/merge lane，或升级运行时/镜像。
+- 强制：资源数、pytest marker、pipeline 路由和共享 stage registry 同步；必需依赖、模型初始化
+  或 collection 失败必须让 job 失败，并证明目标测试数大于零且原失败在对应硬件消失。
+- 禁止：初始化失败后 skip-green；用 CPU 静态检查代替 CUDA/NPU 执行；只改模型目录而漏掉
+  共享 registry/路由；把临时硬件硬编码留到合并。
+- 验收：当前 head 的目标 lane 记录硬件、依赖版本、collection 数和执行结果；注入缺依赖、坏
+  registry 或错误 marker 时 lane 必须红。 ^[PR #3422] ^[PR #5524] ^[PR #5543]
+  ^[PR #5872] ^[PR #6048] ^[PR #6096] ^[PR #6102]
+
+## OMNI-CI-1b — 回归 fence 必须锚定可观察合同且非空转
+
+- 触发：新增 bug regression、API guard、route census 或 middleware fence。
+- 强制：从 assembled app/公开 handler 观察行为，只改变目标变量；必需 state 不仅检查存在，
+  还要检查非 `None`。测试须在旧实现或代表性 mutation 上失败，在修复后通过。
+- 禁止：绑定可搬迁私有符号或单个 router；用恒真类型断言、错误参数的提前失败、宽泛
+  `>=400`、不同文本或长度冒充目标分支证据。
+- 验收：mutation 分别置空 wiring、移除目标 route/method、绕过 inner middleware，fence 均失败；
+  route census 覆盖应用实际暴露的 HEAD/OPTIONS 和依赖 state key。 ^[PR #3422] ^[PR #5074]
+  ^[PR #5670] ^[PR #6202]
+
+## OMNI-CI-2a — CI 工具、schema 和 hook 是可复现供应链
+
+- 触发：修改 pre-commit/Buildkite schema、下载 lint 工具、SPDX/import 检查或 stability marker。
+- 强制：固定工具版本并校验摘要；声明本地与 CI 强制 hook 矩阵；路径跨 Windows/POSIX
+  归一化；源码头使用项目 SPDX 标识且覆盖 `.sh`；marker 参数 shell-quote 并有明确默认值。
+- 禁止：下载浮动 `stable`；让 rebase 静默回退 hook/marker；未引用包含 `: ` 的 YAML command；
+  用测试名后缀代替硬件 marker。
+- 验收：当前 main schema/pre-commit、DCO 和 marker collection 通过；篡改摘要、Windows 路径、
+  shell header 或非法 stability 参数分别被对应 gate 拒绝。 ^[PR #3422] ^[PR #6273]
+  ^[PR #6293] ^[PR #6343]
+
+## OMNI-CI-2b — 并行测试基础设施隔离任务失败和共享状态
+
+- 触发：xdist、共享下载 fixture、长寿命 judge/transcriber worker 或进程池 retry。
+- 强制：任务级异常后丢弃污染 worker；submit/result 串行，只有进程崩溃可 retry-once；传给
+  xdist 的参数可序列化，依赖固定兼容 major；共享文件在读锁前显式检查存在，写入保持锁语义。
+- 禁止：普通 task error 复用同一进程；为 pytest 生命周期不可达的竞态堆测试；把并行参数或
+  活对象隐式跨进程传递。
+- 验收：OOM、普通异常和 BrokenProcessPool 分别验证隔离/重试；online/offline xdist 均通过，
+  并发 cache miss 只产生一个完整文件。 ^[PR #6208] ^[PR #6339]

knowledge/repos/vllm-omni/components/_index.md

@@ -1,7 +1,7 @@
 ---
 title: "vLLM-Omni 组件 owner"
 created: 2026-07-10
-updated: 2026-07-31
+updated: 2026-08-23
 type: index
 tags: [vllm-omni, components]
 sources: []
@@ -18,6 +18,7 @@ sources: []
 | [Serving](serving/_index.md) | 用户请求、OpenAI API、响应、AsyncOmni engine 生命周期 | [rules](serving/rules.md) |
 | [Model Executor](model-executor/_index.md) | stage config/input、模型加载、worker、跨 stage 数据桥 | [rules](model-executor/rules.md) |
 | [Diffusion](diffusion/_index.md) | diffusion pipeline、denoise、VAE/DiT、并行和 cache | [rules](diffusion/rules.md) |
+| [Host Weight Runtime](host-weight-runtime/_index.md) | immutable host artifact、lease、filesystem store、typed outcome 与 restore transaction | [rules](host-weight-runtime/rules.md) |
 | Distributed | connector、KV 迁移、collective、跨 stage 通信 | [index](distributed/_index.md) |
 | [Scheduler](scheduler/_index.md) | 请求队列、token budget、KV transfer、prefix cache | [rules](scheduler/rules.md) |
 

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

@@ -4,7 +4,7 @@ created: 2026-07-20
 updated: 2026-08-23
 type: rule
 tags: [vllm-omni, components, diffusion]
-sources: ["PR #4341", "PR #5001", "PR #5087", "PR #5088", "PR #5136", "PR #6094", "PR #6385", "PR #6445", vllm_omni/diffusion/worker/diffusion_model_runner.py, vllm_omni/diffusion/model_loader/diffusers_loader.py, vllm_omni/diffusion/distributed/hsdp.py]
+sources: ["PR #4341", "PR #5001", "PR #5087", "PR #5088", "PR #5136", "PR #5543", "PR #5848", "PR #5872", "PR #5981", "PR #6094", "PR #6102", "PR #6279", "PR #6385", "PR #6445", vllm_omni/diffusion/worker/diffusion_model_runner.py, vllm_omni/diffusion/model_loader/diffusers_loader.py, vllm_omni/diffusion/distributed/hsdp.py]
 confidence: high
 ---
 
@@ -20,23 +20,23 @@ confidence: high
 
 | PR 描述在做什么 | 精确规则组 | 第一批 live 源码 |
 |---|---|---|
-| CUDA Graph、compile、fused scheduler/solver、cache path、eager parity | `execution-parity`：`DIFF-1a` | `compile.py::regionally_compile` → `diffusion_model_runner.py::{execute_model,execute_model_batch}` → model denoise/solver |
+| CUDA Graph、compile、fused solver、eager parity、tensor dtype/device | `execution-parity`：`DIFF-1a`–`1c` | `compile.py::regionally_compile` → runner batch → model denoise/solver |
 | seed、request-local generator、guidance=0、并发 RNG、batched generators | `execution-parity`：`DIFF-1b` | `inputs/data.py::OmniDiffusionSamplingParams` → runner `_initialize_generator` → request-batch generator collate |
 | ModelOpt/checkpoint adapter、weight/scale remap、unknown tensor、resolution path | `checkpoint-distributed`：`DIFF-2a` | `diffusers_loader.py::{_get_checkpoint_adapter,load_weights}` → `modelopt.py::{_resolve_target_and_output_names,adapt}` |
 | host-weight artifact、source identity、layout/dtype、warm restore | `checkpoint-distributed`：`DIFF-2d` | `model_loader/host_weights/{source_identity,contracts,identity_adapter}.py` → policy/restorer |
 | HSDP/FSDP、`fully_shard`、DeviceMesh、packed/scalar parameter、FP8 | `checkpoint-distributed`：`DIFF-2b` | `distributed/hsdp.py::{apply_hsdp_to_model,shard_model}` → loader `_load_model_with_hsdp` → `hsdp_fp8.py` |
 | component quantization、text encoder/transformer/VAE 独立配置、owner prefix、meta/offload | `checkpoint-distributed`：`DIFF-2c` | `data.py::_propagate_quantization_from_tf_config` → loader weight sources/post-load → component linear consumer |
 | LPIPS/PSNR/相似度阈值、CPU offload、量化质量证据 | `quality-evidence`：`DIFF-3a` | changed exact case → runner `execute_model` → model pipeline；A/B 同路径 |
-| paged KV/cache、block manager、显存预算、warmup/profile、scheduler admission | `system-runtime`：`DIFF-4a`, `DIFF-4b`, `DIFF-4c` | engine init → `diffusion_kv/initialization.py` → worker memory probe → native allocator → scheduler lifecycle |
+| paged KV/cache、backend/platform、GQA/layout、预算与 admission | `system-runtime`：`DIFF-4a`–`4f` | engine init → `diffusion_kv/{initialization,paged_attention_adapter}.py` → platform hook → scheduler |
 | worker/RPC 异常、rank-status、traceback/device cache 清理 | `system-runtime`：`DIFF-4d` | `diffusion_worker.py::{_execute_rpc,_worker_busy_loop}` 的 raise/reply/status 路径 |
 
 | 审查组 | 什么时候触发 | 规则 ID |
 |---|---|---|
-| `core` | 每次共享 diffusion 审查 | `DIFF-1a`, `DIFF-1b` |
-| `execution-parity` | graph/eager、solver、RNG、generator、zero/default | `DIFF-1a`, `DIFF-1b` |
+| `core` | 每次共享 diffusion 审查 | `DIFF-1a`, `DIFF-1b`, `DIFF-1c` |
+| `execution-parity` | graph/eager、solver、RNG、generator、tensor dtype/device | `DIFF-1a`, `DIFF-1b`, `DIFF-1c` |
 | `checkpoint-distributed` | checkpoint、quantization、HSDP/FSDP、artifact identity | `DIFF-2a`, `DIFF-2b`, `DIFF-2c`, `DIFF-2d` |
 | `quality-evidence` | 质量阈值、offload、A/B case | `DIFF-3a` |
-| `system-runtime` | cache/资源预算、native 边界、feature gate、异常或并发调度 | `DIFF-4a`, `DIFF-4b`, `DIFF-4c`, `DIFF-4d` |
+| `system-runtime` | cache/预算、native/backend/platform、attention layout、异常与并发 | `DIFF-4a`–`4f` |
 | `author-routing` | 只供 Direct reviewer 导航，不作为 finding 规则 | `DIFF-0a`, `DIFF-0b` |
 
 ## 优化路径与 eager 的等价合同
@@ -61,6 +61,15 @@ confidence: high
   到达 consumer。Cosmos3 的落地约束见
   [Cosmos3 规则](../../models/cosmos3/rules.md)。 ^[PR #5001]
 
+### DIFF-1c — 新 tensor 从真实 consumer 派生 dtype 和 device
+
+- 触发：mixed precision pipeline 中新建 mask、index、constant、buffer 或预计算 tensor。
+- 强制：从输入或目标权重派生 device/dtype，整数 index 显式使用 consumer 要求的类型；
+  graph/eager 与 batch 重排后保持 shape、alias 和数值语义。
+- 禁止：依赖 process 默认 fp32/CPU 或隐式 cast/move；只测 shape 而不执行 BF16 consumer。
+- 验收：BF16、错长、batch reorder 和 graph/eager 用例断言 consumer 收到相同 device/dtype、
+  alias 与结果。 ^[PR #5067] ^[PR #5068] ^[PR #5174] ^[PR #5981]
+
 ## Checkpoint 与分布式加载
 
 ### DIFF-2a — checkpoint remap 必须追到已注册且真实消费的目标
@@ -71,15 +80,17 @@ confidence: high
 - 禁止：把 producer 有而当前 consumer 不支持的 tensor 静默过滤；必须 fold/map 或
   fail fast，并在错误中标明依赖的 upstream 版本边界。
 - 验收：测试覆盖已消费 key、未知 key、当前版本不支持的 scale 以及两条 resolution
-  path 的输出名。ModelOpt `pre_quant_scale` 是该规则的原始触发。 ^[PR #5087]
+  path 的输出名；fused mixed-FP8 还须覆盖 weight/scale/shard、gate/up 顺序、nested serialized
+  FP8 和 combined projection，缺 shard 不得默认 0。 ^[PR #5087] ^[PR #5848]
 
 ### DIFF-2b — HSDP/FSDP 修复必须执行真实 fully_shard
 
 - 触发：改动 diffusion HSDP/FSDP 参数过滤、packed/scalar parameter 或 DeviceMesh。
 - 强制：至少用单 rank Gloo + CPU DeviceMesh 执行一次真实 `fully_shard`。
 - 禁止：只断言传给 mock 的 kwargs 后声称分布式语义已覆盖。
 - 验收：普通 float parameter 变为 DTensor；packed uint8/scalar parameter 保持本地
-  identity，并覆盖 loader 的真实调用边界。 ^[PR #5088]
+  identity，并覆盖 loader 的真实调用边界；replicate size 非正值拒绝，1 用 1D、>1 用 2D
+  DeviceMesh，测试 world size 与参数一致。 ^[PR #5088] ^[PR #5872]
 
 ### DIFF-2c — component quantization 独立解析且保留完整 owner 前缀
 
@@ -91,7 +102,8 @@ confidence: high
   隐式覆盖其他组件；因为同属一个模型就量化全部 linear。
 - 验收：至少覆盖“只量化一个组件、其他组件保持 BF16”的真实构造与加载，逐层断言
   命中/排除集合，并验证 meta-device parameter 不会被提前 move。FLUX.2 的具体边界见
-  [FLUX.2 规则](../../models/flux2/rules.md)。 ^[PR #5136]
+  [FLUX.2 规则](../../models/flux2/rules.md)；新增 quantization×offload 组合需给兼容矩阵，
+  未验证 quantizer fail-closed，并核对 dtype/shape/stride。 ^[PR #5136] ^[PR #6279]
 
 ### DIFF-2d — Artifact identity 只信任已验证的不可变来源
 
@@ -115,7 +127,8 @@ confidence: high
 - 禁止：用 50-step A/B 数字为 10-step 测试阈值背书；只写“需要 offload”而不说明
   是资源前提还是功能行为。
 - 验收：运行测试文件中的 exact case，并在规则/配置旁保留最短资源原因；对称 baseline
-  证明质量差异来自目标量化变量。 ^[PR #5136]
+  证明质量差异来自目标量化变量。低 steps smoke 只能证明 runtime compatibility，不得声称
+  BF16 quality parity。 ^[PR #5136] ^[PR #6279]
 
 ## Paged cache、资源预算与系统运行时
 
@@ -165,5 +178,25 @@ confidence: high
 - 验收：测试分别覆盖 `collect_rank_status=true` 与抛出/错误回复路径，断言错误文本仍可见、
   `exc.__traceback__ is None`、cache cleanup 被调用，后续健康 RPC 仍成功。 ^[PR #6385]
 
+### DIFF-4e — paged backend 在启动时按平台和逐层能力闭环
+
+- 触发：启用 paged scheduler、增加 diffusion attention backend 或平台 override。
+- 强制：启动阶段解析并验证每层实际 backend 与当前平台；走 Omni platform hook，保留
+  piecewise/SP 等能力。尚无生产 caller 的模式必须明确告警并文档化。
+- 禁止：未知平台继承 GPU 默认；分配 cache 后到首次 dispatch 才失败；静默占用 paged KV
+  却继续 dense；直接换用 upstream backend 丢失 Omni 能力。
+- 验收：unsupported platform/backend fail-fast；CUDA/NPU 对应 lane 和正式模型 E2E 证明
+  resolved backend；mixed-mask piecewise/SP 回归通过。 ^[PR #5543] ^[PR #6102]
+
+### DIFF-4f — paged attention metadata 不从 padding 猜逻辑布局
+
+- 触发：paged adapter 修改 GQA、prefix/current-token packing、LSE layout 或二维特例。
+- 强制：显式传递 Q/KV head 数、每请求 prefix/current span 和 layout；保持压缩 GQA 与 packed
+  current-token 语义，单 token/单 head 二维输入仍使用同一合同。
+- 禁止：从 padding 长度推断逻辑跨度；在 `sequence == heads` 时猜 LSE 维度；fallback 静默换
+  backend 或把 KV heads 扩成 Q heads。
+- 验收：32Q/8KV、异构 prefix、单 token/单 head、非对称等维 LSE 和 batch compaction 精确
+  对照 dense/reference 输出。 ^[PR #5543] ^[PR #6102]
+
 相关执行流见 [Diffusion architecture](architecture.md)；benchmark 证据合同见
 [performance evidence](../../benchmark/guides/performance-evidence.md)。

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

@@ -0,0 +1,26 @@
+---
+title: "Host Weight Runtime"
+created: 2026-08-23
+updated: 2026-08-23
+type: index
+tags: [vllm-omni, components]
+sources: ["PR #6419", vllm_omni/host_weight_runtime/]
+confidence: high
+---
+
+# Host Weight Runtime
+
+- 源码入口：`vllm_omni/host_weight_runtime/`。
+- 主要职责：跨模型共享的 immutable host artifact、lease、filesystem store、typed outcome
+  和 restore transaction；具体 diffusion producer/identity adapter 仍归 Diffusion owner。
+
+## 什么时候查这里
+
+- 修改 host-weight store、lease/lock、deny/quarantine、locality、fallback 或 restore transaction。
+- 具体 diffusion layout/source identity 同时读取 [Diffusion DIFF-2d](../diffusion/rules.md)。
+
+## 目录内容
+
+| 遇到什么 | 查看哪里 |
+|---|---|
+| typed failure、lease/store concurrency、restore transaction | [rules](rules.md) |