chore(hfs): adopt v2.1 preview contract

Author: BlueSkyXN

AGENTS.md

@@ -23,7 +23,7 @@
 | `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/` | 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
 

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 v2.1 `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 v2.1 source-lane manifest、local ledger ignore 边界、allowlisted source bundle fixture、provenance 和 manual deployment workflow：
 
 ```bash
 scripts/validate-contract.sh

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 | 必需 | 默认值 | 什么时候设置 |
 | --- | --- | --- | --- |
@@ -90,7 +90,7 @@ HF Volume:
 - BlueSkyXN/librefs-hfs-data -> /data
 ```
 
-当前生产环境最近回读状态（2026-06-03）：
+当前 canonical preview Space 最近回读状态（2026-06-03）：
 
 ```text
 HF Secrets:

docs/contract-alignment.md

@@ -1,10 +1,10 @@
 # 代码-文档契约对照
 
-本文档把当前代码事实、生产回读状态和文档维护口径放在同一处，用于减少文档漂移。修改代码或远端配置后，先更新这里，再同步其他文档。
+本文档把当前代码事实、canonical preview 回读状态和文档维护口径放在同一处，用于减少文档漂移。修改代码或远端配置后，先更新这里，再同步其他文档。
 
 最后核对时间：2026-06-03。
 
-## 当前生产回读
+## 当前 canonical preview 回读
 
 | 项目 | 当前状态 | 证据命令 |
 | --- | --- | --- |
@@ -15,26 +15,31 @@
 | HF Secrets | `MINIO_ROOT_USER`、`MINIO_ROOT_PASSWORD`、`OPS_TOKEN`、`ADMIN_TOKEN` 已存在；HF 不回显 value。 | `hf spaces secrets list BlueSkyXN/libreFS-HFS` |
 | HF Volume | `bucket BlueSkyXN/librefs-hfs-data -> /data`，`read_only=False` | `hf spaces volumes list BlueSkyXN/libreFS-HFS` |
 
-生产状态是快照，不是永久保证。涉及实时状态、Secret 同步、Volume 挂载或 runtime sha 时必须重新回读。
+canonical preview 状态是快照，不是永久保证。涉及实时状态、Secret 同步、Volume 挂载或 runtime sha 时必须重新回读。
+
+本项目按 HFS v2.1 登记为 `project_class=preview`，canonical Space 的角色是 `primary`。
+日常 Preview 变更允许直接更新 canonical Space；candidate 只作为高风险变更的可选隔离验证，
+不是常规前置门禁。Secret 必须先写入 manifest 声明的 Git ignored 本地明文文件；HF Secret
+只能作为部署副本，不能成为唯一事实源。
 
 ## 不可漂移契约
 
 | 契约点 | 当前事实 | 权威来源 | 文档同步位置 |
 | --- | --- | --- | --- |
 | Space 类型 | Docker Space，`app_port: 7860`，`license: agpl-3.0` | `README.md` front matter | `README.md`, `docs/configuration.md`, `docs/deployment-huggingface.md` |
-| HFS 范式分类 | HFS v2 Pattern A / `port` / `source`；`version_source=commit`，repo root 同时是 Space root 和 GitHub 维护 root，runtime glue 收在 `hfs/` | `hfs-dev.toml`, `README.md`, `Dockerfile`, `hfs/` | `README.md`, `docs/architecture.md`, `docs/source-walkthrough.md`, `AGENTS.md` |
+| HFS 范式分类 | HFS v2.1 / `preview` / `primary` / Pattern A / `port` / `source`；`version_source=commit`，repo root 同时是 Space root 和 GitHub 维护 root，runtime glue 收在 `hfs/` | `hfs-dev.toml`, `README.md`, `Dockerfile`, `hfs/` | `README.md`, `docs/architecture.md`, `docs/source-walkthrough.md`, `AGENTS.md` |
 | Runtime 获取模式 | `bundle-only-build`；Docker build 只能从 clean wrapper bundle 读取 provenance，并从 libreFS upstream `git fetch` 其记录的 source commit 后编译 | `hfs-dev.toml`, `Dockerfile` | `README.md`, `docs/architecture.md`, `docs/development-plan.md` |
 | Source wrapper provenance | 受控发布只上传由 clean immutable wrapper commit 导出的 allowlisted bundle；`BUILD_SOURCE.json` 和 `SHA256SUMS` 被 Docker image 保存，startup 校验 wrapper SHA、libreFS source SHA、digest 和 schema，`/_ops/version` 只返回无密 provenance 摘要 | `scripts/export-space-bundle.sh`, `scripts/verify-space-bundle.sh`, `Dockerfile`, `hfs/start.sh`, `hfs/ops_service.py` | `README.md`, `docs/deployment-huggingface.md`, `docs/operations.md`, `docs/source-walkthrough.md` |
 | 外部端口 | 只暴露 `7860` | `Dockerfile` `EXPOSE 7860`，`hfs/nginx.conf` `listen 7860` | 全部 endpoint/port 文档 |
 | 构建策略 | Ubuntu builder/runtime，从 `https://github.com/libreFS/libreFS.git` 拉源码编译，不使用官方 image | `Dockerfile` | `README.md`, `docs/architecture.md`, `docs/source-walkthrough.md` |
 | Go 版本 | `GO_VERSION=1.26.3` | `Dockerfile` | `docs/configuration.md`, `docs/source-walkthrough.md`, `docs/deployment-huggingface.md` |
 | libreFS ref | bundle-only build 必须同时使用 `HFS_RELEASE_BUILD=true`、`LIBREFS_COMMIT=<upstream commit sha>` 与 bundle 内相同的 `librefs_source_commit`；Docker build 会直接 fetch/checkout 并校验 `git rev-parse HEAD` | `Dockerfile`, `hfs-dev.toml` | `docs/configuration.md`, `docs/troubleshooting.md`, `docs/development-plan.md` |
-| Release hardening | HFS v2 registry不复制 product pin；受控 build 通过 `HFS_RELEASE_BUILD=true` + `LIBREFS_COMMIT=<40 位 SHA>` 固定 upstream。Go tarball checksum 和 Ubuntu base image digest仍是后续 hardening，不改当前 runtime | `Dockerfile`, `hfs-dev.toml` | `docs/configuration.md`, `docs/development-plan.md` |
+| Release hardening | HFS v2.1 registry不复制 product pin；受控 build 通过 `HFS_RELEASE_BUILD=true` + `LIBREFS_COMMIT=<40 位 SHA>` 固定 upstream。Go tarball checksum 和 Ubuntu base image digest仍是后续 hardening，不改当前 runtime | `Dockerfile`, `hfs-dev.toml` | `docs/configuration.md`, `docs/development-plan.md` |
 | Runtime packages | `bash`、`ca-certificates`、`curl`、`nginx`、`python3`、`tini` | `Dockerfile` | `docs/architecture.md`, `docs/source-walkthrough.md` |
 | Runtime user | UID/GID `1000`，存在则复用，不无条件创建 | `Dockerfile` | `docs/source-walkthrough.md`, `docs/troubleshooting.md` |
 | 必需启动 Secrets | 只有 `MINIO_ROOT_USER` 和 `MINIO_ROOT_PASSWORD` 缺失会让 `hfs/start.sh` 立即退出 | `hfs/start.sh` | `docs/configuration.md`, `docs/deployment-huggingface.md`, `docs/troubleshooting.md` |
-| Ops token | `OPS_TOKEN` 默认 `librefs_ops_demo_token`，生产应使用 HF Secret 覆盖 | `hfs/start.sh`, `hfs/ops_service.py` | `README.md`, `docs/configuration.md`, `docs/operations.md` |
-| Admin 开关 | 代码默认 `ADMIN_ENABLED=false`；当前生产回读为 `ADMIN_ENABLED=true` | `hfs/start.sh`, HF Variables | `README.md`, `docs/configuration.md`, `docs/operations.md`, `docs/troubleshooting.md` |
+| Ops token | `OPS_TOKEN` 默认 `librefs_ops_demo_token`；共享或长期运行的 preview 应使用本地明文先行的 HF Secret 覆盖 | `hfs/start.sh`, `hfs/ops_service.py` | `README.md`, `docs/configuration.md`, `docs/operations.md` |
+| Admin 开关 | 代码默认 `ADMIN_ENABLED=false`；当前 canonical preview 回读为 `ADMIN_ENABLED=true` | `hfs/start.sh`, HF Variables | `README.md`, `docs/configuration.md`, `docs/operations.md`, `docs/troubleshooting.md` |
 | Admin token | 开启 admin 时必须设置 `ADMIN_TOKEN`；使用 `X-Admin-Token` 或 bearer token；代码不强制它与 `OPS_TOKEN` 不同 | `hfs/admin_service.py` | `docs/configuration.md`, `docs/operations.md`, `docs/architecture.md` |
 | 公开 URL 推导 | `PUBLIC_BASE_URL` > `SPACE_HOST` > `http://localhost:7860` | `hfs/start.sh` | `docs/architecture.md`, `docs/configuration.md`, `docs/source-walkthrough.md` |
 | `MINIO_SERVER_URL` | 必须有 `http://` 或 `https://`，并去掉尾部 `/` | `hfs/start.sh` | `docs/architecture.md`, `docs/configuration.md`, `docs/source-walkthrough.md` |
@@ -49,16 +54,16 @@
 | Admin 写操作 | `reload-nginx` 是写 action，必须 JSON body `{"confirm": true}`，并写审计日志 | `hfs/admin_service.py` | `docs/architecture.md`, `docs/configuration.md`, `docs/operations.md` |
 | Admin 非目标 | 没有 Web terminal、file manager、bucket/policy/root credential 管理或 `librefs` restart | `hfs/admin_service.py`, 当前路由 | `README.md`, `docs/architecture.md`, `docs/configuration.md`, `docs/usage.md`, `docs/operations.md` |
 | 双语文案 | 支持 `en` 和 `zh-CN`；语言优先级为 `?lang=`、`X-Control-Language`、`Accept-Language`、`CONTROL_PLANE_DEFAULT_LANG`、默认 `en` | `hfs/ops_service.py`, `hfs/admin_service.py` | `README.md`, `docs/configuration.md`, `docs/operations.md`, `docs/architecture.md` |
-| 数据目录 | libreFS 数据默认在 `/data`；admin audit log 默认在 `/tmp/librefs-hfs/admin-audit.jsonl`；当前生产挂载 Storage Bucket 到 `/data` | `hfs/start.sh`, `hfs/admin_service.py`, HF Volumes | `README.md`, `docs/architecture.md`, `docs/operations.md`, `docs/usage.md` |
+| 数据目录 | libreFS 数据默认在 `/data`；admin audit log 默认在 `/tmp/librefs-hfs/admin-audit.jsonl`；当前 canonical preview 挂载 Storage Bucket 到 `/data` | `hfs/start.sh`, `hfs/admin_service.py`, HF Volumes | `README.md`, `docs/architecture.md`, `docs/operations.md`, `docs/usage.md` |
 | 持久化口径 | Volume 挂载不等于持久化验收通过；仍需上传、重启、读取、rebuild、再读取 | 运维要求 | 所有持久化说明 |
 | S3 smoke | `scripts/smoke-s3-curl.sh` 会真实创建临时 bucket/object、设置 public read policy 并清理 | `scripts/smoke-s3-curl.sh` | `docs/README.md`, `docs/operations.md`, `docs/source-walkthrough.md` |
 | 契约验证 | `scripts/validate-contract.sh` 检查 front matter、Dockerfile、`hfs/start.sh`、Python、Nginx、license 和可选远端 health | `scripts/validate-contract.sh` | `docs/README.md`, `docs/operations.md`, `docs/source-walkthrough.md` |
 
 ## 文档维护规则
 
-1. 区分“代码默认值”和“当前生产配置”。例如 `ADMIN_ENABLED` 代码默认是 `false`，但当前生产是 `true`。
+1. 区分“代码默认值”和“当前 canonical preview 配置”。例如 `ADMIN_ENABLED` 代码默认是 `false`，但当前 preview 快照是 `true`。
 2. 不把 Secret 明文写入文档。HF CLI 只能证明 key 存在；value 同步必须用受保护本机 `.env` 的值调线上接口验证。
 3. 不把 health check 写成 S3 功能验收。S3 写入、下载、policy 和匿名直链必须用凭证型 smoke test 验证。
 4. 不把 Volume 挂载写成持久化已验收。必须完成重启和 rebuild 后读回。
 5. 修改 `hfs/ops_service.py` 或 `hfs/admin_service.py` 时，同步检查 `docs/configuration.md`、`docs/operations.md`、`docs/architecture.md` 和本文档。
-6. 修改远端 HF Variables、Secrets 或 Volume 后，同步更新“当前生产回读”，并保留“代码默认值”不变。
+6. 修改远端 HF Variables、Secrets 或 Volume 后，同步更新“当前 canonical preview 回读”，并保留“代码默认值”不变。