docs: 明确 API machinery 与领域控制循环边界

AGENTS.md

@@ -3,6 +3,19 @@
 - 本仓库是 ddupan.top homelab 的内部基础设施控制平面，不以通用发行版为初期目标。
 - 提交、文档和代码注释优先使用中文；公共 API 标识符和代码遵循对应语言惯例。
 - 不要重新实现已有成熟后端的核心能力；新增实现前先确认能否通过稳定 API 进行薄适配。
+- Ayatori 复用 Kubernetes 的核心目标是 API machinery：对象存储与并发控制、list/watch、
+  informer、RBAC、admission、版本化 API 和审计；不要据此推断 Ayatori 是 Kubernetes
+  workload 平台，也不要默认复用 Kubernetes 的调度与数据面语义。
+- kube-apiserver 是 Ayatori 的 API 与状态协调平面，不是领域调度器。资源的调度、生命周期、
+  故障恢复、垃圾回收和后端收敛由 Ayatori controllers 实现；新增能力前应明确其属于 API
+  machinery、Ayatori 领域控制循环还是外部 backend，避免把职责放错层。
+- Kubernetes、OpenSandbox、Proxmox 等均是 Ayatori 的可替换 backend/executor。除管理组件自身
+  的部署外，不得仅因 controller 运行在 Kubernetes 中，就把原生 Pod、Job、Service、
+  NetworkPolicy、owner reference 或同 namespace 行为作为领域 API 的隐含语义；需要这些能力时
+  必须由 adapter 契约显式表达，并考虑后端位于其他集群或完全不是 Kubernetes 的情况。
+- 不要以减少自有 controller 数量为目的引入 generic-apiserver、聚合 API Server 或自行实现
+  API Server。只有 CRD/kube-apiserver 在存储、API 语义或扩展能力上形成已验证的阻碍时，才评估
+  接管 watch、RBAC、版本兼容和存储迁移等复杂度；controller 工作本身不会因此消失。
 - 在自行设计通用控制循环、资源生命周期、调度、回收或故障恢复机制前，先调查 Kubernetes
   核心及成熟开源 controller/operator 的实现；优先复用经过验证的模式，并记录有意偏离的
   理由。

README.md

@@ -28,7 +28,7 @@ Ayatori 是 `ddupan.top` homelab 的内部基础设施控制平面。它以 Kube
 - [执行模型](docs/concepts/execution-model.md)
 - [环境与发布](docs/concepts/environments.md)
 - [路线图](docs/roadmap.md)
-- [ADR-0001：采用 Kubernetes API 作为资源模型](docs/decisions/0001-kubernetes-api-machinery.md)
+- [ADR-0001：采用 Kubernetes API machinery 作为状态协调平面](docs/decisions/0001-kubernetes-api-machinery.md)
 - [ADR-0002：采用 k0s 与可选工作负载运行时](docs/decisions/0002-k0s-optional-workload-runtime.md)
 - [ADR-0003：直接连接 Dev API 的开发循环](docs/decisions/0003-dev-api-development-loop.md)
 

docs/architecture/overview.md

@@ -4,9 +4,11 @@
 Git / CLI / Backstage
           │
           ▼
- Kubernetes API + CRD
+ kube-apiserver + etcd + CRD
+   API / state coordination plane
           │
-   Ayatori controllers
+   Ayatori controller-manager
+ scheduling / lifecycle / recovery / GC
           │
    ┌──────┼──────────────┐
    │      │              │
@@ -19,6 +21,15 @@ Terraform            OpenBao / DNS / KaaS
 Ansible
 ```
 
+Ayatori 复用 Kubernetes 的 API machinery，而不是 Kubernetes 的容器编排产品边界。
+kube-apiserver 提供版本化对象、并发控制、list/watch、RBAC、admission 和审计；Ayatori
+controller-manager 承担所有领域控制循环。Kubernetes workload 集群只是与 OpenSandbox、
+Proxmox 等并列的 executor/backend，不默认等于运行 controller 的 management environment。
+
+因此，领域 API 不得依赖“资源最终一定变成同集群原生对象”的假设。原生 Pod、Job、Service、
+NetworkPolicy、namespace 共置与 owner reference 只有在 Kubernetes adapter 内才具有原生含义；
+跨后端所需能力必须由领域模型显式定义。
+
 ## 控制面
 
 Dev 与 Prod 使用独立的 Kubernetes API、数据库、身份和 controller 实例。两者可以
@@ -58,3 +69,10 @@ Ayatori 不承载或重新实现数据面。控制面故障只应阻止创建与
 
 Controller 无论采用哪种执行方式，都必须提供一致的 ownership、conditions、删除语义、
 错误分类和恢复行为。
+
+## API Server 边界
+
+首选 kube-apiserver + CRD，持续复用其成熟的 watch、RBAC、版本化存储和 API 生态。
+generic-apiserver 或聚合 API Server 不会减少领域 controller 的数量，只会把资源服务端、
+兼容性和存储迁移责任转移给 Ayatori。只有 CRD 的限制已经形成可复现、不可通过合理领域建模
+解决的阻碍时，才重新评估自建 API Server。

docs/decisions/0001-kubernetes-api-machinery.md

@@ -1,4 +1,4 @@
-# ADR-0001：采用 Kubernetes API 作为资源模型
+# ADR-0001：采用 Kubernetes API machinery 作为状态协调平面
 
 - 状态：Accepted
 - 日期：2026-09-17
@@ -10,16 +10,39 @@ homelab 的基础设施状态分散在多套工具和后端中。仅集中 IaC
 
 ## 决策
 
-Ayatori 使用 Kubernetes API machinery 与 CRD 表达平台资源、引用和状态，但不将平台
+Ayatori 使用 kube-apiserver、etcd、Kubernetes API machinery 与 CRD 构成 API 和状态协调
-限定为容器编排系统。Controller 可以运行于专用 management environment，并管理集群外
+平面。主要复用的是以下难以可靠重建的能力：
-的 VM、LB、数据库、对象存储、DNS、凭据和托管 Kubernetes 控制面。
+
+- 版本化对象 API、schema、defaulting、validation 与 admission；
+- 带 `resourceVersion` 的乐观并发、list/watch 与断线恢复；
+- informer/cache/workqueue 生态；
+- authentication、RBAC、namespace、审计与 API discovery；
+- spec/status、conditions、finalizer 等控制面约定。
+
+这项选择不把 Ayatori 限定为容器编排系统，也不意味着原生 Kubernetes workload API 是领域
+模型。kube-apiserver 保存期望、引用和观察状态；Ayatori controller-manager 实现平台领域的
+调度、生命周期、故障恢复、垃圾回收和后端收敛。Controller 可以运行于专用 management
+environment，并管理集群外的 VM、LB、数据库、对象存储、DNS、凭据和托管 Kubernetes 控制面。
+
+Kubernetes workload 集群与 OpenSandbox、Proxmox 等一样，是通过 adapter 接入的 backend 或
+executor。它可以是远端集群，也可以完全不存在。除 Flux 和 Ayatori controllers 等管理组件的
+部署外，领域 API 不得隐含依赖 controller 所在集群的 Pod、Job、Service、NetworkPolicy、
+namespace 共置或 owner reference 语义；确有需要的能力必须由领域 API 和 adapter 契约显式表达。
 
 GitOps 是长期期望状态的主要提交入口；API 是当前意图、关系和状态的在线控制面；真实后端
 仍是运行事实来源。Controller 负责三者之间持续收敛。
 
+`generic-apiserver` 或 Kubernetes API aggregation 只会让 Ayatori 接管资源的服务端实现，并不会
+替代上述领域 controller。除非 CRD/kube-apiserver 的存储模型、API 语义或扩展边界形成经过验证的
+阻碍，Ayatori 不自行承担 watch、RBAC、API 兼容、存储版本迁移和高可用 API Server 的实现与运维。
+
 ## 结果
 
 - 获得统一声明式 API、watch、RBAC、admission、conditions 和 controller 生态。
+- Ayatori controller-manager 实际承担类似 kube-controller-manager 的领域控制循环职责，必须把
+  reconcile、状态迁移、恢复与后端契约作为产品核心，而不是把它们误交给 kube-apiserver。
+- 原生 Kubernetes workload 对象不能成为所有 adapter 的最低公共语义；Kubernetes 只是其中一种
+  执行后端。
 - 可以把机器与人工执行统一建模为异步控制循环。
 - 必须维护 CRD 版本、conversion、认证、备份和控制面升级。
 - 不在 API 中保存日志、指标、大对象或业务数据，只保存控制所需状态及引用。