Document source: e47887d3a11f; code reference: e47887d3a11f. 中文. Source language: zh_CN; requested: en; actual: en; translation: reviewed.

Source documentation does not establish software or physical hardware qualification. See the support and qualification records for their exact scope.

Source versions, factory generations and dependency maintenance

Nexus delivers a source SDK. Consumers rebuild Core, providers, generated bindings and callers under the same configuration, compiler and ABI choices; no stable binary ABI is currently delivered. Precompiled libraries, different enum options, FP ABIs or generated-bundle objects cannot be mixed merely because versions match.

What each version owns

dependencies/platform-compatibility.json is the sole source-interface-generation policy data. tools/configure/metadata.py is the strict pure-stdlib loader shared by production assembly and maintenance tools. It rejects duplicate keys, unknown fields, missing policy, boolean pseudo-integers, noncanonical versions and symlink inputs. It neither migrates TOML, selects hardware, runs builds nor replaces unknown values.

Item	Current value	Contract
Platform semantic version	0.2.1	The sole authored value comes from the compatibility JSON; CMake, generated headers and package metadata derive it and remain consistent.
factory_abi_epoch	1	The only currently recognized generated-source interface generation; not a binary ABI guarantee
source SDK	source_only / exact	CMake packages accept only the exact full version and reject ranges
authored assembly	2	Simplified TOML selection surface; no change to Board/SoC facts
resolved JSON projection / typed IR	1 / 2	The one-way JSON output format and private typed Python source interface have separate generations
Board / SoC / routes	1 / 1 / 1	Physical-fact files and production validators must agree
CPU runtime assembly / facts / resolved	1 / 1 / 1	CPU software configuration cannot promote SoC/Board qualification
installed source SDK manifest	1	Existing complete file-map/source-dependency/package-export validation

These numbers are not interchangeable. Documentation edits or optional mechanisms usually do not change configuration schemas. Schema changes mean production validators/emitters explicitly maintain a new format, with updated policy assertions and negative tests. Policy cannot grant support to an unimplemented schema. Adding a file covered by the SDK manifest file-map does not change the manifest format.

Typed source interface generation 2 accepts only immutable assembly objects produced by strict TOML parsing. Production resolver, factory and emitters use named fields, without a dictionary interface or schema-1 JSON assembly compatibility. resolved.json remains a version-1 one-way output for audits and independent artifact checks, not a trusted configuration input. source_epoch is a Python class contract; it is not serialized to JSON and adds no MCU state or change to public C factory interfaces. Maintenance tools observe both declarations on the actual IR class and check them against the sole version policy.

The current 0.2.1 version is for development and software-candidate preparation. A version value alone does not establish publication or candidate acceptance. The existing v0.2.0 tag retains its original preview source identity. This semantic-version change preserves epoch 1, exact matching and authored schema 2. A version value does not transfer old SDK/candidate qualification to new source. A new candidate must independently bind actual clean source, configuration, dependencies, tools and executed evidence.

0.1.0 is the first public Source SDK developer preview, dated 2026-10-15 (Asia/Shanghai). The 1.0.0 value in earlier source snapshots was a prepublication version; the old 0.1.0 wording for the 2026-01-12 Phase 1 entry remains a historical milestone. See historical 0.1.0 release status for that published version’s scope and original evidence; its release manifest identifies the exact source/tree. Existing tags, release assets and evidence keep their original identity and are not rewritten for the current development version.

Factory compact IDs mean something only within their generated bundle. The factory returns existing static read-only faces without allocation or hardware initialization. Reordering instances or changing configuration may change IDs; persisted IDs cannot be used with another bundle. factory_abi_epoch retains ABI in its name but currently marks only generated-source interface generations: consumers, factory headers, public faces and implementations require recompilation. Current epoch is 1; zero, future values, nonintegers or missing policy must reject rather than become compatibility fallbacks.

Generated configuration includes original policy bytes in the existing inputs/snapshots/hash closure and derives NEXUS_PLATFORM_VERSION and NEXUS_FACTORY_ABI_EPOCH through the sole loader. These compile-time constants add no runtime registry, instance count or RAM. After production-emitter and SDK-packager registration, generated-header checks and real SDK consumption establish complete acceptance; maintenance tools alone cannot replace them. Historical SDKs missing this policy are not automatically recognized by new tools as maintained generations.

Automatic checks

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 takes the actual generated-header path, which may differ between build roots. The tool reads schemas from real Python validator/emitter ASTs, reads actual fact files, and executes existing NexusConfigVersion.cmake.in equal-version, different-version and range-rejection cases. It does not copy resolver selection rules; authority-expression changes fail explicitly and require observer maintenance. All participating bytes have SHA/size and are rechecked before return; concurrent changes cannot report consistency.

--sdk reuses existing package_source_sdk.verify to check the entire source file map, dependencies, vendor imports and package exports, then policy/schema/version consistency. consistent means this metadata agrees, not that fresh full tests, software candidates, signatures, physical HIL or product releases pass.

Version changes first add rejection/compatibility contract tests, then modify the single policy and actual authorities. Source-breaking changes require explicit major/epoch changes and external migration; optional source capabilities use minor and public-contract-preserving fixes use patch. Without real migration, accepting old formats then silently selecting new behavior is prohibited.

Dependency provenance, retrieval and version selection

tools/maintenance/source_catalogue.py is the reviewed Git dependency catalogue: upstream_url identifies the official source and version-observation endpoint, fetch_url identifies the retrieval location approved by this commit, and the Gitlink selects the actual commit. Source locks continue to constrain official provenance, licenses and content; a locked commit must equal the Gitlink rather than override it. Changing hosting does not upgrade a library or change the CMake dependency graph.

The catalogue contains 14 top-level Git submodules and two nested FreeRTOS submodules. The 13 top-level runtime dependencies and their recursive closure participate in the source SDK; GoogleTest/GoogleMock are for host testing only. Nested section names and relative paths are checked separately and need not be identical. Official GD32 archives retain their reviewed subtree, per-file locks and original licenses; they are not represented as forks of an official Git repository.

X-Gen-Lab hosts forks of all 16 official Git dependencies in the catalogue; fetch_url and .gitmodules identify the verified organization repositories. Retrieval locations use the actual repository names recorded in the catalogue, rather than names derived from filesystem paths or upstream URLs. The official upstream_url retains provenance and version-observation responsibilities, while Gitlinks continue to select exact commits. Each Nexus commit approves one explicit retrieval location, without global url.insteadOf, floating branches or automatic fallback to another repository.

FreeRTOS uses an organization commit that changes only two known URLs in its root .gitmodules, with integration ref nexus/transport-v11.1.0-r1. Its sole parent is the locked official baseline; nested Gitlinks, source code, licenses and file modes remain unchanged. dependencies/freertos-transport.lock.json and the baseline file and patch under dependencies/reviews/freertos/ record this review; the patch is never applied dynamically during configuration or builds. Official release tags still identify the official baseline. The organization commit does not represent a new official release.

Development checkouts and SDK packaging verify the actual Git parent chain, complete tree difference and two URL replacements, rather than trusting the lock’s declared changed_paths. Review material and file maps in the SDK verify exported bytes; consumers without Git cannot claim to have reverified the complete parent chain or source tree. Consumers must first establish SDK identity through an independently trusted release identity, candidate record or previously approved archive digest, before executing packaged Python/CMake. Agreement between a self-contained manifest and its payload does not itself establish trusted provenance or signature verification.

Hosting migration, synchronization and recovery

Before changing Nexus retrieval policy, migration verifies the fork’s official parent relationship, anonymous reads, and reachability of fixed commits and required refs. Organization repositories retain refs/tags/nexus/pins/<full-SHA> for maintained commits; network-enabled preparation checks that the ref advertises the selected SHA before changing the checkout. FreeRTOS retains both the official baseline and the organization integration commit. Repository or ref existence does not establish that the current connection can write to it, or that branch or tag protection is enabled; those states require actual readback. Synchronizing upstream must not rewrite production source or published refs.

When an existing checkout migrates from a reviewed official location to a reviewed organization location, preparation first checks the worktree, actual repository root, origin, and allowed old/new commits. Ordinary source edits, untracked dependency files, an unknown origin or an unknown HEAD must stop preparation. A registered old Gitlink is an admissible migration starting point; a normal submodule revision transition must not be misclassified as a user source edit. The tool does not stash, reset, clean or force updates.

For an existing checkout, first select the exact Nexus commit to consume, then run explicit preparation from the repository root. The tool recognizes registered old dependency state according to that selected commit. These commands permit downloads; omit --allow-network for offline verification:

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

The preparation tool first audits the complete source-owned declarations and Gitlinks, then synchronizes and initializes the explicitly selected top-level paths. After each parent module is updated, it audits that parent’s actual declarations and owning Git tree again, then processes the explicitly selected child paths one level at a time. These steps do not perform unscoped recursive downloads; organization-maintained branches declare only dependencies that are selected and reviewed. Update top-level FreeRTOS before synchronizing its nested declarations, so its old .gitmodules cannot write official URLs back. On completion, check each path, Gitlink, actual HEAD, origin and clean state. Missing objects, failed downloads or a provenance mismatch must fail and retain actual execution records; do not substitute --remote or an implicit alternate location. Configuration, builds and commit gates never prepare dependencies through implicit network access.

Rollback uses a normal new commit to restore retrieval policy, Gitlinks, review locks and corresponding example pins together; it does not rewrite old commits, tags or evidence. A fork is not a backup: a Nexus Git bundle does not contain submodule objects. Retain dependency Git objects separately, or keep a verifiable complete source SDK, and actually verify recovery on another host. During a service outage, consume an approved offline package rather than hiding a temporary source change inside a normal build.

Codex weekly dependency process

tools/maintenance/dependency_proposals.py defaults to observing actual Gitlinks, locks, archives and license bytes with zero network reads. It covers exact FreeRTOS, CMSIS, STM32 CMSIS, GD32 import, GoogleTest, ARM-toolchain, development/Python-tool and GitHub Actions pins. Releases needing license review explicitly record required rather than inferring licenses from version names.

.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

Explicit upstream mode queries heads/tags only from the catalogue’s official upstream_url; an organization fork’s fetch_url does not replace the version source. For ordinary dependencies, upstream_revision equals the selected Gitlink. A FreeRTOS URL-migration commit records selected_revision separately from its official upstream_base, avoiding a false report that the organization commit is missing upstream. After an actual official-baseline upgrade, a new organization integration commit must also be prepared and reviewed. The tool invokes git ls-remote without a shell, credential helpers, interaction or global configuration. Each request is limited to 10 seconds, 1 MiB of combined stdout/stderr capture and 8192 refs. It reuses the existing bounded subprocess capture/kill/reap mechanism and performs no HIL admission or device actions. The output directory must be new and free of symlinks; within the source tree, only build directories are allowed. Original streams, argv, actual exit codes, timings and tool/response hashes are retained. Network, timeout, output or format failures remain not_observed. GD32/toolchain/environment entries without Git publication need separate release-source review; successful version observation must not be fabricated. Observing refs neither selects the newest reliable version nor approves an upgrade. Actual weekly workflow execution requires separate GitHub evidence.

Candidate plans use strict JSON: schema_version=1, observed dependency, explicit proposed_revision, public HTTPS source_url without credentials/query, actual nonempty archive identity, declared license expression and notices identities, and optional evidence mapping. Each identity includes absolute path, full sha256 and actual size. Git provenance needs a full 40-character commit, never main/latest. License content needs independent review; declarations are not approval. Independent provenance/license review also checks whether archives match commits and completely contain notices and changes; tools infer none of these facts from arbitrary user-provided notices.

Required gate	Acceptance scope
license_review	Independent Codex review of provenance/archive/commit, all redistributed files and license/notice changes
configuration	All configuration/kernel boundaries, single input closure, schema/epoch and generation consistency
host_models	Complete discovered pinned GoogleTest/GoogleMock execution, tools/CTest and maintained Native sanitizer profiles
cortex_runtime	Current CPU/ISA/FP/MVE/ABI runtimes and maintained MPU/Secure/NS software matrix
board_arm	Three exact Boards × baremetal/FreeRTOS and affected external examples
resource_budgets	Each new ELF’s independent budget, same-fixture before/after costs, RAM domains and reservations
installed_sdk	Clean exact source SDK, version/epoch rejection and real independent consumers
offline_reproduction	Two fresh network-disabled builds in the bound environment with identical ELF/BIN/map bytes
static_analysis	Owned ClangTidy/Cppcheck, formatting/comments, raw failures and explicit vendor-review boundaries

The tool produces proposals only. Missing evidence is not_executed; real file identities become only referenced_unreviewed. Even referenced JSON claiming passed cannot promote qualification, run its commands, modify Gitlinks/locks or create automatic upgrade commits. Existing formal validators independently execute exact upgraded clean sources, full scopes and the same artifacts. Normal staged review, hooks and CI then atomically update source Gitlinks/vendor imports, locks, licensing and external SDK pins.

Without boards, affected electrical behavior, IRQ/DMA timing, low power and long-running load remain physically pending. An upstream request, one model pass or a previous version’s software candidate cannot replace acceptance for this upgrade.