AGENTS.md

@@ -12,6 +12,11 @@
 - Ayatori 复用 Kubernetes 的核心目标是 API machinery：对象存储与并发控制、list/watch、
   informer、RBAC、admission、版本化 API 和审计；不要据此推断 Ayatori 是 Kubernetes
   workload 平台，也不要默认复用 Kubernetes 的调度与数据面语义。
+- 复用 Kubernetes 内置资源只表示采用其 API contract，不表示必须运行或模拟上游实现组件。
+  例如 Ayatori Compute Agent 可以直接实现 `core/v1 Node` 与 Lease 的状态语义，Ayatori
+  controller 可以自行消费 Node；不得仅因使用 Node 推导必须引入 kubelet、Pod、CRI、
+  kube-scheduler 或 kube-controller-manager。对每个复用资源分别明确 producer、consumer、
+  ownership 与实际采用的字段语义。
 - kube-apiserver 是 Ayatori 的 API 与状态协调平面，不是领域调度器。资源的调度、生命周期、
   故障恢复、垃圾回收和后端收敛由 Ayatori controllers 实现；新增能力前应明确其属于 API
   machinery、Ayatori 领域控制循环还是外部 backend，避免把职责放错层。

docs/architecture/overview.md

@@ -30,6 +30,11 @@ Proxmox 等并列的 executor/backend，不默认等于运行 controller 的 man
 NetworkPolicy、namespace 共置与 owner reference 只有在 Kubernetes adapter 内才具有原生含义；
 跨后端所需能力必须由领域模型显式定义。
 
+内置 API 类型也按相同原则选择性复用。采用 `core/v1 Node` 作为计算节点 API 时，可以由
+Ayatori Compute Agent 写入状态、由 Ayatori 自有调度 controller 消费；这不会引入 kubelet、
+Pod 或 kube-scheduler。API contract、负责实现它的 controller/agent 和数据面是三个独立决策，
+不得从其中一个自动推导另外两个。
+
 ## 控制面
 
 Dev 与 Prod 使用独立的 Kubernetes API、数据库、身份和 controller 实例。两者可以

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

@@ -24,6 +24,15 @@ Ayatori 使用 kube-apiserver、etcd、Kubernetes API machinery 与 CRD 构成 A
 调度、生命周期、故障恢复、垃圾回收和后端收敛。Controller 可以运行于专用 management
 environment，并管理集群外的 VM、LB、数据库、对象存储、DNS、凭据和托管 Kubernetes 控制面。
 
+Ayatori 可以选择性复用 Kubernetes 内置资源的 API contract，而不采用其上游实现组件。例如，
+`core/v1 Node` 可以表达计算节点身份、capacity、conditions、labels、taints 和维护状态，由
+Ayatori Compute Agent 更新并由 Ayatori controller 消费；这不要求部署或模拟 kubelet，也不
+要求存在 Pod、CRI、kube-scheduler 或 kube-controller-manager。`Lease`、`Namespace`、
+`Secret`、`ConfigMap`、`Event` 和 RBAC 等资源同样按各自适用的 API 语义独立选择。
+
+复用内置资源前必须明确其 producer、consumer、ownership、采用的字段和未采用的上游语义。
+不能因为 Kubernetes 通常将若干组件一起部署，就把这些实现关系重新带入 Ayatori。
+
 Kubernetes workload 集群与 OpenSandbox、Proxmox 等一样，是通过 adapter 接入的 backend 或
 executor。它可以是远端集群，也可以完全不存在。除 Flux 和 Ayatori controllers 等管理组件的
 部署外，领域 API 不得隐含依赖 controller 所在集群的 Pod、Job、Service、NetworkPolicy、
@@ -43,6 +52,7 @@ GitOps 是长期期望状态的主要提交入口；API 是当前意图、关系
   reconcile、状态迁移、恢复与后端契约作为产品核心，而不是把它们误交给 kube-apiserver。
 - 原生 Kubernetes workload 对象不能成为所有 adapter 的最低公共语义；Kubernetes 只是其中一种
   执行后端。
+- 允许由 Ayatori 自己实现合适的内置 API 资源语义；API 类型与上游 controller/runtime 不绑定。
 - 可以把机器与人工执行统一建模为异步控制循环。
 - 必须维护 CRD 版本、conversion、认证、备份和控制面升级。
 - 不在 API 中保存日志、指标、大对象或业务数据，只保存控制所需状态及引用。