升级 libreFS HFS v3 Preview 与 Protected/Private 发布契约

.env.example

@@ -1,4 +1,4 @@
-# LibreFS HFS v2 local configuration ledger.
+# LibreFS HFS v3 local configuration ledger.
 # Copy to .env only on a protected local machine. This file is never loaded by
 # the container and is not uploaded to Hugging Face. Keep all real values out
 # of Git, logs, screenshots, and generated Space bundles.

.github/workflows/deploy-hf-space.yml

@@ -27,8 +27,8 @@ concurrency:
 
 env:
   FORMAL_SPACE: BlueSkyXN/libreFS-HFS
-  HF_CLI_VERSION: "1.5.0"
-  HF_CLI_CLICK_VERSION: "8.3.3"
+  HF_CLI_VERSION: "1.25.1"
+  HF_CLI_CLICK_VERSION: "8.4.2"
 
 jobs:
   deploy:
@@ -55,6 +55,8 @@ jobs:
           python3 -m pip install --disable-pip-version-check \
             "huggingface_hub==${HF_CLI_VERSION}" \
             "click==${HF_CLI_CLICK_VERSION}"
+          python3 -m huggingface_hub.cli.hf version
+          python3 -m huggingface_hub.cli.hf repos settings --help | grep -- --protected
           export SPACE_ID LIBREFS_COMMIT
           HFS_TARGET="${{ inputs.target }}" python3 - <<'PY'
           import os

AGENTS.md

@@ -21,9 +21,9 @@
 | `README.md` | HF Space card、front matter、公开 endpoint、状态摘要和文档入口 | No | 修改 `sdk`、`app_port`、license、endpoint、能力状态、health check 或文档索引时 |
 | `LICENSE` | 仓库许可证，必须对齐 upstream libreFS AGPL-3.0 | No | 修改 license metadata、合规说明或合并远端 license 变化时 |
 | `Dockerfile` | Ubuntu builder/runtime、Go 下载、pinned upstream source build、runtime packages、healthcheck | No | 修改 base image、build args、`LIBREFS_COMMIT`、UID/GID、复制路径或 `HEALTHCHECK` 时 |
-| `hfs-dev.toml` | HFS development alignment manifest，声明 Pattern A、bundle-only build、Space root 和 release pin surface | No | 修改 HFS 分类、runtime 获取模式、required files、release hardening backlog 或 pin surface 时 |
+| `hfs-dev.toml` | HFS v3.0 closed-schema deployment manifest；仅登记项目、Space、lane、visibility、value source 和 Settings key names | No | 修改 HFS 分类、Space、Settings key names、value source 或 deployment lane 时 |
 | `hfs/` | Runtime glue：container entrypoint、Nginx、ops/admin Python services | Yes | 修改启动流程、进程监管、路由、鉴权、control plane、复制路径或容器写入路径前 |
-| `docs/` | 架构、配置、部署、运维、故障排查、契约对照和源码逐文件说明 | Yes | 修改任何文档、能力状态、endpoint、生产快照、HF Variables/Secrets/Volume 表述前 |
+| `docs/` | 架构、配置、部署、运维、故障排查、契约对照和源码逐文件说明 | Yes | 修改任何文档、能力状态、endpoint、canonical preview 快照、HF Variables/Secrets/Volume 表述前 |
 | `scripts/` | 本地/远端契约验证和 credentialed S3 smoke 工具 | Yes | 修改 validation、smoke、SigV4、清理逻辑、远端验收或脚本参数前 |
 | `.dockerignore` | Docker build context 过滤，避免 `.env*`、`local/`、临时文件进入远端 build | No | 修改 build context 或本地材料忽略规则时 |
 | `.gitattributes` | Hugging Face/Git 展示和文件类型规则 | No | 修改 HF 文件类型、LFS 或展示规则时 |
@@ -90,7 +90,7 @@ Mutating HF commands require explicit live-operation authorization: `hf spaces s
 - Hugging Face Space 外部只暴露 `7860`。`9000`、`9001`、`8081`、`8082` 都是容器内部端口，不要写成外部直连端口。
 - S3 client 应使用 path-style addressing；HF Space 子域名下不要推荐 virtual-hosted bucket URL。
 - 避免建议或创建名为 `console`、`minio`、`_ops`、`_admin` 的公开 bucket，因为这些路径与保留路由冲突。
-- 区分代码默认值和当前生产配置。`ADMIN_ENABLED` 代码默认必须是 `false`；当前线上状态必须用 HF Variables 或 `docs/contract-alignment.md` 的最新回读入口确认。
+- 区分代码默认值和当前 canonical preview 配置。`ADMIN_ENABLED` 代码默认必须是 `false`；当前线上状态必须用 HF Variables 或 `docs/contract-alignment.md` 的最新回读入口确认。
 
 ## Runtime and control-plane invariants
 
@@ -153,7 +153,7 @@ Mutating HF commands require explicit live-operation authorization: `hf spaces s
 1. README front matter 必须保留 `sdk: docker`、`app_port: 7860`、`license: agpl-3.0`。
 2. Dockerfile 必须保持 Ubuntu builder/runtime、bundle-only source build、runtime package 最小集合、`EXPOSE 7860` 和 healthcheck。
 3. `LICENSE` 文件头必须是 `GNU AFFERO GENERAL PUBLIC LICENSE`。
-4. `hfs-dev.toml` 必须保持 Pattern A、`runtime_mode = "bundle-only-build"`、repo-root Space root 和 release pin surface。
+4. `hfs-dev.toml` 必须通过 v3.0 closed-schema checker；Pattern A、bundle-only build、repo-root Space root 和 release pin surface 由 Dockerfile、runtime glue、scripts 和 docs 分别维护，不再塞进 manifest 根字段。
 5. 推送到 HF 后才做 Space API/logs/health/live smoke 复核。
 
 ## Notes for future agents

README.md

@@ -19,7 +19,7 @@ LibreFS HFS 是一个面向 Hugging Face Docker Space 的 libreFS 部署包装
 - Docker build 阶段安装 Go，并从 `https://github.com/libreFS/libreFS.git` 拉取源码编译。
 - Runtime 阶段仍然使用 `ubuntu:24.04`。
 - 不使用 libreFS 官方 Docker image。
-- 仓库根目录同时作为 Hugging Face Space root 和 GitHub 维护 root；`hfs-dev.toml` 声明 HFS v2 Pattern A / `port` / `source` 关系：生产版本始终由 `LIBREFS_COMMIT` 的上游 commit 固定，多服务 runtime glue 集中在 `hfs/`。
+- 仓库根目录同时作为 Hugging Face Space root 和 GitHub 维护 root；`hfs-dev.toml` 声明 HFS v3.0 `preview` / `primary` / Pattern A / `port` / `source` 关系：可复现 wrapper 始终由 `LIBREFS_COMMIT` 的上游 commit 固定，多服务 runtime glue 集中在 `hfs/`。
 - 标准交付只上传由 `scripts/export-space-bundle.sh` 从干净、不可变 Git commit 导出的最小 wrapper；bundle 自带 `BUILD_SOURCE.json` 和 `SHA256SUMS`，同时绑定 wrapper SHA 与实际 libreFS source SHA，不含 libreFS 产品源码、`.env*`、`local/`、缓存、生成数据或凭证。
 - 使用 Nginx 把 libreFS 的 S3 API 和 Web Console 合并到 Hugging Face Space 对外暴露的单端口 `7860`。
 
@@ -84,7 +84,12 @@ Hugging Face Docker Space 只对外暴露一个 app port。本项目用 Nginx 
 | Variable | `ADMIN_ENABLED` | `false` | 是否开启 `/_admin/`；默认保持关闭。 |
 | Variable | `CONTROL_PLANE_DEFAULT_LANG` | `en` | `/_ops/` 和 `/_admin/` JSON 文案默认语言；支持 `en`、`zh-CN`。 |
 
-## 当前生产配置快照
+## 当前 canonical preview 配置快照
+
+日常 Preview 变更允许直接更新 canonical Space；`hfs-dev.candidate.toml` 只用于高风险变更
+的可选隔离验证，不是常规前置门禁。canonical Secret 必须先存在于 manifest 声明的本地
+明文 `.env`；candidate 使用独立的 `local/hfs-targets/candidate.env`。这些文件保持 Git
+ignored，HF Secret 只能作为部署副本。
 
 最近回读时间：2026-06-03。实时状态以命令重新查询为准。
 
@@ -187,7 +192,7 @@ https://blueskyxn-librefs-hfs.hf.space/<bucket>/<object>
 ## 已知边界
 
 - 当前 `hf spaces volumes list` 显示 `/data` 已挂载 Hugging Face Storage Bucket；如果后续移除挂载，上传对象可能在 Space 重启、重建、迁移或停止后丢失。
-- 当前生产环境已显式开启 `/_admin/`。如果需要恢复默认安全姿态，应把 HF Variable `ADMIN_ENABLED` 改回 `false` 或移除。
+- 当前 canonical preview Space 已显式开启 `/_admin/`。如果需要恢复默认安全姿态，应把 HF Variable `ADMIN_ENABLED` 改回 `false` 或移除。
 - 当前 `cpu-basic` 硬件适合功能测试和轻量使用，不适合高吞吐对象存储。
 - 未签名浏览器直接访问根路径 `/` 可能返回 S3 XML error，这是正常现象；签名 S3 请求和配置了 policy 的对象直链才是预期访问方式。
 - 本仓库 license 使用 AGPL-3.0，因为 libreFS 本身是 AGPL-3.0。

docs/AGENTS.md

@@ -2,11 +2,11 @@
 
 `docs/` is the public documentation and operational fact source for LibreFS HFS.
 Read this card before editing live state, endpoints, Secret/Variable names, ops/admin, or persistence wording.
-Start with `docs/contract-alignment.md` for runtime behavior or production snapshots.
+Start with `docs/contract-alignment.md` for runtime behavior or canonical preview snapshots.
 
 ## Local invariants
 
-- Separate code defaults from production config; read back live state before calling it current.
+- Separate code defaults from canonical preview config; read back live state before calling it current.
 - Document Secret keys and presence only; never write token, password, access-key, or private URL values.
 - Health checks prove route/process availability only, not S3 writes, policy, public reads, or persistence.
 - `/data` Volume attached is not persistence validation; require upload, restart, read, rebuild, and read again.
@@ -15,7 +15,7 @@ Start with `docs/contract-alignment.md` for runtime behavior or production snaps
 
 ## Update order
 
-- Runtime contract or production snapshot: update `docs/contract-alignment.md` first, then README and affected docs.
+- Runtime contract or canonical preview snapshot: update `docs/contract-alignment.md` first, then README and affected docs.
 - Endpoint, Console URL, S3 URL, ops/admin route, login, or token transport: check README plus `configuration.md`, `operations.md`, `architecture.md`, and `source-walkthrough.md`.
 - `troubleshooting.md` should cover real or high-probability failures with evidence, not speculative catalogs.
 

docs/README.md

@@ -44,7 +44,7 @@ https://blueskyxn-librefs-hfs.hf.space/console/
 
 ## 本地轻量验证
 
-不安装项目依赖、不本地编译 libreFS 时，可以先运行仓库契约检查。它同时检查 HFS v2 source-lane manifest、local ledger ignore 边界、allowlisted source bundle fixture、provenance 和 manual deployment workflow：
+不安装项目依赖、不本地编译 libreFS 时，可以先运行仓库契约检查。它同时检查 HFS v3.0 source-lane manifest、local ledger ignore 边界、allowlisted source bundle fixture、provenance 和 manual deployment workflow：
 
 ```bash
 scripts/validate-contract.sh

docs/architecture.md

@@ -7,7 +7,7 @@ LibreFS HFS 是 libreFS 的 Hugging Face Docker Space 部署包装层。包装
 
 本项目用 Nginx 监听 `7860`，把外部单端口流量分发到 S3 API、Web Console、只读 ops-service 和默认关闭的 admin-service。
 
-按 HFS v2 开发范式，本仓库是 Pattern A 的 `port` / `source` 项目：仓库根目录仍是 Hugging Face Space root，同时也是 GitHub 维护 root；多服务 runtime glue 集中在 `hfs/` 下。受控发布从不可变 wrapper commit 导出最小 bundle，再由 Space build 从明确的 libreFS upstream commit 编译；没有 artifact 下载、config seed 或 HFS dist 运行依赖。
+按 HFS v3 开发范式，本仓库是 Pattern A 的 `port` / `source` 项目：仓库根目录仍是 Hugging Face Space root，同时也是 GitHub 维护 root；多服务 runtime glue 集中在 `hfs/` 下。受控发布从不可变 wrapper commit 导出最小 bundle，再由 Space build 从明确的 libreFS upstream commit 编译；没有 artifact 下载、config seed 或 HFS dist 运行依赖。
 
 ## 组件
 

docs/configuration.md

@@ -50,7 +50,7 @@ fatal: couldn't find remote ref main
 
 ## Hugging Face Variables
 
-原则：不要把和代码默认值、upstream 默认值相同的配置同步到 Hugging Face Variables。Variables 只用于表达“这个 Space 明确要覆盖默认行为”。代码默认部署下，HF Variables 可以为空；当前生产环境为了开启 admin，已显式设置 `ADMIN_ENABLED=true`，并显式设置 `ADMIN_AUDIT_LOG=/tmp/librefs-hfs/admin-audit.jsonl` 让 admin audit 不写入 `/data`。
+原则：不要把和代码默认值、upstream 默认值相同的配置同步到 Hugging Face Variables。Variables 只用于表达“这个 Space 明确要覆盖默认行为”。代码默认部署下，HF Variables 可以为空；当前 canonical preview Space 为了开启 admin，已显式设置 `ADMIN_ENABLED=true`，并显式设置 `ADMIN_AUDIT_LOG=/tmp/librefs-hfs/admin-audit.jsonl` 让 admin audit 不写入 `/data`。
 
 | Variable | 必需 | 默认值 | 什么时候设置 |
 | --- | --- | --- | --- |
@@ -67,7 +67,7 @@ Release reproducibility 口径：
 
 - 标准发布必须同时提供 `HFS_RELEASE_BUILD=true`、具体 `LIBREFS_COMMIT=<upstream commit sha>`，并由 exporter 将同一 SHA 写入 `BUILD_SOURCE.json`。
 - Docker build 会直接 fetch/checkout 该 commit，校验实际 checkout 的 `git rev-parse HEAD`，并拒绝与 bundle provenance 不一致的输入。
-- `hfs-dev.toml` 只登记 HFS v2 的 Settings 名称和 source-lane 关系；Go tarball checksum、Ubuntu base image 与源码 checkout 规则仍由 Dockerfile 直接定义和验证，不另设第二份 pin 台账。
+- `hfs-dev.toml` 只登记 HFS v3 的 Settings 名称和 source-lane 关系；Go tarball checksum、Ubuntu base image 与源码 checkout 规则仍由 Dockerfile 直接定义和验证，不另设第二份 pin 台账。
 
 Hugging Face runtime 会提供 `SPACE_HOST`。当前 Space 的公开 host 是：
 
@@ -90,7 +90,7 @@ HF Volume:
 - BlueSkyXN/librefs-hfs-data -> /data
 ```
 
-当前生产环境最近回读状态（2026-06-03）：
+当前 canonical preview Space 最近回读状态（2026-06-03）：
 
 ```text
 HF Secrets:
@@ -132,7 +132,7 @@ HF Volume:
 
 ## 本地 `.env` 配置台账
 
-HFS v2 以根目录 `.env` 作为本地值台账，提交的 [.env.example](../.env.example) 只提供空值和安全说明。它用于记录：
+HFS v3 以根目录 `.env` 作为本地值台账，提交的 [.env.example](../.env.example) 只提供空值和安全说明。它用于记录：
 
 - HF Space id、公开 host、Storage Bucket 和挂载点。
 - `MINIO_ROOT_USER` / `MINIO_ROOT_PASSWORD` 等真实值。