From cc303875cfb314af4517384d4877ee2eddbc64e8 Mon Sep 17 00:00:00 2001 From: Dan Calavrezo <195309321+dcalavrezo-qorix@users.noreply.github.com> Date: Tue, 20 Jan 2026 16:38:19 +0200 Subject: [PATCH 1/5] dr: execution contract prepared an execution contract draft Signed-off-by: Dan Calavrezo <195309321+dcalavrezo-qorix@users.noreply.github.com> --- .../DR-001-infra-extension.md | 222 ++++++++++++++++++ 1 file changed, 222 insertions(+) create mode 100644 docs/design_decisions/DR-001-infra-extension.md diff --git a/docs/design_decisions/DR-001-infra-extension.md b/docs/design_decisions/DR-001-infra-extension.md new file mode 100644 index 00000000000..7c880b0ca7c --- /dev/null +++ b/docs/design_decisions/DR-001-infra-extension.md @@ -0,0 +1,222 @@ + + + +# DR-001-Infra-Extension: S-CORE Build Execution Contract + + +* **Date:** 2026-01-20 + +```{dec_rec} S-CORE Build Execution Contract +:id: dec_rec__infra__execution_contract +:status: accepted +:context: Infrastructure +:decision: Adopt a layered execution contract + +``` + +--- + +## Purpose + +This document defines the execution contract for S-CORE builds across developer machines +and CI infrastructure. +Its goal is to ensure **long-term reproducibility (≥10 years)**, **traceability** and +**practical hermeticity**, despite changes in underlying infrastructure such as +GitHub-hosted runners. + +The contract is intentionally **layered**, because different parts of the system control +different capabilities and failure modes. + +--- + +## Core Requirements + +### R1 — Long-Term Reproducibility +S-CORE builds must be reproducible for **at least 10 years** after creation, given: +- the source revision +- archived execution context +- archived toolchains +- recorded build metadata + +This must remain possible even if: +- GitHub runner images change or are retired +- upstream toolchains are no longer available +- external services are unavailable + +--- + +### R2 — Traceability +For every build artifact, it must be possible to determine **exactly**: +- which sources were used +- which toolchains and tool versions were used +- which Bazel version and flags were used +- which execution context (container image) was used +- which host baseline constraints applied + +This information must be recorded in a **build manifest** and stored alongside the build +outputs. + +--- + +### R3 — Hermeticity (Practical) +Build actions must not depend on **undeclared inputs**. + +In practice: +- Tools affecting build outputs must either be: + - managed by Bazel, or + - explicitly injected as Bazel action inputs, or + - reflected in cache partitioning +- Reliance on host state must be minimized and documented where unavoidable. + +Perfect hermeticity is not required, but **undeclared variability is not acceptable**. + +--- + +## Three-Layer Execution Contract + +### Layer 1 — Host Platform Contract + +This layer defines the **non-virtualized constraints** imposed by the machine running +the build. + +#### Scope +- GitHub-hosted runners +- self-hosted runners (VM or bare metal) +- kernel-level features shared with containers + +#### Responsibilities +- Linux kernel version and configuration +- Security mechanisms (AppArmor / LSM) +- Filesystems, networking, namespaces +- Support for: + - Bazel `linux-sandbox` + - QEMU / `binfmt` + - privileged operations where required + +#### Requirements +- Linux host OS (Ubuntu LTS for reference integration) +- Kernel must support: + - unprivileged user namespaces + - mount operations required by Bazel sandboxing +- Host security policies must not block Bazel `linux-sandbox` unless explicitly documented + +#### Known Constraints +- Ubuntu 24.04+ AppArmor may block Bazel sandbox mount operations +- Containers **cannot** mitigate host-kernel restrictions + +#### Policy +- A **Reference Integration Host Baseline** must be defined (e.g. Ubuntu 22.04). +- Deviations (e.g. privileged runners, sandbox disabled) must be explicit and isolated. + +--- + +### Layer 2 — Execution Context Contract (Devcontainer) + +This layer defines the **default user-space environment** in which builds are executed. + +#### Purpose +- Provide consistent runtime ABI (`glibc`, `libstdc++`) +- Ensure tool binaries (e.g. rustc) can execute reliably +- Eliminate “works on my machine” discrepancies +- Enable local reproduction of CI builds + +#### Definition +- A **versioned devcontainer image** is the default execution context. +- The container image must be: + - built from a known OS baseline (Ubuntu LTS) + - referenced by immutable digest + - archived for long-term reproducibility + +#### Responsibilities +- User-space runtime libraries +- Bootstrap tooling (git, bash, coreutils, python, etc.) +- Bazel entrypoint (preferably Bazelisk) +- Development UX tooling (optional) + +#### Non-Goals +- The devcontainer must **not silently override** repository-declared Bazel versions. +- The devcontainer must **not be the only place** where critical tool versions are defined. + +#### Policy +- The devcontainer defines the **default** environment, not the **only** supported one. +- Builds should still be possible on compatible bare-metal hosts. + +--- + +### Layer 3 — Bazel Contract + +This layer defines **what Bazel controls and guarantees**. + +#### Bazel Versioning +- Each repository must contain `.bazelversion`. +- S-CORE uses a **single Bazel version** across repositories. +- CI enforces version consistency. + +#### Toolchains and Tools +- Toolchains (e.g. Rust/Ferrocene, C/C++) must be: + - versioned + - immutable + - built against a documented baseline +- Tools affecting outputs must be known to Bazel or reflected in action inputs. + +#### Hermeticity Guarantees +- Bazel sandboxing provides reproducibility **given runnable tools**. +- Bazel does **not** virtualize: + - kernel + - `glibc` + - host security configuration + +These constraints must be handled in Layer 1 and Layer 2. + +--- + +## Minimum Supported Baselines + +### OS and Runtime Baseline +- Minimum supported baseline: **Ubuntu 20.04 LTS** (subject to revision) +- Toolchains must be built against this baseline +- Older environments are **not supported** + +### Rationale +We explicitly do **not** support all historical `glibc` or kernel versions. +Portability is achieved by choosing and documenting a baseline, not by unlimited +backward compatibility. + +--- + +## Build Provenance and Archiving + +Each CI build must produce and archive: +- build manifest (metadata) +- container image digest +- toolchain identifiers +- source revision(s) + +These artifacts form the basis for: +- long-term reproducibility +- forensic analysis +- compliance and auditing + +--- + +## Summary + +- **Layer 1** defines what the host *must* provide. +- **Layer 2** defines the default execution environment. +- **Layer 3** defines how Bazel achieves reproducibility and caching. +- Reproducibility, traceability, and hermeticity are enforced through +**explicit contracts**, not assumptions. + +This separation allows S-CORE to scale infrastructure, evolve toolchains, and still +reproduce builds years into the future. From d8505443571c72e377d9d440da6d48884e27f80d Mon Sep 17 00:00:00 2001 From: Dan Calavrezo <195309321+dcalavrezo-qorix@users.noreply.github.com> Date: Wed, 21 Jan 2026 13:39:52 +0200 Subject: [PATCH 2/5] Update docs/design_decisions/DR-001-infra-extension.md Co-authored-by: Alexander Lanin Signed-off-by: Dan Calavrezo <195309321+dcalavrezo-qorix@users.noreply.github.com> --- docs/design_decisions/DR-001-infra-extension.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/design_decisions/DR-001-infra-extension.md b/docs/design_decisions/DR-001-infra-extension.md index 7c880b0ca7c..b4c0670bc04 100644 --- a/docs/design_decisions/DR-001-infra-extension.md +++ b/docs/design_decisions/DR-001-infra-extension.md @@ -35,6 +35,8 @@ Its goal is to ensure **long-term reproducibility (≥10 years)**, **traceabilit **practical hermeticity**, despite changes in underlying infrastructure such as GitHub-hosted runners. +It builds on [DR-001], which was concerned about the same topics, but was focused on tools only. This adds details where the original description was too fuzzy. + The contract is intentionally **layered**, because different parts of the system control different capabilities and failure modes. From 0c6a3b62f582dd1b1e0bda912632391092e06601 Mon Sep 17 00:00:00 2001 From: Dan Calavrezo <195309321+dcalavrezo-qorix@users.noreply.github.com> Date: Thu, 22 Jan 2026 14:07:21 +0200 Subject: [PATCH 3/5] Update docs/design_decisions/DR-001-infra-extension.md Co-authored-by: Alexander Lanin Signed-off-by: Dan Calavrezo <195309321+dcalavrezo-qorix@users.noreply.github.com> --- docs/design_decisions/DR-001-infra-extension.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design_decisions/DR-001-infra-extension.md b/docs/design_decisions/DR-001-infra-extension.md index b4c0670bc04..fa2db479551 100644 --- a/docs/design_decisions/DR-001-infra-extension.md +++ b/docs/design_decisions/DR-001-infra-extension.md @@ -193,7 +193,7 @@ These constraints must be handled in Layer 1 and Layer 2. ### Rationale We explicitly do **not** support all historical `glibc` or kernel versions. Portability is achieved by choosing and documenting a baseline, not by unlimited -backward compatibility. +backward compatibility. Layer 2 can easily be virtualized as needed, for future reproducibility. --- From bff99a98c57aeb85bd8f49ec45bf358ffab2311d Mon Sep 17 00:00:00 2001 From: Dan Calavrezo <195309321+dcalavrezo-qorix@users.noreply.github.com> Date: Thu, 22 Jan 2026 14:58:23 +0200 Subject: [PATCH 4/5] Update docs/design_decisions/DR-001-infra-extension.md Co-authored-by: lurtz <727209+lurtz@users.noreply.github.com> Signed-off-by: Dan Calavrezo <195309321+dcalavrezo-qorix@users.noreply.github.com> --- docs/design_decisions/DR-001-infra-extension.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/design_decisions/DR-001-infra-extension.md b/docs/design_decisions/DR-001-infra-extension.md index fa2db479551..cc8a869e903 100644 --- a/docs/design_decisions/DR-001-infra-extension.md +++ b/docs/design_decisions/DR-001-infra-extension.md @@ -134,11 +134,18 @@ This layer defines the **default user-space environment** in which builds are ex - Enable local reproduction of CI builds #### Definition -- A **versioned devcontainer image** is the default execution context. +- A **versioned devcontainer image** is the default execution context for CI and local builds. - The container image must be: - - built from a known OS baseline (Ubuntu LTS) - - referenced by immutable digest - - archived for long-term reproducibility + - built from a **defined Ubuntu LTS baseline** + - compatible with common developer tooling (e.g. by following the [specification](https://containers.dev/)) + - referenced by an **immutable image digest** + - archived for **long-term reproducibility** + +#### Baseline Preservation and Reproducibility +- Once a devcontainer image is used in CI, its image digest becomes part of the build provenance +- All such images must be archived and retrievable for **at least 10 years** +- Reproducing historical builds may rely on legacy container runtimes or CLI-only execution, + and does not require continued IDE support #### Responsibilities - User-space runtime libraries From 0e5f9d7b1312b6e9e67674a3e5da9aef02686a4a Mon Sep 17 00:00:00 2001 From: Dan Calavrezo <195309321+dcalavrezo-qorix@users.noreply.github.com> Date: Thu, 22 Jan 2026 15:04:07 +0200 Subject: [PATCH 5/5] contract: solved some comments solved comments from PRs Signed-off-by: Dan Calavrezo <195309321+dcalavrezo-qorix@users.noreply.github.com> --- docs/design_decisions/DR-001-infra-extension.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/design_decisions/DR-001-infra-extension.md b/docs/design_decisions/DR-001-infra-extension.md index cc8a869e903..348b09b1270 100644 --- a/docs/design_decisions/DR-001-infra-extension.md +++ b/docs/design_decisions/DR-001-infra-extension.md @@ -12,7 +12,7 @@ SPDX-License-Identifier: Apache-2.0 --> -# DR-001-Infra-Extension: S-CORE Build Execution Contract +# DR-001-B-Infra-Extension: S-CORE Build Execution Contract * **Date:** 2026-01-20 @@ -168,7 +168,7 @@ This layer defines the **default user-space environment** in which builds are ex This layer defines **what Bazel controls and guarantees**. #### Bazel Versioning -- Each repository must contain `.bazelversion`. +- Each relevant repository must contain `.bazelversion`. - S-CORE uses a **single Bazel version** across repositories. - CI enforces version consistency.