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

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 表达平台资源、引用和状态，但不将平台
-限定为容器编排系统。Controller 可以运行于专用 management environment，并管理集群外
-的 VM、LB、数据库、对象存储、DNS、凭据和托管 Kubernetes 控制面。
+Ayatori 使用 kube-apiserver、etcd、Kubernetes API machinery 与 CRD 构成 API 和状态协调
+平面。主要复用的是以下难以可靠重建的能力：
+
+- 版本化对象 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 中保存日志、指标、大对象或业务数据，只保存控制所需状态及引用。