开发者文档代码样例漂移门禁：版本矩阵、可执行证明与回退别名

代码样例最危险的状态不是明显报错，而是语法仍能编译、语义已经过期：SDK 方法保留了旧重载，示例却把金额单位传错；文档站隐藏了初始化代码，用户复制可见部分后缺少 import；latest 又在发布后指向了另一主版本。AI 驱动的产品文档站关注内容生成与检索，本篇只回答一个可验问题：当前页面展示的每个可执行代码块，是否仍能在它声明的版本组合上完成明确任务。

这也不同于 SEO 内容刷新证据账本：更新时间与查询漂移不能证明样例可运行；还不同于 API Mock 与 Fixture 漂移门禁，后者治理测试替身是否代表生产者，这里治理用户实际复制到本地的公开片段以及渲染链是否忠实。

给每个可见样例稳定身份

文档构建先产出不可变的 docs.sampleSet.v1。每个 sampleId 绑定源文件与 marker、规范化源码摘要、渲染后可复制文本摘要、文档 revision、SDK 制品摘要、依赖锁摘要、运行时镜像摘要、API revision、所需 scope、环境变量 schema、场景 ID，以及独立 oracleBundle 的版本和摘要。样例被移动可以保留身份；代码、隐藏前置或 oracle 引用任一变化都必须生成新 generation，禁止覆盖旧证明。

schema: docs.sampleSet.v1
sampleId: node.widgets.create.v3
sourceDigest: sha256:91c...
renderedCopyDigest: sha256:113...
sdkArtifact: npm:@acme/[email protected]#sha512-...
runtimeImage: sha256:83a...
apiRevision: widgets.v3
scenario: create-and-read-back
oracleBundle: api-conformance.widgets@7#sha256:5ce...

SemVer 可以表达公开 API 的版本意图，却不能证明某个方法在真实凭证、区域或默认配置下仍有相同行为。因此版本范围只用于生成测试矩阵，不能代替执行。^4.1 必须解析成测试时的确切版本并写入 proof；历史文档则固定原制品，不能随 registry 的 latest 漂移。REST API 版本控制提供接口兼容策略，样例清单负责把策略落实到页面、SDK 与执行环境。

从 Markdown 到服务端结果做两段验证

第一段从最终 HTML 用结构化解析器重新抽取用户可复制文本，在无仓库上下文的空目录创建项目、安装锁定依赖、编译并运行。隐藏 bootstrap 只有在页面明确提供完整下载入口且摘要一致时才允许；不能让 CI 偷用读者看不到的 helper。shell、PowerShell 和 Windows 路径分别执行，输出按声明规则去掉 request ID 等非确定字段，金额、排序、分页和错误码不能被归一化掉。

第二段用短期沙箱凭证调用待发布 API 制品，再由独立版本的 oracle bundle 验证 OpenAPI 结构之外的业务不变量，例如创建后可读回、幂等键重放不重复写入、分页能到达终点。真实服务本身不是 oracle：bundle 由 API conformance owner 维护和批准，文档 generator 无权生成或修改；同一变更同时修改样例与 oracle 必须经过两个所有权边界的独立审批。离线模拟器可以让 PR 快速失败，但它和实际服务不能由同一生成过程互相证明；每日 canary 必须跑真实发布组合。API 或 oracle 不可用时结果为 INFRA_UNAVAILABLE，不能沿用上次绿色状态冒充新证明。

每次执行写出 docs.sampleVerification.v1，包含 sample set 与 oracle bundle 摘要、两边审批 generation、runner 版本、解析出的完整依赖图、环境类别、开始与结束时间、逐步结果、服务端操作摘要和日志脱敏计数。证明采用制品血缘式的 subject/material 关系，让审阅者知道验证的是哪个渲染结果和哪套独立断言，而非源码旁边另一份相似文件。AI 供应链安全说明依赖风险，本文只将已批准制品和构建材料钉进样例证明。

主动制造“看起来没坏”的漂移

变异套件应删除可见 import、把 SDK 提升一个不兼容主版本、移动默认 endpoint、撤销所需 scope、将 nullable 改成 absent、改变金额单位、让异步流在 flush 前退出、令分页游标重复、把 bash 引号放进 PowerShell，并让 CDN 返回旧 HTML 配新下载包。还要让生成器只更新展示代码而遗漏下载工程、让服务端返回合法 schema 但错误业务值，并尝试在同一 PR 中同步放宽样例与断言。门禁必须定位到 source、renderer、package、runtime、API 或 oracle，且拒绝未经独立批准的 oracle 摘要，不能统一报“sample failed”。

发布接受条件为：所有标记 runnable 的可见片段抽取率 100%；当前 SDK 与仍承诺支持的前一主版本矩阵通过率 100%；HTML 复制文本与受测文本摘要一致率 100%；sample 与 oracle 独立审批覆盖率 100%；规定场景在全新环境 60 秒内完成率不低于 98%；包括耦合放宽在内的变异检出率 100%；未声明外连为 0；日志与制品中的秘密泄漏为 0。暂时无法验证的语言显示明确的“未验证”状态并阻断默认 Quickstart，不准用其他语言的绿灯填补。

上线先让新 runner 对现有页面 shadow 执行一周，只产生差异报告；随后给内部流量启用带 proof generation 的新 renderer，再扩大到 10% 公共请求。若复制摘要不一致、任一支持矩阵失败或 p95 执行时间翻倍，将文档 alias 原子切回上一份已证明的 sample set，同时保留失败页面与 proof 供复现。修复发布新 generation，不能静默改写存档页面或删除红色记录；Feature Flag 灰度可以控制入口，但是否合格始终由这里的不可变证明决定。