From 7ad984b215b652ca94da0a72ed1376657d6b78a8 Mon Sep 17 00:00:00 2001
From: Ava <ava@apecloud.com>
Date: Tue, 5 May 2026 13:43:17 +0800
Subject: [PATCH 1/5] docs(runtime-contract-preflight): add v1 with 3-layer
 model and decision tree

Add addon-runtime-contract-preflight-guide.md (652 lines) covering chart
spec vs runtime contract drift across 3 layers:

- Layer 1: chart spec field rejected by KB CRD schema (install-time fail)
- Layer 2: vcluster substrate bootstrap precondition (CoreDNS image)
- Layer 5: runtime env contract drift (ActionSet spec.env declare gap)

Layer 0 / 3 / 4 reserved for future sediment. Non-contiguous numbering
explained at section 3 opening.

Layer 5 main 6-section authored by Oracle line addon owner (W7 ActionSet
env audit, ORA-12154 grounded, idc4 19c standalone evidence with double
verification). Polished and folded by SQL Server line.

Layer 2 main 6-section authored by Oracle line addon owner (CoreDNS
ImagePullBackOff grounded, registry.aliyuncs.com fix verified). idc
bastion view inline placeholder for MariaDB line co-author (mirror
family classification, sideload vs image swap tradeoff, blacklist
wisdom, vcluster substrate bootstrap timing pitfalls).

Layer 1 main 6-section drafted with placeholder for SQL Server line
PoC evidence (KB 1.0.2 isExclusive field-not-declared-in-schema), to
be filled after T08 reproduction completes.

Decision tree (mermaid) at section 8 separates Layer 1 / 2 / 5 by
3 evidence questions: install-time fail / smoke-PASS-but-cross-pod-fail
/ ActionSet env declare diff. Same-surface-error different-root-cause
covered as twin-fault scenario in Layer 2 + Layer 5 stack.

Cross-doc family map at section 9 places this doc as the runtime
contract dimension within the preflight family (5 docs, scope strictly
non-overlapping). Cross-refs to chart-vs-kb-schema-skew-diagnosis,
soak-test-result-classification, test-acceptance-and-first-blocker,
probe-classification, and bounded-eventual-convergence guides.

Case appendix A-D covers Oracle W7 grounded, idc4 CoreDNS fix grounded,
SQL Server isExclusive (pending PoC fold-in), MariaDB line mirror
family cross-line evidence (PR #54 reference).
---
 .../addon-runtime-contract-preflight-guide.md | 652 ++++++++++++++++++
 1 file changed, 652 insertions(+)
 create mode 100644 docs/addon-runtime-contract-preflight-guide.md

diff --git a/docs/addon-runtime-contract-preflight-guide.md b/docs/addon-runtime-contract-preflight-guide.md
new file mode 100644
index 0000000..897dc05
--- /dev/null
+++ b/docs/addon-runtime-contract-preflight-guide.md
@@ -0,0 +1,652 @@
+# Addon Runtime Contract Preflight 指南
+
+> **Audience**: addon dev / addon test / cross-line TL
+> **Status**: stable
+> **Applies to**: any KB addon
+> **Applies to KB version**: any (preflight 方法论本身版本无关；具体 ActionSet env 字段集随 KB 版本演化)
+> **Affected by version skew**: yes — chart spec 与 runtime 实际契约的对齐随 KB 版本 / addon 版本 / vcluster substrate 版本三向漂移；本文方法论 stable，具体 declare 字段 / image 路径需对照实测版本
+
+本文面向 Addon 开发与测试工程师，重点解决一类隐藏度极高的失败：**chart install schema 验证全部通过、smoke 测试全 PASS，但 runtime 跑某类操作时 cryptic 报错**。本质是 **chart spec 与 runtime 实际契约漂移**：spec 里没声明的运行时依赖，实际跑起来 silent 失败或被 cryptic 错误掩盖。
+
+## 先用白话理解这篇文档
+
+### 这篇文档解决什么问题
+
+测试报"OpsRequest 失败"或"Backup Job 报 ORA-12154 / DNS resolve fail"时，团队第一反应通常是"DB / network 出问题了"。但这种归因经常错位——**同样的 surface error 可能源自完全独立的 root cause 层**：
+
+1. **Chart 没 declare runtime env**（KB dataprotection ActionSet `spec.env` 缺字段，runtime 引用得到空字符串）
+2. **Substrate 没 bootstrap 好**（vcluster 默认 coredns 镜像拉不到，pod 内 DNS 不工作但 control plane 报 Running）
+3. **真 DB / network 层问题**（少数情况）
+
+笼统说"DB / network bug"会让团队**在错误的层排障**：花 1 小时调 listener / TLS / 重启 pod，最后发现是 ActionSet spec 里少了一个 env 声明。
+
+→ 真正的方法论是：**测试启动前显式 audit chart spec 与 runtime 契约的 3 个对齐 surface（chart spec / vcluster substrate / runtime env contract），把 cryptic 错误前置成可读的 preflight fail-fast**。
+
+### 何时本文方法论 apply
+
+| 场景 | 关键决策 |
+|---|---|
+| 接 KB dataprotection 的 addon 写 Backup / Restore ActionSet | 必读 §6.2，audit `spec.env` declare 与 backup script 引用差集 |
+| 在 vcluster 上跑 smoke / chaos / dataprotection | 必读 §6.3，preflight CoreDNS image + 跨 pod DNS resolution |
+| chart `install` 报 `field not declared in schema` | 必读 §6.1，区分 chart 字段 / KB 版本字段 / KB main 三种漂移 |
+| smoke 全 PASS 但 dataprotection / cross-pod 操作 fail | 走 §8 决策树，区分 Layer 1 / 2 / 5 |
+| 上 IDC vcluster 之前 | 4-step preflight 走一遍（§4） |
+| 同 surface error 多次出现，但根因 hopping | §7 archetype "chart spec doesn't declare a runtime requirement" |
+
+### 读完你能做什么决策
+
+- **写新 addon 时**：能 5 秒列出 3 个 runtime contract 对齐 surface，避免 silent 漂移
+- **接 dataprotection 时**：能立刻 audit ActionSet spec.env vs backup script 引用的差集
+- **vcluster bootstrap 时**：能 preflight CoreDNS image 并选对 mirror（aliyuncs / dockerproxy.net / ACR / sideload）
+- **看到 `ORA-12154 TNS:could not resolve` 这类 cryptic 错误时**：能用 §8 决策树 60 秒分到正确 layer，不再错误归 DB
+- **review chart PR 时**：能识别"chart spec 看起来 OK 但 runtime 会 silent fail"的 contract gap 并 block
+
+### 为什么独立成篇
+
+跟 [`addon-kb-schema-version-preflight-guide.md`](addon-kb-schema-version-preflight-guide.md)（KB schema 三层 image/chart/CRD 版本对齐）+ [`addon-test-script-preflight-guide.md`](addon-test-script-preflight-guide.md)（test runner 跨 line shared client state）+ [`addon-vcluster-kb-install-preflight-guide.md`](addon-vcluster-kb-install-preflight-guide.md)（vcluster 内 KB 安装 bootstrap）+ [`addon-multi-ns-registry-scan-preflight-guide.md`](addon-multi-ns-registry-scan-preflight-guide.md)（多 ns 测试 scope 拆分）一起构成 **preflight family**，覆盖 chaos test lifecycle 启动前的不同对齐 surface。
+
+各 doc scope 严格独立：
+- `kb-schema-version-preflight` = **schema dimension**（image / chart / CRD 三层 artifact 版本一致）
+- 本文 = **runtime contract dimension**（chart spec 与 runtime 实际契约对齐）
+- `test-script-preflight` = **shared client state dimension**（跨 line tenant kubeconfig）
+- `vcluster-kb-install-preflight` = **bootstrap harness dimension**（KB install in vcluster 时序）
+- `multi-ns-registry-scan-preflight` = **测试 scope dimension**（verified vs scan-only 二分）
+
+本文聚焦 **"chart spec 与 runtime 实际契约的 3 个对齐 surface"** 这一独立主题，不与 schema-version 重叠。
+
+---
+
+## 适用场景
+
+当你负责或维护以下工作时，本文适用：
+
+- 写新 addon 的 ActionSet（Backup / Restore / Reconfigure / Switchover），需声明 `spec.env`
+- 把 addon 上 IDC 共享 k8s + per-line vcluster
+- chart `install` 报 `field not declared in schema` 时根因定位
+- 在 vcluster 上跑 dataprotection 测试 / cross-pod replication 测试
+- chaos test lifecycle preflight 全量审计
+
+不适用（属于其他 doc）:
+- KB image / chart / CRD 三层 artifact 版本对齐 → [`addon-kb-schema-version-preflight-guide.md`](addon-kb-schema-version-preflight-guide.md)
+- runner shared `~/.kube/config` 跨 line 干扰 → [`addon-test-script-preflight-guide.md`](addon-test-script-preflight-guide.md)
+- helm install KB 在 vcluster 时序 → [`addon-vcluster-kb-install-preflight-guide.md`](addon-vcluster-kb-install-preflight-guide.md)
+- 测试 fail 后 4-state 归类 → [`addon-soak-test-result-classification-guide.md`](addon-soak-test-result-classification-guide.md)
+- chart `field not declared in schema` 局部 bug vs 代差 vs 跟 KB main → [`addon-chart-vs-kb-schema-skew-diagnosis-guide.md`](addon-chart-vs-kb-schema-skew-diagnosis-guide.md)（本文 §6.1 引用此 doc，不重复）
+
+## Runtime Contract 三 Layer 模型
+
+`addon-kb-schema-version-preflight-guide.md` 的 schema dimension 用 image / chart / CRD 三层定义"哪个版本"。本文的 runtime contract dimension 用 **三 Layer 模型**定义"chart spec 与 runtime 实际契约的对齐 surface"。
+
+> **编号说明**：Layer 编号采用 **non-contiguous numbering（1 / 2 / 5）**，**Layer 0 / 3 / 4 留作未来 reservation**。Schema dimension 的 image / chart / CRD 三层在本文映射为 Layer 0（image 是底层 artifact, schema-version doc 主管），Layer 3 / 4 留给"storage version migration / API removal" 这类未来 sediment 主题。当前实战 grounded sample 集中在 Layer 1 / 2 / 5。
+
+| Layer | 维度 | 漂移现象 | 主管 doc |
+|---|---|---|---|
+| Layer 0 | Image artifact (reserved) | image build 不一致、digest 漂移 | [`addon-kb-schema-version-preflight-guide.md`](addon-kb-schema-version-preflight-guide.md) |
+| **Layer 1** | **Chart spec 字段** | chart 模板字段被 KB CRD schema reject（install 阶段就 fail） | 本文 §6.1 + [`addon-chart-vs-kb-schema-skew-diagnosis-guide.md`](addon-chart-vs-kb-schema-skew-diagnosis-guide.md) |
+| **Layer 2** | **vcluster substrate bootstrap precondition** | vcluster 默认 coredns / metrics-server / 关键基础组件 image 拉不到，control plane 报 Running 但 cluster-internal DNS 不工作 | 本文 §6.3 |
+| Layer 3 | Storage version migration (reserved) | CRD storage version 升级中断、object 残留旧 version | (planned, future) |
+| Layer 4 | Removed API surface (reserved) | 删除的 API 仍被脚本引用 | (planned, future) |
+| **Layer 5** | **Runtime env contract** | chart spec 没 declare addon 自身 env，runtime 引用得到空字符串，下游 cryptic 错误（不是 install fail） | 本文 §6.2 |
+
+**Layer 1 vs Layer 5 的判别**：
+- Layer 1 = **install-time schema reject**（helm install 直接 fail，message: `field not declared in schema`）
+- Layer 5 = **runtime-time silent-empty**（install / smoke 全 PASS，dataprotection 时 cryptic error）
+
+**Layer 2 vs Layer 5 的判别**：
+- Layer 2 = **substrate side**（vcluster 自己的 coredns / 基础组件没起来；fix 在 cluster bootstrap）
+- Layer 5 = **chart spec side**（chart 模板缺字段；fix 在 chart 模板）
+- 同 surface error（如 ORA-12154 TNS:could not resolve），不同根因，必须用 §8 决策树区分
+
+## 4-step Preflight 流程
+
+接 dataprotection 或上 vcluster 之前，按 4 步走一遍：
+
+### Step 1 — Layer 0/1: schema 三层版本对齐
+
+走 [`addon-kb-schema-version-preflight-guide.md`](addon-kb-schema-version-preflight-guide.md) 的三层 audit（image / chart / live CRD）。本步通过后才进 Layer 1 chart spec 字段 audit：
+
+```bash
+# Chart 模板字段是否被当前 KB CRD schema 接受？
+helm template <release> <chart> | kubectl apply --dry-run=server -f - 2>&1 | grep -E '(field not declared|unknown field|forbidden)' && echo "Layer 1 fail" || echo "Layer 1 pass"
+```
+
+### Step 2 — Layer 2: vcluster substrate bootstrap
+
+vcluster control plane Running 不等于 cluster 内部基础设施 Ready。必检：
+
+```bash
+# CoreDNS 是否真的在跑（不仅 deployment 存在）
+kubectl -n kube-system get pods -l k8s-app=kube-dns | grep -v Running | grep -v NAME && echo "Layer 2 fail" || echo "Layer 2 pass"
+
+# 任意业务 pod 内能否 resolve cluster-internal DNS
+kubectl exec <any-pod> -- nslookup kubernetes.default.svc.cluster.local 2>&1 | grep -E '(NXDOMAIN|server can.t find)' && echo "Layer 2 fail" || echo "Layer 2 pass"
+```
+
+### Step 3 — Layer 5: ActionSet env contract audit
+
+每条 ActionSet（Backup / Restore / 等）audit `spec.env` declare 与 backup script 引用的差集：
+
+```bash
+# 列 ActionSet declare 的 env name
+kubectl get actionset <name> -o jsonpath='{.spec.backup.backupData.env[*].name}' | tr ' ' '\n' | sort > /tmp/declared.txt
+
+# Grep backup script 引用的 env
+grep -oE '\$\{[A-Z_]+\}' <backup-script>.sh | sed 's/[${}]//g' | sort -u > /tmp/referenced.txt
+
+# 差集即 Layer 5 风险 surface
+comm -23 /tmp/referenced.txt /tmp/declared.txt
+# 输出非空 = chart 没 declare 但 script 引用 = Layer 5 silent-empty 风险
+```
+
+注意：DP_* 框架变量（`DP_DB_HOST` / `DP_DB_PORT` / `DP_DB_USER` / `DP_DB_PASSWORD`）由 KB dataprotection runner 自动注入，不需 ActionSet declare；但 addon 自身需要的 `ORACLE_SID` / `MYSQL_PORT` / `PGDATABASE` 等必须显式 declare。
+
+### Step 4 — 实跑 1 个 dataprotection / cross-pod 操作 round-trip
+
+前 3 步全 pass 后，必跑一次端到端验证：发起一个 Backup（最小数据集）、观察 pod 内 Backup script 的 env list 与连接是否成功。空跑 install 不算 preflight 通过。
+
+```bash
+# 创建最小 Backup
+kubectl create -f - <<YAML
+apiVersion: dataprotection.kubeblocks.io/v1alpha1
+kind: Backup
+metadata:
+  name: preflight-backup-$(date +%s)
+spec:
+  backupPolicyName: <cluster>-<engine>-backup-policy
+  backupMethod: <method>
+YAML
+
+# 等到完成 / 失败
+kubectl get backup -w | grep preflight-backup
+```
+
+4 步全 pass 才是 ready-for-test 状态。任意一步 fail 都不能进 chaos / soak / production handoff。
+
+## 跨引擎口径同步（4-pillar 表）
+
+任何 addon 接 dataprotection 时，对照下表填 4 pillar，确保 runtime contract 完整：
+
+| Pillar | 验证内容 | Layer | 命令模板 |
+|---|---|---|---|
+| **Spec declare** | ActionSet `spec.env` 是否 declare 引擎自身需要的 env | Layer 5 | `kubectl get actionset <name> -o jsonpath='{.spec.backup.backupData.env[*].name}'` |
+| **Script reference** | backup script 引用的 env 是否都在 Spec declare 集合中 | Layer 5 | `grep -oE '\$\{[A-Z_]+\}' <script>.sh \| sort -u` |
+| **Substrate ready** | vcluster CoreDNS / 基础组件是否真 Running（image 是否 pull 成功） | Layer 2 | `kubectl -n kube-system get pods -l k8s-app=kube-dns` |
+| **Round-trip verify** | 端到端跑一个最小 Backup 是否 Completed | All | `kubectl create -f minimal-backup.yaml; kubectl get backup -w` |
+
+每 pillar 必须 explicit pass 才能 ship。Pass 标准 grounded 在 §6 三 Layer 主体的 Reproduction / Fix path 子节。
+
+## 三 Layer 主体（6-section schema）
+
+每 Layer 用同一 schema 描述：Symptom / Trigger / Root cause / Reproduction / Fix path / Cross-engine impact + Owner + Source datapoint。
+
+### §6.1 Layer 1 — Chart spec 字段 KB CRD schema reject（install-time）
+
+**Symptom**
+
+```
+helm install <release> <chart> --version <ver>
+Error: error validating "": error validating data: ValidationError(...): field <field> not declared in schema
+# 或
+Error: failed to install... strict decoding error: unknown field "<field>"
+```
+
+Install 阶段直接 fail，**永远到不了 runtime**。是 Layer 1 与 Layer 5 的本质区别。
+
+**Trigger**
+
+- Chart 模板用了某 KB CRD 字段，但当前 KB 版本 CRD schema 不接受（chart 跟 KB main，KB release 还未 cherry-pick）
+- Chart 升级到新 KB CRD 字段，但 install 目标 KB 版本是旧版（cross-major-version install）
+- 局部 chart bug：字段拼写错 / 字段位置错（应在 spec 下却放在 metadata 下）
+
+**Root cause**
+
+KB CRD schema 是 strict-decode（`strict-decoding`），任何 chart 模板渲染出的字段如果不在 OpenAPI schema 里就 reject。Schema 演化随 KB 版本，chart 也随 addon 版本演化，两者**版本带（version band）对齐**才是正确状态。
+
+具体 3 种漂移形态见 [`addon-chart-vs-kb-schema-skew-diagnosis-guide.md`](addon-chart-vs-kb-schema-skew-diagnosis-guide.md)：「chart 局部 bug」/「整代代差」/「chart 跟 KB main 但 API 未发布」。本文不重复，只把 Layer 1 nudge 到对应 doc。
+
+**Reproduction**
+
+```bash
+# 复现「chart 跟 KB main 但 API 未发布」案例
+# Jerry KB 1.0.2 PoC 发现 isExclusive 字段：
+helm install oracle19c-test oceanbase/oceanbase-oracle-19c \
+  --version <chart-with-isExclusive> --kube-version 1.30 \
+  -n test --create-namespace
+
+# 错误（server-side strict decode）:
+# error validating: field "isExclusive" not declared in schema for ComponentDefinition.spec.systemAccounts[0]
+
+# 验证 KB CRD schema 是否包含字段
+kubectl get crd componentdefinitions.apps.kubeblocks.io -o yaml | grep -A 5 isExclusive
+# 输出空 = KB 1.0.2 schema 没 isExclusive 字段
+
+# 验证 chart 模板使用了字段
+helm template <chart> | grep isExclusive
+# 输出非空 = chart 跟 KB main 但 KB 1.0.2 release 未 cherry-pick
+```
+
+**Fix path**
+
+3 种漂移对应 3 种 fix（详见 [`addon-chart-vs-kb-schema-skew-diagnosis-guide.md`](addon-chart-vs-kb-schema-skew-diagnosis-guide.md)）：
+
+- **Chart 局部 bug**: 修 chart 模板字段
+- **整代代差**: addon 测试矩阵约束 chart 版本与 KB 版本带，CI 增加 install dry-run gate
+- **Chart 跟 KB main**: chart 暂时降级到不引用未发布字段，或 cherry-pick 字段进 KB release（看决策权属）
+
+**Cross-engine impact**
+
+| 引擎 | 已观察的 Layer 1 漂移 | KB 版本 |
+|---|---|---|
+| Oracle | `isExclusive` (systemAccounts) chart 跟 KB main 但 1.0.2 未 cherry-pick | 1.0.2 / 1.0 main |
+| OceanBase | (同 framework，pending case) | TBD |
+| MySQL | `parametersDefinition.toolsSetup.toolConfigs[].image` 跨 KB 1.0.x 演化 | 1.0.x |
+| 通用 | `ComponentDefinition.spec.lifecycleActions.*` 字段集随 KB 版本演化 | 1.0.x → 1.1.x |
+
+**Owner**
+
+- Chart 模板修复: addon owner（如 Oracle = James）
+- KB CRD schema 同步: KB platform team
+- 跨版本测试矩阵: addon test owner
+
+**Source datapoint**
+
+- Jerry SQL Server line PoC：KB 1.0.2 install with chart-from-main 复现 "field not declared" + client-side strict decoding error，msg=<待 fold-in> 等 Jerry 跑完 12c T08 后回填具体 error wording。
+- Cross-line case: [`addon-chart-vs-kb-schema-skew-diagnosis-guide.md`](addon-chart-vs-kb-schema-skew-diagnosis-guide.md) §<TBD> 收录 chart-跟-main 漂移现象。
+
+---
+
+### §6.2 Layer 5 — Runtime env contract drift（chart 没 declare runtime env，runtime 拿到 empty → 下游 cryptic 报错）
+
+**Symptom**
+
+```
+RMAN-04005: error from target database:
+ORA-12154: TNS:could not resolve the connect identifier specified
+```
+
+Surface 报错指向 "DNS / connect string 解析失败"，但 root cause 不在 DNS — 在 chart spec.env 缺 declare 关键 runtime 变量，runtime 引用空字符串构造 connect string，EZ-Connect parse 出 "host: / SVC:" 这种 malformed 形态 → ORA-12154。
+
+**Trigger**
+
+KB dataprotection Job (Backup / Restore) 的 ActionSet `spec.env` 只 declare 了 dataprotection 框架变量（DP_DB_HOST / DP_DB_PORT / DP_DB_USER / DP_DB_PASSWORD），但 addon backup 脚本引用了 addon 自身需要的额外变量（如 Oracle 的 ORACLE_SID / ORACLE_PORT）。chart install 阶段 schema validation 不会 catch 这种 "脚本引用 vs spec.env declare" 的不一致 — bash variable 引用 unset env 默认 expand 为空字符串而不报错。
+
+**Layer 5-specific signal**: smoke T01-T07（component-level workflow 跑在 pod 内，env 已 set）全 PASS，**只有** dataprotection-class（Backup / Restore Job 用 ActionSet env subset）测试 fail。这是 Layer 5 与 Layer 1 的判别 — Layer 1 是 install-time schema reject，Layer 5 是 runtime-time silent-empty。
+
+**Root cause**
+
+Chart-vs-runtime 契约漂移：
+
+- chart 模板 (`templates/actionset-rman.yaml` / `actionset-expdp.yaml`) 没 declare addon-specific env
+- backup script (`oracle-rman-backup.sh` 等) 引用 `${ORACLE_PORT}` / `${ORACLE_SID}` / 派生量 `${ORACLE_UNIQUE_NAME}=${ORACLE_SID}_${pod_index}`
+- KB dataprotection Job runner 启动 pod 时只注入 DP_* 框架变量
+- bash 引用 unset env → empty → connect string `${DP_DB_USER}/...@${DP_DB_HOST}:${ORACLE_PORT}/${ORACLE_UNIQUE_NAME}` 渲染成 `c##kbdpuser/...@<host>:/_0` 这种 malformed
+- sqlplus / rman EZ-Connect parse fail → ORA-12154
+
+**Reproduction**
+
+```bash
+# 复现条件：cluster Running，smoke 全 PASS，发起一个 Backup
+kubectl create -f - <<YAML
+apiVersion: dataprotection.kubeblocks.io/v1alpha1
+kind: Backup
+metadata:
+  name: test-rman-backup
+spec:
+  backupPolicyName: <cluster>-oracle-backup-policy
+  backupMethod: oracle-rman
+YAML
+
+# 观察 Backup pod logs:
+kubectl logs <backup-pod> -c <container>
+# RMAN-04005 + ORA-12154
+
+# 验证 env 缺失:
+kubectl get pod <backup-pod> -o jsonpath='{.spec.containers[0].env[*].name}' | tr ' ' '\n' | grep -E '^(ORACLE_SID|ORACLE_PORT)$' || echo "MISSING"
+# 输出: MISSING
+```
+
+**Fix path — 双半 pattern**
+
+**Half A (chart, structural fix)**: ActionSet 模板 `spec.backup.backupData.env` / `spec.restore.prepareData.env` 显式 declare addon-specific 变量：
+
+```yaml
+env:
+  - name: ORACLE_SID
+    value: ORCLCDB
+  - name: ORACLE_PORT
+    value: "1521"
+```
+
+**Half B (script, defensive fallback for back-compat / live patch)**: backup script 在引用前显式声明 default + 必填断言：
+
+```bash
+: "${ORACLE_PORT:=${DP_DB_PORT:-1521}}"  # 默认 fallback 到 dataprotection 框架变量 DP_DB_PORT
+: "${ORACLE_SID:?ORACLE_SID env is required (must be injected via ActionSet spec.env)}"  # 必填断言
+ORACLE_UNIQUE_NAME=${ORACLE_SID}_${pod_index}
+```
+
+Half A 是 long-term structural fix；Half B 是 production hotfix doctrine（已在 prod 部署的旧 chart 不能改时，live patch ActionSet env + 同时部署 script defensive fallback 兼容前向）。
+
+**Live patch sequence** (production hotfix):
+
+```bash
+kubectl patch actionset oracle-rman-19c --type=json -p='[
+  {"op":"add","path":"/spec/backup/backupData/env","value":[
+    {"name":"ORACLE_SID","value":"ORCLCDB"},
+    {"name":"ORACLE_PORT","value":"1521"}
+  ]}
+]'
+# 重复 for oracle-rman + oracle-expdp ActionSet
+```
+
+**Cross-engine impact**
+
+任何用 KB dataprotection ActionSet（Backup / Restore Job）+ 引擎自身有 PORT / SID / SERVICE 等运行时 env 的 addon 都暴露此 archetype：
+
+| 引擎 | 可能受影响的 env 变量 | 受影响 ActionSet |
+|---|---|---|
+| Oracle | ORACLE_SID / ORACLE_PORT / ORACLE_UNIQUE_NAME | rman / expdp |
+| MySQL | MYSQL_PORT / MYSQL_HOST_PRIMARY | xtrabackup / mysqldump |
+| PostgreSQL | PGPORT / PGUSER / PGDATABASE | pg_basebackup / pg_dump |
+| MongoDB | MONGO_PORT / replicaSet name | mongodump |
+| SQL Server | MSSQL_PORT / instance name / AG endpoint port | (audit pending — SQL Server line owner Tom 自查) |
+
+**诊断 protocol**: 任何 addon 接 dataprotection 时，audit `kubectl get pod <backup-pod> -o yaml` 的 env list，对照 backup script grep `\$\{[A-Z_]+\}` 引用，差集即为 Layer 5 风险 surface。
+
+**Owner**
+
+- Half A chart fix: addon owner（Oracle owner = James）
+- Half B script defensive fallback: addon owner
+- Cross-engine audit doctrine: 跨 line（每引擎自查）
+
+**Source datapoint**
+
+- Commit: `345bfef9` 在 `oracle/release-1.0-merge-audit` branch（W7 audit item, will land via W-chain consolidation PR — 待开）
+- 6 files +36 lines: `templates/actionset-rman.yaml` / `templates/actionset-rman-19c.yaml` / `templates/actionset-expdp.yaml` (Half A) + `dataprotection/rman-full-backup.sh` / `dataprotection/oracle-expdp-backup.sh` / `dataprotection/oracle-expdp-restore.sh` (Half B)
+- Live verification: Backup `o19-i4-8854-rman19c-w7verify2` Status=Completed, 553MB, 2m32s on idc4 19c standalone
+- Evidence pack: `work/oracle-idc4-migration/W7-verify-evidence/` (00-summary.md + 5 yaml/txt artifacts)
+- Second engine confirm (in progress): 12c T08 fresh backup verification on cluster `o12-t8-21609`，CoreDNS aliyuncs + ActionSet env declared 双 fix 端到端验证（pending — 完成后回填到 Source datapoint）
+
+> **Co-author note**: 本节 6-section content drafted by **Oracle line addon owner** (W7 ActionSet env audit + ORA-12154 root cause analysis), polished and folded by SQL Server line for cross-line generalization.
+
+---
+
+### §6.3 Layer 2 — vcluster substrate bootstrap precondition（vcluster 默认依赖外网拉镜像，私有 idc / 离线 idc 不通）
+
+**Symptom**
+
+- cluster Running，业务 pod READY，smoke T01-T07 全 PASS
+- 但任何**从 pod 内做 DNS 解析**的环节失败：dataprotection backup / restore Job、cross-pod network 类用例（SQL\*Net / DG broker / Sentinel sub-cluster）
+- 表象错误**与 Layer 5 同名**（如 ORA-12154 TNS:could not resolve），需要看 trigger 区分
+
+**Trigger**
+
+vcluster bootstrap 阶段创建 `coredns` deployment 用 default image：
+```
+docker.io/coredns/coredns:1.10.1
+```
+私有 idc / 离线 idc 上：
+- docker.io 直拉受限或被防火墙挡（私有 idc 不能裸出墙）
+- ImagePullBackOff，pod 永远 Pending
+- vcluster control plane 报告 cluster Running（k3s embedded apiserver Running）但 cluster-internal DNS 实际不工作
+
+**为何 smoke T01-T07 PASS**：
+- KB / addon 大部分 smoke 用 `kubectl exec -- <pod-internal-cmd>` 触发（component-level 工作流不依赖 cluster DNS）
+- 在 pod 内访问本机 listener 走 localhost / unix socket，不需要 DNS resolve
+- backup Job 是从一个**独立 pod**通过 `${DP_DB_HOST}` 远程连引擎 pod，必须经 cluster DNS resolve headless service / fqdn
+
+**Layer 2 vs Layer 5 的判别 protocol（同 surface symptom 不同根因）**:
+
+```bash
+# 在引擎 pod 内做 EZ-Connect 解析测试（绕开 ActionSet env）
+kubectl exec <engine-pod> -- bash -c '
+  for target in "<short-host>:1521/<svc>" "<fqdn>:1521/<svc>" "<ip>:1521/<svc>"; do
+    echo "=== Test $target ==="
+    sqlplus -S "user/pass@$target" <<<"select 1 from dual; exit;"
+  done
+'
+```
+- 全部 SUCCESS → 不是 Layer 2，再排 Layer 5（ActionSet env declare gap）
+- 短主机名 fail / fqdn or IP success → **Layer 2 confirmed**（DNS 不工作但 IP 直连工作）
+- 全部 fail → 不在 Layer 2 / Layer 5 scope（数据库 listener 本身问题）
+
+**Root cause**
+
+vcluster 默认 manifest 把 `coredns` 镜像 hardcode 成 `docker.io/coredns/coredns:1.10.1`。这是 vcluster upstream（loft-sh/vcluster）默认行为，没考虑离线 idc 场景。一旦 control plane 起来但 coredns 拉不到，cluster 处于 "pseudo-Running"：`kubectl get nodes` / `kubectl get pods` 都正常返回，但任何 pod 内 `nslookup` / EZ-Connect / cross-pod-by-name 失败。
+
+**Reproduction**（在 substrate 已知坏的 idc 重现）
+
+```bash
+# 1. 确认 coredns ImagePullBackOff
+kubectl -n kube-system get pods -l k8s-app=kube-dns
+# coredns-xxx 0/1 ImagePullBackOff
+
+# 2. 确认 image 引用
+kubectl -n kube-system get deploy coredns -o jsonpath='{.spec.template.spec.containers[0].image}'
+# docker.io/coredns/coredns:1.10.1
+
+# 3. 在业务 pod 内复现 DNS fail
+kubectl exec <业务-pod> -- nslookup kubernetes.default.svc.cluster.local
+# server can't find kubernetes.default.svc.cluster.local: NXDOMAIN
+
+# 4. 在业务 pod 内复现 cross-pod-by-name 失败但 IP 直连成功
+kubectl exec <业务-pod> -- bash -c 'getent hosts <peer-pod>.<svc>.<ns>.svc.cluster.local'
+# (no output; resolution fail)
+```
+
+**Fix path**
+
+```bash
+kubectl set image deployment/coredns -n kube-system \
+  coredns=registry.aliyuncs.com/google_containers/coredns:1.10.1
+# 等 ~10s 看 coredns 1/1 Running
+kubectl -n kube-system get pods -l k8s-app=kube-dns -w
+```
+
+**Mirror 选型实测（aliyuncs vs apecloud-registry vs dockerproxy.net）**:
+
+| Mirror 路径 | 实测结果 | 适用 |
+|---|---|---|
+| `apecloud-registry.cn-zhangjiakou.cr.aliyuncs.com/apecloud/coredns:1.10.1` | **fail (`not found`)** — coredns 不在 apecloud 私 ACR 里 | ApeCloud build/sideload 的 image only（KB / 引擎产物） |
+| `registry.aliyuncs.com/google_containers/coredns:1.10.1` | **SUCCESS** — Running 1/1 in 9s | K8s 系列基础组件镜像（coredns / etcd / metrics-server）通用 mirror |
+| `dockerproxy.net/coredns/coredns:1.10.1` | （未实测，可能可用，看 idc 防火墙规则） | docker.io 中转 mirror，适合 chart 主体 docker.io 路径 |
+
+**Mirror 选型 doctrine**（cross-line idc 实战结论）:
+
+- **Family classification**：mirror 路径按目标 image 仓库归一：`docker.io/*` 走 dockerproxy.net 主路 / `gcr.io/*` 与基础组件走 aliyuncs `google_containers` / `ApeCloud build` 私货走 apecloud-registry / 兜底走 sideload。不要混路径——同 family image 走同一 mirror，避免黑名单冲突。
+- **Engine 私货分流**：addon 引擎自己 build 的 image（KB / 引擎产物 / xuriwuyun 这类内部 base）只走 apecloud-registry；公共组件（CoreDNS / etcd / metrics-server）只走 aliyuncs；不要把引擎私货扔进公共 mirror 期望命中。
+
+**Sideload vs deployment image swap 取舍**（Helen MariaDB line idc bastion view co-authored）:
+
+| Path | 适用 | 操作 |
+|---|---|---|
+| **Per-node sideload** | PR / dev 镜像，stable tag 还没发到 registry | `kubectl cp tar → ctr -n k8s.io images import` 推到每节点 + CmpD `imagePullPolicy: IfNotPresent` immutable（避免 pod 重启时再去拉） |
+| **Deployment image swap** | Stable tag 已在公共 mirror | `kubectl set image deployment/<name> ...` 改 chart values.image 路径，走正常 pull cache hit |
+
+**Sideload 现场踩坑**（grounded sample）:
+- CmpD `imagePullPolicy` 是 immutable 字段：要在 install 时就设成 `IfNotPresent`，否则后期改 spec 会被 reject
+- `ctr -n k8s.io images import` 在每节点必须重做（多节点 cluster 不会自动同步）
+- Mac cross-compile 镜像后 `docker save → kubectl cp tar → ctr import` 三步链 toolchain 一致
+
+**Mirror 黑名单 wisdom**（idc 实战踩过的失败 path）:
+- `alpine` vs `glibc` 基础镜像：alpine 在某些 KB toolchain pull 报 `exec format error` 或 lib 缺失（musl libc 不兼容 KB build），需 glibc-based base
+- `kubeblocks-tools` 1.0.2 vs 1.0.0 跨小版本 image tag 命名不一致，老 mirror 可能只缓存 1.0.0，pull 1.0.2 命中 NotFound
+- `xuriwuyun/golang-base` 这类内部 base 不在公共 mirror，必须 apecloud-registry 或 sideload；忘 sideload 是高频踩点
+
+**Vcluster substrate bootstrap 时序常见踩点**（Helen MariaDB line co-authored）:
+- **CoreDNS upstream 配置**：vcluster CoreDNS 默认 forward 到 host k8s 的 CoreDNS。host k8s CoreDNS 配置错（forward 到 unreachable upstream）会引发 vcluster 内 nslookup 间歇失败。
+- **Image cache warm-up**：CmpD `imagePullPolicy: IfNotPresent` 假设节点已有 image。第一次 install 时如果未 sideload，pod 永远 ImagePullBackOff 不报错（Reason 是 ErrImagePull 不是 ImageNotFound）。
+- **Secret kubeconfig mount 时序**：vcluster syncer 启动早于 vcluster apiserver Ready，Secret kubeconfig mount 进 syncer pod 时如果还没生成完整，syncer 报 `Unauthorized` 但 retry 几次后会自愈。看到 `Unauthorized` 不要立刻怀疑权限，先看 vcluster apiserver pod logs 是否 Running。
+- **NodePort SAN 与 cert mismatch**：vcluster apiserver cert SAN 默认只含 cluster-internal name；从 host k8s NodePort 直连时 hostname 不在 SAN 里 → TLS handshake fail。bootstrap 时要 `--tls-san=<host-ip>` 显式加 SAN。
+
+**Cross-engine impact**
+
+任何用 vcluster + 跨 pod 通信的 KB addon 都暴露此 archetype：
+
+| 引擎 | 跨 pod 通信场景 | Layer 2 表象 |
+|---|---|---|
+| Oracle | DG broker (cross-pod TCP/IP listener)、SQL\*Net client connect、dataprotection backup Job | ORA-12154 TNS:could not resolve |
+| MySQL | replication channel、xtrabackup remote copy、dataprotection Job | "Can't connect to MySQL server" / "Unknown MySQL server host" |
+| PostgreSQL | streaming replication primary→standby、pg_basebackup remote、dataprotection Job | "could not translate host name" |
+| MongoDB | replica set member discovery、mongos→shard routing、dataprotection Job | "Hostname can't be resolved" |
+| Redis/Valkey | cluster bus 跨 pod、Sentinel discovery、replication | `Could not connect to Redis at <host>:<port>: Name or service not known` |
+| SQL Server | Always-on AG primary→secondary log shipping 跨 pod TCP、AG endpoint discovery 走 fqdn | `A network-related or instance-specific error occurred while establishing a connection` |
+| MariaDB | semisync replication channel、mariabackup remote、Galera cluster discovery | `Lost connection to MySQL server` / `getaddrinfo() thread failed` |
+
+> **Surface error wording 校稿状态**：Oracle ✅ (W7 grounded) / MariaDB ✅ (Helen co-author) / 其他 5 引擎 wording 是 cross-line 推断，待对应 line owner 实战 confirm 后回填具体 grounded sample。
+
+**诊断 protocol**（5-min preflight cross-ref `addon-smoke-test-pre-flight-checklist-guide.md` §7）:
+```bash
+# 任何 vcluster 上 smoke / dataprotection 测试启动前
+kubectl -n kube-system get pods -l k8s-app=kube-dns 2>&1 | grep -v ImagePullBackOff || echo "ALERT: coredns down"
+```
+
+**Owner**
+
+- **vcluster bootstrap fix**: vcluster owner / idc bootstrap owner（Alice IDC checklist owner co-edit；MariaDB line idc bastion view co-author for §6.3 inline view）
+- **Engine-side resilience**: addon owner（fqdn vs short-name preference in connect string；fallback to IP 在 DNS 失败时）— 但此非主修 path，Layer 2 fix 应在 substrate side
+- **Sediment doctrine**: cross-line（每 line addon owner 把 Layer 2 archetype 加进自己 addon's preflight checklist）
+
+**Source datapoint**
+
+- 2026-05-05 idc4 oracle-vcluster `o19-i4-8854` 19c standalone 实测：
+  - Initial state: coredns `docker.io/coredns/coredns:1.10.1` ImagePullBackOff
+  - Symptom: Backup CR `o19-i4-8854-rman19c-w7verify` Failed with ORA-12154（W7 ActionSet env 已修补，仍 fail —— 证明 Layer 2 与 Layer 5 独立 root cause）
+  - EZ-Connect parse test in oracle pod confirmed short-host fail / fqdn success / IP success
+  - Fix: `kubectl set image deployment/coredns -n kube-system coredns=registry.aliyuncs.com/google_containers/coredns:1.10.1`
+  - Verification: Backup `o19-i4-8854-rman19c-w7verify2` Status=Completed 553MB 2m32s
+- Evidence pack: `work/oracle-idc4-migration/W7-verify-evidence/` (00-summary.md + 5 yaml/txt artifacts including `05-coredns-running-after-fix.txt`)
+- MariaDB line cross-line evidence: `addon-idc-image-registry-mirror-guide.md` PR #54 §1 mirror family classification + §5 MariaDB row（chart body docker.io/dockerproxy.net + 2 件 ACR runner+initContainer pair + 0 ghcr.io 主体）+ 11:16-12:55 syncer cross-compile sideload 实战
+- Cross-ref to [`addon-smoke-test-pre-flight-checklist-guide.md`](addon-smoke-test-pre-flight-checklist-guide.md) §7 + case study appendix（PR #71）
+
+> **Co-author note**: 本节主体 drafted by **Oracle line addon owner** (W7 idc4 evidence), idc 实操 view 1-2 段（Mirror 选型 doctrine / Sideload vs swap 取舍 / 黑名单 wisdom / 时序踩点）by **MariaDB line idc bastion view** (PR #54 §5 author + 11:16-12:55 syncer deployment 实战), polished by SQL Server line for cross-line generalization。
+
+---
+
+## Archetype: chart spec doesn't declare a runtime requirement
+
+把 §6.1 / §6.2 / §6.3 三种漂移抽到一个共通 archetype，方便其他场景套用：
+
+> **Archetype 名**: `chart-spec-doesnt-declare-runtime-requirement`
+>
+> **核心 principle**: chart spec 是**接口契约**，runtime 实际依赖是**实现需求**。两者不对齐时，runtime 失败的 surface error 通常 cryptic（不是"chart 缺字段"这种自描述错），需要倒推到 chart spec 层才能 fix。
+>
+> **三层映射**:
+> - Layer 1 = chart spec 字段超出 KB CRD schema → install-time hard fail
+> - Layer 2 = chart 假设 substrate ready 但 vcluster substrate 没 bootstrap 好 → smoke pass 但跨 pod fail
+> - Layer 5 = chart spec 没 declare addon 自身 env 但 script 引用 → runtime silent-empty
+>
+> **教科书级共通现象**: ORA-12154 在 idc4 oracle-vcluster `o19-i4-8854` 同时是 Layer 5 + Layer 2 的 surface error
+>
+> - Layer 5 root cause: ActionSet `spec.env` 没 declare ORACLE_SID / ORACLE_PORT
+> - Layer 2 root cause: vcluster CoreDNS ImagePullBackOff
+> - 两个独立 root cause，**同一 surface symptom**
+> - 修一个还会撞另一个 → 必须 §8 决策树系统排查
+>
+> **跨引擎适用性**: 任何 addon 接 dataprotection / vcluster / cross-pod 通信都暴露 archetype。每条 ActionSet / 每个 vcluster 都需要 4-step preflight。
+
+## 决策树（mermaid）
+
+撞到 cryptic surface error（DNS / connect string / ORA-12154 / "Can't connect" 等）时，按下面决策树定位：
+
+```mermaid
+flowchart TD
+  Start[Surface error: DNS / connect / cryptic]
+  Q1{install 阶段就 fail?}
+  Q2{smoke T01-T07 全 PASS?}
+  Q3{业务 pod 内能 nslookup<br/>kubernetes.default.svc.cluster.local?}
+  Q4{业务 pod 内 fqdn / IP 直连成功<br/>但短主机名失败?}
+  Q5{kubectl get pod backup-pod -o yaml<br/>env list 包含引擎 specific env?}
+  Q6{backup-script grep '\${[A-Z_]+}'<br/>差集 vs ActionSet declare 集 = ?}
+
+  Start --> Q1
+  Q1 -->|YES| L1[Layer 1: chart-vs-CRD-schema reject<br/>→ §6.1 + chart-vs-kb-schema-skew-diagnosis]
+  Q1 -->|NO| Q2
+  Q2 -->|NO| OTHER[非本文 scope: 真 DB / 引擎层 bug<br/>→ test-acceptance-and-first-blocker / probe-classification]
+  Q2 -->|YES| Q3
+  Q3 -->|NO 'NXDOMAIN'| L2[Layer 2: vcluster substrate bootstrap<br/>→ §6.3 + CoreDNS image fix]
+  Q3 -->|YES| Q4
+  Q4 -->|YES| L2
+  Q4 -->|NO| Q5
+  Q5 -->|NO 'MISSING'| L5[Layer 5: ActionSet env declare gap<br/>→ §6.2 双半 fix Half A chart + Half B script]
+  Q5 -->|YES| Q6
+  Q6 -->|差集非空| L5
+  Q6 -->|差集空| OTHER
+```
+
+**Layer 2 + Layer 5 双根因情景**：在某些 idc cluster 上两个 layer 同时存在，修一个还会撞另一个。这种情况下：
+
+1. 先修 Layer 2（substrate side，影响范围广，priority 高）
+2. 再修 Layer 5（chart side，影响特定 ActionSet）
+3. 最后跑 §4 Step 4 round-trip 验证两个 layer 都 pass
+
+不要看到 fix Layer 2 后 reproduction 还 fail 就以为修错了——可能只是 cascade 中前一个 fault 修好后撞到了独立的下一个。
+
+## Cross-doc family map (chaos test lifecycle phases)
+
+按 chaos test lifecycle 划分 doc family，本文的位置：
+
+| Lifecycle phase | 主管 doc | scope |
+|---|---|---|
+| **Pre-test 1: source provenance** | [`addon-test-script-preflight-guide.md`](addon-test-script-preflight-guide.md) §1.5 | test runner workspace `git merge-base --is-ancestor` 验证 |
+| **Pre-test 2: shared client state** | [`addon-test-script-preflight-guide.md`](addon-test-script-preflight-guide.md) §1.1-§1.4 | `~/.kube/config` 跨 line 干扰 / HTTPS_PROXY 残留 |
+| **Pre-install: KB schema 三层** | [`addon-kb-schema-version-preflight-guide.md`](addon-kb-schema-version-preflight-guide.md) | image / chart / CRD 三层 artifact 版本对齐 |
+| **Pre-install: vcluster bootstrap** | [`addon-vcluster-kb-install-preflight-guide.md`](addon-vcluster-kb-install-preflight-guide.md) | vcluster 内 helm install KB 时序 |
+| **Pre-install: scope split** | [`addon-multi-ns-registry-scan-preflight-guide.md`](addon-multi-ns-registry-scan-preflight-guide.md) | verified scope vs scan-only future-gate |
+| **Pre-install: runtime contract** | **本文** `addon-runtime-contract-preflight-guide.md` | **chart spec 与 runtime 实际契约 3 layer 对齐**（chart spec / vcluster substrate / runtime env contract） |
+| **Run-time: 撞错诊断** | [`addon-chart-vs-kb-schema-skew-diagnosis-guide.md`](addon-chart-vs-kb-schema-skew-diagnosis-guide.md) | `field not declared in schema` 三种漂移定位 |
+| **Run-time: 探针失败分层** | [`addon-test-probe-classification-guide.md`](addon-test-probe-classification-guide.md) | 探针 fail → route_api / client_channel / empty / parse_empty / runtime_mismatch / real_mismatch |
+| **Run-time: 收敛判定** | [`addon-bounded-eventual-convergence-guide.md`](addon-bounded-eventual-convergence-guide.md) | 异步系统 N retry 边界 |
+| **Run-time: 单次 fail first-blocker** | [`addon-test-acceptance-and-first-blocker-guide.md`](addon-test-acceptance-and-first-blocker-guide.md) | 单次失败的成功语义分层 |
+| **Post-run: 多次失败聚合分类** | [`addon-soak-test-result-classification-guide.md`](addon-soak-test-result-classification-guide.md) | 4-state classification (invariant-break / product-path-failure / harness-race / external-env-cascade) + N≥3 race-likely gradient |
+| **Post-run: evidence discipline** | [`addon-evidence-discipline-guide.md`](addon-evidence-discipline-guide.md) | N=1 不当 baseline / 间接旁证不当系统性证伪 |
+
+**Preflight family**（启动前对齐 surface）共 5 doc 互补，scope 严格不重叠：
+1. test-script-preflight = shared client state dimension
+2. kb-schema-version-preflight = schema dimension
+3. **runtime-contract-preflight (本文)** = runtime contract dimension
+4. vcluster-kb-install-preflight = bootstrap harness dimension
+5. multi-ns-registry-scan-preflight = 测试 scope dimension
+
+## 案例附录
+
+### Case A — Oracle W7 ActionSet env audit (Layer 5 grounded)
+
+- 时间: 2026-05-05
+- Cluster: idc4 oracle-vcluster `o19-i4-8854` (19c standalone)
+- 现象: Backup CR `o19-i4-8854-rman19c-w7verify` Failed with `RMAN-04005: ORA-12154`
+- 验证: `kubectl get pod <backup-pod> -o yaml | grep -A 1 ORACLE_` 输出空 = ActionSet `spec.env` 没 declare
+- 修复: 双半 pattern：Half A 改 `templates/actionset-rman.yaml` declare ORACLE_SID/ORACLE_PORT；Half B 改 `dataprotection/rman-full-backup.sh` defensive fallback `: "${ORACLE_PORT:=${DP_DB_PORT:-1521}}"`
+- 二次验证: Backup `o19-i4-8854-rman19c-w7verify2` Status=Completed 553MB 2m32s
+- Evidence pack: `work/oracle-idc4-migration/W7-verify-evidence/`
+- Source: commit `345bfef9` on `oracle/release-1.0-merge-audit` branch (待 W-chain consolidation PR open，URL 落地后回填 clickable link)
+
+### Case B — vcluster CoreDNS ImagePullBackOff (Layer 2 grounded)
+
+- 时间: 2026-05-05
+- Cluster: 同 idc4 oracle-vcluster `o19-i4-8854`（与 Case A 同 cluster，独立 root cause）
+- 现象: 修完 Case A Half A+B 后，Backup `o19-i4-8854-rman19c-w7verify` 仍报 ORA-12154
+- 判别: `kubectl exec <oracle-pod> -- sqlplus -S <user>/<pwd>@<short>:1521/<svc>` fail，`<fqdn>:1521/<svc>` success，`<ip>:1521/<svc>` success → Layer 2 confirmed
+- 验证 substrate: `kubectl -n kube-system get pods -l k8s-app=kube-dns` 显示 ImagePullBackOff，image 是 `docker.io/coredns/coredns:1.10.1`
+- 修复: `kubectl set image deployment/coredns -n kube-system coredns=registry.aliyuncs.com/google_containers/coredns:1.10.1`
+- 二次验证: Backup `o19-i4-8854-rman19c-w7verify2` Status=Completed 553MB 2m32s（与 Case A 共用同 verification run，因 Layer 2 + Layer 5 双根因都修了才端到端 pass）
+- Evidence: `05-coredns-running-after-fix.txt` in evidence pack
+
+### Case C — chart 跟 KB main isExclusive (Layer 1 grounded, 待 fold-in)
+
+- SQL Server line PoC（Jerry 跑）：KB 1.0.2 install with chart from KB main ref → server-side strict decode reject `field "isExclusive" not declared in schema for ComponentDefinition.spec.systemAccounts[0]` + client-side `strict decoding error: unknown field "isExclusive"`
+- 漂移类型: 「chart 跟 KB main 但 API 未发布」
+- Fix path: 看决策权属——chart 暂降级 vs cherry-pick 字段进 KB 1.0.2 release
+- Cross-ref: [`addon-chart-vs-kb-schema-skew-diagnosis-guide.md`](addon-chart-vs-kb-schema-skew-diagnosis-guide.md) §<TBD> 三种漂移分类
+- 待 Jerry 12c T08 跑完后回填具体 client/server error wording 到 §6.1 Reproduction 子节
+
+### Case D — MariaDB line mirror family classification (Layer 2 cross-line)
+
+- Source: PR #54 `addon-idc-image-registry-mirror-guide.md` §1 mirror family classification + §5 MariaDB row
+- 内容: chart body docker.io/dockerproxy.net 主路 + 2 件 ACR (runner + initContainer pair) + 0 ghcr.io 主体审计 + 11:16-12:55 syncer cross-compile sideload 实战
+- Mirror 黑名单 wisdom: alpine vs glibc / kubeblocks-tools 1.0.2 vs 1.0.0 / xuriwuyun golang base 三类 idc 失败 path
+- Cross-ref to §6.3 Mirror 选型实测表 + Sideload vs swap 取舍 + 时序踩点子节
+
+---
+
+> **本文 ownership**: SQL Server line addon TL 主笔（cross-line 抽象 / Archetype / 决策树 / Family map）。Layer 5 §6.2 主体 by Oracle line addon owner（W7 grounded）。Layer 2 §6.3 主体 by Oracle line + idc 实操 view 1-2 段 by MariaDB line（PR #54 §5 author + 11:16-12:55 syncer 实战）。

From 79dafbd4d706c72ae8b9415a193e800524d1f6a2 Mon Sep 17 00:00:00 2001
From: Ava <ava@apecloud.com>
Date: Tue, 5 May 2026 13:46:53 +0800
Subject: [PATCH 2/5] docs(skill-index): add runtime-contract-preflight entry
 under section 3
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add SKILL-INDEX.md entry for addon-runtime-contract-preflight-guide.md
in section 3 "环境 ready 前 / 环境层撞坑", documenting the 3-layer
chart-vs-runtime contract drift methodology and its position within
the preflight family (5 docs, scope strictly non-overlapping).

Entry references the Oracle line W7 grounded evidence (idc4 19c +
12c double minor-version confirm) and MariaDB line idc bastion view
co-authored content (PR #54 mirror family + 11:16-12:55 syncer
deployment experience).
---
 docs/SKILL-INDEX.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/SKILL-INDEX.md b/docs/SKILL-INDEX.md
index 0007bf4..2943385 100644
--- a/docs/SKILL-INDEX.md
+++ b/docs/SKILL-INDEX.md
@@ -53,6 +53,7 @@
 - [`addon-k3d-backup-restore-prereqs-guide.md`](addon-k3d-backup-restore-prereqs-guide.md) — k3d 跑 Backup/Restore 的两层前置：装 VolumeSnapshot CRD + 建默认 BackupRepo
 - [`addon-idc-image-registry-mirror-guide.md`](addon-idc-image-registry-mirror-guide.md) — IDC vcluster 镜像供给的三档决策（mirror 主路径 / ACR 直拉 / sideload 兜底）+ chart audit 反 ghcr.io / docker.io 主依赖 + vcluster 内 chaos-mesh 双层 syncer 注入；含 6 line × 3 IDC 行 ground-truth cross-engine reuse 表
 - [`addon-multi-ns-registry-scan-preflight-guide.md`](addon-multi-ns-registry-scan-preflight-guide.md) — *(also relevant in: 写新 smoke / chaos 测试)* 多 ns / 多 topology 测试启动前 audit live `ComponentVersion` + `ParametersDefinition.toolsSetup.toolConfigs[].image` 的 image source；verified scope vs scan-only future-gate 二分
+- [`addon-runtime-contract-preflight-guide.md`](addon-runtime-contract-preflight-guide.md) — chart spec 与 runtime 实际契约的 3 个对齐 surface preflight：Layer 1 (chart spec 字段被 KB CRD schema reject, install-time fail) / Layer 2 (vcluster substrate bootstrap precondition, CoreDNS image pull fail 但 control plane 报 Running) / Layer 5 (chart spec 没 declare addon 自身 runtime env, ActionSet `spec.env` declare 与 backup script 引用差集 → silent-empty + cryptic surface error 如 ORA-12154)。Non-contiguous Layer 编号（0/3/4 reserved）+ 4-step preflight + 4-pillar 跨引擎表 + Layer 1/2/5 mermaid 决策树 + Archetype "chart-spec-doesnt-declare-runtime-requirement"。Oracle line W7 grounded (idc4 19c standalone 553MB 2m32s + 12c standalone 628MB 1m58s 双 minor-version confirm) + MariaDB line idc bastion view (PR #54 §1 §5 mirror family + 11:16-12:55 syncer 实战) cross-line co-author。与 [`addon-kb-schema-version-preflight-guide.md`](addon-kb-schema-version-preflight-guide.md)（schema dimension）+ [`addon-test-script-preflight-guide.md`](addon-test-script-preflight-guide.md)（shared client state dimension）+ [`addon-vcluster-kb-install-preflight-guide.md`](addon-vcluster-kb-install-preflight-guide.md)（bootstrap harness dimension）+ [`addon-multi-ns-registry-scan-preflight-guide.md`](addon-multi-ns-registry-scan-preflight-guide.md)（测试 scope dimension）共同构成 preflight family 5 doc，scope 严格不重叠
 - [`addon-idc-vcluster-migration-checklist-guide.md`](addon-idc-vcluster-migration-checklist-guide.md) — addon 测试环境从本地 k3d / 单租户 idc 迁到 IDC 共享 k8s + 每线 vcluster 时的迁移 checklist：per-cluster baseline 维度、4 条架构 invariant（runner-on-host / vcluster API 内通主路 NodePort 兜底 / 控制器全部 in-vcluster / 显式 KUBECONFIG 锁）、13 条已观察反模式（NodePort SAN / HTTPS_PROXY / libc / 跨 arch / default-class 不 sync / data-protection 缺装 / VolumeSnapshot CRD 缺 / chart 全局 nodeSelector 经 CM_NODE_SELECTOR 泄漏 / IDC LB 无 EXTERNAL-IP / pod IP cap 探测 / chaos 跑赢 CNI 回收 / helm hook 镜像不存在 / 缺装组件枚举），+ "环境 fault before engine fault" 5 项 cross-cutting checklist
 - [`addon-vanilla-vcluster-bootstrap-guide.md`](addon-vanilla-vcluster-bootstrap-guide.md) — 在 IDC host k8s 上创建 vanilla（OSS 0.19.x，非 Loft 企业版）vcluster 的完整 bootstrap 步骤：default StorageClass / node 资源 / ghcr.io mirror / kubeconfig 隔离 4 项前置 + helm install + kubeconfig (port-forward vs NodePort) + 验证 + 8 个跨线 Blocker 汇总
 

From fd77b67d40ebe737161ebd74731456fb602cb14b Mon Sep 17 00:00:00 2001
From: Ava <ava@apecloud.com>
Date: Tue, 5 May 2026 13:48:20 +0800
Subject: [PATCH 3/5] docs(runtime-contract-preflight): fold W8 inter-version
 drift + 12c confirm + Step 3.5 audit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Apply 4 fold-ins from Oracle line W8 deliverable + 12c second-engine
confirm into runtime-contract-preflight-guide v1:

1. Section 4 Step 3.5 — ActionSet env reference systemAccount CMPD
   declare audit, with cross-variant `cmpd*.yaml` diff audit script
   covering systemAccounts names + vars credentialVarRef.name set +
   lifecycleActions keys (closes the silent W8-style runtime gap)

2. Section 6.2 Source datapoint — N=2 minor-version reproducibility
   confirm: 12c standalone (cluster o12-t8-21609) RMAN 628MB 1m58s +
   expdp 220KB 2m56s + 19c standalone (cluster o19-i4-8854) RMAN 553MB
   2m32s, identical kubectl patch actionset spec.env recipe

3. Section 6.2 Inter-minor-version chart drift sub-bullet (Layer 5
   grounded form orthogonal to KB cross-version drift): symptom +
   audit signal + fix shape, anchored on Oracle line W8 commit
   1cb93055 cmpd-19c misalignment evidence

4. Section 6.3 MongoDB wording footnote — no current MongoDB line
   owner, K8s evidence pack inferred wording, pending future line
   owner grounded confirm
---
 .../addon-runtime-contract-preflight-guide.md | 44 ++++++++++++++++++-
 1 file changed, 42 insertions(+), 2 deletions(-)

diff --git a/docs/addon-runtime-contract-preflight-guide.md b/docs/addon-runtime-contract-preflight-guide.md
index 897dc05..ee802ba 100644
--- a/docs/addon-runtime-contract-preflight-guide.md
+++ b/docs/addon-runtime-contract-preflight-guide.md
@@ -140,6 +140,37 @@ comm -23 /tmp/referenced.txt /tmp/declared.txt
 
 注意：DP_* 框架变量（`DP_DB_HOST` / `DP_DB_PORT` / `DP_DB_USER` / `DP_DB_PASSWORD`）由 KB dataprotection runner 自动注入，不需 ActionSet declare；但 addon 自身需要的 `ORACLE_SID` / `MYSQL_PORT` / `PGDATABASE` 等必须显式 declare。
 
+### Step 3.5 — ActionSet env reference 的 systemAccount 是否 CMPD declare（关闭 inter-version chart drift gap）
+
+W8 audit 实战发现 silent 漂移类型：addon chart 内不同 minor variant 的 CMPD declare 不一致。例如 oracle addon chart 的 `cmpd.yaml` (12c) declare `systemAccounts: kbdataprotection`，但 sibling `cmpd-19c.yaml` (19c) 没 declare 这个 systemAccount → ActionSet env injection `DP_DB_USER`/`DP_DB_PASSWORD` 通过 `valueFrom.credentialVarRef.name` 引用一个不存在的 systemAccount → runtime silent fail（oracle-expdp worker pod `CreateContainerConfigError` on 19c，PASS on 12c，identical KB build）。
+
+**Audit check（仅适用于 ActionSet 用 `valueFrom.credentialVarRef` 引用 systemAccount 的情形）**:
+
+```bash
+# 列 CMPD declare 的 systemAccount name 集合
+kubectl get cmpd <component-name> -o jsonpath='{.spec.systemAccounts[*].name}' | tr ' ' '\n' | sort > /tmp/cmpd-accounts.txt
+
+# 列 ActionSet 引用的 systemAccount name (DP_DB_USER + DP_DB_PASSWORD 都查)
+kubectl get actionset <name> -o jsonpath='{.spec.backup.backupData.env[?(@.name=="DP_DB_USER")].valueFrom.componentField.fieldPath}' 2>/dev/null
+kubectl get actionset <name> -o jsonpath='{.spec.backup.backupData.env[?(@.name=="DP_DB_PASSWORD")].valueFrom.componentField.fieldPath}' 2>/dev/null
+
+# 差集即 inter-version chart drift 风险 surface
+# - 如果 ActionSet 改用 raw username/password 直接注入（不通过 valueFrom credentialVarRef），此 check 不适用
+```
+
+**Cross-variant CMPD 字段 diff audit（chart-side，作 Pre-install scan）**:
+
+```bash
+# 在 chart source dir
+diff <(yq '.spec.systemAccounts[].name' templates/cmpd.yaml | sort) \
+     <(yq '.spec.systemAccounts[].name' templates/cmpd-19c.yaml | sort)
+diff <(yq '.spec.vars[].valueFrom.credentialVarRef.name' templates/cmpd.yaml | sort) \
+     <(yq '.spec.vars[].valueFrom.credentialVarRef.name' templates/cmpd-19c.yaml | sort)
+diff <(yq '.spec.lifecycleActions | keys' templates/cmpd.yaml) \
+     <(yq '.spec.lifecycleActions | keys' templates/cmpd-19c.yaml)
+# 非空 diff = drift（除非 design intent inline 文档说明 variant 之间差异是有意的）
+```
+
 ### Step 4 — 实跑 1 个 dataprotection / cross-pod 操作 round-trip
 
 前 3 步全 pass 后，必跑一次端到端验证：发起一个 Backup（最小数据集）、观察 pod 内 Backup script 的 env list 与连接是否成功。空跑 install 不算 preflight 通过。
@@ -353,6 +384,13 @@ kubectl patch actionset oracle-rman-19c --type=json -p='[
 
 **诊断 protocol**: 任何 addon 接 dataprotection 时，audit `kubectl get pod <backup-pod> -o yaml` 的 env list，对照 backup script grep `\$\{[A-Z_]+\}` 引用，差集即为 Layer 5 风险 surface。
 
+**Inter-minor-version chart drift (Layer 5 grounded form)** — Same engine, different `cmpd*.yaml` variants in the same addon chart can drift; orthogonal to KB cross-version drift but feeds the same audit muscle.
+
+- **Symptom**: addon chart's reference variant declares N CMPD elements (here `cmpd.yaml` 12c declares 3: `systemAccounts: kbdataprotection` + `vars: KB_BACKUP_USER/PASSWORD credentialVarRef` + `lifecycleActions.accountProvision`); a sibling variant (here `cmpd-19c.yaml`) declares 0; KB-version is identical so no schema-gating signal — runtime-only failure (oracle-expdp worker pod `CreateContainerConfigError` on 19c, PASS on 12c, identical KB build).
+- **Audit signal**: `diff` of `(spec.systemAccounts names, spec.vars credentialVarRef.name set, spec.lifecycleActions keys)` across all `cmpd*.yaml` siblings inside one addon chart; non-empty diff = drift unless design intent is documented inline (engine genuinely lacks the capability).
+- **Fix shape**: copy reference variant's missing field set verbatim; runtime script (`account_provision.sh` here) is typically version-agnostic by construction (`CREATE USER c##${KB_ACCOUNT_NAME} ... CONTAINER=ALL` works on any CDB minor version) — no engine-side change.
+- **Source**: Oracle line W8 audit, commit `1cb93055` on `oracle/release-1.0-merge-audit` branch (待 W-chain consolidation PR open，URL 落地后回填 clickable link)
+
 **Owner**
 
 - Half A chart fix: addon owner（Oracle owner = James）
@@ -365,7 +403,9 @@ kubectl patch actionset oracle-rman-19c --type=json -p='[
 - 6 files +36 lines: `templates/actionset-rman.yaml` / `templates/actionset-rman-19c.yaml` / `templates/actionset-expdp.yaml` (Half A) + `dataprotection/rman-full-backup.sh` / `dataprotection/oracle-expdp-backup.sh` / `dataprotection/oracle-expdp-restore.sh` (Half B)
 - Live verification: Backup `o19-i4-8854-rman19c-w7verify2` Status=Completed, 553MB, 2m32s on idc4 19c standalone
 - Evidence pack: `work/oracle-idc4-migration/W7-verify-evidence/` (00-summary.md + 5 yaml/txt artifacts)
-- Second engine confirm (in progress): 12c T08 fresh backup verification on cluster `o12-t8-21609`，CoreDNS aliyuncs + ActionSet env declared 双 fix 端到端验证（pending — 完成后回填到 Source datapoint）
+- **Layer 5 reproducibility verified at N=2 minor versions of the same engine (Oracle 12c CDB 12.2.0.1 standalone + 19c CDB 19.3.0 standalone) on identical KB build (KB 1.0.x line, idc4 vcluster substrate)**. Identical patch shape: `kubectl patch actionset oracle-{rman,expdp,expdp-restore} --type=json -p='[{"op":"add","path":"/spec/env",...}]'`. End-to-end PASS on both engines:
+  - 12c standalone (cluster `o12-t8-21609`): RMAN backup `o12-rman-w7verify` Completed 628MB 1m58s + expdp backup `o12-expdp-w7verify` Completed 220KB 2m56s
+  - 19c standalone (cluster `o19-i4-8854`): RMAN backup `o19-i4-8854-rman19c-w7verify2` Completed 553MB 2m32s
 
 > **Co-author note**: 本节 6-section content drafted by **Oracle line addon owner** (W7 ActionSet env audit + ORA-12154 root cause analysis), polished and folded by SQL Server line for cross-line generalization.
 
@@ -493,7 +533,7 @@ kubectl -n kube-system get pods -l k8s-app=kube-dns -w
 | SQL Server | Always-on AG primary→secondary log shipping 跨 pod TCP、AG endpoint discovery 走 fqdn | `A network-related or instance-specific error occurred while establishing a connection` |
 | MariaDB | semisync replication channel、mariabackup remote、Galera cluster discovery | `Lost connection to MySQL server` / `getaddrinfo() thread failed` |
 
-> **Surface error wording 校稿状态**：Oracle ✅ (W7 grounded) / MariaDB ✅ (Helen co-author) / 其他 5 引擎 wording 是 cross-line 推断，待对应 line owner 实战 confirm 后回填具体 grounded sample。
+> **Surface error wording 校稿状态**：Oracle ✅ (W7 grounded) / MariaDB ✅ (MariaDB line idc bastion view co-author) / MySQL + PostgreSQL + Redis-Valkey + SQL Server 待对应 line owner 实战 confirm 后回填具体 grounded sample。**MongoDB wording 来自 K8s evidence pack 推断（cross-line K8s patterns），待 future MongoDB line owner 加入后 grounded confirm**。
 
 **诊断 protocol**（5-min preflight cross-ref `addon-smoke-test-pre-flight-checklist-guide.md` §7）:
 ```bash

From befb6923865bb54020bd88a2c754c6ca5e81b131 Mon Sep 17 00:00:00 2001
From: weicao <weicao@apecloud.com>
Date: Tue, 5 May 2026 13:49:47 +0800
Subject: [PATCH 4/5] =?UTF-8?q?docs(runtime-contract-preflight):=20refine?=
 =?UTF-8?q?=20=C2=A76.3=20idc=20bastion=20view=20=E2=80=94=20sideload=20tr?=
 =?UTF-8?q?ap=20+=20mirror=20blacklist=20+=20bootstrap=20timing?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Refine the four idc-bastion-view sub-blocks Tom drafted as starter content in §6.3 with grounded detail from the 2026-05-05 patched syncer cross-compile + sideload cycle:

- Sideload 现场踩坑: clarify that imagePullPolicy 'Never' is fresh-deploy invariant only; existing CmpD upgrade must keep 'IfNotPresent' (which honors local cache identically). Add per-node 'ctr images ls' as the evidence gate for declaring sideload complete (sideload to N-1 of N nodes is a silent partial-success). Add cross-compile workaround pattern: when host docker buildx cannot pull a base image, GOOS=linux GOARCH=amd64 go build + minimal Dockerfile graft binary onto a substrate-pullable base image. Add the 'verify before propagate' trap: cross-host / cross-stash builds may miss module registration code that lives in collaborator's local stash; handoff 'image ready' must include a verify gate.

- Mirror 黑名单 wisdom: correct three entries to match real failure modes —
  - alpine/distroless toolchain image (e.g. kubeblocks-tools:1.0.2) lacks /bin/bash, bash-dependent runner scripts cannot start (not 'exec format error'). Pin to debian-flavored tag or split into init+main containers.
  - Third-party Aliyun-hosted Go base image (xuriwuyun/golang) reliably times out from offshore Mac docker buildx. Workaround is to bypass buildx entirely via cross-compile, not to fix the mirror.
  - ghcr.io references in chart main body are a hard blocker, not a fallback. Sideload救场 is short-term; the long-term fix is upstream chart replaces ghcr.io with mirror-friendly registry.

- Vcluster substrate bootstrap 时序常见踩点: split the Secret kubeconfig timing pitfall into two distinct cases (vcluster-syncer's own Secret vs test-runner Job's Secret) since they fail at different layers and have different mitigations. Add the probe Job pattern as substrate-readiness gate, with cross-link to addon-host-runner-job-pattern-guide.md §基础资源. Add the rule that DNS readiness must be probed from inside the workload's namespace, not from the bastion host.

- Cross-engine impact MariaDB row: replace the cross-line guess wording with substrate-based wording (Could not resolve host name / getaddrinfo / Galera gcomm channel open). Mark wording status as ⚠ pending grounded sample, not ✅, since the MariaDB cycle 2026-05-05 ran with vcluster API via NodePort and idc-k8s CoreDNS healthy — Layer 2 DNS failure path was not triggered, no real error trace captured.

- Source datapoint MariaDB cross-line evidence: add concrete anchors from the 2026-05-05 11:16-12:55 patched syncer deploy (idc-k8s 3-node mariadb-runner namespace, kubectl cp tar + ctr import to all 3 nodes, CmpD imagePullPolicy: IfNotPresent honored cache, alpha.16 fresh-matrix 8/8 PASS validating the patch).

Evidence anchors:
- addons/mariadb/templates/cmpd-{replication,semisync,galera}.yaml — chart main-body image route via DockerHub family
- addon-idc-image-registry-mirror-guide.md PR #54 §1 mirror family + §5 MariaDB row — chart audit + ACR-direct runner toolchain pair
- addon-host-runner-job-pattern-guide.md §基础资源 + §常见坑表 — initContainer toolchain split + alpine vs glibc + image cache warm-up
- addon-evidence-discipline-guide.md anti-pattern library — the 'verify before propagate' trap is a documented anti-pattern instance
---
 .../addon-runtime-contract-preflight-guide.md | 41 +++++++++++--------
 1 file changed, 23 insertions(+), 18 deletions(-)

diff --git a/docs/addon-runtime-contract-preflight-guide.md b/docs/addon-runtime-contract-preflight-guide.md
index ee802ba..4365bc5 100644
--- a/docs/addon-runtime-contract-preflight-guide.md
+++ b/docs/addon-runtime-contract-preflight-guide.md
@@ -496,7 +496,7 @@ kubectl -n kube-system get pods -l k8s-app=kube-dns -w
 - **Family classification**：mirror 路径按目标 image 仓库归一：`docker.io/*` 走 dockerproxy.net 主路 / `gcr.io/*` 与基础组件走 aliyuncs `google_containers` / `ApeCloud build` 私货走 apecloud-registry / 兜底走 sideload。不要混路径——同 family image 走同一 mirror，避免黑名单冲突。
 - **Engine 私货分流**：addon 引擎自己 build 的 image（KB / 引擎产物 / xuriwuyun 这类内部 base）只走 apecloud-registry；公共组件（CoreDNS / etcd / metrics-server）只走 aliyuncs；不要把引擎私货扔进公共 mirror 期望命中。
 
-**Sideload vs deployment image swap 取舍**（Helen MariaDB line idc bastion view co-authored）:
+**Sideload vs deployment image swap 取舍**（MariaDB line idc bastion view co-authored）:
 
 | Path | 适用 | 操作 |
 |---|---|---|
@@ -504,20 +504,22 @@ kubectl -n kube-system get pods -l k8s-app=kube-dns -w
 | **Deployment image swap** | Stable tag 已在公共 mirror | `kubectl set image deployment/<name> ...` 改 chart values.image 路径，走正常 pull cache hit |
 
 **Sideload 现场踩坑**（grounded sample）:
-- CmpD `imagePullPolicy` 是 immutable 字段：要在 install 时就设成 `IfNotPresent`，否则后期改 spec 会被 reject
-- `ctr -n k8s.io images import` 在每节点必须重做（多节点 cluster 不会自动同步）
-- Mac cross-compile 镜像后 `docker save → kubectl cp tar → ctr import` 三步链 toolchain 一致
-
-**Mirror 黑名单 wisdom**（idc 实战踩过的失败 path）:
-- `alpine` vs `glibc` 基础镜像：alpine 在某些 KB toolchain pull 报 `exec format error` 或 lib 缺失（musl libc 不兼容 KB build），需 glibc-based base
-- `kubeblocks-tools` 1.0.2 vs 1.0.0 跨小版本 image tag 命名不一致，老 mirror 可能只缓存 1.0.0，pull 1.0.2 命中 NotFound
-- `xuriwuyun/golang-base` 这类内部 base 不在公共 mirror，必须 apecloud-registry 或 sideload；忘 sideload 是高频踩点
-
-**Vcluster substrate bootstrap 时序常见踩点**（Helen MariaDB line co-authored）:
-- **CoreDNS upstream 配置**：vcluster CoreDNS 默认 forward 到 host k8s 的 CoreDNS。host k8s CoreDNS 配置错（forward 到 unreachable upstream）会引发 vcluster 内 nslookup 间歇失败。
-- **Image cache warm-up**：CmpD `imagePullPolicy: IfNotPresent` 假设节点已有 image。第一次 install 时如果未 sideload，pod 永远 ImagePullBackOff 不报错（Reason 是 ErrImagePull 不是 ImageNotFound）。
-- **Secret kubeconfig mount 时序**：vcluster syncer 启动早于 vcluster apiserver Ready，Secret kubeconfig mount 进 syncer pod 时如果还没生成完整，syncer 报 `Unauthorized` 但 retry 几次后会自愈。看到 `Unauthorized` 不要立刻怀疑权限，先看 vcluster apiserver pod logs 是否 Running。
-- **NodePort SAN 与 cert mismatch**：vcluster apiserver cert SAN 默认只含 cluster-internal name；从 host k8s NodePort 直连时 hostname 不在 SAN 里 → TLS handshake fail。bootstrap 时要 `--tls-san=<host-ip>` 显式加 SAN。
+- CmpD `imagePullPolicy` 是 immutable 字段：升级既存 CmpD 时不要把它从 `IfNotPresent` 改到 `Never`——KB spec-immutable 校验会拒。`IfNotPresent` 已经能命中本地 cache，效果与 `Never` 等同；`Never` 只在全新部署的 chart 上设。
+- `ctr -n k8s.io images import` 在每节点必须独立做。sideload 应用到 N 个节点中的 N-1 个时，调度落在第 N 个节点的 pod 才会暴露问题——必须在每节点跑 `ctr -n k8s.io images ls | grep <tag>` 留 evidence 才算 sideload 完成。
+- Mac 端 build 失败时（如 docker buildx 拉境外 base image 超时）的绕法：直接在 Mac 上交叉编译，`GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build` 拿到 binary，再写一个 5-line Dockerfile 把 binary `COPY` 到一个 substrate 已经能拉的 base image 上做 graft，避开 buildx pull 战场；`docker save` 出 tar 后走 `kubectl cp → ctr import` 三步链。
+- 跨人 / 跨 commit / 跨 stash 的 build：handoff "image ready" 之前必须 verify binary 实际包含哪些 module（如 `strings binary | grep <module>` 或一次 unit-test smoke），不要把 main HEAD 默认当作完整功能。**反例**：从 main HEAD 交叉编译, 但某 engine 注册码还在协作者本地 stash 里, 编出来的 binary 缺这一段, 部署后冷门 path 直接 panic `no XXX manager for engineType`. 修法：用临时 worktree 把所有要的代码合并到一个 branch 再 build, 不靠默认 HEAD。
+
+**Mirror 黑名单 wisdom**（idc 实战反复踩过到默认绕开的失败 path）:
+- **Toolchain image 的 alpine / distroless 变体没有 `/bin/bash`**：`apecloud/kubeblocks-tools:1.0.2` 是 alpine 系，runner 脚本若依赖 bash 4 特性（`mapfile` / arrays / `[[ ]]` / `(( ))`）直接起不来——pod 报 `exec /bin/bash: no such file or directory` 或 `OCI runtime exec failed`。修法：要么 pin 到上一个 debian-flavored tag（`apecloud/kubeblocks-tools:1.0.0`），要么拆双层——`initContainer = alpine 镜像拷 kubectl + musl loader 到 sharedVolume → main = debian 镜像跑 bash 脚本`。批量部署前用一次性 probe 验证：`kubectl run probe --rm -it --image=<candidate> --restart=Never -- bash -c 'command -v bash kubectl tar sha256sum'`。
+- **第三方境外 Aliyun 命名空间的 Go base image** 如 `registry.cn-hangzhou.aliyuncs.com/xuriwuyun/golang:1.24`：境外 Mac 主机 `docker buildx build` 拉这条 path 反复超时。绕法不是修 mirror 而是**绕过 buildx 阶段**——在 Mac 上 `GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build` 直接交叉编译，再用极简 Dockerfile 把 binary graft 到 substrate 已能拉的 base image 上。这条 path 默认 blacklist。
+- **Chart 主体里出现 ghcr.io 引用**：当作硬阻塞，不当作 fallback——IDC 几乎都拉不动，且没有可靠的公共 mirror。短期可 sideload 救场，长期方案是上游 chart 把 ghcr.io 引用替换成 mirror-friendly registry。chart 审计时必须把 ghcr.io 主体引用全列出来。
+
+**Vcluster substrate bootstrap 时序常见踩点**（MariaDB line idc bastion view co-authored）:
+- **CoreDNS upstream 配置**：vcluster CoreDNS 默认 forward 到 host k8s 的 CoreDNS。host k8s CoreDNS 配置错（forward 到 unreachable upstream）会引发 vcluster 内 nslookup 间歇失败。规则：宣称 substrate ready 之前要从 vcluster **内部** pod 里探测 DNS，不能只在 bastion 主机视角探。
+- **Image cache 在节点子集里冷的**：sideload 应用到 N 个节点中的 N-1 个时，scheduler 把 pod 调度到已 warm 的节点会神秘成功；落到剩下那一个节点才暴露 ImagePullBackOff。规则：sideload 必须**所有节点**做完，且每节点 `ctr -n k8s.io images ls | grep <tag>` 留 evidence。`imagePullPolicy: IfNotPresent` 不会自动跨节点同步 cache，假设的是节点本地已有 image。
+- **vcluster syncer 自身 Secret 时序**：vcluster syncer 启动早于 vcluster apiserver Ready，Secret kubeconfig mount 进 syncer pod 时如果还没生成完整，syncer 报 `Unauthorized`，retry 几次后会自愈。看到 `Unauthorized` 不要立刻怀疑权限，先看 vcluster apiserver pod logs 是否 Running。
+- **测试 runner Job 的 Secret kubeconfig 时序**（与 vcluster syncer 自身 Secret 不是同一个 Secret）：runner Job spec 引用一个 Secret，但创建那个 Secret 的步骤还没跑；Job 先调度上来在 missing Secret 上 crashloop。规则：Secret 创建必须排在 Job 提交之前；并且加一个 probe Job（什么都不做，只 `cat` 挂载点）作为 substrate ready 的最后一道门——probe Job 通过之后，再让正式 run Job 触碰任何测试资源。详见 [`addon-host-runner-job-pattern-guide.md`](addon-host-runner-job-pattern-guide.md) §基础资源。
+- **NodePort SAN 与 cert mismatch**：vcluster apiserver cert SAN 默认只含 cluster-internal name；从 host k8s NodePort 直连时 hostname 不在 SAN 里 → TLS handshake fail。bootstrap 时要 `--tls-san=<host-ip>` 显式加 SAN，或在 runner kubeconfig 上设 `insecure-skip-tls-verify: true`（隔离 bastion 内可接受，生产线上不行）。
 
 **Cross-engine impact**
 
@@ -531,9 +533,9 @@ kubectl -n kube-system get pods -l k8s-app=kube-dns -w
 | MongoDB | replica set member discovery、mongos→shard routing、dataprotection Job | "Hostname can't be resolved" |
 | Redis/Valkey | cluster bus 跨 pod、Sentinel discovery、replication | `Could not connect to Redis at <host>:<port>: Name or service not known` |
 | SQL Server | Always-on AG primary→secondary log shipping 跨 pod TCP、AG endpoint discovery 走 fqdn | `A network-related or instance-specific error occurred while establishing a connection` |
-| MariaDB | semisync replication channel、mariabackup remote、Galera cluster discovery | `Lost connection to MySQL server` / `getaddrinfo() thread failed` |
+| MariaDB | semisync replication channel、mariabackup remote、Galera cluster discovery | `Could not resolve host name` / `getaddrinfo: Name or service not known` / Galera `Failed to open channel '<cluster>' at 'gcomm://<seeds>'`（待 grounded sample 回填） |
 
-> **Surface error wording 校稿状态**：Oracle ✅ (W7 grounded) / MariaDB ✅ (MariaDB line idc bastion view co-author) / MySQL + PostgreSQL + Redis-Valkey + SQL Server 待对应 line owner 实战 confirm 后回填具体 grounded sample。**MongoDB wording 来自 K8s evidence pack 推断（cross-line K8s patterns），待 future MongoDB line owner 加入后 grounded confirm**。
+> **Surface error wording 校稿状态**：Oracle ✅ (W7 grounded) / MariaDB ⚠ (idc bastion 视角推断，MariaDB line 2026-05-05 当前 cycle 未触发 cluster-DNS 失败 path——vcluster 走 NodePort 直连 + idc-k8s CoreDNS 健康，无 grounded sample) / MySQL + PostgreSQL + Redis-Valkey + SQL Server 待对应 line owner 实战 confirm 后回填具体 grounded sample。**MongoDB wording 来自 K8s evidence pack 推断（cross-line K8s patterns），待 future MongoDB line owner 加入后 grounded confirm**。**待回填规则**：每条 line 在实战实际触发 Layer 2 DNS 失败时回填本 line 真实 error string + 上下文 trace；未触发的 line 保留 ⚠ 不要标 ✅。
 
 **诊断 protocol**（5-min preflight cross-ref `addon-smoke-test-pre-flight-checklist-guide.md` §7）:
 ```bash
@@ -556,7 +558,10 @@ kubectl -n kube-system get pods -l k8s-app=kube-dns 2>&1 | grep -v ImagePullBack
   - Fix: `kubectl set image deployment/coredns -n kube-system coredns=registry.aliyuncs.com/google_containers/coredns:1.10.1`
   - Verification: Backup `o19-i4-8854-rman19c-w7verify2` Status=Completed 553MB 2m32s
 - Evidence pack: `work/oracle-idc4-migration/W7-verify-evidence/` (00-summary.md + 5 yaml/txt artifacts including `05-coredns-running-after-fix.txt`)
-- MariaDB line cross-line evidence: `addon-idc-image-registry-mirror-guide.md` PR #54 §1 mirror family classification + §5 MariaDB row（chart body docker.io/dockerproxy.net + 2 件 ACR runner+initContainer pair + 0 ghcr.io 主体）+ 11:16-12:55 syncer cross-compile sideload 实战
+- MariaDB line cross-line evidence:
+  - `addon-idc-image-registry-mirror-guide.md` PR #54 §1 mirror family classification + §5 MariaDB row（chart body docker.io/dockerproxy.net + 2 件 ACR runner + initContainer pair + 0 ghcr.io 主体审计）
+  - 2026-05-05 11:16-12:55 patched syncer cross-compile + sideload 实战（idc-k8s 三节点 mariadb-runner ns）：交叉编译 binary → graft 到现有 base image → `kubectl cp tar` + `ctr -n k8s.io images import` 推到所有 3 节点 → CmpD `imagePullPolicy: IfNotPresent` 命中本地 cache（升级既存 CmpD 不能改 immutable 字段到 `Never`）→ alpha.16 fresh-matrix 8/8 PASS 复测验证补丁
+  - 取证：`addon-idc-image-registry-mirror-guide.md` §5 MariaDB row + `addon-host-runner-job-pattern-guide.md` §"常见坑表"
 - Cross-ref to [`addon-smoke-test-pre-flight-checklist-guide.md`](addon-smoke-test-pre-flight-checklist-guide.md) §7 + case study appendix（PR #71）
 
 > **Co-author note**: 本节主体 drafted by **Oracle line addon owner** (W7 idc4 evidence), idc 实操 view 1-2 段（Mirror 选型 doctrine / Sideload vs swap 取舍 / 黑名单 wisdom / 时序踩点）by **MariaDB line idc bastion view** (PR #54 §5 author + 11:16-12:55 syncer deployment 实战), polished by SQL Server line for cross-line generalization。

From 9aca3cc9ff02b85bbf53b4a835f75cae07954d6d Mon Sep 17 00:00:00 2001
From: Ava <ava@apecloud.com>
Date: Tue, 5 May 2026 13:56:27 +0800
Subject: [PATCH 5/5] docs(runtime-contract-preflight): Allen 4 fixes + James
 jsonpath correction
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Allen curator pass 4 mandatory fixes (PR #72 c472d1e2):
- Status: stable -> draft (v1) (5-field intro)
- SKILL-INDEX 文档全列表 entry added (paste-ready wording)
- Line 552/577 addon-smoke-test-pre-flight-checklist-guide.md
  marked (planned, PR #71) for forward-decl
- Lines 574/576/702 addon-idc-image-registry-mirror-guide.md
  backtick -> clickable markdown (landed doc on main)
- Line 576 addon-host-runner-job-pattern-guide.md also linkified
  (landed doc on main)

James jsonpath correction (PR #72 1c15cbb5):

Step 3.5 audit shape was wrong. DP_DB_USER / DP_DB_PASSWORD are
NOT declared in ActionSet spec.env at all -- KB dataprotection Job
runner auto-injects them based on BackupPolicy.spec.backupMethods[]
.target.account (which references systemAccount name). The W8
contract boundary lives at BackupPolicy layer, not ActionSet layer.

Corrected audit:
1. cluster-side: kubectl get backuppolicy ... .spec.backupMethods[].
   target.account vs kubectl get cmpd ... .spec.systemAccounts[].name
   diff
2. chart-side: yq diff cmpd-19c.yaml systemAccounts vs
   backuppolicytemplate.yaml backupMethods[].target.account
3. Added "Audit shape 关键澄清" paragraph documenting that
   systemAccount -> DP_DB_* contract is at BackupPolicy layer

W8 grounded form documented: addons/oracle/templates/
backuppolicytemplate.yaml line 33 references account: kbdataprotection
but cmpd-19c.yaml does not declare it -> KB never generates secret
-> CreateContainerConfigError on 19c.

Doctrine B 5-pattern grep on this commit: clean.
---
 docs/SKILL-INDEX.md                           |  1 +
 .../addon-runtime-contract-preflight-guide.md | 58 +++++++++++--------
 2 files changed, 36 insertions(+), 23 deletions(-)

diff --git a/docs/SKILL-INDEX.md b/docs/SKILL-INDEX.md
index 2943385..17aa4f8 100644
--- a/docs/SKILL-INDEX.md
+++ b/docs/SKILL-INDEX.md
@@ -129,6 +129,7 @@
 - [`docs/addon-ship-readiness-multi-phase-validation-guide.md`](addon-ship-readiness-multi-phase-validation-guide.md) — addon 何时算可以 ship 的三段矩阵（baseline / chaos × N / regression × N），累积 N、Wilson 95% CI、ship 阈值表（数据丢失 0% / 服务不可用 5% / transient 30%）、二段判定（产品 fail = 0 + caveat 全 document）+ 5 个常见误判
 - [`docs/addon-github-submission-discipline-guide.md`](addon-github-submission-discipline-guide.md) — 多 agent 协作 + GitHub 公开仓库的边界纪律：(1) AI provenance trailer（`Co-Authored-By: Claude` / `🤖 Generated with` / `noreply@anthropic.com`）不外漏的硬规则与兜底命令链（heredoc + `git commit --amend -m "$(... | sed)"` strip / push 前 grep 自检）；(2) 多 agent 并发推同一 PR branch 的 cascade 事故响应 playbook（force-with-lease lemma：lease 锚 last-fetched remote tip 不防 fetch 后并发 push / 双向 `git log --oneline` ritual / dropped-commit owner self-recover / single-owner-execute 收口）。5 条 doctrine（A force-with-lease / B per-commit grep / C cascade single-owner-execute / D forensic 自查 / E content-delta verify）+ §5 cross-cutting rules（forensic self-review / Doctrine E shorthand / evidence-post obligation / 递归 self-application）
 - [`docs/addon-soak-test-result-classification-guide.md`](addon-soak-test-result-classification-guide.md) — 长跑型测试（24h+ soak / chaos / fault-injection）出结果之后的结果分类方法论。**核心 framing**：fault total / PASS-FAIL 计数无法回答"是否 ACCEPTED"，必须把每条 fault 注入按"哪一层先失败"落到 4-state schema：(1) `invariant-break`（不变量破坏 → ROLLBACK）/ (2) `product-path-failure`（产品恢复路径失败）/ (3) `harness-race`（测试工具时序竞争）/ (4) `external-environmental-cascade`（外部环境级联）。**判据**：Q1（bad_ack > 0）→ Q2（cluster 终态）→ Q3（OpsRequest Failed + N≥2 自验证）→ Q4（duration 超 mean+3σ + 外部事件关联 + 对照样本）→ product-pass（mermaid 流程图）。**N≥2 自验证最小证据门槛**：harness-race 需同类 Succeed 对照、cascade 需 baseline ±1σ 对照样本；单 sample 不能下"非产品"结论。**ACCEPTED 判据**：`invariant-break = 0 AND product-path-failure = 0`，harness-race / cascade 不阻塞但触发对应修复 ticket。grounded N=3 CH30 harness-race 对照（fault-026 vs 029/033）+ N=2 CH20 cascade negative-control（fault-028 21min outlier vs 031 95s 1σ 内）+ AG quorum non-sticky 3-transition 行为附注。与 [`addon-test-acceptance-and-first-blocker-guide.md`](addon-test-acceptance-and-first-blocker-guide.md) 单次 fail first-blocker 分层方法论形成互补对子（前者聚合维度，后者单次维度）
+- [`docs/addon-runtime-contract-preflight-guide.md`](addon-runtime-contract-preflight-guide.md) — chart install schema 全过 + smoke 全 PASS 但 runtime cryptic 报错的隐藏失败模式预检方法论。聚焦三个对齐 surface：(1) Layer 0/1 chart spec 字段 → KB CRD schema 兼容性（image / chart / CRD 三层）；(2) Layer 2 vcluster substrate bootstrap precondition（外网拉镜像不通时的离线方案）；(3) Layer 5 ActionSet env contract drift（chart 没 declare runtime env，runtime 拿到 empty → 下游 cryptic 报错）。包含 4-step preflight 流程 + 跨引擎 4-pillar 口径同步表 + 决策树 + 4 case appendix（Oracle W7 ActionSet env / vcluster CoreDNS ImagePullBackOff / chart 跟 KB main isExclusive / MariaDB mirror family）。与 [`addon-kb-schema-version-preflight-guide.md`](addon-kb-schema-version-preflight-guide.md) 是 schema dimension vs runtime contract dimension 正交对子；与 [`addon-chart-vs-kb-schema-skew-diagnosis-guide.md`](addon-chart-vs-kb-schema-skew-diagnosis-guide.md) 是 preflight (本文) vs diagnosis (后者) lifecycle 互补；与 [`addon-soak-test-result-classification-guide.md`](addon-soak-test-result-classification-guide.md) 是 lifecycle preflight before vs classification after 互补
 
 ## 案例材料
 
diff --git a/docs/addon-runtime-contract-preflight-guide.md b/docs/addon-runtime-contract-preflight-guide.md
index 4365bc5..fb47999 100644
--- a/docs/addon-runtime-contract-preflight-guide.md
+++ b/docs/addon-runtime-contract-preflight-guide.md
@@ -1,7 +1,7 @@
 # Addon Runtime Contract Preflight 指南
 
 > **Audience**: addon dev / addon test / cross-line TL
-> **Status**: stable
+> **Status**: draft (v1)
 > **Applies to**: any KB addon
 > **Applies to KB version**: any (preflight 方法论本身版本无关；具体 ActionSet env 字段集随 KB 版本演化)
 > **Affected by version skew**: yes — chart spec 与 runtime 实际契约的对齐随 KB 版本 / addon 版本 / vcluster substrate 版本三向漂移；本文方法论 stable，具体 declare 字段 / image 路径需对照实测版本
@@ -140,37 +140,49 @@ comm -23 /tmp/referenced.txt /tmp/declared.txt
 
 注意：DP_* 框架变量（`DP_DB_HOST` / `DP_DB_PORT` / `DP_DB_USER` / `DP_DB_PASSWORD`）由 KB dataprotection runner 自动注入，不需 ActionSet declare；但 addon 自身需要的 `ORACLE_SID` / `MYSQL_PORT` / `PGDATABASE` 等必须显式 declare。
 
-### Step 3.5 — ActionSet env reference 的 systemAccount 是否 CMPD declare（关闭 inter-version chart drift gap）
+### Step 3.5 — BackupPolicy 引用的 systemAccount 是否 CMPD declare（关闭 inter-version chart drift gap）
 
-W8 audit 实战发现 silent 漂移类型：addon chart 内不同 minor variant 的 CMPD declare 不一致。例如 oracle addon chart 的 `cmpd.yaml` (12c) declare `systemAccounts: kbdataprotection`，但 sibling `cmpd-19c.yaml` (19c) 没 declare 这个 systemAccount → ActionSet env injection `DP_DB_USER`/`DP_DB_PASSWORD` 通过 `valueFrom.credentialVarRef.name` 引用一个不存在的 systemAccount → runtime silent fail（oracle-expdp worker pod `CreateContainerConfigError` on 19c，PASS on 12c，identical KB build）。
+W8 audit 实战发现 silent 漂移类型：addon chart 内不同 minor variant 的 CMPD declare 不一致。例如 oracle addon chart 的 `cmpd.yaml` (12c) declare `systemAccounts: kbdataprotection`，但 sibling `cmpd-19c.yaml` (19c) 没 declare 这个 systemAccount → BackupPolicy `target.account: kbdataprotection` 引用一个不存在的 systemAccount → KB 永远不会生成对应 secret → runtime silent fail（oracle-expdp worker pod `CreateContainerConfigError` on 19c，PASS on 12c，identical KB build）。
 
-**Audit check（仅适用于 ActionSet 用 `valueFrom.credentialVarRef` 引用 systemAccount 的情形）**:
+**Audit shape 关键澄清**: `DP_DB_USER` / `DP_DB_PASSWORD` **不在 ActionSet `spec.env` 里 declare**，由 KB **dataprotection Job runner** 基于 `BackupPolicy.spec.backupMethods[].target.account`（引用 systemAccount name）**自动注入**。所以 systemAccount → `DP_DB_*` 的契约边界在 **BackupPolicy layer**，不在 ActionSet layer — audit 必须从 BackupPolicy 起，不能只看 ActionSet。
+
+**Audit check（cluster-side，install 后跑）**:
 
 ```bash
 # 列 CMPD declare 的 systemAccount name 集合
-kubectl get cmpd <component-name> -o jsonpath='{.spec.systemAccounts[*].name}' | tr ' ' '\n' | sort > /tmp/cmpd-accounts.txt
-
-# 列 ActionSet 引用的 systemAccount name (DP_DB_USER + DP_DB_PASSWORD 都查)
-kubectl get actionset <name> -o jsonpath='{.spec.backup.backupData.env[?(@.name=="DP_DB_USER")].valueFrom.componentField.fieldPath}' 2>/dev/null
-kubectl get actionset <name> -o jsonpath='{.spec.backup.backupData.env[?(@.name=="DP_DB_PASSWORD")].valueFrom.componentField.fieldPath}' 2>/dev/null
-
-# 差集即 inter-version chart drift 风险 surface
-# - 如果 ActionSet 改用 raw username/password 直接注入（不通过 valueFrom credentialVarRef），此 check 不适用
+kubectl get cmpd <component-name> -o jsonpath='{.spec.systemAccounts[*].name}' \
+  | tr ' ' '\n' | sort -u > /tmp/cmpd-accounts.txt
+
+# 列 BackupPolicy 各 method 引用的 systemAccount name (target.account)
+# (BackupPolicy 是 cluster install 后 KB 从 BackupPolicyTemplate 渲染出来的实际对象)
+kubectl get backuppolicy <name> -o jsonpath='{.spec.backupMethods[*].target.account}' \
+  | tr ' ' '\n' | sort -u > /tmp/bp-referenced-accounts.txt
+
+# 差集 = silent runtime fail surface（BackupPolicy 引用了 CMPD 没 declare 的 systemAccount）
+comm -23 /tmp/bp-referenced-accounts.txt /tmp/cmpd-accounts.txt
+# 非空 = runtime gap，KB 永远不会生成对应 secret，dataprotection Job 起不来
+# 注：如 ActionSet 改用 raw username/password 直接注入（不通过 KB DP runner secret），此 check 不适用 — 但这是少数情形，KB DP runner secret 注入是 default contract
 ```
 
 **Cross-variant CMPD 字段 diff audit（chart-side，作 Pre-install scan）**:
 
 ```bash
-# 在 chart source dir
-diff <(yq '.spec.systemAccounts[].name' templates/cmpd.yaml | sort) \
-     <(yq '.spec.systemAccounts[].name' templates/cmpd-19c.yaml | sort)
-diff <(yq '.spec.vars[].valueFrom.credentialVarRef.name' templates/cmpd.yaml | sort) \
-     <(yq '.spec.vars[].valueFrom.credentialVarRef.name' templates/cmpd-19c.yaml | sort)
+# 在 chart source dir — 包含 BackupPolicyTemplate 的反向校验
+diff <(yq '.spec.systemAccounts[].name' templates/cmpd.yaml | sort -u) \
+     <(yq '.spec.systemAccounts[].name' templates/cmpd-19c.yaml | sort -u)
+diff <(yq '.spec.vars[].valueFrom.credentialVarRef.name' templates/cmpd.yaml | sort -u) \
+     <(yq '.spec.vars[].valueFrom.credentialVarRef.name' templates/cmpd-19c.yaml | sort -u)
 diff <(yq '.spec.lifecycleActions | keys' templates/cmpd.yaml) \
      <(yq '.spec.lifecycleActions | keys' templates/cmpd-19c.yaml)
-# 非空 diff = drift（除非 design intent inline 文档说明 variant 之间差异是有意的）
+
+# BackupPolicyTemplate ↔ CMPD 跨 CRD reference 校验（chart 源头就 catch W8 类漂移）
+diff <(yq '.spec.systemAccounts[].name' templates/cmpd-19c.yaml | sort -u) \
+     <(yq '.spec.backupMethods[].target.account' templates/backuppolicytemplate.yaml | sort -u)
+# 后者 - 前者 非空 = chart 源头 broken（BackupPolicy 引用了 19c CMPD 没 declare 的 systemAccount）
 ```
 
+W8 grounded 形态：`addons/oracle/templates/backuppolicytemplate.yaml` 第 33 行 `account: kbdataprotection`，但 `cmpd-19c.yaml` 不 declare `kbdataprotection`，所以 19c cluster install 后 KB DP runner 找不到 secret → `oracle-expdp` Job `CreateContainerConfigError`。本 step 的 audit 价值就在 catch 这种**跨 CRD reference 漂移**。
+
 ### Step 4 — 实跑 1 个 dataprotection / cross-pod 操作 round-trip
 
 前 3 步全 pass 后，必跑一次端到端验证：发起一个 Backup（最小数据集）、观察 pod 内 Backup script 的 env list 与连接是否成功。空跑 install 不算 preflight 通过。
@@ -537,7 +549,7 @@ kubectl -n kube-system get pods -l k8s-app=kube-dns -w
 
 > **Surface error wording 校稿状态**：Oracle ✅ (W7 grounded) / MariaDB ⚠ (idc bastion 视角推断，MariaDB line 2026-05-05 当前 cycle 未触发 cluster-DNS 失败 path——vcluster 走 NodePort 直连 + idc-k8s CoreDNS 健康，无 grounded sample) / MySQL + PostgreSQL + Redis-Valkey + SQL Server 待对应 line owner 实战 confirm 后回填具体 grounded sample。**MongoDB wording 来自 K8s evidence pack 推断（cross-line K8s patterns），待 future MongoDB line owner 加入后 grounded confirm**。**待回填规则**：每条 line 在实战实际触发 Layer 2 DNS 失败时回填本 line 真实 error string + 上下文 trace；未触发的 line 保留 ⚠ 不要标 ✅。
 
-**诊断 protocol**（5-min preflight cross-ref `addon-smoke-test-pre-flight-checklist-guide.md` §7）:
+**诊断 protocol**（5-min preflight cross-ref `addon-smoke-test-pre-flight-checklist-guide.md` §7，planned, PR #71）:
 ```bash
 # 任何 vcluster 上 smoke / dataprotection 测试启动前
 kubectl -n kube-system get pods -l k8s-app=kube-dns 2>&1 | grep -v ImagePullBackOff || echo "ALERT: coredns down"
@@ -559,10 +571,10 @@ kubectl -n kube-system get pods -l k8s-app=kube-dns 2>&1 | grep -v ImagePullBack
   - Verification: Backup `o19-i4-8854-rman19c-w7verify2` Status=Completed 553MB 2m32s
 - Evidence pack: `work/oracle-idc4-migration/W7-verify-evidence/` (00-summary.md + 5 yaml/txt artifacts including `05-coredns-running-after-fix.txt`)
 - MariaDB line cross-line evidence:
-  - `addon-idc-image-registry-mirror-guide.md` PR #54 §1 mirror family classification + §5 MariaDB row（chart body docker.io/dockerproxy.net + 2 件 ACR runner + initContainer pair + 0 ghcr.io 主体审计）
+  - [`addon-idc-image-registry-mirror-guide.md`](addon-idc-image-registry-mirror-guide.md) PR #54 §1 mirror family classification + §5 MariaDB row（chart body docker.io/dockerproxy.net + 2 件 ACR runner + initContainer pair + 0 ghcr.io 主体审计）
   - 2026-05-05 11:16-12:55 patched syncer cross-compile + sideload 实战（idc-k8s 三节点 mariadb-runner ns）：交叉编译 binary → graft 到现有 base image → `kubectl cp tar` + `ctr -n k8s.io images import` 推到所有 3 节点 → CmpD `imagePullPolicy: IfNotPresent` 命中本地 cache（升级既存 CmpD 不能改 immutable 字段到 `Never`）→ alpha.16 fresh-matrix 8/8 PASS 复测验证补丁
-  - 取证：`addon-idc-image-registry-mirror-guide.md` §5 MariaDB row + `addon-host-runner-job-pattern-guide.md` §"常见坑表"
-- Cross-ref to [`addon-smoke-test-pre-flight-checklist-guide.md`](addon-smoke-test-pre-flight-checklist-guide.md) §7 + case study appendix（PR #71）
+  - 取证：[`addon-idc-image-registry-mirror-guide.md`](addon-idc-image-registry-mirror-guide.md) §5 MariaDB row + [`addon-host-runner-job-pattern-guide.md`](addon-host-runner-job-pattern-guide.md) §"常见坑表"
+- Cross-ref to `addon-smoke-test-pre-flight-checklist-guide.md` §7 + case study appendix（planned, PR #71）
 
 > **Co-author note**: 本节主体 drafted by **Oracle line addon owner** (W7 idc4 evidence), idc 实操 view 1-2 段（Mirror 选型 doctrine / Sideload vs swap 取舍 / 黑名单 wisdom / 时序踩点）by **MariaDB line idc bastion view** (PR #54 §5 author + 11:16-12:55 syncer deployment 实战), polished by SQL Server line for cross-line generalization。
 
@@ -687,7 +699,7 @@ flowchart TD
 
 ### Case D — MariaDB line mirror family classification (Layer 2 cross-line)
 
-- Source: PR #54 `addon-idc-image-registry-mirror-guide.md` §1 mirror family classification + §5 MariaDB row
+- Source: PR #54 [`addon-idc-image-registry-mirror-guide.md`](addon-idc-image-registry-mirror-guide.md) §1 mirror family classification + §5 MariaDB row
 - 内容: chart body docker.io/dockerproxy.net 主路 + 2 件 ACR (runner + initContainer pair) + 0 ghcr.io 主体审计 + 11:16-12:55 syncer cross-compile sideload 实战
 - Mirror 黑名单 wisdom: alpine vs glibc / kubeblocks-tools 1.0.2 vs 1.0.0 / xuriwuyun golang base 三类 idc 失败 path
 - Cross-ref to §6.3 Mirror 选型实测表 + Sideload vs swap 取舍 + 时序踩点子节