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

1.0.0

Must match the actual CMake project version

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

projection / typed IR

1 / 1

Source format of the strict resolver and actual emitter

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.

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.

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 only heads/tags of public GitHub origins associated with locks. It runs shell-free git ls-remote with credential helpers, interaction and global configuration disabled: at most 10 seconds per request, 1 MiB total stdout/stderr and 8192 refs. Existing bounded subprocess capture/kill/reap is reused without HIL admission or device actions. Output directories must be new and symlink-free; only build directories are allowed within source. Original streams, argv, actual exits, timestamps and tool/response SHAs remain. Network/time/output/format failures are not_observed; GD32/toolchain/environment entries without Git publication need separate release-provenance review and cannot invent successful version observations. Observing refs neither selects a latest reliable version nor approves upgrades. 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.