源码版本、factory 代际与依赖维护¶

Nexus 交付源码 SDK。消费方在同一配置、编译器和 ABI 选择下重新编译 Core、 provider、生成 bindings 和调用者；当前不交付稳定二进制 ABI。预编译库、不同 enum 选项、不同 FP ABI 或不同生成 bundle 的对象不能因为版本号相同而混合链接。

版本各自负责什么¶

dependencies/platform-compatibility.json 是源码接口代际的唯一策略数据。 tools/configure/metadata.py 是生产装配器和维护工具共用的严格纯 stdlib loader。它拒绝重复键、未知字段、缺失策略、布尔伪整数、非规范版本和 symlink 输入；不会迁移 TOML、选择硬件、执行构建或替换任何未知值。

项目	当前值	合同
平台语义版本	`0.2.1`	唯一人工维护值来自兼容性 JSON；CMake、生成头文件和包元数据派生并保持一致
`factory_abi_epoch`	`1`	当前唯一认可的生成源码接口代际；不是 binary ABI 保证
源码 SDK	`source_only` / `exact`	CMake package 只接受相同完整版本，拒绝 ranges
作者装配	`2`	简化的 TOML 选择面；不改变 Board/SoC 事实
resolved JSON 投影／typed IR	`1` / `2`	单向 JSON 输出格式与私有 Python 类型化源码接口分别计代
Board／SoC／路由	`1` / `1` / `1`	物理事实文件及生产 validator 必须一致
CPU runtime 装配／事实／解析结果	`1` / `1` / `1`	CPU 软件配置，不能升格 SoC/Board 资格
已安装源码 SDK 清单	`1`	既有完整 file-map/源依赖/package-export 校验

这些数字不能互相替代。修改文档或新增可选机制通常不改变配置 schema；改变 schema 意味着生产 validator/emitter 明确维护了新的格式，并更新策略断言与负测。策略不能使尚未实现的 schema 获得支持。SDK manifest 增加一个被 file-map 覆盖的源码文件，不等于修改 manifest 格式。

类型化源码接口第 2 代只接受严格 TOML 解析后的不可变装配对象；生产 resolver、 factory 和 emitter 使用具名字段，不提供字典接口或 schema-1 JSON 装配兼容。 resolved.json 仍是第 1 版单向输出，用于审计和独立产物检查，不是可信配置入口。 source_epoch 是 Python 类级合同，不写入 JSON，也不增加 MCU 状态或改变公共 C factory 接口。维护工具直接观察实际 IR 类的两项声明，并核对唯一版本策略。

当前 0.2.1 用于开发与软件候选准备；版本值本身不表示已公开发行或已通过候选验收。既有 v0.2.0 标签保留原始预览源码身份。本次 semantic version 变化保留 epoch 1、 exact 匹配和 authored schema 2；版本值不把旧 SDK／候选的资格转移到新源码。新候选仍须独立绑定实际 clean source、配置、依赖、工具与执行证据。

0.1.0 是 2026-10-15（Asia/Shanghai）首个公开源码 SDK 开发者预览版。之前源码快照中的 1.0.0 是公开发行前的版本值；2026-01-12 第一阶段的旧 0.1.0 文字保留为历史里程碑。该已发布版本的范围和原始证据见 0.1.0 历史发行状态，准确 source／tree 以其发行 manifest 为准。既有 tag、发行附件和证据保持原始身份，不随当前开发版本改写。

factory 的 compact ID 只在该生成 bundle 内有意义。它返回既有静态 readonly face，不分配、不初始化硬件。重新排序实例或改变配置可能改变 ID；不能把 ID 持久化后拿到另一 bundle 使用。factory_abi_epoch 命名保留 ABI 字样，但目前只标记生成源码接口代际：消费者、factory header、公共 face 和实现必须重新编译。当前 epoch 为 1；指定 0、未来值、非整数或找不到策略时必须拒绝，不能当成兼容 fallback。

生成配置须把策略原字节加入既有 inputs/snapshots/hash 闭包，并从唯一 loader 生成 NEXUS_PLATFORM_VERSION 和 NEXUS_FACTORY_ABI_EPOCH。这些是编译期常量，不会增加运行时 registry、实例数量或 RAM。生产 emitter 与 SDK 打包注册完成后，生成 header 校验和真实 SDK 消费才构成这条链路的完整验收；仅有维护工具不能代替它们。历史 SDK 缺少该新策略，不被新工具自动认定为已维护代际。

自动检查¶

PATH="$(pwd)/.venv/bin:$PATH" .venv/bin/python \
    tools/maintenance/compatibility.py
PATH="$(pwd)/.venv/bin:$PATH" .venv/bin/python \
    tools/maintenance/compatibility.py --expected-factory-epoch 1 \
    --generated build/native-debug/generated/nexus_factory.h
PATH="$(pwd)/.venv/bin:$PATH" .venv/bin/python \
    tools/maintenance/compatibility.py --sdk /abs/prefix/share/nexus/src

--generated 使用实际生成 header 的路径；不同构建根的路径可能不同。工具从真实 Python validators/emission 的 AST 读取 schema，读取实际事实文件，并运行现有 NexusConfigVersion.cmake.in 的相等版本、不同版本与 range 拒绝用例。它不复制 resolver 选择规则；如果 authority 的表达形式改变，检查会明确失败，维护者需更新观察器。所有参与字节有 SHA/size，结束前复验，观察过程中变化不能报告一致。

--sdk 复用既有 package_source_sdk.verify 校验整个源文件映射、依赖、厂商 import 和 package exports，再检查策略及 schema/version 一致。consistent 只表示这些元数据一致，不表示 fresh 全量测试、软件候选、签名、物理 HIL 或产品发布通过。

版本变更需先写拒绝/兼容契约测试，再修改唯一策略及实际 authority。source breaking 变更需明确 major/epoch 的变化和外部迁移；可选源码能力用 minor，保持公开合同的缺陷修复用 patch。没有实际迁移实现时，禁止接受旧格式后静默选择新行为。

依赖来源、获取与选版¶

tools/maintenance/source_catalogue.py 是已审 Git 依赖目录：upstream_url 标识官方来源与版本观察地址，fetch_url 标识本提交允许的获取地址，Gitlink 选择实际 commit。源码锁继续约束官方来源、许可和内容；锁中的 commit 必须与 Gitlink 相等，不能覆盖它。更换托管地址不意味着升级库或改变 CMake 依赖图。

目录包含 14 个顶层 Git 子模块和 FreeRTOS 的两个嵌套子模块。13 个顶层运行时依赖及其递归闭包参与源码 SDK；GoogleTest/GoogleMock 只供主机测试使用。嵌套模块的 section name 和相对路径分别核对，不能假设两者相同。GD32 官方归档继续按已审子树、逐文件锁和原许可管理，不伪装成官方 Git 仓库的 fork。

X-Gen-Lab 托管目录中全部 16 个官方 Git 依赖的 fork；fetch_url 与 .gitmodules 指向已验证的组织仓库。获取地址使用目录中的实际仓库名，不从磁盘路径或上游 URL 推导名称。官方 upstream_url 保留来源与版本观察职责，Gitlink 继续选择准确 commit。每个 Nexus 提交只认可一个明确获取地址，不使用全局 url.insteadOf、浮动分支或自动回退到其他仓库。

FreeRTOS 使用仅修改根 .gitmodules 中两个已知 URL 的组织提交，集成引用为 nexus/transport-v11.1.0-r1。它的唯一父提交是已锁定官方基线，嵌套 Gitlink、源码、许可和文件模式保持原样。dependencies/freertos-transport.lock.json 与 dependencies/reviews/freertos/ 中的基线文件和补丁记录该审查；补丁不在配置或构建期间动态应用。官方发行 tag 仍指向官方基线，组织提交不代表新的官方发行版。

开发 checkout 与 SDK 打包执行实际 Git 父链、完整树差异和两处 URL 替换检查，不能只信锁文件声明的 changed_paths。SDK 内的审查材料和文件映射验证导出字节，无 Git 的消费环境不能据此声称重新验证了完整父链或源码树。消费者须先通过独立可信的发行身份、候选记录或预先批准的归档摘要确认 SDK，再执行包内 Python/CMake。包内自带 manifest 与内容一致，本身不证明来源可信，也不等于签名验证。

托管迁移、同步与恢复¶

迁移先验证 fork 的官方父仓库关系、匿名读取、固定 commit 与所需引用可达，再更新 Nexus 获取策略。组织仓库为受维护提交保留 refs/tags/nexus/pins/<完整SHA>；联网准备在改动 checkout 前核对引用返回的对象与所选 SHA。FreeRTOS 同时保留官方基线和组织集成提交。仓库或引用存在不代表当前连接能写入它，也不代表分支或 tag 保护已经启用；这些状态需实际读回。生产源码和已发布引用不得因同步上游而被重写。

已有 checkout 从已审官方地址迁往已审组织地址时，准备工具先检查工作区、实际仓库根、origin 和允许的旧/新 commit。普通源码修改、未跟踪依赖文件、未知 origin 或未知 HEAD 都应停止处理。已登记的旧 Gitlink 可以作为迁移起点；不能将一次正常的子模块版本切换误判为用户源码修改。工具不 stash、reset、clean 或强制更新。

已有 checkout 先切换到要消费的准确 Nexus 提交，再从仓库根运行显式准备入口。工具按所选提交识别已登记的旧依赖状态；以下命令允许下载，离线检查省略 --allow-network：

python tools/dev/dev.py prepare --scope native --allow-network
python tools/dev/dev.py prepare --preset stm32-nucleo-h743-baremetal-uart --allow-network

准备工具先审查源码拥有的完整声明和 Gitlink，再同步、初始化明确选中的顶层路径。每个父模块更新后，重新审查其实际声明和所属 Git 树，再逐层处理明确选中的子路径。这些步骤不使用无范围的递归下载；组织维护分支只声明已选择并审查的依赖。先更新顶层 FreeRTOS，再同步它的嵌套声明，避免旧 .gitmodules 把官方地址写回。成功后逐项核对路径、Gitlink、实际 HEAD、origin 和干净状态。缺失对象、下载失败或来源不符必须失败，保留实际执行记录，不改用 --remote 或隐式备用地址。配置、构建和提交门禁均不自动联网准备依赖。

回滚使用正常的新提交，一起恢复获取策略、Gitlink、审查锁和相应示例 pin；不改写旧提交、tag 或证据。fork 不等于备份：Nexus 自身的 Git bundle 不包含子模块对象，需要另存依赖 Git 对象，或保留可验证的完整源码 SDK，并实际验证异地恢复。服务不可用时消费已批准的离线包，不把临时换源隐藏在普通构建中。

Codex 的每周依赖流程¶

tools/maintenance/dependency_proposals.py 默认只观察当前实际 Gitlink、锁、归档和许可证字节，网络读取为零。它覆盖 FreeRTOS、CMSIS、STM32 CMSIS、GD32 import、 GoogleTest、ARM 工具链、开发环境/Python 工具锁和 GitHub Actions 的确切 pins。某项发行物还需审查许可证时，会明确记录 required，不从版本名猜许可。

.venv/bin/python tools/maintenance/dependency_proposals.py
.venv/bin/python tools/maintenance/dependency_proposals.py \
    --observe-upstream --upstream-output build/maintenance/upstream-fresh
.venv/bin/python tools/maintenance/dependency_proposals.py \
    --plan /abs/candidate-proposal.json

显式 upstream 模式只查询目录中官方 upstream_url 的 heads/tags，组织 fork 的 fetch_url 不替代版本来源。普通依赖的 upstream_revision 等于所选 Gitlink； FreeRTOS 地址迁移提交分别记录 selected_revision 与官方 upstream_base，避免把组织提交误判为官方缺失版本。真正升级官方基线后，新的组织集成提交也必须重新准备并审查。使用无 shell、禁止 credential helper/交互/global config 的 git ls-remote；每个请求最长 10 秒， stdout/stderr 总捕获上限 1 MiB，refs 最多 8192 条。复用已有有界 subprocess capture/kill/reap 机制，不执行 HIL admission 或设备动作。输出目录必须新建且无 symlink；源码内只允许 build 目录。原始 stream、argv、实际退出码、时间和工具/ 响应 SHA 均保留。网络、超时、输出或格式失败为 not_observed；没有 Git publication 的 GD32/工具链/环境项需单独审查发行来源，不能伪造版本观察成功。观察 refs 不是选择最新可靠版本或批准升级。周度 workflow 的实际运行状态需另看 GitHub 证据。

candidate plan 使用严格 JSON：schema_version=1、已观察的 dependency、明确 proposed_revision、不带凭据/query 的公共 HTTPS source_url、实际非空 archive identity、声明的 license expression 和 notices identities，以及可选的 evidence 映射。每个 identity 都是绝对 path、完整 sha256 和真实 size。Git 来源必须是完整 40 位 commit，不能用 main/latest；license 内容必须独立审查，声明不是许可批准。archive 是否来自该 commit、是否完整包含声明 notice 和所有变更也在独立来源/许可证 review 中验证，工具不会从任意用户提供的 notice 推断这些事实。

必需 gate	验收范围
license_review	来源/archive/commit、全部再分发文件、许可/notice 变更，由独立 Codex review 复核
configuration	全配置/内核边界、单一输入闭包、schema/epoch 与生成一致性
host_models	pinned GoogleTest/GoogleMock 全发现执行、工具/CTest、维护的 Native sanitizer profiles
cortex_runtime	当前 CPU/ISA/FP/MVE/ABI runtime、受维护 MPU 与 Secure/NS 软件矩阵
board_arm	三块精确 Board × baremetal/FreeRTOS，受影响的外部 examples
resource_budgets	每个新 ELF 独立预算、同 fixture 前后成本、各 RAM 域和 reservation
installed_sdk	clean exact source SDK、版本/epoch 拒绝、实际独立消费者
offline_reproduction	绑定环境内两次 fresh network-disabled 构建及同一 ELF/BIN/map bytes
static_analysis	owned ClangTidy/Cppcheck、格式/注释、原始失败与明确 vendor 审查边界

工具只形成 proposal。缺证据为 not_executed；提供真实 file identities 也只变成 referenced_unreviewed。即使引用 JSON 自称 passed，工具也不升级资格，不执行其命令、不修改 Gitlink/lock、不创建自动升级 commit。现有正式 validators 必须对升级的 exact clean 源、完整 scope 和同一 artifact 独立执行。随后通过正常 staged review、hooks 和 CI 原子更新源码 Gitlink/厂商 import、锁、许可和外部 SDK pin。

没有实板时，受升级影响的电气、IRQ/DMA timing、低功耗和长期负载仍是物理 pending。一次 upstream request、一个模型 pass 或之前版本的软件候选都不能代替本次验收。