feat: harden reproducibility and release validation

Author: yaochao

.github/workflows/README.en.md

@@ -7,6 +7,6 @@ This directory stores the GitHub Actions workflows. It now includes both continu
 ## Current File
 
 - `ci.yml`
-  continuous integration workflow covering tests, build, and `ls` boot verification
+  continuous integration workflow covering tests, build, `ls` boot verification, and a two-build reproducibility check
 - `release.yml`
-  release workflow that rebuilds images from source and uploads them to GitHub Release on a tag push or manual dispatch, with optional `source_ref` support for manual republish runs
+  release workflow that rebuilds images from source, uploads them to GitHub Release, and then reads those published assets back for another boot verification; manual republish runs also support an optional `source_ref`

.github/workflows/README.md

@@ -7,6 +7,6 @@
 ## 当前文件
 
 - `ci.yml`
-  持续集成工作流，覆盖单测、构建和 `ls` 启动验证
+  持续集成工作流，覆盖单测、构建、`ls` 启动验证，以及双次构建可复现性检查
 - `release.yml`
-  发布资产工作流，按 tag 或手动触发，从源码重建镜像并上传到 GitHub Release；手动触发时支持额外指定 `source_ref`
+  发布资产工作流，按 tag 或手动触发，从源码重建镜像并上传到 GitHub Release；上传后还会把发布资产重新拉回并再次启动验证；手动触发时支持额外指定 `source_ref`

.github/workflows/ci.yml

@@ -119,3 +119,26 @@ jobs:
           name: linux-012-macos-ci-artifacts
           path: |
             out/repo-images
+
+  linux-012-reproducibility:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 90
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Run unit tests
+        run: python3 -m unittest discover -s tests -v
+
+      - name: Build twice and compare image digests
+        run: python3 rebuild/driver.py check-reproducible-build
+
+      - name: Upload reproducibility artifacts
+        if: always()
+        uses: actions/upload-artifact@v6
+        with:
+          name: linux-012-reproducibility-artifacts
+          path: |
+            rebuild/out/images
+            rebuild/out/logs

.github/workflows/release.yml

@@ -97,3 +97,6 @@ jobs:
             images/hdc-0.12.img.xz \
             images/manifest.json \
             --clobber
+
+      - name: Verify release readback against published assets
+        run: python3 rebuild/driver.py verify-release-readback

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaochao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,47 @@
+.DEFAULT_GOAL := help
+
+.PHONY: help bootstrap-host build run run-window verify verify-userland check-images fetch-release-images repro-check release-readback
+
+help:
+	@printf '%s\n' \
+		'Available targets:' \
+		'  bootstrap-host      Check Python, QEMU, and Docker on the current host' \
+		'  build               Build Linux 0.12 runtime images from source' \
+		'  run                 Boot QEMU from the committed repo snapshots' \
+		'  run-window          Boot QEMU from the committed repo snapshots in a visible window' \
+		'  verify              Boot Linux 0.12 and verify that ls succeeds' \
+		'  verify-userland     Verify minimal shell built-ins and helper commands' \
+		'  check-images        Verify committed repo snapshots against images/manifest.json' \
+		'  fetch-release-images Restore committed repo snapshots from the tagged GitHub Release' \
+		'  repro-check         Build twice and verify that image outputs are reproducible' \
+		'  release-readback    Re-download release assets and verify they still boot'
+
+bootstrap-host:
+	./scripts/bootstrap-host.sh
+
+build:
+	/usr/bin/python3 rebuild/driver.py build
+
+run:
+	./scripts/run.sh
+
+run-window:
+	./scripts/run-window.sh
+
+verify:
+	./scripts/verify.sh
+
+verify-userland:
+	./scripts/verify-userland.sh
+
+check-images:
+	./scripts/check-images.sh
+
+fetch-release-images:
+	./scripts/fetch-release-images.sh
+
+repro-check:
+	./scripts/check-reproducible-build.sh
+
+release-readback:
+	./scripts/verify-release-readback.sh

README.en.md

@@ -2,6 +2,7 @@
 
 [中文 README](./README.md)
 [Changelog](./CHANGELOG.en.md)
+[Third-Party Notes](./THIRD_PARTY.en.md)
 
 This repository does one specific thing: on a modern host, it builds the two runtime images required to boot Linux 0.12 under QEMU from source and repo-owned manifests, enters the shell, and verifies the result by running `ls`.
 
@@ -34,7 +35,9 @@ This is not a “download a historical image and boot it” repo. It is a “reb
 
 Current formal release: `v1.0.1`
 
-The repository also includes an automated GitHub Actions release workflow: pushing a `v*` tag, or manually dispatching `.github/workflows/release.yml`, rebuilds the images from source, runs a real boot verification, and uploads `bootimage-0.12-hd`, `hdc-0.12.img.xz`, and `manifest.json` to the matching GitHub Release. Manual dispatch also accepts an optional `source_ref`, which is useful when republishing an existing release from the current `main` branch or another ref.
+The root [LICENSE](./LICENSE) covers repo-authored scripts, patches, userland sources, tests, and documentation only. The bundled upstream Linux 0.12 source archive and the generated runtime artifacts have their own upstream-related licensing boundary, documented in [THIRD_PARTY.en.md](./THIRD_PARTY.en.md).
+
+The repository also includes an automated GitHub Actions release workflow: pushing a `v*` tag, or manually dispatching `.github/workflows/release.yml`, rebuilds the images from source, runs a real boot verification, and uploads `bootimage-0.12-hd`, `hdc-0.12.img.xz`, and `manifest.json` to the matching GitHub Release. After upload, the workflow downloads that published asset set back from the release URL and boots it again as a readback validation. Manual dispatch also accepts an optional `source_ref`, which is useful when republishing an existing release from the current `main` branch or another ref.
 
 ## Supported Hosts
 
@@ -97,6 +100,12 @@ Windows CMD:
 scripts\bootstrap-host.cmd
 ```
 
+If you prefer a single top-level entrypoint on macOS / Ubuntu, you can also run:
+
+```sh
+make bootstrap-host
+```
+
 ### 3. Start QEMU From The Bundled Images
 
 If you want to verify the committed snapshots before launch, run:
@@ -281,8 +290,49 @@ Windows CMD:
 scripts\verify-userland.cmd
 ```
 
+If you also want to verify that two full source builds produce byte-identical image outputs, run:
+
+macOS / Ubuntu:
+
+```sh
+./scripts/check-reproducible-build.sh
+```
+
+or use:
+
+```sh
+make repro-check
+```
+
+If you want to confirm that the assets published on GitHub Release still boot after being downloaded back into a clean repo snapshot, run:
+
+macOS / Ubuntu:
+
+```sh
+./scripts/verify-release-readback.sh
+```
+
+or use:
+
+```sh
+make release-readback
+```
+
 ## Common Commands
 
+On macOS / Ubuntu you can also prefer the top-level `Makefile`:
+
+```sh
+make help
+make build
+make run
+make verify
+make check-images
+make fetch-release-images
+make repro-check
+make release-readback
+```
+
 Start QEMU from the committed repo images:
 
 ```sh
@@ -301,6 +351,18 @@ Fetch the committed repo image snapshots from the GitHub Release:
 python3 rebuild/driver.py fetch-release-images
 ```
 
+Run two full source builds and compare the SHA-256 digests of `bootimage-0.12-hd`, `hdc-0.12.img`, and `hdc-0.12.img.xz`:
+
+```sh
+python3 rebuild/driver.py check-reproducible-build
+```
+
+Delete local snapshots, read them back from the release declared in `images/manifest.json`, and boot-verify them:
+
+```sh
+python3 rebuild/driver.py verify-release-readback
+```
+
 Start QEMU from the committed repo images with a visible window:
 
 ```sh
@@ -321,7 +383,7 @@ python3 rebuild/driver.py build-and-run-repo-images-window
 
 ## Continuous Integration
 
-The repository now includes the GitHub Actions workflow [ci.yml](/Users/infoxmed-01/ai/workspace/linux-012/.github/workflows/ci.yml). On pushes to `main` and pull requests targeting `main`, it runs two kinds of jobs:
+The repository now includes the GitHub Actions workflow [ci.yml](/Users/infoxmed-01/ai/workspace/linux-012/.github/workflows/ci.yml). On pushes to `main` and pull requests targeting `main`, it runs four kinds of jobs:
 
 - full `ubuntu-22.04` pipeline:
   `python3 -m unittest discover -s tests -v`
@@ -341,8 +403,11 @@ The repository now includes the GitHub Actions workflow [ci.yml](/Users/infoxmed
   automatic unpack of the repo-managed disk snapshot
   `python3 tools/qemu_driver.py verify --dry-run`
   `python3 tools/qemu_driver.py run-window --dry-run`
+- `ubuntu-22.04` reproducibility check:
+  `python3 -m unittest discover -s tests -v`
+  `python3 rebuild/driver.py check-reproducible-build`
 
-On failure it uploads Ubuntu artifacts from `out/verify` and `rebuild/out/logs`, plus the Windows and macOS smoke artifacts from `out/repo-images`.
+On failure it uploads Ubuntu boot-verification artifacts from `out/verify` and `rebuild/out/logs`, reproducibility artifacts from `rebuild/out/images` and `rebuild/out/logs`, plus the Windows and macOS smoke artifacts from `out/repo-images`.
 
 Build the images explicitly:
 
@@ -443,6 +508,8 @@ The current standalone userland binaries are:
 - The boot image is shorter than 1.44MB, so the driver pads it into a full floppy image before launch
 - `scripts/check-images.*` verifies the repo-managed snapshots against `images/manifest.json`
 - `scripts/fetch-release-images.*` re-downloads the repo-managed snapshots from the GitHub Release referenced by `images/manifest.json`
+- `scripts/check-reproducible-build.*` runs two full builds and compares image digests to verify reproducibility
+- `scripts/verify-release-readback.*` reads the current snapshots back from the release URL and boot-verifies them
 - `scripts/run.*` uses the committed snapshots in `images/` by default and unpacks the hard disk image into `out/repo-images/`
 - `scripts/run-window.*` uses the committed snapshots in `images/`, unpacks the hard disk image into `out/repo-images/`, and opens a visible QEMU window
 - `scripts/build-and-run.*` rebuilds from source and refreshes `images/`
@@ -472,3 +539,4 @@ This project does not try to:
 
 - `vendor/src/linux-0.12.tar.gz` comes from the kernel.org historic Linux 0.12 source archive
 - Runtime images are not downloaded from third parties; they are built locally from repo-owned sources, patches, and manifests
+- The licensing and provenance boundary is documented in [THIRD_PARTY.en.md](./THIRD_PARTY.en.md)

README.md

@@ -2,6 +2,7 @@
 
 [English README](./README.en.md)
 [变更日志](./CHANGELOG.md)
+[第三方来源与许可](./THIRD_PARTY.md)
 
 这个仓库的目标很直接：在现代宿主机上，从源码和仓库内清单出发，构建出 Linux 0.12 运行所需的两张 QEMU 镜像，启动进入 shell，并成功执行 `ls`。
 
@@ -34,7 +35,9 @@
 
 当前正式发布版本：`v1.0.1`
 
-仓库还带有自动发布资产的 GitHub Actions 工作流：推送 `v*` tag，或者手动触发 `.github/workflows/release.yml`，都会从源码重建镜像、执行一次真实启动验证，并把 `bootimage-0.12-hd`、`hdc-0.12.img.xz`、`manifest.json` 上传到对应的 GitHub Release。手动触发时还可以额外指定 `source_ref`，用于从当前 `main` 或其他 ref 重新发布某个已有 release 的资产。
+根目录 [LICENSE](./LICENSE) 只覆盖仓库自行编写的脚本、补丁、用户态源码、测试和文档。随仓库保留的上游 Linux 0.12 源码归档，以及由它参与生成的镜像产物，边界说明见 [THIRD_PARTY.md](./THIRD_PARTY.md)。
+
+仓库还带有自动发布资产的 GitHub Actions 工作流：推送 `v*` tag，或者手动触发 `.github/workflows/release.yml`，都会从源码重建镜像、执行一次真实启动验证，并把 `bootimage-0.12-hd`、`hdc-0.12.img.xz`、`manifest.json` 上传到对应的 GitHub Release。上传完成后，工作流还会按 release 链接重新拉回这组资产，再启动一次 QEMU 做回读验证。手动触发时还可以额外指定 `source_ref`，用于从当前 `main` 或其他 ref 重新发布某个已有 release 的资产。
 
 ## 支持的宿主机
 
@@ -97,6 +100,12 @@ Windows CMD：
 scripts\bootstrap-host.cmd
 ```
 
+如果你在 macOS / Ubuntu 上更喜欢统一的顶层入口，也可以直接运行：
+
+```sh
+make bootstrap-host
+```
+
 ### 3. 直接启动仓库内置镜像
 
 如果你想先检查仓库快照是否完整，可以运行：
@@ -281,8 +290,49 @@ Windows CMD：
 scripts\verify-userland.cmd
 ```
 
+如果你还想验证“连续两次源码构建产物完全一致”，可以运行：
+
+macOS / Ubuntu：
+
+```sh
+./scripts/check-reproducible-build.sh
+```
+
+或者直接使用：
+
+```sh
+make repro-check
+```
+
+如果你想验证 GitHub Release 上发布出去的快照重新拉回后仍然能启动并执行 `ls`，可以运行：
+
+macOS / Ubuntu：
+
+```sh
+./scripts/verify-release-readback.sh
+```
+
+或者直接使用：
+
+```sh
+make release-readback
+```
+
 ## 常用命令
 
+在 macOS / Ubuntu 上，也可以优先使用顶层 `Makefile`：
+
+```sh
+make help
+make build
+make run
+make verify
+make check-images
+make fetch-release-images
+make repro-check
+make release-readback
+```
+
 直接启动仓库内置镜像：
 
 ```sh
@@ -301,6 +351,18 @@ python3 rebuild/driver.py check-repo-images
 python3 rebuild/driver.py fetch-release-images
 ```
 
+连续做两次源码构建并比较 `bootimage-0.12-hd`、`hdc-0.12.img`、`hdc-0.12.img.xz` 的 SHA-256：
+
+```sh
+python3 rebuild/driver.py check-reproducible-build
+```
+
+删除本地快照、按 `images/manifest.json` 从 release 回读，再启动验证：
+
+```sh
+python3 rebuild/driver.py verify-release-readback
+```
+
 直接弹出可见的 QEMU 窗口：
 
 ```sh
@@ -321,7 +383,7 @@ python3 rebuild/driver.py build-and-run-repo-images-window
 
 ## 持续集成
 
-仓库现在包含 GitHub Actions 工作流 [ci.yml](/Users/infoxmed-01/ai/workspace/linux-012/.github/workflows/ci.yml)。它会在推送到 `main` 或对 `main` 发起 Pull Request 时执行两类任务：
+仓库现在包含 GitHub Actions 工作流 [ci.yml](/Users/infoxmed-01/ai/workspace/linux-012/.github/workflows/ci.yml)。它会在推送到 `main` 或对 `main` 发起 Pull Request 时执行四类任务：
 
 - `ubuntu-22.04` 完整链路：
   `python3 -m unittest discover -s tests -v`
@@ -341,8 +403,11 @@ python3 rebuild/driver.py build-and-run-repo-images-window
   基于仓库快照自动解包系统镜像
   `python3 tools/qemu_driver.py verify --dry-run`
   `python3 tools/qemu_driver.py run-window --dry-run`
+- `ubuntu-22.04` 可复现性检查：
+  `python3 -m unittest discover -s tests -v`
+  `python3 rebuild/driver.py check-reproducible-build`
 
-失败时会上传 Ubuntu 的 `out/verify`、`rebuild/out/logs`，以及 Windows 和 macOS 的 `out/repo-images` 作为排查产物。
+失败时会上传 Ubuntu 启动验证产物 `out/verify`、`rebuild/out/logs`，可复现性检查产物 `rebuild/out/images`、`rebuild/out/logs`，以及 Windows 和 macOS 的 `out/repo-images` 作为排查产物。
 
 显式构建镜像：
 
@@ -443,6 +508,8 @@ python3 rebuild/driver.py run
 - 启动镜像本身不足 1.44MB，驱动会在启动前补齐成标准软盘镜像
 - `scripts/check-images.*` 会按 `images/manifest.json` 校验仓库快照
 - `scripts/fetch-release-images.*` 会从 `images/manifest.json` 指向的 GitHub Release 重新拉取仓库快照
+- `scripts/check-reproducible-build.*` 会连续构建两次并比较镜像摘要，验证构建可复现性
+- `scripts/verify-release-readback.*` 会从 release 回读当前快照，再启动 QEMU 验证
 - `scripts/run.*` 默认直接使用仓库里的 `images/` 快照，并在 `out/repo-images/` 里自动解包系统镜像
 - `scripts/run-window.*` 默认直接使用仓库里的 `images/` 快照，并在 `out/repo-images/` 里自动解包系统镜像后弹出可见的 QEMU 窗口
 - `scripts/build-and-run.*` 会重编源码并刷新 `images/`
@@ -472,3 +539,4 @@ python3 rebuild/driver.py run
 
 - `vendor/src/linux-0.12.tar.gz` 来自 kernel.org 的 Linux 0.12 历史源码归档
 - 运行镜像不来自第三方下载，而是由仓库内源码、补丁和清单在本地构建生成
+- 许可边界、第三方来源和生成产物注意事项见 [THIRD_PARTY.md](./THIRD_PARTY.md)