Add strict RootFS source download cache

CHANGELOG.en.md

@@ -46,6 +46,12 @@ All notable PocketRoot changes are recorded here. Semantic Versioning begins wit
   review; `apk-tools` and `pax-utils` have no remaining candidate-material
   engineering items, six origins still need package-specific material, and
   legal and redistribution gates remain closed.
+- Strict external download-cache input for the RootFS source-review
+  materializer. A cache replaces network transport only: inputs remain
+  size-bounded and symlink/overlap-rejected, with pinned SHA-512 and canonical
+  extracted-aports-tree verification; v2 receipts distinguish network from
+  cache acquisition instead of fabricating a selected URL, and ambiguous
+  legacy v1 bundles must be regenerated through cache mode.
 - arm64 Simulator and unsigned-device final-link gates for the full Experimental graph.
 - Repository iOS 18 native smoke covering 17 preparation, boot, guest, 8 MiB sustained binary-output, stdout/stderr overflow, command, cancellation, recovery, shutdown, and 256 MiB Simulator lifecycle peak-memory checks.
 - A repository-external, unapproved RootFS double-build candidate path for the

CHANGELOG.md

@@ -41,6 +41,10 @@ PocketRoot 的重要变化记录在这里。首个公开版本发布后遵循 Se
   75/75 个候选 payload 已完成 checksum-bound 工程复核，`apk-tools`、
   `pax-utils` 的候选材料工程项关闭，另外 6 个 origin 仍需补逐包材料，法律和
   再分发门禁保持关闭。
+- RootFS source-review materializer 新增严格仓库外下载缓存输入；缓存只替代网络
+  传输，仍逐项限制大小、拒绝 symlink/重叠路径、核对固定 SHA-512，并重新验证
+  解包后的 canonical aports tree；v2 receipt 会明确区分网络与缓存获取，不伪造
+  selected URL，来源含糊的旧 v1 bundle 需通过缓存模式重新生成。
 - 加入完整 Experimental graph 的 arm64 Simulator 与 unsigned device final-link gate。
 - 加入 repository-owned iOS 18 native smoke App 和 runner，覆盖 17 项 prepare、boot、guest、8 MiB 持续二进制输出、stdout/stderr 超限、command、取消、recovery、shutdown 与 256 MiB Simulator 生命周期峰值内存门禁。
 - native smoke 新增仓库外、未授权 RootFS 双构建候选入口：校验候选 provenance、

Compliance/RootFS/v0.3.3/README.md

@@ -104,6 +104,35 @@ ruby Scripts/prepare-rootfs-source-bundle.rb \
   --verify /absolute/new/path/outside-the-repository/rootfs-v0.3.3-source-review
 ```
 
+网络不可用时，可把另一份 source-review 目录或同布局的只读目录作为下载缓存：
+
+When the network is unavailable, another source-review directory or a
+read-only directory with the same cache layout can supply the downloads:
+
+```bash
+ruby Scripts/prepare-rootfs-source-bundle.rb \
+  --download-cache /absolute/existing/rootfs-v0.3.3-source-review \
+  --output /absolute/new/path/outside-the-repository/rootfs-v0.3.3-source-review
+```
+
+缓存布局为 `downloads/aports/<source-origin>.tar.gz` 与
+`distfiles/<source-origin>/<filename>`。缓存只替代网络传输；工具仍拒绝符号链接和
+仓库内/重叠路径，限制每个输入大小，核对固定 SHA-512，并重新校验解包后的规范化
+aports tree 后才原子提升输出。
+
+The cache layout is `downloads/aports/<source-origin>.tar.gz` and
+`distfiles/<source-origin>/<filename>`. It replaces network transport only:
+the tool still rejects symlinks and repository-local or overlapping paths,
+bounds every input, verifies pinned SHA-512 digests, and revalidates each
+canonical extracted aports tree before atomically promoting the output.
+The receipt marks cached acquisition explicitly and records cache-relative
+paths instead of claiming that an upstream URL was contacted; pinned upstream
+origins remain in `SOURCE-ACQUISITION.json`.
+Receipt schema v2 requires that explicit acquisition mode. A legacy v1
+source-review directory can be passed to `--download-cache` to regenerate a
+verifiable v2 bundle, but it is no longer accepted directly by `--verify`
+because its transport provenance is ambiguous.
+
 `--verify` 同时核对所有普通文件摘要、目录集合和符号链接目标。该输出不会被 App、
 Git 或 CI artifact 自动打包或上传。
 

Docs/RootFS.md

@@ -98,6 +98,23 @@ ruby Scripts/prepare-rootfs-source-bundle.rb \
   --verify /absolute/new/path/outside-the-repository/rootfs-v0.3.3-source-review
 ```
 
+已有 source-review 或同布局的仓库外只读缓存可用于离线重建，不降低任何固定校验：
+
+```bash
+ruby Scripts/prepare-rootfs-source-bundle.rb \
+  --download-cache /absolute/existing/rootfs-v0.3.3-source-review \
+  --output /absolute/new/path/outside-the-repository/rootfs-v0.3.3-source-review
+```
+
+缓存必须提供 `downloads/aports/<source-origin>.tar.gz` 和
+`distfiles/<source-origin>/<filename>`。脚本拒绝 symlink、特殊/缺失文件、仓库内
+缓存及输入/输出重叠，逐项限制大小并核对 SHA-512；aports 仍会重新解包并校验规范化
+tree identity。缓存不构成来源批准，也不会改变 receipt 的固定上游来源。
+receipt 会明确标记缓存获取并记录缓存内相对路径，不会伪称访问了某个上游 URL；
+固定上游来源仍保留在 `SOURCE-ACQUISITION.json`。
+receipt schema v2 强制包含该模式。旧 v1 source-review 的传输来源存在歧义，不再
+直接通过 `--verify`；仍可把它传给 `--download-cache`，重新生成可验证的 v2 bundle。
+
 规范化 aports 目录身份覆盖条目类型、路径、普通文件权限位和内容摘要；物化时会保留
 这些权限位，`--verify` 会再次校验。
 

Docs/en/RootFS.md

@@ -73,6 +73,28 @@ ruby Scripts/prepare-rootfs-source-bundle.rb \
   --verify /absolute/new/path/outside-the-repository/rootfs-v0.3.3-source-review
 ```
 
+An existing source-review directory, or a read-only external directory with
+the same layout, can rebuild the bundle offline without weakening any pin:
+
+```bash
+ruby Scripts/prepare-rootfs-source-bundle.rb \
+  --download-cache /absolute/existing/rootfs-v0.3.3-source-review \
+  --output /absolute/new/path/outside-the-repository/rootfs-v0.3.3-source-review
+```
+
+The cache must provide `downloads/aports/<source-origin>.tar.gz` and
+`distfiles/<source-origin>/<filename>`. The script rejects symlinks,
+special or missing files, repository-local caches, and input/output overlap;
+bounds each input; verifies SHA-512; and re-extracts every aports snapshot to
+verify its canonical tree identity. A cache is not source approval and does
+not change the receipt's pinned upstream origins.
+The receipt marks cached acquisition explicitly and records cache-relative
+paths rather than claiming that an upstream URL was contacted; the pinned
+upstream origins remain in `SOURCE-ACQUISITION.json`.
+Receipt schema v2 requires that explicit mode. A legacy v1 source-review
+directory has ambiguous transport provenance and is no longer accepted by
+`--verify`; pass it to `--download-cache` to regenerate a verifiable v2 bundle.
+
 After that source-review directory verifies, extract the 21 pinned
 license/attribution candidates into another directory outside the repository: