Merge pull request 'refactor: 分离 Database 资源与申请并撤除 registry' (#9) from feat/database-registry-inspection into main

Reviewed-on: #5

.gitea/workflows/verify.yml

@@ -1,9 +1,9 @@
 name: Verify
 
 on:
+  # 合并前完成全量验证，合并到 main 后不重复运行同一套检查。
   pull_request:
-  push:
+  workflow_dispatch:
-    branches: [main]
 
 jobs:
   test:
@@ -40,4 +40,32 @@ jobs:
           cache: true
 
       - name: Lint
-        run: make lint
+        run: |
+          make lint
+          make lint-database-integration
+
+  database-integration:
+    runs-on: [self-hosted, pod]
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          persist-credentials: false
+
+      - name: Set up Go
+        uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      # Runner 提供本 job 可用的 Docker；workflow 只验证，不重复启动 daemon。
+      - name: Verify Docker availability
+        shell: bash
+        run: |
+          set -euo pipefail
+          docker version
+          docker info --format 'Server={{.ServerVersion}} StorageDriver={{.Driver}}'
+
+      - name: Test Database integration with real backends
+        run: make test-database-integration

Makefile

@@ -67,6 +67,14 @@ test: manifests generate fmt vet setup-envtest ## Run tests.
 lint: golangci-lint ## Run golangci-lint linter
 	"$(GOLANGCI_LINT)" run
 
+.PHONY: test-database-integration
+test-database-integration: setup-envtest ## 使用临时 API server 与独立 PostgreSQL 容器验证凭据读取和连接更新。
+	KUBEBUILDER_ASSETS="$(shell "$(ENVTEST)" use $(ENVTEST_K8S_VERSION) --bin-dir "$(LOCALBIN)" -p path)" go test -tags=integration -race -count=1 ./internal/database/...
+
+.PHONY: lint-database-integration
+lint-database-integration: golangci-lint ## 检查集成测试构建标签下的 Database 代码。
+	"$(GOLANGCI_LINT)" run --build-tags=integration ./internal/database/...
+
 .PHONY: lint-fix
 lint-fix: golangci-lint ## Run golangci-lint linter and perform fixes
 	"$(GOLANGCI_LINT)" run --fix

README.md

@@ -34,6 +34,7 @@ Ayatori 是 `ddupan.top` homelab 的内部基础设施控制平面。它以 Kube
 - [ADR-0006：按实际管理缺口扩展资源 API](docs/decisions/0006-demand-driven-resource-scope.md)
 - [ADR-0007：复用 Node API 建立按需实现的 Compute 能力](docs/decisions/0007-compute-node-and-vm-boundary.md)
 - [ADR-0008：将 PostgreSQL Tenant Operator 合并为 Ayatori Database 模块](docs/decisions/0008-merge-postgresql-tenant-operator.md)
+- [ADR-0009：分离 Database 资源与 Tenant 申请](docs/decisions/0009-database-resource-and-claim.md)
 
 ## 当前状态
 

docs/concepts/api-design.md

@@ -26,6 +26,11 @@ cloud-init 设备、bridge/VLAN 映射和默认 placement 由平台维护。
 
 ## 生命周期基线
 
+新增资源、绑定、回收或恢复语义前，先引用 Kubernetes 官方对应资源设计与成熟 controller
+模式，说明采用部分及有意偏离的原因。不要仅沿用字段名称而忽略生命周期与权限边界。
+例如 Database 借鉴 PV/PVC 的资源与申请分离、排他绑定和 Retain，但不引入 CSI 协议、
+存储调度或额外 registry；见 [ADR-0009](../decisions/0009-database-resource-and-claim.md)。
+
 所有受管资源必须定义：
 
 - `observedGeneration`

docs/concepts/environments.md

@@ -1,5 +1,18 @@
 # 环境与发布
 
+## CI 验证入口
+
+Verify 工作流在 PR 上执行全量测试、lint 和 Database 集成测试；合并到 main 后不通过 push
+事件重复运行。需要排障或验证直接推送的紧急修复时，可通过 workflow_dispatch 手动运行。
+此约定不减少检查项目，也不修改分支保护设置；常规变更必须经过 PR，直接推送 main 不会自动验证。
+
+Gitea 的 PR 工作流验证分支 head，而不是合并预览提交，见
+[官方事件说明](https://docs.gitea.com/usage/actions/faq/)。合并前必须确认最新 head 检查通过，
+且与当前 main 合并不会引入未经验证的内容组合；基线有实质变化时先更新分支并重验。
+只改变基线引用且目标文件树不变时，不需要为了合并提交的 SHA 不同重复全量验证。
+
+## 环境与制品晋级
+
 Ayatori 首先建立 Dev。首个产品能力完成开发并达到可发布状态前，Prod 不实际存在；此时
 没有生产制品需要承载，提前维护第二套环境没有收益。
 

docs/database/README.md

@@ -1,7 +1,19 @@
 # Database 模块
 
-Database 是 Ayatori 首批实际产品领域之一。第一个迁移切片只建立 PostgreSQL Instance 的纯领域
+Database 是 Ayatori 首批实际产品领域之一。当前已包含 Instance 领域基础、管理凭据连接与
-模型，不注册 CRD、不启动 controller，也不访问 PostgreSQL、OpenBao 或 Kubernetes Secret。
+metadata 观察切片，尚未完成 Database API/controller 和 Tenant 供应链路。
+
+## 当前设计（2026-09-24）
+
+采用 Instance → Database → Tenant 的资源与申请模型；Database 独立存在，支持显式导入、
+Retain 后人工重新绑定与资源侧 Delete。撤销 PostgreSQL ownership registry 及任意 status
+丢失自动恢复所有权的要求。未知同名资源或创建结果不确定时，清楚报告 Conflict 并人工处理。
+
+依据 [ADR-0009](../decisions/0009-database-resource-and-claim.md)，当前合同见
+[系统规格](specification.md)。下面的迁移来源与已存在代码不反向约束新设计。
+registry adapter、专属迁移/测试及 Instance 的 registry 判定现已撤除；Instance 根据完整管理
+能力观察直接判定 Ready。新增 Database 资源、绑定、导入、角色/凭据管理边界与回收链路尚未实现。wiki 同步位置见
+`homelab-wiki/services/postgresql-tenant-operator.md`，跨仓库发布状态由 wiki 的同步记录维护。
 
 ## 来源基线
 
@@ -13,7 +25,8 @@ Database 是 Ayatori 首批实际产品领域之一。第一个迁移切片只
 - 迁移日期：2026-09-20
 
 本目录迁入该基线的 specification、architecture、API、领域、部署、安全、开发、迁移与运维
-文档，并只进行 Ayatori 产品归属、API group、目录和链接适配；其余已批准行为保持不变。
+文档，最初只进行 Ayatori 产品归属、API group、目录和链接适配；2026-09-24 经维护者
+批准的资源/申请分离修订明确替代 registry、自动恢复与原 Retain 合同，其余适用的安全约束保留。
 
 迁移只使用该 commit 中已提交的文件。源仓库
 `feature/instance-extension-observations` 工作树中的 `instance.go` 修改与
@@ -21,15 +34,79 @@ Database 是 Ayatori 首批实际产品领域之一。第一个迁移切片只
 
 代码被移动到 Ayatori 的 `internal/database/domain/instance`，测试 import 和文档链接相应更新；
 首个后续切片按已批准合同增加 Instance extension observation：观测与当前 target 绑定，进入重新
-验证或删除时失效，且支持判定不授权 Tenant provisioning。其余 Ready/observation 行为仍应先更新
+验证或删除时失效，且支持判定不授权 Tenant provisioning。已有 Ready 切片曾按原合同加入
-合同与测试再实现，不能把旧运行链路接回该模型。
+registry 准备决策；这一依赖现已从代码移除，不能把旧运行链路接回模型。
+各层验证边界见 [Instance 领域规格](domain-instance.md)。
 
 ## 边界
 
 - 领域层不依赖 Kubernetes types、数据库 driver 或凭据 provider。
 - CredentialReference 只携带管理 Secret 的名称与字段映射，不包含 Secret 内容或 OpenBao path。
 - Instance checkpoint 不是外部事实；实际能力必须由 application/adapter 观察后交给领域对象判断。
-- 当前代码不授权 Tenant provisioning，也不表示 Database API 已经可用。
+- 当前代码只检查 Instance 供应前置条件，不授予 Tenant 所有权或外部写入权限，也不表示
+  Database API 已经可用。
+
+## 管理凭据与连接切片
+
+`application.InstanceService` 适配自原项目固定基线
+[`internal/instance/service.go`](https://git.ddupan.top/panxiao81/postgresql-tenant-operator/src/commit/dae546e58efa1be81e930861c87f7fb13bb12113/internal/instance/service.go)，
+保留 CredentialReader、Connector、Database 的装配边界及串行操作/释放规则。
+具体连接池完全由 pgxpool v5.11.0 提供，PostgreSQL adapter 不拥有凭据缓存、轮换流程或任意观测回调。
+
+相对源基线有两项按已批准合同作出的必要修改：管理凭据从固定 controller namespace 的
+Kubernetes Secret 直接读取；每轮比较有效用户名、密码，检测到变化即关闭旧连接并重新装配。
+Secret metadata 和无关字段变化不重建连接。观测后再次读取 Secret，中途有效值变化则丢弃结果，
+不把旧连接的成功作为新凭据有效的证据；这不构成跨 Kubernetes/PostgreSQL 的原子事务。
+Instance UID、endpoint 或凭据引用变化也会释放旧连接；Forget/Close 只释放本地资源。
+
+当前通过 `ObserveMetadata` 读取服务器版本和可用扩展，`ObserveVersion` 只是其版本读取便捷入口，
+不能产生完整 CapabilityObservation 或 Ready。
+controller 接入、Secret watch、finalizer 与真实权限检查仍待后续切片；并发 CR 更新
+必须由调用者通过 resourceVersion 校验。应用层沿用源实现的串行处理，本阶段未引入新的调度框架。
+
+运行 `make test-database-integration` 验证真实 API server + 一次性 PostgreSQL；fixture 不接受外部
+DSN，镜像固定摘要，使用随机本机回环端口并在退出时删除测试容器。覆盖缺失/错误凭据、RBAC、
+namespace 边界、有效值轮换、metadata 无关变化、中途轮换、重建/重试、并发读取、Forget/Close
+与 TLS DNS/IP SAN、错误 CA/主机名和禁止明文降级。CI 使用 Pod runner 执行，由 runner 提供
+可用的 Docker，workflow 只做预检、不自行启动 daemon；不依赖 VM。普通 lint 之外还检查
+integration 标签代码。领域单测、真实 API 行为与真实 PostgreSQL 行为分别验收，不以本切片
+替代整个 Instance controller 的集成验收。
+
+## 服务器 metadata 与扩展观测
+
+SQL adapter 通过一条只读语句读取 `pg_catalog.current_setting('server_version')` 和
+`pg_catalog.pg_available_extensions`，避免从已安装列表推断可用列表，且不依赖可修改的
+`search_path`。查询失败丢弃整份结果；成功返回空列表与尚未观察严格区分。
+参考 PostgreSQL 的 [pg_available_extensions](https://www.postgresql.org/docs/18/view-pg-available-extensions.html)
+与 [CREATE EXTENSION](https://www.postgresql.org/docs/18/sql-createextension.html) 合同：可用列表
+表示服务器提供的扩展，不证明管理账号有安装权限，也不保证依赖和其他安装前提满足。
+
+`InstanceService` 保留原有 CredentialReader → Connector → Database 边界，复用同一个
+凭据读取、连接刷新和串行释放流程，不新增连接池封装或任意查询回调。每次重新查询 metadata，
+并在 Secret 有效值回读一致后生成不可变的 `MetadataObservation`，绑定本次 target（含当前
+generation），不绑定建池时的旧 target。结果不包含凭据，扩展集合不与 driver 的可变 slice 共享。
+凭据中途变化、读取失败或查询失败时，返回零值观察并释放连接，不复用旧的扩展列表。
+
+调用方可将 `Target()` 与 `Extensions()` 交给 Instance 的 `ObserveExtensions`；应用调用链
+仍负责同轮次使用，不能持久化或跨轮缓存这份证据。metadata 读取不安装扩展、不初始化 registry、
+不设置 Ready，也不授予 Tenant 写权限。管理权限矩阵及 controller 的
+checkpoint/status/finalizer 链路仍是后续切片。
+
+真实 API server + PostgreSQL 测试验证未安装扩展可被观察、名称保持大小写、search_path 遮蔽
+不改变查询来源、低权限账号读取、权限撤回失败与恢复、Secret 中途变化丢弃扩展结果。
+单元测试补充成功空列表、查询附带部分数据时丢弃、结果与可变 slice 隔离、每轮重新读取和
+generation 变化时的目标绑定；原凭据/TLS/超时/并发测试沿同一 metadata 路径继续运行。
+
+## Registry 撤除
+
+原 `adapter/postgresql/registry`、SQL 迁移、registry 专属集成测试及 tern 依赖已删除；
+未提交的 inspection 实验也已撤除。来源仍可在 Git 历史追溯，没有删除外部 PostgreSQL 对象。
+Instance 不再具有 InitializingRegistry 阶段、RegistryState、准备决策或回读方法；
+首次完整管理能力观察即可完成验证，重验失败则撤销本轮就绪证据。
+
+保留凭据读取与连接刷新、TLS、metadata/扩展观察及其真实后端测试。领域测试覆盖每项能力
+在初次验证和 Ready 重验时失败、依赖恢复、重启后重新取证、错误目标/阶段及删除保护。
+这不等于管理权限探测矩阵或三资源 controller 已实现。
 
 ## 设计入口
 

docs/database/api-reference.md

@@ -2,33 +2,34 @@
 
 | 项目 | 内容 |
 | --- | --- |
-| 状态 | Review |
+| 状态 | 三资源模型已批准；新增字段与绑定协议待评审 |
-| API group | `database.ayatori.ddupan.top` |
+| API group/version | `database.ayatori.ddupan.top/v1alpha1` |
-| version | `v1alpha1` |
+| 最后更新 | 2026-09-24 |
-| 最后更新 | 2026-09-10 |
 
-本文把已批准的系统规格映射为 CRD 字段合同。API types、生成 CRD、sample 和测试必须与本文
+以 [系统规格](specification.md) 与
-一致。Ayatori 尚未注册这些 API，本页是后续实现的规范来源。
+[ADR-0009](../decisions/0009-database-resource-and-claim.md) 为准。尚未实现新 API，
+本页不提供可直接 apply 的三资源 YAML，以免把工作名称和未决字段当作已发布合同。
 
 ## 通用约定
 
-- PostgreSQL identifier 匹配 `^[a-z][a-z0-9_]{0,62}$`。
+- Instance 是 cluster-scoped；Tenant 是 namespaced；Database scope 待字段评审。
-- 所有引用名称使用 Kubernetes DNS label/name 的相应校验。
+- 每类资源提供唯一的 Ready Condition、observedGeneration；phase 用于进度展示，
-- Tenant 的 `spec.instanceRef` 与 `metadata.name` 长度合计不超过 241 个字符，确保派生的
+  不能单独作为写权限或所有权证明。
-  `<instanceRef>-<metadata.name>-postgresql` 不超过 Kubernetes DNS subdomain 的
+- 引用必须区分定位名称与已绑定 UID；同名新对象不继承绑定。
-  253 字符限制。
+- controller 管理 status；资源侧管理与回收权限不得随 Tenant editor 权限自动授予。
-- port、TLS mode、deletion policy 等固定默认值由 CRD defaulting 提供。database、
+- 固定默认值使用 CRD defaulting，跨字段/不可变校验使用 CEL 或 controller；
-  loginRole、Secret 名称等依赖其他字段的值是 controller 语义默认值：字段保持省略，
+  并发更新使用 resourceVersion，不增加 mutating webhook 或跨系统事务。
-  controller 计算 effective value 并通过 status/受管资源展示，不引入 mutating webhook。
+- database/role identifier 继续匹配 `^[a-z][a-z0-9_]{0,62}$`。
-- 需要读取旧值或跨字段的校验由 CEL 或 controller 完成。
+- 动态申请的 database/loginRole 省略时继续以 Tenant metadata.name 为语义默认值；
-- `status` 由 controller 独占写入，禁止出现密码、Token、管理用户名或完整连接串。
+  显式导入资源使用实际目标，不从新 Tenant 名称重新推导。最终互斥字段须经 API 评审。
-- 两个 Kind 都只承诺一个 `Ready` Condition；调用方不得依赖内部协调阶段。
+- 投射仍位于 Tenant namespace，ExternalSecret 默认命名沿用
+  `<instanceRef>-<metadata.name>-postgresql`；目标 Secret 可由申请指定，省略时同名。
+  有效 Instance 名称与 Tenant 名称合计不超过 241 字符；完整名称须满足 API 名称校验。
+- 任何 spec/status/错误不得出现密码、Token 或完整秘密响应。
 
 ## PostgreSQLInstance
 
-cluster-scoped，short name 为 `pginstance`。
+保留管理入口字段：
-
-### Spec
 
 | JSON path | 类型 | 必填/默认 | 合同 |
 | --- | --- | --- | --- |
@@ -41,150 +42,79 @@ cluster-scoped，short name 为 `pginstance`。
 | `spec.adminCredentialRef.usernameKey` | string | `username` | Secret data 中的键名 |
 | `spec.adminCredentialRef.passwordKey` | string | `password` | Secret data 中的键名 |
 
-`adminCredentialRef` 不接受 namespace 或 Bao path。管理 Secret 固定在 controller
-namespace，名称须合法，两个字段须存在且非空。管理员维护 ExternalSecret，由 ESO
-同步；controller 只读管理 Secret，不创建或修改它。此为 2026-09-13 批准的修订，
-现有 API types、生成 CRD 和 samples 尚未更新。
 
-Instance endpoint、管理凭据引用可以修改。修改后 controller 重新验证。
+管理 Secret 固定在 controller namespace，不接受 namespace 或 Bao path。
-2026-09-14 修订：v1alpha1 不实现 allowedExtensions；现有 API types、生成 CRD 和
+管理员维护其 ExternalSecret，controller 只读；有效用户名/密码变化时重验连接。
-samples 中的字段待后续移除，不作为一个可配置但被忽略的策略保留。
+endpoint 变化使旧观察失效，不迁移旧服务器的数据，不自动接管旧 UID 的资源。
-扩展请求按目标 PostgreSQL 实际可安装列表判断，可用列表由应用层查询。
 
-endpoint 由管理员负责，不校验变更前后是否同一物理服务器／registry，只重验新配置
+Status 保留 observedGeneration、postgresqlVersion 和 conditions；
-的连接与管理能力。新 UID 按新 Instance 处理，不授权接管旧 UID 的 Tenant 资源。
+phase 为 Pending、Validating、Ready、Deleting，移除 InitializingRegistry。
+Ready 要求连接、metadata 与所需管理权限，不要求 registry。
+实例实际可用扩展来自查询，不提供 allowedExtensions 配置。
 
-### Status
+开始受管时保存 finalizer；删除时阻止新供应，并检查 Database（含 Released）及未绑定
+Tenant 引用。无引用才解除，不级联删除资源；查询失败不能视为无引用。
 
-| JSON path | 类型 | 含义 |
+## Database 资源（工作 Kind：PostgreSQLDatabase）
-| --- | --- | --- |
-| `status.observedGeneration` | int64 | 最近完成有结论协调的 generation |
-| `status.phase` | enum | `Pending`、`Validating`、`InitializingRegistry`、`Ready`、`Deleting` |
-| `status.postgresqlVersion` | string | 从 server 回读的版本，不用于客户端解析 |
-| `status.conditions[]` | `metav1.Condition` | 至少包含唯一的 `Ready` |
 
-print columns：`Endpoint=.spec.endpoint.host`、`Phase`、`Ready`、`Age`。
+以下是字段职责，不是已批准的 JSON schema：
 
-Instance `Ready=True` 要求管理凭据可读、TLS/认证成功、server metadata 可读、registry
+| 内容 | 合同 |
-可访问且权限预检成功。它不代表数据库已经备份或高可用。
+| --- | --- |
+| `instanceRef` | Database 自身必填；定位来源并记录绑定的 Instance UID，不依赖 Tenant 补齐 |
+| 外部目标 | 实际 database 名称及已确认的管理范围；操作开始后不可隐式改目标 |
+| 来源 | 区分动态供应与管理员显式导入；不能从同名存在推断导入授权 |
+| 申请预留/绑定 | 至多一个 Tenant，含 namespace/name/UID；Released 保留旧身份 |
+| 回收策略 | 资源侧 Retain（默认）或显式 Delete；普通 Tenant editor 不得扩大授权 |
+| 观察与进度 | 实际目标、当前阶段、条件和安全诊断，不保存秘密 |
 
-管理凭据从 Kubernetes Secret 装配；已有有效凭据可访问 PostgreSQL 时，Bao／ESO
+概念生命周期包含供应/验证、可绑定、已绑定、Released 和删除；最终 phase 枚举待协议评审。
-暂时不可用不单独撤销 Instance Ready。Tenant 凭据操作仍依赖 Bao。
+Released 不自动变成可绑定。Database 不以 Tenant 为 GC owner；使用中的资源受删除保护。
+
+导入的初始检查只读；存在不等于 Ready，也不等于有权交付给任意 Tenant。
+默认保留不隐含密码、owner、授权或删除的变更许可。
 
 ## PostgreSQLTenant
 
-namespaced，short name 为 `pgtenant`。
+保留用户申请与交付职责：
 
-### Spec
+- 动态申请描述 Instance、所需数据库/登录角色、扩展与目标 Secret；
+  或显式引用管理员已登记的 Database。后者从 Database 获取 Instance，不重复指定来源；
+  两条路径互斥，具体 schema 在 API 切片固定。
+- 绑定前固定有效需求，绑定/开始供应后不能通过改引用或名称迁移资源。
+- extensions 成功后只允许追加，不自动卸载。
+- status 展示绑定 Database 身份、Ready、交付 Secret 引用及不含认证信息的 OpenBao URL。
+- Tenant 删除释放申请，按照 Database 的回收策略处理，不独立持有最终删除授权。
 
-| JSON path | 类型 | 必填/默认 | 合同 |
+旧 Tenant `spec.deletionPolicy` 不再作为最终资源回收策略；旧字段表、供应 phase 枚举及
-| --- | --- | --- | --- |
+仅按 Tenant namespace/name 派生凭据路径的规则不再是实现合同。已有代码没有兼容负担，
-| `spec.instanceRef` | string | 必填 | cluster-scoped Instance 名称 |
+不保留两套相互覆盖的策略字段。
-| `spec.database` | string | `metadata.name` | 合法 PostgreSQL identifier |
-| `spec.loginRole` | string | `metadata.name` | database owner 兼应用 login |
-| `spec.extensions` | set[string] | 空集合 | 必须属于目标实例实际可安装的扩展列表；成功创建后只允许追加 |
-| `spec.credential.secretName` | string | `<instance>-<name>-postgresql` | 合法的同 namespace ESO target Secret 名称 |
-| `spec.deletionPolicy` | enum | `Retain` | `Retain` 或 `Delete` |
 
-Tenant 不声明 OpenBao mount 或 path。controller 使用部署级 mount/base path 和
+## 绑定协议评审要求
-`namespace/name` 推导稳定路径，并用 UID metadata 验证所有权。ExternalSecret 固定为
-`<instanceRef>-<metadata.name>-postgresql`；目标 Secret 可以由用户指定，只需
-满足 Kubernetes Secret 名称校验，不限制命名内容；省略时使用相同默认名。
 
-`instanceRef`、`database`、`loginRole` 和 `credential.secretName` 在首次成功创建外部
+实现前必须明确：
-状态后不可变。
-`extensions` 只允许集合不变或追加；移除返回 `ImmutableField`，不会执行
-`DROP EXTENSION`。`deletionPolicy` 在对象进入删除前可以修改；删除开始后以 finalizer
-首次观察到的值为准，避免清理过程中改变授权范围。
 
-### Status
+1. 资源 scope 与 typed reference 格式，管理员预留/导入与普通申请者的 RBAC 边界。
+2. 资源侧排他记录的写入点、双向绑定顺序、API 冲突重试与单边完成恢复。
+3. Tenant UID 变化、对象删除、Released 旧引用与管理员重新授权的判断。
+4. 同一物理数据库重复登记的冲突处理；列表查询不是原子认领。
+5. Database 的 role/凭据管理范围、稳定凭据定位、旧访问处置与投射清理顺序。
+6. 删除开始后的策略固定点和 Tenant/Database finalizer 配合。
 
-| JSON path | 类型 | 含义 |
+该协议使用 Kubernetes API 持久化，不为它新增 PostgreSQL registry。
-| --- | --- | --- |
+未完成一致绑定不得供应或交付；外部创建结果不确定按 Conflict 人工处理。
-| `status.observedGeneration` | int64 | 最近完成有结论协调的 generation |
-| `status.phase` | enum | controller 状态机的权威 checkpoint |
-| `status.database` | string | 应用语义默认值后的实际 database 名称 |
-| `status.loginRole` | string | 应用语义默认值后的实际 owner/login role 名称 |
-| `status.databaseOID` | uint32 | 回读的 database OID，仅供诊断 |
-| `status.credential.secretRef.name` | string | 同 namespace 目标 Secret 名称 |
-| `status.credential.openBaoURL` | string | 完整 KV v2 API URL，不含认证信息 |
-| `status.conditions[]` | `metav1.Condition` | 至少包含唯一的 `Ready` |
 
-Secret reference 不重复 namespace，因为它必定与 Tenant 同 namespace。OpenBao URL 格式
+## Conditions
-为 `<consumer-address>/v1/<mount>/data/<derived-path>`；不得包含 Token、用户名、密码或
-query credential。
 
-Tenant phase 枚举为 `Pending`、`Planned`、`CredentialCreated`、`RoleCreated`、
+每类资源至少提供唯一的 Ready；同类型 Condition 不重复，维护 lastTransitionTime 与
-`DatabaseCreated`、`ExternalSecretCreated`、`CredentialProjected`、`Ready`、`Deleting`。
+observedGeneration。最低安全错误分类见 [系统规格](specification.md#10-conditions-与可观测性)。
-它不包含 `Failed` 或 `Retained`；失败类型由 Condition Reason 表达。
 
-print columns：`Instance`、`Database`、`Phase`、`Secret`、`Ready`、`Age`。完整 OpenBao URL 只在
+Conflict 必须说明目标、步骤、已确认与不确定部分及人工核实建议；不能建议清空 status、
-YAML/JSON status 中输出。
+伪造 Ready 或改密码绕过。可恢复依赖故障退避重试，冲突不忙循环。
+具体 Reason 在 API 切片固定，Released 不得误报为可立即交付。
 
-两个 Kind 的 `status.phase` 都是 controller 状态机的权威 checkpoint。controller 用它
+## 实现验收
-选择下一候选动作，但必须在动作前后核对外部事实，不能仅凭 phase 跳过幂等检查。status
-丢失或领先于实际状态时必须保守重建/纠正。自动化就绪判断仍应读取 `Ready` Condition；
-phase 用于进度展示、恢复和排障。
 
-## Condition
+CRD defaulting、CEL、status subresource、resourceVersion、并发绑定、重启与依赖 watch
-
+使用真实 API server 验证；ownerReference/namespace 删除的实际 GC 使用测试集群。
-每种类型最多一个 Condition；更新必须保留正确的 `lastTransitionTime` 语义。
+类型、CRD、sample 和 contract tests 必须一起对齐，不以 fake client 替代 API 语义。
-
-| Reason | Kind | 可重试性 |
-| --- | --- | --- |
-| `Reconciling` | 两者 | 正常进行中 |
-| `Ready` | 两者 | 已收敛 |
-| `InvalidSpec` | 两者 | 修改 spec 前不会恢复 |
-| `ImmutableField` | Tenant | 恢复原值或重新迁移 |
-| `DependencyUnavailable` | 两者 | 自动重试 |
-| `AuthenticationFailed` | Instance | 修复凭据/TLS 后重试 |
-| `InsufficientPrivileges` | Instance | 修复管理 role 后重试 |
-| `InstanceNotReady` | Tenant | Instance 恢复后重试 |
-| `Conflict` | Tenant | 人工解除名称/所有权冲突 |
-| `ProvisioningFailed` | Tenant | 按错误类别退避重试 |
-| `CredentialProjectionFailed` | Tenant | ESO/Secret 恢复后重试 |
-
-`Ready=True` 必须使用 Reason `Ready`。处理中为 `Unknown/Reconciling`；已知未满足合同为
-`False`。Condition message 可以包含资源名和错误类别，禁止包含凭据值或完整 Secret。
-
-## 删除语义
-
-- `Retain` 不需要等待外部依赖；删除 CR 后外部记录保留原 UID 并标记 unmanaged。
-- `Delete` 添加 finalizer，严格按规格的所有权验证和清理顺序执行；失败保持 finalizer。
-- Instance 开始受管时即添加并保存 finalizer；删除时停止新供应，存在 Tenant 引用
-  （包括正在删除的 Tenant）就保留 finalizer，无引用才移除。引用查询失败时继续等待。
-  不级联删除 Tenant 或外部资源；管理员可使用运维逃生流程。
-- finalizer 不禁止创建 Tenant CR；并发创建者遇到删除中或不存在的 Instance 不得
-  开始供应。首版不增加跨对象锁或准入控制，不承诺跨对象原子删除。
-
-## 示例
-
-```yaml
-apiVersion: database.ayatori.ddupan.top/v1alpha1
-kind: PostgreSQLInstance
-metadata:
-  name: shared
-spec:
-  endpoint:
-    host: postgresql.home.arpa
-    hostaddr: 192.0.2.10
-    port: 5432
-    database: postgres
-    sslMode: verify-full
-  adminCredentialRef:
-    name: shared-postgresql-admin
----
-apiVersion: database.ayatori.ddupan.top/v1alpha1
-kind: PostgreSQLTenant
-metadata:
-  name: netbox
-  namespace: netbox
-spec:
-  instanceRef: shared
-  database: netbox
-  loginRole: netbox
-  extensions: [pg_trgm]
-  credential:
-    secretName: shared-netbox-database-credentials
-  deletionPolicy: Retain
-```

docs/database/architecture.md

@@ -1,99 +1,58 @@
-# 系统架构
+# Database 系统架构
 
-本文是已批准 [`specification.md`](specification.md) 的架构视图。规范定义外部行为，
+本页解释 [系统规格](specification.md) 的组件边界；资源与申请分离的依据见
-本文解释组件边界；二者冲突时以规范为准。Ayatori Database 模块目前只有首批领域模型，尚未
+[ADR-0009](../decisions/0009-database-resource-and-claim.md)。设计已确认，运行链路尚未完成。
-注册 API 或接入运行链路。
 
-## 组件与数据流
+## 资源与后端
 
 ```text
-GitOps / kubectl / Terraform / Backstage
+Kubernetes API
-                    |
+  Instance ──引用── Database ──排他绑定── Tenant
-                    v
+                         |
-          Kubernetes API (CRD)
+              Ayatori Database controllers
-                    |
+                   |          |          |
-                    v
+              PostgreSQL   OpenBao   ExternalSecret
-       Ayatori Database controller
+                catalog                  |
-          |          |          |
+                                        ESO → Secret
-          v          v          v
- PostgreSQL DBMS  OpenBao KV  ExternalSecret
- catalog+registry              |
-                               v
-                         Kubernetes Secret
 ```
 
-- Kubernetes `spec` 保存期望状态；`status.phase` 保存 controller 状态机 checkpoint，
+Kubernetes 保存声明、绑定与操作进度；PostgreSQL 保存实际数据库状态；OpenBao 保存应用凭据。
-  其他 status 字段保存可重建的观察结果。整个 status 都必须能由外部事实保守恢复。
+不在 PostgreSQL 中再建立管理 registry。Instance 是管理入口而非 CSI 协议实现，adapter 是薄访问层。
-- PostgreSQL catalog 保存 database、role、grant 和 extension 的实际状态。
-- 两个 CR 的 `status.phase` 是 controller 状态机的权威 checkpoint。
-- PostgreSQL 管理 database 中的 controller registry 只负责所有权、安装身份和保留标记。
-- OpenBao KV v2 是应用凭据的事实来源。
-- External Secrets Operator（ESO）读取 OpenBao，并创建应用使用的 Kubernetes Secret。
 
-controller 不运行 PostgreSQL/OpenBao，不管理 VM、存储、备份或 OpenBao PKI，也不直接
+Instance 验证当前目标的管理能力，不供应 Tenant 数据库，不因 registry 缺失初始化任何 schema。
-把明文凭据写入 Kubernetes API。
+Database 用例负责独立资源的供应、显式导入、保留与回收；Tenant 用例负责申请、绑定与凭据交付。
+这是用例职责，不要求为每一步新增一个 controller 或通用控制循环。
 
-## 资源模型
+## 协调与恢复
 
-`PostgreSQLInstance` 是 cluster-scoped，由平台管理员创建，描述外部 PostgreSQL 的
+通过 Kubernetes API 的 resourceVersion 保护并发更新，watch 推动依赖恢复；外部操作前保存
-DNS host、IP host address、端口、管理 database、TLS 模式和管理 Secret 引用。
+资源与意图，执行后观察并记录结果。数据库实际操作仍须处理后端竞态，列表检查不是唯一约束。
-实际可安装扩展由应用层查询后交给领域对象判定，v1alpha1 不实现管理员 allowlist。
 
-管理连接使用管理员维护的 ExternalSecret 经 ESO 同步到 controller namespace 的
+可靠确认的步骤允许幂等继续；外部创建与进度写入之间的失败若导致归属不确定，则停止写入并
-Secret；Instance 只选择 Secret 名称与字段，controller 只读，不直接从 Bao 获取
+报告 Conflict。不创建第二套所有权存储，不承诺跨系统事务或任意 status 丢失自动认领。
-管理凭据。Tenant 凭据的创建、读取与销毁仍由 controller 直接访问 Bao。
+错误必须提供人工可用的步骤、资源与结果确定性信息，但不泄漏秘密。
 
-`PostgreSQLTenant` 是 namespaced。一个 Tenant 对应一个 database、一个同时作为 owner
+## 绑定、导入与回收
-的 login role、一组只允许追加的 extension、一个由 controller 推导的 OpenBao KV
-记录，以及同 namespace 的 ExternalSecret 和目标 Secret。
 
-Tenant namespace 只提供 Kubernetes RBAC 和身份边界。database 与 role 名称在一个
+Database 独立于 Tenant 存在，不能以会导致级联删除的 ownerReference 连接两者。
-Instance 内仍然全局唯一。
+Instance 删除检查 Database 引用，包括 Released 资源，不直接清理数据库。
 
-## Reconcile 与所有权
+动态供应和管理员导入使用同一种资源记录。导入验证初始只读；未知同名数据库仍为冲突。
+Retain 保留资源及旧绑定身份；重新绑定必须经过人工数据和访问权限处置，不自动分配。
+Delete 由资源侧明确授权，在 finalizer 保护下按管理范围清理并逐步回读。
 
-系统采用最终一致性，不在 Kubernetes、PostgreSQL、OpenBao 和 ESO 之间假装存在分布式
+角色、凭据与投射的具体管理字段和清理顺序仍需 API 评审，不能用 PV 类比代替数据库权限设计。
-事务。每个外部写入前在 CR status 记录阶段，执行幂等操作，回读验证，再推进阶段：
 
-```text
+## 保持的访问边界
-Planned -> CredentialCreated -> RoleCreated -> DatabaseCreated
-        -> ExternalSecretCreated -> CredentialProjected -> Ready
-```
 
-controller 每轮同时读取 CR、registry、PostgreSQL catalog、OpenBao metadata 和 ESO
+管理 Secret 固定在 controller namespace，管理员维护其 ExternalSecret；controller 只读。
-投射状态。`status.phase` 是状态机 checkpoint，但不能替代外部回读；丢失或与事实冲突
+有效值变化刷新管理连接，不直接访问 Bao 获取管理凭据，不自行实现连接池。
-时必须保守重建/纠正。`metadata.generation` 只表示 spec 修改；Condition 的
+应用凭据写 OpenBao，由 ESO 投射；controller 不直接写明文 Secret。
-`observedGeneration` 表示该版本是否已经完成一次有结论的协调。
+TLS、DNS/IP SAN、七键凭据输出和最小权限合同继续适用。
 
-所有权使用 Instance UID、Tenant UID 与 namespace/name 验证。database/role COMMENT
+## 导航
-可以辅助排障，但不能代替 registry。未知资源只报告 `Conflict`，不得修改、接管或
-删除。Retain 后用相同名称重建 CR 会获得新 UID，因此仍然冲突。
 
-## 创建与删除边界
+- [API 合同与待细化字段](api-reference.md)
-
+- [领域模型](domain-model.md)与[Instance 规格](domain-instance.md)
-创建时先校验全部输入和冲突，再生成一次密码并写入 OpenBao，随后创建 role、database、
+- [部署](deployment.md)、[安全](security.md)、[开发测试](development.md)
-extension 和 ExternalSecret。只有 ESO 已投射 Secret 且应用凭据实际登录成功，Tenant
+- [导入与迁移](migration.md)、[运维](operations.md)
-才可 Ready。
-
-`Retain` 是默认删除策略，只移除 Kubernetes 管理关系并保留外部资源。显式 `Delete`
-使用 finalizer，在重新验证所有权后依次删除 ExternalSecret/Secret、连接、database、
-role、OpenBao KV 历史和 registry。详细恢复与逃生步骤见
-[`operations.md`](operations.md)。
-
-## 网络与 TLS
-
-Instance 同时公布 DNS `host` 和 IP `hostaddr`。PostgreSQL server 证书必须包含对应的
-DNS SAN 和 IP SAN，消费者自行选择可达目标，并可使用 `verify-full` 验证。OpenBao PKI
-持有 CA 私钥并签发服务端证书；controller 只挂载公开 CA bundle。
-
-OpenBao 的 controller 内部地址和外部消费者地址可以不同。Tenant status 同时提供目标
-Kubernetes Secret reference 和不含认证信息的 OpenBao KV v2 API URL。
-
-## 文档入口
-
-- API 字段与 Condition：[`api-reference.md`](api-reference.md)
-- 安装、依赖和配置：[`deployment.md`](deployment.md)
-- 本地与 CI 测试：[`development.md`](development.md)
-- 安全模型与最小权限：[`security.md`](security.md)
-- 现有数据库迁移：[`migration.md`](migration.md)
-- 日常排障和删除逃生：[`operations.md`](operations.md)

docs/database/deployment.md

@@ -1,13 +1,13 @@
 # 部署与配置
 
 > 本页迁入作为 Database 模块的目标部署合同。Ayatori manager flags、manifests 与发布装配尚未
-> 实现；原设计行为保持有效，但当前仓库不能直接按本页完成部署。
+> 实现；当前行为以修订后的系统规格为准，本页不能直接用于部署。
 
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | Review |
 | 环境 | homelab Kubernetes + 外部 PostgreSQL/OpenBao |
-| 最后更新 | 2026-09-10 |
+| 最后更新 | 2026-09-24 |
 
 本文定义 v1alpha1 的运行依赖、启动顺序和部署级配置。当前 manifests 尚未实现这些
 配置，示例是后续实现合同，不可直接用于现有脚手架。
@@ -30,8 +30,9 @@
 
 ## Controller 配置合同
 
-controller 使用以下 CLI flags。必填项缺失、路径无效或 duration 不为正数时，进程必须
+以下是尚待实现的部署配置合同，凭据定位随三资源 API 继续细化。controller 使用这些 CLI flags。
-在启动 manager 前失败；不得等到 reconcile 时才逐个资源报告配置错误。
+必填项缺失、路径无效或 duration 不为正数时，进程必须在启动 manager 前失败；
+不得等到 reconcile 时才逐个资源报告配置错误。
 
 | CLI flag | 必填/默认 | 说明 |
 | --- | --- | --- |
@@ -51,9 +52,9 @@ address 必须是绝对 `http` 或 `https` URL，不允许 userinfo、query 或
 `/` 开头，不含空段、`.` 或 `..`；base path 还不得编码 KV v2 的 `data`/`metadata`
 API 层。生产环境的 `--openbao-address` 必须使用 HTTPS；HTTP 只用于明确的开发 fixture。
 
-Tenant 路径固定推导为 `<base-path>/<namespace>/<metadata.name>`。namespace/name 都已通过
+Tenant 不能选择任意凭据路径。凭据必须能随 Database 保留并安全交付给被授权的新 Tenant；
-Kubernetes 名称校验，因此不再允许 CR 提供任意路径。KV v2 API URL 使用 consumer
+原 `<base-path>/<namespace>/<metadata.name>` 定位规则不再直接作为新 API 合同。
-address 拼为 `<address>/v1/<mount>/data/<base-path>/<namespace>/<metadata.name>`。
+稳定位置与导入关联方式待 API 评审；consumer URL 仍使用无认证信息的 KV v2 API URL。
 
 base path 必须是合法 mount-relative path，不以 `/` 开头且不包含空段、`.`、`..`、
 `data`/`metadata` API 层。ExternalSecret 固定命名为
@@ -61,8 +62,8 @@ base path 必须是合法 mount-relative path，不以 `/` 开头且不包含空
 满足 Kubernetes Secret 名称校验，不限制命名内容，默认与 ExternalSecret 同名。
 
 配置变化不得隐式迁移既有凭据。修改 KV mount/base path 或 consumer address 前必须
-停止 controller、评估现有 Tenant，并走明确迁移；实现应把 mount/base path 视为安装
+停止 controller、评估现有 Database 与绑定，并走明确迁移。资源记录应能定位原凭据，
-身份的一部分并在 registry 留存，以便检测错误配置。
+不能根据新部署参数静默切换；不再使用 registry 保存安装身份。
 
 ## PostgreSQL 管理 role
 
@@ -73,7 +74,6 @@ base path 必须是合法 mount-relative path，不以 `/` 开头且不包含空
 - 创建 database 并指定 owner；
 - 撤销 `PUBLIC` CONNECT、授予租户 role CONNECT；
 - 连接租户 database 并创建实例实际支持、租户申请的 extension；
-- 创建和维护 controller 专属 registry schema/table；
 - `Delete` 时禁止连接、终止目标 database session、删除已验证归属的 database/role。
 
 部分 PostgreSQL 操作天然要求较高权限，尤其终止其他 session 和安装某些 extension。
@@ -90,13 +90,15 @@ data 和 metadata，Delete 必须能永久删除全部版本及 metadata；不
 只读对应管理路径，不能供 Tenant 使用。租户 ESO 身份只读 tenant base path，不得
 读取 PostgreSQL 管理凭据。controller 不创建或修改管理 ExternalSecret／Secret。
 `ClusterSecretStore` 由平台管理员创建，controller 只引用，不创建或修改 Store。
-controller 创建的 ExternalSecret 与 Tenant 同 namespace，并设置 ownerReference；目标
+controller 创建的 ExternalSecret 与 Tenant 同 namespace；其 ownerReference 和 Retain 时的
+保留/清理须与凭据交付协议一起确定，不能把投射关系等同于 Database 的 GC 关系。目标
 Secret 包含固定七键：`username`、`password`、`database`、`host`、`hostaddr`、`port`、
 `sslmode`。
 
 ## Kubernetes RBAC
 
-- controller 可读/写 Instance、Tenant 的 status/finalizer 和 Event。
+- controller 按用例读/写 Instance、Database、Tenant 及其 status/finalizer 和 Event。
+- Database 不设置随 Tenant 级联删除的 ownerReference；导入、预留、回收和重新绑定授权限管理员。
 - controller 可在 Tenant namespace 创建、读取、更新、删除 ExternalSecret，并只读检查
   对应 Secret 是否完成投射。
 - namespace 用户可以管理本 namespace Tenant，但不能管理 Instance、Store、controller
@@ -108,9 +110,9 @@ Secret 包含固定七键：`username`、`password`、`database`、`host`、`hos
 
 ## 升级与回滚
 
-v1alpha1 尚不承诺跨版本转换。升级前备份 CR、PostgreSQL registry 和 OpenBao metadata，
+v1alpha1 尚不承诺跨版本转换。升级前备份 CR/绑定、PostgreSQL 数据与 OpenBao，
 先在隔离 Kind 环境运行 E2E。禁止在同一组 CR 上同时运行两个 controller 版本。若新版本
-在执行任何破坏性迁移前失败，可回滚镜像；涉及 API/storage 或 registry schema 迁移时，
+在执行任何破坏性迁移前失败，可回滚镜像；涉及 API/storage 或凭据定位迁移时，
 必须先写独立升级规格和回滚步骤。
 
 ## 上线验证

docs/database/development.md

@@ -3,6 +3,58 @@
 > 本页迁入作为 Database 模块的测试分层与 fixture 合同。旧项目的 Make target、devcontainer
 > 和脚手架版本尚未适配 Ayatori；实现时应复用 Ayatori 现有工具链，并保持这里定义的测试边界。
 
+## 当前设计验收（2026-09-24）
+
+[ADR-0009](../decisions/0009-database-resource-and-claim.md) 将资源生命周期从 Tenant 中分离。
+新增验收矩阵见 [系统规格](specification.md#11-验收)。registry 实现、专属测试与迁移依赖已撤除，不继续 schema 审计或自动所有权恢复切片。
+
+| 层次 | 本次设计要求 |
+| --- | --- |
+| 纯领域 | Instance 无 registry 就绪判定、排他绑定、Released 不自动复用、管理范围与冲突规则 |
+| envtest | 三资源 schema/status、RBAC、resourceVersion 并发、绑定单边更新/重启、依赖 watch、finalizer |
+| 真实 PostgreSQL/OpenBao | 同名不修改、显式导入只读验证、创建不确定报冲突、可靠步骤幂等、Delete 故障重试 |
+| 测试集群 | Tenant/namespace 删除不 GC Database、ESO 交付/释放、人工重新绑定前的旧访问处置 |
+
+需故障注入外部成功而 API 写入失败、后端响应丢失、双 Tenant 竞争、同名新 UID、依赖稍后出现、
+Instance 删除与 Released 引用。冲突必须给出可操作而不泄密的诊断；不要求自动认领不确定结果。
+envtest 不运行 GC 或 ESO；这些行为必须由测试集群验证。
+新增资源 API 尚未实现，本轮没有完成或运行这些新增行为测试。
+
+## Ayatori 已接入的凭据与 metadata 切片测试
+
+本节命令已在 Ayatori 接入；以下历史 Compose/Kind 操作仍属于迁入的目标合同。
+
+```sh
+make test
+make lint
+make lint-database-integration
+make test-database-integration
+```
+
+最后一项要求本机 Docker 可用。它启动 envtest 的真实 API server/etcd 和固定镜像摘要的临时
+PostgreSQL 容器，随机绑定回环端口，不读取 kubeconfig，也不接受指向现有数据库的 DSN。
+每个凭据场景使用独立环境；测试清理仅关闭自己的进程和按确切 ID 删除自己的容器。
+TLS 测试在临时目录生成一次性证书与私钥，不使用生产 CA。
+
+当前覆盖固定 namespace 的 Secret 读取与 RBAC、缺失/无效凭据恢复、有效凭据变化后的重连、
+无关字段更新不重连、中途轮换时丢弃观察、会话重建、并发读取、本地连接释放和 TLS 验证。
+快速测试、lint 和 Database 集成测试均使用 Pod runner。按维护者于 2026-09-21 更新的接口
+约定，runner 提供默认可用的 Docker；workflow 通过 `docker version` 和 `docker info` 预检，
+不自行启动 daemon、不强制 storage driver 或覆盖 Docker endpoint。该约定的 CI 验收依赖
+runner 后端修复上线，不能从本地测试通过推断远端已经可用。
+fixture 启动失败会保留退出错误与 stderr，并遮蔽测试密码，
+以区分缺少命令、daemon 不可达、权限和镜像拉取失败。
+
+metadata 测试验证版本与可用扩展的只读查询，包括未安装扩展、大小写保持、search_path 遮蔽、
+低权限账号读取、catalog 访问被撤回后的失败与恢复，以及凭据中途变化时同时丢弃版本和扩展。
+权限撤回只修改每个场景自建 PostgreSQL 容器的 ACL；不连接现有服务。
+可用列表不等于安装权限，这些检查不替代后续的完整管理权限矩阵或 Instance Ready 验收。
+
+Instance 领域测试不再提供 registry 状态，初次验证与 Ready 重验分别覆盖所有管理检查项的
+未观察、不可用、认证失败、权限不足及未知值，并验证依赖恢复；完整管理观察可直接 Ready。
+
+这些测试尚不包含 Instance CRD/controller、Secret watch、status/finalizer 事件链、权限探测矩阵、ESO 或 Tenant 供应。版本查询成功不意味着 Instance Ready。
+
 本项目同时依赖 Kubernetes API、PostgreSQL、OpenBao 和 ESO。日常开发不连接 homelab
 中的真实服务：Kubernetes 使用 envtest 或一次性 Kind，另外两个依赖使用一次性
 容器。这样既避免污染真实数据，也能把启动顺序固化为命令。
@@ -67,8 +119,8 @@ make lint
 `make test` 会下载与 `go.mod` 中 Kubernetes minor 版本匹配的 envtest 二进制，
 启动临时 API server/etcd，测试结束后自动关闭。
 
-规格实现后，快速测试必须覆盖默认值/校验、Condition `observedGeneration`、两个 CR 的
+规格实现后，快速测试必须覆盖默认值/校验、Condition `observedGeneration`、三资源的
-status 状态机、不可变字段、extension 只追加、registry 所有权和外部错误分类。envtest 只断言 controller 创建了正确
+状态与绑定、不可变字段、extension 只追加、冲突和外部错误分类。envtest 只断言 controller 创建了正确
 的 ExternalSecret；它不能证明 ESO 已生成 Secret。
 
 ### 2. 启动 PostgreSQL/OpenBao adapter 依赖
@@ -118,8 +170,8 @@ make test-integration
 ```
 
 该 target 会启动一次性 Compose 依赖，并通过 `POSTGRES_TEST_DSN` 把测试指向开发
-PostgreSQL。registry 测试会删除并重建固定的测试 schema，因此禁止将该变量指向真实
+PostgreSQL。这是旧环境设计，不是当前 Ayatori 入口；当前 fixture 不接受外部 DSN，
-homelab database。测试后运行 `make dev-down` 清理依赖。
+使用本页前部的 `make test-database-integration`，禁止把测试指向真实 homelab database。
 
 Gitea Actions 的 job 本身运行在 Docker container 中，不能通过 `127.0.0.1` 访问
 Docker host 上发布的 Compose 端口。CI 会暂时将 job container 加入 Compose 网络，
@@ -168,24 +220,22 @@ E2E fixture 必须把测试 PostgreSQL、OpenBao 和 ESO 部署进 Kind，并等
   -> 等待 Instance Ready
   -> 创建 Tenant
   -> 等待 Tenant Ready
-  -> 验证 registry、PostgreSQL catalog、OpenBao KV、ExternalSecret 和 Secret
+  -> 验证 Database 绑定、PostgreSQL catalog、OpenBao KV、ExternalSecret 和 Secret
   -> 分别使用 DNS host 与 IP hostaddr 登录
   -> 删除 Tenant 并分别验证 Retain 与 Delete（含故障点重试）
   -> 删除 Kind
 ```
 
-当前 controller 已实现第一条 Instance Ready 纵向链路：E2E fixture 在 Kind 内启动
+以上 Compose/Kind 流程来自旧项目的环境设计，不是 Ayatori 已实现的运行状态。
-PostgreSQL/OpenBao，配置 Kubernetes auth，验证管理凭据读取、PostgreSQL 登录、registry
+Ayatori 尚未完成 Instance/Database/Tenant controller 链路；当前可执行的切片命令以本页
-migration 和 Instance Ready。Tenant provisioning、ESO、TLS DNS/IP SAN 与删除路径仍需
+前部为准，不能从旧脚手架或 adapter 测试推断完整生命周期已经通过。
-后续纵向切片覆盖，不能从 Instance Ready 推断这些合同已经通过。
 
 ## 测试数据与泄漏检查
 
 - 只使用显眼的固定 canary 测试密码，测试后扫描日志、Event、Condition、metrics 和
   CR dump，出现 canary 即失败。
-- 每个最终一致性阶段都注入一次中断，重启后验证密码不变且阶段只向前推进。
+- 每个写入阶段注入中断：已确认步骤继续且密码不变；结果不确定则停止并明确报告 Conflict。
-- 清空、落后或伪造超前的 `status.phase` 后验证它能从外部事实保守恢复/纠正，且不会
+- 缺少绑定/进度记录时不得凭同名外部对象恢复所有权；过期 phase 不得绕过实际观察。
-  跳过任何回读。
 - 为未知同名 database、role、Bao record 和伪造 COMMENT 分别构造 Conflict。
 - Delete 在每个外部删除步骤失败后重试，确认未误删非当前 UID 资源。
 - 迁移测试按 [`migration.md`](migration.md) 完整执行，不以单纯 `pg_restore` 成功代替

docs/database/domain-instance.md

@@ -1,230 +1,88 @@
 # Instance 领域对象规格
 
-状态：Draft，含已确认决策。日期：2026-09-13。
+日期：2026-09-24。资源模型修订依据
+[ADR-0009](../decisions/0009-database-resource-and-claim.md)，行为以
+[系统规格](specification.md) 为准。本页替代原 registry 准备与恢复合同；领域依赖已撤除，完整应用/controller 链路尚未接入。
 
-上层合并边界见 [ADR-0008](../decisions/0008-merge-Ayatori Database controller.md)。本文只展开 Instance，不包含 Tenant 的供应
+## 职责
-实现，也不新增 CRD 字段。设计签名用于评审职责与行为，不是待复制的 Go 接口代码。
 
-## 1. 对象职责与生命周期
+Instance 是登记的 PostgreSQL 管理入口，只接收观察、判断规则，不直接或通过回调执行 IO。
+应用层读 Secret、调用 adapter、关联目标与观察，再将结果交给领域判定。
+领域不持有客户端、连接池、context 或完整 Database/Tenant 集合。
 
-Instance 表示一次登记的 PostgreSQL 管理对象，是聚合根。它负责字段与策略校验、
+每轮由 CR 重建；连接可由应用层复用，但旧连接、旧 Ready 不是本轮能力证据。
-根据观察结果判断能力是否满足要求、保护状态转换规则；不登录数据库，不读取 Bao，
+身份与 endpoint 以管理员声明为准，变更使观察失效，不验证物理服务器连续性，
-不查询权限或初始化 registry。
+不迁移旧数据，不自动授权旧 UID 资源的操作。
 
-本草案选择：**领域对象只接收数据并做业务决策，不直接或通过端口、回调访问外部。**
+## 字段与观察
-应用层调用适配器获取事实、执行被允许的操作，并将观察结果交回对象。Instance 不接收
-context、客户端或 IO 接口。领域行为不是公共 SetReady：调用方提供事实，不能指定结论。
 
-每轮从 CR 重建一个 Instance；对象不跨 reconcile 缓存，也不是线程共享单例。
+| 内容 | 合同 |
-管理连接可由装配层跨轮次复用，但连接复用不代表上次能力验证仍然成立。
+| --- | --- |
+| identity | Instance UID/name；同名新 UID 是新对象 |
+| revision | 当前 generation，不能与旧观察混用 |
+| definition | endpoint 与管理 Secret 引用，不含明文 |
+| checkpoint | Pending、Validating、Ready、Deleting |
+| observedRevision/readiness/version | 映射 CR status，只表示进度或最近结果 |
+| availableExtensions | 本轮实际可用集合；未观察与空集合不同 |
+| evidence | 本轮目标、版本与管理能力检查结果，不持久化为永久授权 |
+| deleting | 删除请求；禁止新的供应 |
 
-身份与 endpoint 以管理员声明为准。改变 endpoint 不验证是否同一物理服务器或
+CapabilityObservation 包含目标（UID、generation、endpoint、凭据引用）、server version、
-registry，不增加安装身份连续性检查；只使旧观察失效，按新配置重验管理能力。
+连接/metadata/role/database/grant/extension 管理检查项。各项区分成功、失败和未观察，
-新 CR 是新 Instance，不自动获得旧 UID 资源的所有权，也不迁移或清理旧目标。
+不包含 registry 状态、凭据或驱动错误。缺项或目标不匹配不得 Ready。
-下文“观察绑定匹配”仅指结果属于本轮身份／配置，不是物理服务器身份认证协议。
 
-## 2. 字段与值对象
+实际可用扩展不等于安装权限，不做 allowlist，不改大小写；查询失败不当作不支持，
+列表变化不自动卸载。安装必须由实际操作及回读验证。
+resourceVersion 留在应用层处理 API 并发，不是领域版本或物理数据库身份。
 
-所有可变状态封装在对象内部。构造后身份和本轮 definition 不可变；配置变更通过
+## 行为
-下一轮装载新的 definition 处理，不提供任意 SetPhase/SetReady/SetEndpoint。
 
-| 字段 | 类型与内容 | 来源／持久化 | 修改规则 |
+- Reconstitute 校验 definition，重建 checkpoint，丢弃旧 evidence。
-| --- | --- | --- | --- |
+- BeginValidation 清空能力证据并进入 Validating。
-| identity | InstanceIdentity：UID、name | CR metadata | 本次对象身份内不可变；同名新 UID 是新对象 |
+- AssessManagement/AssessReadiness 根据本轮完整观察判断 Ready 或安全失败；
-| revision | 正整数，期望配置版本 | metadata.generation | 本轮不可变；不是物理服务器版本 |
+  方法的具体合并方式在实现重构时决定，不保留无意义的中间初始化阶段。
-| definition.endpoint | Endpoint：host、hostaddr、port、managementDatabase、tlsMode | CR spec | 本轮不可变；新配置重验 |
+- CheckExtensions 判定请求集合，不能单独授权供应。
-| definition.adminCredential | CredentialReference：name、usernameKey、passwordKey | CR spec | 只引用 controller namespace 的管理 Secret，不存明文 |
+- RequireProvisioningReady 检查本轮能力与删除状态；不授予 Database 所有权。
-| availableExtensions | 可选的实际可安装扩展集合 | 应用层从目标 PostgreSQL 查询；本轮观察，不新增 status 字段 | 未观察与已观察的空集合不同；目标变化后旧结果失效 |
+- BeginDeletion 禁止新供应，不执行外部删除。
-| checkpoint | Pending/Validating/InitializingRegistry/Ready/Deleting | CR status.phase | 只能由领域动作变更，应用层负责持久化 |
+- Snapshot 返回值副本，不序列化 evidence 或秘密。
-| observedRevision | 最近完成有结论协调的版本 | CR status.observedGeneration | 成功或已知失败时更新，单纯记录意图不更新 |
-| readiness | Unknown/Ready/NotReady，加安全失败类别和操作说明 | 由 status Ready Condition 重建，结果再映射回 Condition | 方法更新；不是第二套持久化状态 |
-| reportedVersion | 可选服务器版本字符串 | status.postgresqlVersion；验证后从服务器更新 | 仅供展示，不能证明连接成功 |
-| deleting | 是否已请求删除 | metadata.deletionTimestamp 映射 | 本轮不可变；优先于其他动作 |
-| evidence | 可选 CapabilityEvidence | 本轮外部回读；不新增 status 字段 | 重建时始终为空，不能从 Ready Condition 伪造 |
 
-Endpoint 的构造约束沿用 API：非空 host、合法 IP、1–65535 端口、合法 PostgreSQL
+撤销 PlanRegistryPreparation、AssessRegistryResult、RegistryPreparationResult、
-identifier、显式 TLS mode，禁止隐式降级。CredentialReference 包含合法 Secret 名称
+RegistryState 与 InitializingRegistry 的设计需求。不能用始终返回 Usable 的兼容层绕过旧逻辑。
-及非空字段名，不包含 namespace 或 Bao path；namespace 由应用层固定为 controller
-自身 namespace。这里校验领域值，不在对象里校验整个 controller 部署配置。
 
-CapabilityEvidence 包含本轮目标绑定（Instance UID、revision、endpoint、凭据引用）、
+## 应用与连接边界
-server version、管理能力检查结果、registry 观察结果。registry 结果区分
-Absent/NeedsMigration/Usable；连接失败不能当作 Absent。它不包含密码、token 或 DSN。
 
-管理能力要求来自规格中的 role/database/grant/extension 操作，不等价于“能执行
+管理凭据来自 controller namespace 的 Secret；管理员维护 ExternalSecret，ESO 同步。
-SHOW server_version”。具体权限探测矩阵需在 PostgreSQL 适配器规格中定义，不能
+Instance 不直接访问 Bao。有效用户名/密码变化时应用层释放旧连接、用新值装配并重验；
-让一个没有定义检查内容的布尔值承担验收。
+metadata/无关字段变化不重建。采集途中有效值变化必须丢弃观察，不因 generation 没变而复用。
+controller 不修改 PostgreSQL 密码、管理 Secret 或 Bao 管理凭据。
 
-不属于 Instance 的字段：Tenant 清单、客户端、连接池、token TTL、CA 文件句柄、
+InspectManagement 是观察能力，不包含 schema 初始化/迁移。只读 metadata 查询仍不足以
-Kubernetes resourceVersion。resourceVersion 留在应用层作为乐观并发保存的前提。
+证明管理权限；真实权限矩阵由 adapter 定义和测试。连接复用由 pgxpool 提供，不自建池。
+已可用管理凭据下，Bao/ESO 当前故障不单独撤销 Instance Ready。
 
-### 扩展支持判定（2026-09-14 已确认方向）
+## 状态与删除
-
-v1alpha1 按目标 PostgreSQL 实际可安装的扩展列表判断请求，不实现管理员 allowlist。
-allowlist 仅保留为后续可选策略，不接受一个看似生效、实际被忽略的策略字段；现有
-CRD 的 allowedExtensions 应在对应 API 改动中移除，本次只修订文档。
-
-应用层查询实际可用扩展并提供与本轮目标绑定的观察；Instance 只做集合判断，不
-访问数据库。不沿用之前提议的字符正则，不自动改大小写或名称；SQL 适配器仍须
-安全引用 identifier。可用列表不是已安装列表，也不保证权限或其他安装前提满足。
-
-未观察／查询失败不得当作空集合或不支持；不得用旧目标的列表授权新目标的操作。
-非空请求须属于已观察的可用集合，返回不支持的名称；空请求无需扩展支持判定，
-但不绕过 Instance 的其他就绪要求。安装后仍需回读，不能以集合匹配代替安装验证。
-列表变化不触发自动卸载；已有扩展的漂移处理留到 Tenant 用例细化。
-
-## 3. 设计签名
 
 ```text
-Reconstitute(identity, revision, definition, checkpointSnapshot, deleting)
+Pending → Validating → Ready
-    -> Instance | InvalidDefinition
+Ready → Validating（配置/凭据变更或能力失效）
-
+任意阶段 → Deleting
-Instance.BeginValidation() -> Outcome
-Instance.AssessManagement(observation: CapabilityObservation) -> Outcome
-Instance.PlanRegistryPreparation(observation: CapabilityObservation)
-    -> AlreadyUsable | PreparationAllowed | PreparationDenied
-Instance.AssessRegistryResult(result: RegistryPreparationResult) -> Outcome
-Instance.AssessReadiness(observation: CapabilityObservation) -> Outcome
-Instance.CheckExtensions(requested: ExtensionSet)
-    -> Accepted | ExtensionsUnsupported | ExtensionSupportUnobserved
-Instance.RequireProvisioningReady() -> Accepted | InstanceNotReady
-Instance.BeginDeletion() -> Outcome
-Instance.Snapshot() -> InstanceSnapshot
 ```
 
-Outcome 是正常推进、已知失败或方法前提不成立，不包含重试秒数、Kubernetes patch
+应用层保存意图、获取观察、领域判定、按 resourceVersion 保存结果；
-或原始驱动错误。InstanceSnapshot 只包含 checkpoint、observedRevision、readiness、
+保存冲突重新装载，不能覆盖较新配置。Instance 观察本身不创建外部资源，
-reportedVersion，不能序列化 evidence。快照与集合访问返回值副本。
+初始 status 缺失可重新探测，不由此推出 Database 所有权可自动重建。
 
-CapabilityObservation 是不可变的事实输入：目标绑定、服务器版本、管理能力检查项和
+受管前先保存 finalizer。删除期间查询 Database 引用（包括 Released/删除中）及未绑定
-registry 观察结果；各检查项区分成功、失败、未观察，未观察不视为成功。失败只含安全
+Tenant；存在引用或查询失败都等待，无引用才解除。不得级联删除数据库或凭据。
-类别，不含驱动异常或凭据。对象校验目标绑定与当前身份／配置一致，拒绝不匹配输入，
+finalizer 不阻止并发申请 CR 创建；新请求见 Instance 删除中/不存在时不得供应。
-不改变状态；完整性不足不能产生 Ready。观察结果由应用层收集，对象不能自行证明
+不引入跨对象锁，不声称列表与删除之间存在原子事务。
-这些事实的真实性或实时性；采集来源、同轮次关联和并发检查由应用层保证。
 
-RegistryPreparationResult 为操作失败（目标绑定、安全失败类别）或操作后的完整回读
+## 验收与实现差距
-观察。单独的“迁移调用成功”不是就绪证据。CapabilityEvidence 是对象接受并判定满足
-要求的观察值，不是调用方传入的 Ready 布尔值。
 
-### 构造与恢复
+领域单测覆盖缺项、旧配置、错误目标、扩展空集合与未观察、重验与删除禁用。
+真实 API server 验证 Secret、resourceVersion、watch、finalizer；真实 PostgreSQL 验证
+权限、TLS、凭据更新和查询失败，不以领域布尔值或 server_version 查询代替管理权限验收。
 
-Reconstitute 校验期望 definition；无效输入不构造一个可参与用例决策的 Instance。
+Instance 领域代码、adapter 与测试的 registry 依赖已撤除。AssessManagement 根据完整观察
-入口把 InvalidDefinition 映射成 InvalidSpec，不必为了报告坏 CR 而制造非法领域对象。
+直接完成验证；AssessReadiness 失败进入 Validating，依赖恢复后重新验证。领域测试覆盖各检查项
-checkpoint 缺失或未知时保守使用 Pending；reportedVersion 和 Ready 都只是旧观察，
+在这两个入口的失败与恢复，但完整权限探测、Instance controller 和三资源生命周期尚未完成。
-evidence 为空。若 observedRevision 与 revision 不一致，旧 Ready 不得通过供应检查。
-
-### 方法合同
-
-| 方法 | 前置条件／输入 | 行为与状态变化 | 失败语义 |
-| --- | --- | --- | --- |
-| BeginValidation | 未删除；初次登记、配置变更或需重建 checkpoint | 转 Validating，readiness=Unknown，清空 evidence；不做外部 IO，不推进 observedRevision | deleting 时不启动验证 |
-| AssessManagement | 未删除；Validating；目标匹配的观察 | 判定管理访问、metadata、权限是否满足；registry 可用或可安全准备时转 InitializingRegistry，仍为 Unknown；不执行探测 | 失败保持 Validating，NotReady，observedRevision=当前版本 |
-| PlanRegistryPreparation | 未删除；InitializingRegistry；本轮前置观察 | 根据管理能力及 registry 现状决定无需写入、允许准备或禁止准备；返回决策，不执行迁移、不标 Ready | 访问失败、不兼容或证据不足时禁止写入，NotReady；保持阶段，更新 observedRevision |
-| AssessRegistryResult | 未删除；InitializingRegistry；准备结果或无需写入时的完整回读 | 按全部就绪条件判断回读结果；全满足才 Ready，并更新 observedRevision/version/evidence | 操作失败或回读不满足时保持 InitializingRegistry、NotReady；不得提前 Ready |
-| AssessReadiness | 未删除；Ready；本轮观察 | 配置版本不一致时仅 BeginValidation；否则根据全部观察判断是否仍满足就绪条件 | 访问失败转 Validating/NotReady；registry 缺失或需迁移时转 InitializingRegistry，保存后下一轮修复 |
-| CheckExtensions | 请求集合；本轮实际可用扩展观察 | 判断请求是否为实际可用集合的子集，返回不支持的名称；无 IO、无状态修改 | ExtensionsUnsupported 或 ExtensionSupportUnobserved；不卸载已存在扩展 |
-| RequireProvisioningReady | 供 Tenant 用例使用 | 要求未删除、Ready、observedRevision 匹配，并有本次调用链的新鲜完整 evidence | 不满足即 InstanceNotReady；持久化 Ready 本身不构成授权 |
-| BeginDeletion | deleting=true | 转 Deleting，清除供应能力，Unknown；不执行任何数据库或凭据删除 | 引用检查／finalizer 处理失败不得恢复成可供应 |
-| Snapshot | 任意合法对象状态 | 返回可安全持久化的结果值 | 不触发 IO，也不改变状态 |
-
-领域方法只检查对象状态，不知道 checkpoint 是否已落盘。“已持久化 checkpoint”是
-应用用例执行外部写入的前提。内存字段变成 InitializingRegistry 不代表已保存成功；不能
-在同一轮无条件接着执行迁移。通过用例测试验证此约束，而不是伪造一个内存事务。
-
-AssessManagement 成功只是中间步骤，observedRevision 不前移；完成就绪判定或
-明确失败才产生相应有结论结果。旧版本字符串可供诊断，但失败会清空 evidence。
-
-Instance 不在本轮暴露 CreateDatabase/DeleteDatabase：Tenant 的供应／销毁授权来自
-Tenant 和 OwnershipClaim，不是从 Instance.Ready 推导。数据库执行能力如何承接
-已授权动作，留到 Tenant 对象规格，不在这里设计第二个万能 service。
-
-## 4. 应用层与外部访问边界
-
-```text
-应用层依赖的适配器能力（不传入 Instance）：
-InspectManagement(context, target) -> ManagementObservation | AccessFailure
-InspectRegistry(context, target) -> RegistryObservation | AccessFailure
-EnsureRegistry(context, target) -> Completed | AccessFailure
-```
-
-应用层在 IO 前绑定目标并关联结果，领域对象在接受观察时检查身份和配置匹配；旧
-endpoint 的成功结果不得用于新 endpoint。Inspect 是只读；EnsureRegistry 是幂等初始化／迁移，
-不能顺带建立 Tenant 数据库或接管未知 schema。Completed 不足以推进 Ready，必须回读。
-
-适配器由装配层绑定管理连接；Secret 读取与连接池释放留在该边界之后，Instance
-管理连接不涉及 Bao token。适配器不得把基础设施异常转换成 Ready。失败区分依赖不可用、
-认证失败、权限不足和 registry 不兼容；不兼容属于不可安全继续，不自动覆写。
-registry 不兼容的具体 Condition 映射须在接口规格中确定，不能统一误报权限不足。
-
-管理连接由应用层从 controller namespace 的 Secret 装配；管理员维护 ExternalSecret，
-ESO 负责同步。Instance 路径不直接访问 Bao，也不以 Bao／ESO 当前可用性作为就绪条件。
-首次装配缺少有效 Secret 时失败；已有凭据可正常访问 PG 时继续按 PG 能力判定。
-检测到所引用 Secret 的有效用户名或密码变化时，应用／基础设施层使用新值重建连接池
-并重新采集管理能力观察；metadata 或无关字段变化不重建。不要求 Instance generation
-变化，也不能复用旧连接的成功观察来证明新凭据有效。Secret 变化监听、连接释放和
-刷新均不进入领域对象；应用层保证旧连接观察不混入刷新后的调用链。
-controller 不修改 PostgreSQL 密码、不回写 Secret 或 Bao 管理凭据。
-
-## 5. 状态转换与初始化走查
-
-```text
-Pending --BeginValidation/保存--> Validating
-Validating --AssessManagement(观察)/保存--> InitializingRegistry
-InitializingRegistry --AssessRegistryResult(回读结果)/保存--> Ready
-Ready --配置变化或访问失败/保存--> Validating
-Ready --registry 需修复/保存--> InitializingRegistry
-任意阶段 --删除请求/保存--> Deleting
-```
-
-1. 入口读取 CR，装配 definition、checkpointSnapshot；客户端不注入领域对象。
-2. 应用层按 checkpoint 协调用例；首次调用 BeginValidation，没有 IO。
-3. 保存 Validating。若保存失败，结束本轮，不执行 registry 写入。
-4. 下一轮应用层调用适配器探测实例，将观察交给 AssessManagement；领域判定通过后
-   保存 InitializingRegistry，保存失败则停止，不进行迁移。
-5. 再下一轮应用层采集前置观察，调用 PlanRegistryPreparation。仅在意图已持久化且
-   领域允许时调用 EnsureRegistry；AlreadyUsable 则跳过写入，PreparationDenied 则
-   保存失败结果并停止。允许的操作完成后回读，交给 AssessRegistryResult 决定能否
-   Ready；操作失败也用安全结果交回，不在应用层直接修改 phase。
-6. 入口用原 resourceVersion 前提保存快照；并发变更导致冲突时重新装载，不覆盖新状态。
-7. 后续 Ready 检查先由应用层探测，再调用 AssessReadiness；Tenant 用例同样获取当前事实，不能
-   仅凭另一个 CR 的 Ready Condition 永久缓存授权。实际资源写入仍须处理并发变化。
-
-阶段调度和外部操作顺序在应用层；“观察是否满足业务要求、是否允许准备 registry、
-哪些结果算完成、失败退到哪里”在 Instance 方法内。controller 不重复这些规则，
-也不直接把 phase 设置成 Ready。领域允许操作并不锁住外部世界，适配器仍须保障幂等
-和并发安全；禁止把旧观察当成永久授权。
-
-## 6. 不变量与恢复验收
-
-- UID 不随名称复用；不同 UID 的 evidence/结果不可互用。
-- 未完成当前配置的能力回读，不能新产生 Ready，也不能通过供应检查。
-- checkpoint 可以落后或被伪造；每次初始化／供应前都核对事实。status 清空只需重新
-  验证和幂等准备，不删除 registry，更不能重新生成 Tenant 密码。
-- 迁移成功而 status 保存失败：重试回读已存在 registry，安全完成，不重复破坏性写入。
-- registry 在 Ready 后消失：下一次回读撤销 Ready，保存修复意图后才能重新准备。
-- 外部 IO 超时：产生安全失败结果；保存 status 使用仍有效的外层上下文，不能复用
-  已超时的 IO 上下文而丢失失败状态。
-- 已请求删除的 Instance 不允许新供应；BeginDeletion 不删除 PostgreSQL、Tenant 或
-  Bao。应用层在开始受管时添加并保存 finalizer，而非出现 Tenant 后再添加。
-  删除时查询所有引用它的 Tenant（含删除中的对象）；有引用或查询失败就保留
-  finalizer，确认无引用才移除。引用查询、finalizer 写入和本地连接释放均不属于
-  领域 IO，Instance 只根据删除请求禁用供应能力。
-- 首版不为 Instance 删除增加跨对象锁或准入控制。并发创建的 Tenant CR 不被
-  finalizer 拦截，但遇到删除中／不存在的 Instance 不得开始供应；不承诺取消
-  已在途的外部操作，也不声称引用查询与移除 finalizer 是跨对象原子事务。
-- CheckExtensions 失败不能授权扩展安装；可用列表变化不会自行卸载已有扩展。
-- Snapshot、错误、日志和领域对象格式化不输出明文凭据或 token。
-- 领域测试只提供观察值，无需数据库、网络、context 或 IO mock；相同状态和输入
-  得到相同决策。缺少检查项、目标不匹配和旧配置结果不得产生 Ready。
-
-上述每条都对应领域或用例测试；真实权限检查、迁移与并发保障由适配器集成测试
-验证。本文为设计文档，未执行或宣称通过这些测试。
-
-## 7. 本轮待评审与后续阻塞项
-
-本轮请先确认字段归属、应用层采集事实／Instance 纯决策的分工、方法与状态转换合同。
-管理 Secret 来源、Bao 故障不单独撤销 Instance Ready，以及管理用户名／密码变化时
-重建连接池，以及管理员声明的 Instance 身份／endpoint 和简化 finalizer 删除规则
-均已确认。其他决策及未决项见总体草案，不增加后台清扫器或状态字段。
-
-批准本对象结构不等于批准这些未决行为，也不意味着立刻实现完整供应链路。

docs/database/domain-model.md

@@ -1,149 +1,76 @@
-# 领域模型设计草案
+# Database 领域模型
 
-状态：Draft，含已确认决策。日期：2026-09-13。
+状态：资源模型已确认，字段与绑定协议待细化。日期：2026-09-24。
+行为以 [系统规格](specification.md) 为准；决策依据见
+[ADR-0009](../decisions/0009-database-resource-and-claim.md)。
 
-本文定义领域职责、身份与一致性边界，并用对象规格细化字段和方法合同；方法使用
+## 统一语言与关系
-设计签名，不固定 Go 目录、SDK 或框架，也不批准实现。外部行为以
-[系统规格](specification.md) 为准；下列未决问题不能由实现自行决定。
-PR #6 的代码和已有 registry 表结构是可评估的实现素材，不反向决定领域模型。
 
-## 1. 领域与统一语言
+| 术语 | 含义 |
+| --- | --- |
+| Instance | 平台登记的 PostgreSQL 资源来源与管理入口 |
+| Database | 独立存在的数据库资源，保存目标、管理范围、绑定与回收策略 |
+| Tenant | 用户对数据库的申请与使用合同 |
+| Binding | Database 与 Tenant 的排他关联，不是独立 Claim 或 registry |
+| LoginRole | 当前单数据库场景中兼任 owner 的登录角色 |
+| CredentialLocation | 与资源生命周期一致的凭据定位，不是密码 |
+| CredentialProjection | 面向当前使用者的凭据投射要求与观察 |
 
-本系统的领域是“在共享 PostgreSQL 上供应并管理应用租户”，不是数据库服务器运维。
+Instance 一对多 Database；每个 Database 同时零或一个 Tenant，Tenant 最多一个 Database。
-v1alpha1 先采用一个限界上下文，不把 PostgreSQL、Bao、Kubernetes 各自当成业务上下文。
+Instance 不持有全部资源的内存集合。三者以引用关联，操作一个资源无需加载整个实例集合。
 
-| 术语 | 含义 | 不是什么 |
+Database 的 instanceRef 表达资源归属，手工登记时也必须提供，不从 Tenant 反推。
-| --- | --- | --- |
+Tenant 动态申请才选择 Instance；引用已有 Database 时使用资源声明的 Instance。
-| Instance | 平台登记的外部 PostgreSQL 管理对象及其供应策略 | 连接池、VM 或 controller 单例 |
+释放使用绑定不改变 Database 的实例归属，修改引用不能实现外部数据库迁移。
-| Tenant | 一个应用的数据库使用合同及受管资源生命周期 | PostgreSQL database 的别名 |
-| Database | 租户数据库的名称、owner、扩展等期望描述与实际观察 | 包含 Bao 登录与连接关闭的操作接口 |
-| LoginRole | 同时作为 database owner 和应用登录身份的角色 | 额外的 NOLOGIN owner |
-| OwnershipClaim | 某个 Tenant 身份对一组资源名称与凭据位置的所有权声明 | 工作流阶段或仅凭名称推断的归属 |
-| CredentialLocation | 固定推导的凭据位置及所有权关联 | 密码本身或用户可任意选择的 KV path |
-| CredentialProjection | 把既定凭据交付到目标 Secret 的要求与观察结果 | controller 直接写入明文 Secret |
 
-UID 表示一次 Kubernetes 对象身份；namespace/name 用于定位，不足以证明归属。
+Database 不再是 Tenant 内的无独立生命周期描述。原 OwnershipClaim 不再作为独立领域能力：
-database OID 是诊断观察值，不充当本系统的租户身份。
+排他绑定是资源自身的不变量，Kubernetes 保存记录，不另建 PostgreSQL 所有权存储。
 
-## 2. 候选聚合边界
+## 职责
 
-### Instance：实例能力与供应策略
+Instance 只接收观察并判断当前连接、metadata、管理权限和扩展支持，不访问 IO、不初始化
+registry。管理凭据来源和连接刷新由应用层协调，连接池由 pgxpool 实现。见
+[Instance 规格](domain-instance.md)。
 
-Instance 是候选聚合根，持有自身身份、endpoint、管理凭据引用、实际可用扩展观察，
+Database 保护目标和管理范围、排他绑定、导入验证与 Retain/Delete 规则。资源首次外部操作前
-以及用于判断当前能力的观察结果。它不持有所有 Tenant 对象的集合。
+必须已有持久记录；完成记录与外部存在性分别检查。数据库名称不是归属证明。
 
-其行为包括：
+Tenant 表达申请与交付要求；显式选择已有资源不自动授权使用。绑定后检查数据库满足要求、
+应用凭据可登录且 ESO 投射完成，才可 Ready。Tenant 删除意味着释放使用关系。
 
-- 判断租户申请的 extension 是否在本实例实际可安装列表中；v1alpha1 暂不实现 allowlist。
+LoginRole 与 CredentialLocation 的生命周期必须随独立资源保留，不能因为 Tenant 消失就
-- 根据管理连接、服务器信息、registry 和权限检查结果判断是否具备供应能力。
+失去定位或未经授权被删除；具体字段归属及导入时的管理范围需继续评审。不要因此新增 Role、
-- 判断配置变化使哪些能力观察过期，禁止以旧 generation 的 Ready 证明新配置可用。
+Credential 或 Claim CRD。当前首版仍是单 database + 单 login owner。
-- 在 registry 初始化完成并回读验证后，接受新的就绪结果。
 
-“探测实例”“准备管理 registry”是应用用例协调的外部操作，不是 Instance 的 IO 方法。
+## 生命周期与恢复
-领域对象只接收观察值，负责前提、规则和状态决策；应用层调用适配器获取事实与执行
-获准操作。领域对象不持有或调用外部访问端口、客户端或回调。具体选择见
-[Instance 字段与行为](domain-instance.md)，仍处于待评审状态。
 
-### Tenant：供应合同与资源生命周期
+- 动态创建与显式导入最终形成同一种 Database 资源，但导入本身不允许改密、改 owner 或删除。
+- Retain 后 Database 保持 Released 与旧绑定身份，人工确认数据、权限和凭据后才可重新绑定。
+- 回收策略属于资源侧；Tenant 与 Database 不是可随申请级联 GC 的父子关系。
+- 绑定 UID 防止同名新申请继承权限。双向记录的单边写入不代表绑定完成。
+- 普通失败按 reconcile 重试；可靠确认的步骤幂等继续；不确定创建/未知同名对象报告 Conflict。
+- Kubernetes status 是持久进度和观察，不是外部事实，也不是 controller 内存。
+  不引入“status 任意丢失后自动恢复所有权”的附加要求。
 
-Tenant 是另一个候选聚合根，通过身份引用 Instance，而不是 Instance 的聚合成员。
+## 分层
-操作一个 Tenant 不应要求装载、锁定或保存整个实例的租户集合。
 
-Tenant 持有有效的 database/role 名称、请求的扩展、凭据交付目标、删除策略，以及
+| 层 | 责任 |
-已建立的资源绑定。它负责：
+| --- | --- |
+| 领域 | 值、身份、允许动作、不变量、完成与冲突判定；不做 IO |
+| 应用 | 装载记录与事实、协调 API 更新和 adapter、回读、交回领域判定 |
+| controller | watch/调度、映射、conditions/status/finalizer；不重写领域规则 |
+| adapter | Kubernetes、PostgreSQL、OpenBao、ESO 的具体访问与安全错误分类 |
+| 装配 | 客户端与成熟连接池的生命周期，不是领域状态 |
 
-- 检查绑定后的不可变字段、extension 只追加规则。
+不引入通用 Repository CRUD、跨系统 Unit of Work、事务队列或第二套 phase 存储。
-- 判断外部部分状态属于本 Tenant、尚不存在，还是与未知资源冲突。
+resourceVersion 解决 API 对象并发更新，不宣称 PostgreSQL 与 Kubernetes 原子提交。
-- 决定是否允许继续供应、何时达到 Ready、是否允许释放受管资源。
-- 按 Retain/Delete 合同限制行为，禁止把保留资源自动认领给同名新 UID。
 
-Database、LoginRole 和 CredentialProjection 暂不设独立聚合根或独立 CRUD 用例。
+## API 切片前需明确
-它们可作为 Tenant 内的资源描述与观察值；有规则才增加行为，不为了“充血”添加方法。
-真实 PostgreSQL database/role 的存在不意味着内存中必须各有一个有身份的实体。
 
-聚合边界是业务规则的保护边界，不表示 Tenant 对应的 PostgreSQL、Bao、ESO 资源
+- Database 的 scope、引用格式、谁可以预留/绑定/释放，以及绑定字段和更新顺序。
-能够一次事务提交。跨系统供应必须允许部分完成。
+- 资源侧回收策略与 Tenant/Database finalizer 配合。
+- 导入时角色/凭据的管理范围，稳定凭据定位、旧使用者撤权及新投射授权。
+- 绑定/导入同一实际目标的重复声明如何拒绝，且不引入 registry。
+- 管理员确认冲突、解除旧绑定的具体可审计操作入口。
 
-### OwnershipClaim：跨租户唯一性与持久证据
+这些细节不阻止已确认的三资源设计，但必须先于对应 API 与生命周期实现获得评审。
-
-名称唯一性不可能只靠某个 Tenant 的内存检查保证。需要一项领域能力，在持久化边界
-原子认领资源；已有 registry 是其适配器候选，仍需结合 catalog 和 Bao metadata 检查。
-
-Claim 与 Tenant 关联，但不随 Tenant CR 消失：Retain 后证据必须继续存在。因此不能
-把它仅视为 CR 的附属 status。是否作为独立的小聚合，先以“可独立持久化、保留并保护
-归属不变量的声明”建模；不因此引入新的 CRD。
-
-- 同一身份、同一绑定的重复认领可以成功；不同 UID 或不同绑定不能覆盖。
-- Claim 预留名称不等于证明同名外部资源由本 controller 创建。
-- 实际写入仍须核对所有权，不能把先查后建当成并发安全保证。
-- 当前 registry 的数据库事务不能覆盖 Bao；跨实例的凭据路径竞争也不能靠单个
-  registry 的唯一约束解决。写入前提与条件创建协议需单独设计和验收。
-
-## 3. 领域、用例与适配器的分工
-
-| 层 | 承担的职责 | 禁止承揽的职责 |
-| --- | --- | --- |
-| 领域对象／策略 | 身份、有效合同、归属判断、允许的动作、完成条件 | 外部 IO（包括通过接口间接调用）、解析 CLI、生成 Kubernetes Condition |
-| 应用用例 | 装载模型与事实、持久化意图、调用能力、回读、提交结果 | 另写一套绕过领域规则的判断流程 |
-| controller 入口 | CR 映射、调度、watch、重试、status/finalizer 写入 | 在 reconcile 中重新定义业务规则 |
-| 基础设施适配器 | PostgreSQL、registry、Bao、ESO 的实际读写与并发保障 | 自行决定接管、改密码或扩大删除范围 |
-| 启动装配 | 校验部署配置，创建共享客户端、连接管理器及用例依赖 | 把连接生命周期当成 Instance 的业务状态 |
-
-领域可使用独立的身份、endpoint、identifier、extension 集合等值对象，不依赖 CRD
-类型、pgx pool 或 Bao SDK。Kubernetes 对象的存取与 registry 的存取不是一个通用
-`Save(Tenant)` 可以原子完成的事情；不虚构跨系统 Unit of Work。
-
-暂不引入事件总线、事件溯源、通用聚合框架或全套 Repository CRUD。领域建模的依据
-是业务规则，而不是接口和目录数量。
-
-## 4. 状态与恢复
-
-CR `status.phase` 仍是已批准的工作流 checkpoint，不在内存对象或 registry 再建一套
-权威 phase。领域对象可以由 CR 的期望状态、checkpoint 和外部观察重新构造。
-
-phase 只决定候选步骤，外部证据决定该步骤是否允许执行、是否已经完成。应用层在
-写操作前保存意图，调用幂等操作后回读，再保存下一 checkpoint。status 写入失败时，
-下次从外部事实识别完成结果；不能重发密码，也不能相信伪造的 Ready。
-
-业务失败区分 InvalidSpec、ImmutableField、Conflict 等；依赖故障由适配器转换成
-安全的能力失败，应用层决定重试并映射 Condition。凭据不进入模型序列化、status、
-事件或错误明细；只能在实际需要它的执行边界短暂传递。
-
-## 5. 用例走查与验收方向
-
-| 场景 | 领域判定 | 应用与适配器执行／恢复 |
-| --- | --- | --- |
-| 登记 Instance | 当前配置的能力要求是否满足 | 读取管理凭据，验证连接与权限，准备并回读 registry；完成后才 Ready |
-| 供应 Tenant | Instance 策略、绑定与归属允许供应 | 保存意图，认领资源，先写并回读 Bao 凭据，再创建 role/database，登录验证和 ESO 投射 |
-| Bao 写入后进程中断 | 同一身份的部分状态可继续 | 回读原凭据继续，不生成第二份密码 |
-| 两个 Tenant 竞争名称 | 只有匹配所有权的一方可继续 | 持久化认领和条件写入裁决竞争，失败方 Conflict，不覆盖资源 |
-| Delete 中断 | 已消失资源可视为完成；剩余资源仍须归属正确 | 按规格顺序继续删除，全部回读不存在后才清 registry 和 finalizer |
-| Retain 后同名 CR 重建 | 新 UID 不等于原所有者 | Conflict，不恢复管理、不改密码 |
-
-领域测试验证规则与决策；adapter 测试验证锁、条件写入、SQL 与协议行为；controller
-测试验证 checkpoint 持久化和重启恢复；E2E 验证最终合同。不能只验证一串 mock 调用
-就声称实现了最终一致性。
-
-## 6. 决策记录与待细化边界
-
-1. **Instance 身份与物理目标（已确认）**：以管理员声明为准，endpoint 变更不验证
-   物理服务器／registry 连续性，不增加安装身份绑定检查；旧观察失效，重验新配置
-   的连接与管理能力。新 CR 视为新 Instance，不自动接管旧 UID 资源或迁移数据。
-2. **Retain 完成条件**：外部依赖不可用不能永久阻止 CR 删除，但 registry 又需标记
-   unmanaged。需定义 CR 消失后的补偿／清扫入口及所需身份依据，不能承诺同时原子
-   完成两者，也不能在没有回读时声称已写入保留标记。
-3. **管理凭据来源与 Ready（已确认）**：Instance 引用 controller namespace 内的
-   管理 Secret 名称和字段；管理员维护 ExternalSecret，ESO 同步。controller 不直接
-   从 Bao 读取管理凭据。已有凭据仍可访问 PG 时，Bao／ESO 故障不撤销 Instance Ready；
-   首次装配无有效 Secret 则失败。Secret 的有效用户名／密码变化时重建管理连接池并
-   重验，不因无关字段变化重建；controller 不修改 PG 密码，不回写 Secret 或 Bao。
-4. **绑定时机**：系统规格写“首次成功后不可变”，API 文档写“首次创建外部状态后
-   不可变”。应明确绑定在认领、首次外部写入还是 Ready 时固定，及如何在 status 丢失
-   后恢复；否则供应中途改名称可能产生无人管理的资源。
-
-5. **Instance 删除（已确认）**：开始受管即添加 finalizer；删除期间停止新供应，
-   有 Tenant 引用就等待，无引用才解除，不级联删除外部资源。首版采用 finalizer
-   与引用检查，不引入跨对象锁／准入控制；不保证并发创建与删除的原子性。
-
-Tenant 的 Retain 等待决行为留到 Tenant 设计，不属于本轮 Instance 设计范围。
-相关用例在决策批准前不进入实现，不同时实现整套模型。

docs/database/migration.md

@@ -1,13 +1,33 @@
-# 现有数据库迁移 Runbook
+# 现有数据库导入与迁移 Runbook
 
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | Review；尚未在临时 PostgreSQL 演练 |
-| 适用范围 | 任意既有数据库迁移为新建 v1alpha1 Tenant |
+| 适用范围 | 管理员显式导入，或通过 dump/restore 迁移到新资源 |
-| 最后更新 | 2026-09-10 |
+| 最后更新 | 2026-09-24 |
 
-v1alpha1 不接管现有 database、role 或 OpenBao record。本流程通过逻辑 dump/restore 把
+当前设计支持管理员显式登记已有 Database；未知同名资源仍不得自动认领。
-数据迁移到 controller 创建的新资源，保留旧资源作为限时回滚点。
+导入不要求移动数据，不隐含改密码、owner、授权或删除权限。API 尚未实现，以下导入步骤
+是验收要求而非可直接执行的命令。
+
+## 显式导入与保留资源复用
+
+1. 核对 Instance、数据库、owner、角色权限、扩展、使用者与备份，确定允许管理的范围。
+2. 由管理员声明 Database，指定已有目标，回收策略默认 Retain；导入验证初始只读。
+3. 安全关联现有应用凭据；具体 API 待定，不把密码写入 CR，不因验证失败重置密码。
+4. 管理员授权目标 Tenant；controller 验证资源与申请符合要求并建立排他绑定。
+5. 验证实际登录与 ESO 交付；不满足时停止，不以修改原数据库作为默认修复。
+
+Released 资源复用前另需核实旧使用者的访问权限、数据交接与投射处置。保留旧绑定身份直到
+人工处理完成，不仅靠清空 claimRef 或修改 UID 授予新使用权。
+
+导入失败时原数据库应保持不变；撤回登记不得触发 Delete。绑定后的回退按 Retain 释放，
+检查新投射与访问授权的影响，不能承诺撤回 CR 自动恢复此前所有外部访问状态。
+
+## 可选的 dump/restore 路径
+
+不适合直接导入、需要改变 owner/权限模型或移动数据时，可使用下述逻辑迁移流程。
+它不是纳管现有数据库的唯一路径；保留旧资源作为限时回滚点。
 
 以下命令是顺序模板，不可原样复制到真实环境。先把尖括号变量解析成明确值，确认当前
 连接目标，再逐条执行。dump 可能包含敏感业务数据，必须放在加密临时存储且不得提交 Git。
@@ -67,8 +87,8 @@ identifier 必须由管理员工具安全引用，不能把未经校验的值直
 
 应用 `PostgreSQLTenant`，使用未被占用的 database/loginRole，等待 Ready。确认：
 
-- registry 记录 UID 正确；
+- Database/Instance 身份及 Tenant 排他绑定正确；
-- OpenBao metadata 属于该 Tenant；
+- OpenBao 凭据位置与 Database 管理范围及当前交付授权一致；
 - ExternalSecret Ready 且目标 Secret 已投射；
 - 新凭据可以通过 DNS host 和 IP hostaddr 分别登录空 database。
 
@@ -96,7 +116,7 @@ extension 应由 Tenant spec 创建。若 dump 仍包含 extension 定义，预
 ### 7. 收尾
 
 回滚窗口结束后，按独立变更删除旧 database/role/旧凭据；它们不属于 controller，禁止
-通过 Tenant `Delete` 清理。安全删除 dump 和临时凭据材料，并记录验证结果。
+通过新 Database 的 `Delete` 清理。安全删除 dump 和临时凭据材料，并记录验证结果。
 
 ## 回滚
 
@@ -105,9 +125,9 @@ extension 应由 Tenant spec 创建。若 dump 仍包含 extension 定义，预
 1. 立即停止新目标写入。
 2. 评估切换后是否产生新数据；若有，先决定反向迁移或接受丢弃，不能盲目切回。
 3. 将应用连接切回 retained database/role；若必须恢复原名称，先确保新受管目标已用
-   `Delete` 完整清理或改用不同名称，再安全地反向执行 rename。
+   资源侧 `Delete` 完整清理或改用不同名称，再安全地反向执行 rename。
 4. 恢复旧凭据（MD5 环境可能需要重设），验证旧服务。
-5. 保留失败 Tenant 供排障；选择 Retain 或 Delete 前明确其外部资源后果。
+5. 保留失败 Tenant 供排障；修改 Database 的 Retain/Delete 策略前明确其外部资源后果。
 
 若已经删除旧资源，则只能使用已验证备份恢复，不再属于本 runbook 的快速回滚。
 
@@ -115,6 +135,7 @@ extension 应由 Tenant spec 创建。若 dump 仍包含 extension 定义，预
 
 发布首个可用版本前，必须在临时 PostgreSQL/OpenBao/Kind 环境执行本文并记录：
 
+- 显式导入与 Released 重新绑定的授权、旧访问处置和失败不修改原资源；
 - 使用的 PostgreSQL major version 和命令版本；
 - dump/restore 返回码和对象差异；
 - DNS/IP TLS 登录结果；

docs/database/operations.md

@@ -1,76 +1,67 @@
 # 运维与故障处理
 
-| 项目 | 内容 |
+状态：设计合同，操作入口待 API 实现与隔离环境演练。日期：2026-09-24。
-| --- | --- |
+依据 [系统规格](specification.md)，不再查询或维护 PostgreSQL registry。
-| 状态 | Review；命令待实现后演练 |
-| 最后更新 | 2026-09-10 |
 
 ## 日常检查
 
-先看 API 合同，而不是从日志猜状态：
+先看 Instance、Database、Tenant 的 Ready Condition、绑定 UID、阶段与 observedGeneration，
+再核对 PostgreSQL catalog、OpenBao metadata、ExternalSecret 与 Secret 投射状态。
+具体 kubectl 资源名、finalizer 名称与人工确认字段在 API 实现后补齐，不提供猜测的 patch 命令。
+不得把 Secret data、密码或带 Token 的请求粘贴到 issue/日志。
 
-```sh
+## 故障分类
-kubectl get postgresqlinstances
-kubectl get postgresqltenants -A
-kubectl get postgresqltenant -n <namespace> <name> -o yaml
-kubectl describe postgresqltenant -n <namespace> <name>
-```
 
-随后检查 controller 日志、ExternalSecret/Secret、OpenBao metadata、registry 和
+| Reason/状态 | 首要检查 |
-PostgreSQL catalog。排障时不得把 Secret data 或带 Token 的请求粘贴到 issue/日志。
-`status.phase` 是 controller 状态机 checkpoint，也用于定位当前步骤；`Ready`
-Condition/Reason 用于判断对外结果。phase 不能替代外部事实，清空或不一致时应由
-controller 自动重建/纠正。
-
-## 常见 Reason
-
-| Reason | 首要检查 |
 | --- | --- |
-| `InvalidSpec` / `ImmutableField` | API 字段、identifier、不可变/只追加约束 |
+| InvalidSpec / ImmutableField | 请求、名称、不可变目标与只追加扩展约束 |
-| `DependencyUnavailable` | 网络、DNS、服务状态和超时 |
+| DependencyUnavailable | 网络、DNS、服务状态和超时；恢复后退避重试 |
-| `AuthenticationFailed` | 管理凭据、CA、DNS/IP SAN、OpenBao auth |
+| AuthenticationFailed | 管理 Secret、TLS、OpenBao auth |
-| `InsufficientPrivileges` | PostgreSQL grants、OpenBao policy、Kubernetes RBAC |
+| InsufficientPrivileges | PostgreSQL/OpenBao 权限与 Kubernetes RBAC |
-| `InstanceNotReady` | 先恢复所引用 Instance |
+| InstanceNotReady | 当前目标的管理能力，不检查 registry |
-| `Conflict` | registry UID、同名 DB/role、OpenBao metadata；禁止直接覆盖 |
+| Conflict | 绑定 UID、未知同名资源、失败步骤与外部结果确定性 |
-| `CredentialProjectionFailed` | ClusterSecretStore、ExternalSecret Condition、目标 Secret |
+| CredentialProjectionFailed | 授权的凭据位置、Store、ESO 与目标 Secret |
-| `ProvisioningFailed` | `status.phase` 及对应外部资源的回读结果 |
+| Released | 资源已保留，不代表可直接交给另一个 Tenant |
 
-修复依赖后让正常 reconcile 自动重试。不要通过删除/重建 CR 规避 Conflict；新 UID 只会
+## 创建不确定或同名冲突
-使已有保留资源继续冲突。
 
-## Retain 后的资源
+1. 保留 CR、绑定与安全诊断，不清空 status、不反复删除重建申请。
+2. 核对确切 Instance/database/role 和凭据位置；区分已确认完成与结果不确定的操作。
+3. 使用只读检查确认资源内容、使用者和权限，不通过重设密码来“验证归属”。
+4. 管理员决定清理确定的残留后重试，或显式导入保留资源；涉及删除需另有明确授权。
+5. 记录处理依据，再按 API 的受控入口恢复协调。
 
-Retain 删除完成后，database、role、OpenBao record 和 registry 所有权记录仍存在但标记
+普通依赖故障可以自动继续，未知归属不得因后端恢复就自动认领。
-unmanaged。v1alpha1 不支持重新关联。需要恢复管理时，使用 [`migration.md`](migration.md)
+controller 重启保留 Kubernetes 中的记录，不需要恢复第二套 registry。
-把数据迁移到一个全新受管名称；不要手工把 registry UID 改成新 CR UID。
+
+## Retain 与重新绑定
+
+Tenant 删除后 Database 及实际资源保留，进入 Released，保存旧绑定身份。
+不要删除 Database 对象来“释放名称”，也不要只修改 UID 或 Ready 强行交付。
+
+管理员先确认数据是否允许交给新使用者、旧角色是否共享、旧账号访问如何撤销或保留、
+新使用者如何获得凭据，以及原 ExternalSecret/Secret 的处置。删除 Secret 不会撤销已持有密码
+的 PostgreSQL 访问。完成这些处置后，才通过显式授权重新绑定；不自动回到可分配状态。
+具体凭据关联与解除绑定字段尚待 API 评审，当前不能宣称已有可执行恢复命令。
 
 ## Delete 卡住
 
-1. 暂停应用写入并记录 Tenant UID、Instance UID、database、role 和 Bao path。
+核对 Database/Instance/绑定身份、资源侧 Delete 授权及实际管理范围，修复相关依赖，
-2. 从 registry 和 OpenBao metadata 独立确认所有权。
+让 controller 从已确认的步骤继续。不要删除共享角色或未纳管凭据，不使用扩大范围的 CASCADE。
-3. 检查删除阶段，修复 PostgreSQL/OpenBao/ESO 依赖，让 controller 继续。
-4. 若依赖永久丢失，列出每个可能残留的 database、role、KV metadata 和 Secret。
-5. 只有确认接受这些残留后，才人工移除 finalizer。
 
-最终 finalizer 名称由 API 实现固定后补入命令。人工移除 finalizer不会执行剩余清理，
+依赖永久丢失时列出每个可能残留的数据库、角色、凭据与投射。只有管理员接受残留与后续处置
-也不会把外部资源变成可由新 CR 接管的资源。
+责任后才人工移除确切对象的 finalizer。该操作不会完成清理，也不会授权新申请使用残留资源。
 
 ## 备份与恢复
 
-- PostgreSQL VM/磁盘备份必须与数据库一致性策略配套；仅复制在线磁盘不自动等于有效
+分别备份 PostgreSQL 数据、Kubernetes 资源与绑定记录、OpenBao 数据及必要配置。
-  PostgreSQL 备份。
+不再要求备份专用 registry。只复制在线磁盘不等于有效数据库备份；秘密备份必须加密并限制访问。
-- PostgreSQL 备份必须包含管理 database 中的 controller registry。
-- OpenBao 使用独立的受支持备份/快照流程，且恢复点应与 PostgreSQL 尽量接近。
-- Kubernetes 侧备份 CR、controller 配置、ClusterSecretStore 和公开 CA bundle，不备份
-  明文 Secret 作为凭据事实来源。
-- 定期在隔离环境执行恢复演练，验证 registry、KV metadata、应用登录及 Retain/Delete。
 
-恢复后先停止 controller，核对 PostgreSQL/OpenBao 时间点与 UID 映射，再启动单副本
+灾难恢复先暂停 controller，核对三者恢复点、UID、外部目标与凭据的一致性，再恢复协调。
-controller 观察；出现一侧存在、一侧缺失时不得手工生成新密码或改 registry，应先按
+不一致时按 Conflict 人工处理，不承诺仅凭外部同名数据库重建丢失绑定。
-Conflict 处理并决定恢复哪一侧。
+在隔离环境演练登录、导入、Retain、重新绑定与 Delete 后才能标记验证通过。
 
-## 升级与紧急停止
+## 紧急停止
 
-有疑似越权删除或凭据泄漏时，先把 controller Deployment scale 到 0，保留 CR、registry
+疑似越权删除或秘密泄漏时暂停 controller，保留 CR 与脱敏证据，限制相关管理身份权限，
-和日志证据，再撤销 OpenBao token/role 并限制 PostgreSQL 管理 role。恢复前在隔离环境
+在隔离环境复现并确认修复后恢复。一般依赖失败不需要停机。
-复现并确认不会扩大破坏。一般依赖故障无需 scale down，最终一致性会自动重试。

docs/database/security.md

@@ -3,13 +3,13 @@
 | 项目 | 内容 |
 | --- | --- |
 | 状态 | Review |
-| 最后更新 | 2026-09-10 |
+| 最后更新 | 2026-09-24 |
 
 ## 保护目标
 
 - 应用密码只存在于 OpenBao、ESO 投射的目标 Secret 和需要使用它的进程内存中。
-- controller 只能修改其 registry 能证明归属当前 Tenant UID 的资源。
+- controller 只能在 Database 已确认的管理范围和当前绑定/操作授权内修改资源；未知同名对象报冲突。
-- namespace 租户不能越权管理 Instance、其他 namespace 或 controller 配置。
+- namespace 租户不能越权管理 Instance、Database 导入/回收、其他 namespace 或 controller 配置。
 - PostgreSQL 和 OpenBao 的网络身份使用受信 CA 验证，不因 DNS 不可用而降级 TLS。
 
 ## 信任边界
@@ -18,15 +18,15 @@ Kubernetes 管理员、OpenBao 管理员和 PostgreSQL 管理员是平台信任
 目标 Secret 或对应 OpenBao path 的主体等同于持有数据库账号。database owner 可以
 改变自己 database 内的对象，因此 COMMENT 不能作为 controller 所有权依据。
 
-VM/磁盘备份会包含 PostgreSQL registry 和租户数据，但不应包含 OpenBao 中的密码；完整
+数据库备份包含业务数据；Kubernetes 保存资源与绑定记录；OpenBao 保存应用凭据。
-灾难恢复必须同时保护 PostgreSQL 与 OpenBao，并控制两份备份的访问权限。
+完整灾难恢复必须分别保护三者并核对恢复点，不依靠数据库内 registry 重建绑定。
 
 ## 凭据处理
 
 - controller 使用 Kubernetes auth 获取短期 OpenBao token，不配置长期静态 token。
 - 管理凭据只从 Instance 引用的 controller namespace Secret 读取，不复制到
   CR/status/Event/metric/trace；管理员维护 ExternalSecret，由 ESO 同步该 Secret。
-- 租户密码使用密码学安全随机源生成一次；中断恢复必须复用 OpenBao 现值。
+- 动态供应密码使用密码学安全随机源；已有可靠关联时复用 OpenBao 现值，结果不确定时停止并报冲突。
 - controller 创建 ExternalSecret，不直接创建含 data/stringData 的 Secret。
 - 日志字段允许 namespace/name、UID、generation、阶段和错误类别；禁止记录请求/响应体、
   DSN、Authorization header、密码或完整 OpenBao URL path 作为 metric label。
@@ -51,13 +51,15 @@ PostgreSQL 管理 role 不应是 superuser。若平台选择 SECURITY DEFINER
 删除操作，函数必须固定 `search_path`、严格校验 identifier、拒绝任意 SQL，并仅向
 controller role 授予 EXECUTE。controller 不调用 shell 或 `psql` 拼接用户输入。
 
-Kubernetes RBAC 应把 cluster-scoped Instance 管理限制给平台管理员。Tenant editor
+Kubernetes RBAC 应把 Instance 管理、Database 导入、预留、重新绑定授权和回收限制给平台管理员。
+知道 Database 名称不等于有权使用；Tenant editor
 不自动获得 Secret read；是否读取目标 Secret 由 namespace 内独立 RBAC 决定。
 
 ## 删除保护
 
-Delete 是明确的数据销毁授权，但仍必须在每一步校验 Instance UID、Tenant UID、名称和
+资源侧 Delete 是明确的数据销毁授权，但仍必须在每一步校验 Instance/Database UID、
-OpenBao metadata。禁止对未知对象使用 `CASCADE`。删除 finalizer 卡住时只能按
+绑定、实际目标及角色/凭据管理范围；CR 中记录了意图不等于外部对象由本系统创建。
+禁止对未知对象使用 `CASCADE`。删除 finalizer 卡住时只能按
 [`operations.md`](operations.md) 核实外部状态后人工移除；该操作可能遗留资源。
 
 ## 发布前安全验收
@@ -68,4 +70,6 @@ OpenBao metadata。禁止对未知对象使用 `CASCADE`。删除 finalizer 卡
 - 应用 login 不能创建 role/database，也不能连接其他租户 database。
 - 日志、Event、Condition、metrics、CR 导出和测试 artifact 不含 canary password/token。
 - 伪造 COMMENT、同名 database/role 或错误 UID metadata 均不能绕过 Conflict。
-- Delete 只销毁 registry 可证明归属当前 Tenant 的资源。
+- Delete 只销毁 Database 已确认管理范围内且获得删除授权的资源。
+- 导入检查不改密码/owner，Released 不自动授权新使用者；旧访问处理后才能重新交付。
+- 导入默认 Retain；角色/凭据的管理与删除范围未明确时不得扩大操作范围。

docs/database/specification.md

@@ -1,558 +1,207 @@
-# PostgreSQL Tenant Operator 系统规格说明书
+# Ayatori Database 系统规格
 
 | 项目 | 内容 |
 | --- | --- |
-| 状态 | Approved |
+| 状态 | 资源模型与生命周期已批准；字段协议待 API 评审 |
 | 目标 API | `database.ayatori.ddupan.top/v1alpha1` |
-| 最后更新 | 2026-09-13 |
+| 最后更新 | 2026-09-24 |
-| 批准日期 | 2026-09-10 |
+| 决策 | [ADR-0009](../decisions/0009-database-resource-and-claim.md) |
-| 规范范围 | 首次注册外部 PostgreSQL 实例并创建一个应用租户 |
 
-本文档定义系统对用户和外部依赖呈现的行为，是 API、测试和实现共同遵守的合同。
+本文是当前行为合同，替代旧的 Tenant 同时承担申请与资源生命周期、PostgreSQL registry
-实现若需要改变本文合同，必须先修改规格并重新获得批准。
+持久所有权、任意 status 丢失自动恢复的设计。批准设计不表示实现已完成。
+未决字段不能由实现自行补成新产品约定。
 
-文中的“必须”“禁止”“应当”“可以”分别对应强制要求、强制限制、推荐行为和可选
+## 1. 范围
-行为。
 
-## 1. 背景
+在已存在的 PostgreSQL 实例上供应独立数据库、一个兼任 owner 的 login role、申请的扩展及
+应用凭据；支持管理员显式导入已有数据库。Kubernetes API 管理声明与绑定，OpenBao 保存
+应用凭据，ESO 向应用 namespace 投射 Secret。
 
-homelab 中的大部分应用共享一个运行在独立 VM 上的 PostgreSQL DBMS。应用需要各自
+不运行 PostgreSQL、VM、存储、备份或 OpenBao；不提供跨实例数据迁移、自动密码轮换、
-独立的 database、作为 owner 的 login role 和密码，但不需要独立 PostgreSQL 实例。
+多角色权限产品或跨系统事务。备份与数据恢复仍由管理员负责。
-目前这些资源依靠人工 SQL 和人工 Secret 管理，难以重复、审计和检测漂移。
 
-本系统使用 Kubernetes CRD 作为声明式 API，持续协调外部 PostgreSQL 与 OpenBao：
+## 2. 资源与职责
 
 ```text
-PostgreSQLInstance / PostgreSQLTenant
+Instance
-                  |
+  └─ Database × N          独立持久资源
-                  v
+       └─ Tenant × 0..1    排他绑定的用户申请
-      Ayatori Database controller
-          |                 |
-          v                 v
- PostgreSQL catalog    OpenBao KV v2
 ```
 
-## 2. 目标
+| 资源 | 职责 | 不承担的职责 |
-
-v1alpha1 必须实现以下目标：
-
-1. 注册一个已经存在的外部 PostgreSQL 实例并报告连接状态。
-2. 为一个应用租户创建独立 database 和一个同时作为 database owner 的 login role。
-3. 根据实例实际可安装扩展列表检查并安装租户申请的 PostgreSQL extension。
-4. 首次生成高强度长期密码，并只把凭据明文写入 OpenBao KV v2。
-5. 为 Kubernetes 应用创建 ExternalSecret，由 ESO 将凭据投射到同 namespace Secret。
-6. 同时输出 OpenBao API URL，使 Kubernetes 外的应用可以直接读取凭据。
-7. 同时输出 PostgreSQL DNS hostname 和 IP address，不假定所有消费者都能使用集群内
-   DNS。
-8. 持续检测并修正由本系统管理的非破坏性漂移。
-9. 通过 Kubernetes Condition 报告进度、成功和可操作的失败原因。
-10. 重复 reconcile、controller 重启及外部依赖暂时失败不得重复创建或破坏资源。
-11. 删除 Tenant CR 时默认保留外部资源；显式选择 `Delete` 时提供完整清理路径。
-
-## 3. 非目标
-
-v1alpha1 不负责：
-
-- 创建、升级、备份或高可用运行 PostgreSQL DBMS/VM；
-- 创建或运维 OpenBao；
-- 直接写入包含凭据明文的 Kubernetes Secret；Secret 必须由 ESO 投射；
-- 动态凭据、定时或自动密码轮换；
-- Web UI、独立 REST API 或 Backstage 插件；
-- 跨实例迁移 database；
-- schema/table 级别租户、多 login role 或跨租户 grant；
-- 删除不属于本系统管理的 database、role、extension 或 OpenBao Secret；
-- 接管不是由本系统创建的外部资源；
-- 提供生产环境 SLA。
-
-## 4. 参与者与事实来源
-
-| 对象 | 事实来源 | 说明 |
 | --- | --- | --- |
-| 期望状态 | Kubernetes CR `spec` | 用户声明的合同 |
+| Instance | 登记实例、管理连接、能力与供应前置条件 | 持有租户集合、保存所有权表 |
-| 最近观察结果与当前阶段 | Kubernetes CR `status` | 可以丢失并重建，不是外部事实来源 |
+| Database | 描述外部数据库、管理范围、绑定与回收策略 | 充当第二套 registry 或通用资源框架 |
-| database/role/grant/extension | PostgreSQL catalog | 每轮 reconcile 必须重新读取 |
+| Tenant | 声明需求或显式选择资源，申请使用并交付凭据 | 删除时隐式销毁独立资源记录 |
-| 受管资源所有权与保留标记 | PostgreSQL controller registry | 与受管 DBMS 一起备份和恢复 |
-| controller 工作流阶段 | Kubernetes CR `status.phase` | 状态机 checkpoint；可由外部事实保守重建 |
-| 应用凭据 | OpenBao KV v2 | Kubernetes API 中不得出现明文 |
-| Kubernetes 凭据投射 | External Secrets Operator | ExternalSecret 由本 controller 管理 |
-| PostgreSQL 管理凭据 | controller namespace 的 Kubernetes Secret | 管理员维护 ExternalSecret，由 ESO 同步；Instance 只引用 Secret |
 
-平台管理员管理 `PostgreSQLInstance`、controller 部署配置、OpenBao policy 和
+Instance 保持 cluster-scoped，Tenant 保持 namespaced。Database 的工作名称是
-PostgreSQL 管理 role。应用或 GitOps 流程在获得 namespace RBAC 后管理
+PostgreSQLDatabase；scope、字段拼写和管理角色/凭据的具体边界待 API 评审。
-`PostgreSQLTenant`。
+单 database + 单 login owner 的首版使用场景不变，不新增独立 Role 或 Claim CRD。
 
-## 5. 资源模型
+Database 自身必须声明 `instanceRef`，手工登记时同时指定实际数据库名；无需先存在 Tenant，
+即可通过 Instance 验证目标。动态申请由 Tenant 选择 Instance，供应时把该引用写入 Database；
+选择已有 Database 的 Tenant 从资源获取 Instance，不重复指定另一份来源。资源与实例的归属
+独立于使用绑定，Tenant 删除后仍保留；修改引用不是数据库迁移。
 
-### 5.1 PostgreSQLInstance
+参考 [Kubernetes PV/PVC](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) 的
+资源/申请分离与绑定生命周期，不复制存储调度和 CSI 协议。资源与申请的关系不是 GC 所有关系。
 
-`PostgreSQLInstance` 是 cluster-scoped 资源，表示一个已经存在、可由 controller
+## 3. 身份与事实来源
-管理的 PostgreSQL server。
 
-它必须声明：
+- Kubernetes spec 保存声明；受保护的资源绑定记录与 status 保存身份关联、操作进度和观察。
+  它们通过 API 持久化，不因 controller 重启而消失。
+- PostgreSQL catalog 是 database、role、grant、extension 实际状态的来源。
+- OpenBao 是应用凭据的事实来源；ESO 状态和目标 Secret 存在性说明投射结果。
+- Instance、Database、Tenant 以 UID 区分对象身份；namespace/name 用于定位，
+  同名新 UID 不继承旧绑定。数据库 OID 仅供诊断，不是永久身份或删除授权。
+- 不新增 PostgreSQL 所有权表、安装身份表或 Retain 墓碑；COMMENT 也不能授权认领。
+- 记录操作意图不等于外部操作成功，phase 不等于外部所有权；执行前后仍须观察实际状态。
 
-- PostgreSQL host、port 和管理连接使用的 database；
+## 4. Instance 合同
-- PostgreSQL host address，供无法解析 DNS 的消费者使用；
-- TLS mode；
-- controller namespace 中 PostgreSQL 管理 Secret 的名称和字段名。
 
-可安装的 extension 集合由应用层从目标 PostgreSQL 查询，不由管理员在 Instance
+Instance 声明 host、hostaddr、port（默认 5432）、管理 database（默认 postgres）、
-中声明。v1alpha1 不实现 allowlist；该概念保留为后续可选策略。实际可用不代表安装
+TLS mode（默认 verify-full）及 controller namespace 的管理 Secret 名称和字段映射。
-权限及前置条件已满足，安装仍需执行并回读；查询失败不得被解释为扩展不支持。
+禁止隐式 TLS 降级。凭据引用不接受自选 namespace 或 OpenBao path。
 
-实例 Ready 不代表 PostgreSQL 数据有备份或高可用，只表示 controller 当前可以安全
+管理员维护 ExternalSecret，由 ESO 同步管理 Secret；controller 只读，不修改管理密码，
-建立管理连接、读取 server metadata、访问 controller registry 并使用所需管理能力。
+不直接从 Bao 取管理凭据。有效用户名或密码变化时释放旧连接并重验；仅 metadata 或无关
+字段变化不重建。中途凭据变化必须丢弃旧观察。已有有效管理凭据时，Bao/ESO 故障本身
+不撤销 Instance Ready；首次缺少有效 Secret 时不能 Ready。
 
-Instance 身份和 endpoint 以管理员声明为准。修改 endpoint 不验证是否仍是原物理
+Ready 要求当前目标的连接、服务器 metadata 和所需管理能力检查通过，不要求创建、
-服务器或原 registry，不增加服务器／安装身份绑定检查；但旧配置观察失效，必须按
+迁移或读取 registry，也不证明备份或高可用。阶段简化为 Pending → Validating → Ready，
-新配置重新检查连接和管理能力。新 CR 按新 Instance 处理，不自动接管旧 UID 的租户
+删除进入 Deleting。实际扩展可用列表不等于安装权限；查询失败不等于不支持。
-资源。controller 不迁移旧服务器上的数据，也不清理旧目标，影响由管理员负责评估。
 
-Instance 开始受管时即添加 finalizer，成功保存后才参与供应，不等发现 Tenant 后
+endpoint 变更由管理员负责评估，不验证物理服务器连续性，不迁移或清理旧目标；
-再补加。删除期间停止新供应；仍有引用它的 Tenant（包括正在删除的 Tenant）时保留
+旧观察失效。新 UID 不接管旧资源。Instance 开始受管前保存 finalizer；删除时停止新供应，
-finalizer，无引用后才移除。不级联删除 Tenant 或任何外部数据库、角色、凭据。
+只要有引用它的 Database（包括 Released/删除中）或尚未绑定的 Tenant 就等待。
-引用检查失败不得当作无引用。首版不引入跨对象锁或准入控制：finalizer 不禁止同时
+查询失败不视为无引用；无引用才解除 finalizer，不级联删除任何业务资源。
-创建 Tenant CR，新 Tenant 遇到正在删除或已不存在的 Instance 时不得开始供应。
+引用检查不是跨对象事务，正在删除或不存在的 Instance 不允许开始新的供应/绑定。
-这不保证列表检查、CR 创建和在途外部操作之间的原子性；不是严格的跨对象事务。
 
-### 5.2 PostgreSQLTenant
+## 5. 动态供应与排他绑定
 
-`PostgreSQLTenant` 是 namespaced 资源。v1alpha1 中，一个 Tenant 精确对应：
+1. 校验 Tenant 请求、Instance 能力、名称和扩展要求。
+2. 在首次外部写入前持久化独立 Database 记录、确定目标与管理范围。
+3. 建立带 UID 的排他预留/绑定，避免两个 Tenant 同时使用同一 Database。
+4. 按已确认步骤建立凭据、role、database、授权和扩展，逐步回读。
+5. 验证应用登录与 ESO 投射后，Tenant 才可 Ready。
 
-- 一个 `PostgreSQLInstance`；
+绑定前固定有效目标；绑定或开始外部供应后不得通过修改名称或引用实施隐式迁移。
-- 一个 database；
+每个 Database 最多一个使用者，每个 Tenant 最多一个 Database。
-- 一个同时作为 database owner、供应用使用的 `LOGIN` role；
+绑定 API 写入采用 resourceVersion 并发控制；双向记录不原子，单边完成不得授予使用权限。
-- 零个或多个 extension；
+具体字段、写入顺序与重启恢复协议须在 API 切片定义，并由真实 API server 验证。
-- 一个 OpenBao KV v2 凭据位置；
-- 一个同 namespace ExternalSecret 及其目标 Kubernetes Secret。
 
-Tenant 的 namespace 用于 Kubernetes RBAC 和身份识别，不代表 PostgreSQL schema。
+不同 Database 记录请求同一外部名称仍可能竞争，不能仅靠 Kubernetes 中的列表检查保证
-同一 Instance 中的 database 和 role 名称全局唯一。
+PostgreSQL 名称唯一。后端创建时的重名失败报告 Conflict，失败方不得接管胜方资源。
+不为此新增跨系统锁或 registry。管理员也不得把同一物理数据库登记成多个可绑定资源。
 
-## 6. 标识与默认值
+## 6. 显式导入
 
-以下是 v1alpha1 的标识合同：
+管理员创建资源声明，明确 Instance、已有数据库和允许管理的范围，构成导入授权。
+初始检查只读验证存在性、owner、角色权限和扩展等是否匹配；不匹配报告清楚的差异，
+不得通过重置密码、改变 owner 或撤销现有访问来“完成导入”。
 
-| 字段 | 默认值 | 约束 |
+未显式导入的同名数据库一律 Conflict。导入资源默认 Retain，不隐含 Delete 授权。
-| --- | --- | --- |
+Tenant 显式引用已登记资源仍需通过绑定资格与授权检查；知道资源名称不等于有权使用。
-| Instance port | `5432` | 1–65535 |
+资源侧预留/授权的具体 API 和已有凭据的安全关联入口待细化，完成前不能宣称可用。
-| Instance host address | 无 | 必须是合法 IPv4 或 IPv6 address |
-| 管理 database | `postgres` | 合法 PostgreSQL identifier |
-| TLS mode | `verify-full` | 禁止隐式降级 |
-| Tenant database | `metadata.name` | 同一 Instance 全局唯一 |
-| login role | `metadata.name` | 同一 Instance 全局唯一 |
-| deletion policy | `Retain` | `Retain` 或 `Delete` |
 
-Tenant 的 `spec.instanceRef` 与 `metadata.name` 长度合计不得超过 241 个字符，确保
+## 7. Retain、重新绑定与 Delete
-派生的 ExternalSecret/Secret 默认名称
-`<instanceRef>-<metadata.name>-postgresql` 不超过 Kubernetes 253 字符限制。
 
-固定默认值由 CRD defaulting 写入。依赖 `metadata.name` 或 `instanceRef` 的 database、
+回收策略属于 Database，默认 Retain；Tenant 删除是释放申请，不是独立资源的 GC 授权。
-login role、ExternalSecret/Secret 名称属于 controller 语义默认值：省略字段不会被 admission
+Database 不得设置会让它随 Tenant 消失的 ownerReference。
-回写，controller 必须始终计算同一个 effective value，并通过 status 的 database、
-loginRole、credential reference 以及实际资源展示。
-v1alpha1 不为此引入 mutating webhook。
 
-database 和 role 名称必须作为 PostgreSQL identifier 参数安全引用，禁止通过字符串
+### Retain
-拼接执行。名称校验必须拒绝空字符串、NUL 和超过 PostgreSQL identifier 长度限制的
-值，并统一限制为小写字母、数字和下划线。
 
-Tenant 首次成功后，`instanceRef`、database、login role 和凭据位置必须
+- 保留 Database 对象、外部数据以及与资源关联的角色和凭据，不自动删除或重置。
-不可变。修改这些字段不是 rename 或 migration，API 必须拒绝或报告明确的
+- Tenant 释放后 Database 进入 Released，保留旧绑定身份用于诊断和防止自动复用。
-`ImmutableField`。
+  Released 不是 Available，不再向原申请交付新状态，也不自动分配给同名新 Tenant。
+- 保留策略不要求 PostgreSQL/Bao 在线才能完成申请释放，但必须先将释放关系安全记录到
+  Kubernetes；API 写入失败时不能宣称释放完成。仍有在途操作时不得跳过必要协调。
+- 管理员检查数据、旧账号访问与凭据后，显式授权重新绑定。保留数据的复用可以不清空数据，
+  但必须由管理员确认新使用者应获得这些数据及旧使用者的权限处置。
+- 删除旧投射 Secret 或解除绑定不等于撤销 PostgreSQL 访问；Retain 不承诺自动撤权。
+  ExternalSecret/Secret 的保留与清理细节需随凭据交付协议明确。
 
-## 7. PostgreSQL 权限合同
+### Delete
 
-建议的 v1alpha1 权限模型如下：
+必须由有权限的主体在资源侧明确授权，并核对 Database 身份、绑定、实际对象和管理范围。
+在相关 finalizer 保护下清理投射、阻止新登录、处理已有连接、删除 database，再按已确认的
+独占管理范围清理 role 与凭据；共享或未纳管的对象不得删除，禁止扩大 CASCADE 范围。
 
-1. database 必须由 login role 拥有。
+每步回读，失败保持进度与 finalizer；确认已删除的对象可幂等跳过，未知同名对象不能继续删除。
-2. login role 必须是 `LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION`。
+数据库被使用时，直接删除 Database 不得绕过绑定保护。资源已释放后才按策略处理。
-3. 必须撤销 `PUBLIC` 对租户 database 的连接权限，再显式允许 login role 连接。
+具体 Tenant/Database finalizer 配合与投射清理顺序须经 API 设计及故障注入验收。
-4. controller 不得修改其他 database 或无关 role 的权限。
-5. controller 只保证请求的 extension 存在；移除 extension 不得自动执行
-   `DROP EXTENSION`。
 
-这意味着应用可以在自己的 database 内执行 schema migration，但不能创建其他
+## 8. 幂等、失败与人工处理
-database、role 或访问其他租户。v1alpha1 不创建只有形式意义、却未隔离运行时权限的
-额外 `NOLOGIN` owner。若以后应用能分别使用 migration 和 runtime 凭据，再通过新的
-权限 profile 引入 owner/migrator/runtime 角色模型。
 
-## 8. OpenBao 凭据合同
+普通依赖故障退避重试。已持久确认且仍与观察一致的步骤可以幂等继续；controller 重启
+不重新生成密码，不重复创建已确认资源。
 
-### 8.1 Controller 自身认证
+外部创建成功但记录尚未保存，或超时导致结果不确定时，若不能可靠确认归属，报告
+Conflict 并停止相关写入；不得仅凭名称相同、曾记录意图或字段相似自动认领。
+失败恢复不承诺全部自动完成，也不实现队列模拟事务。
 
-controller 必须使用 Kubernetes auth 登录 OpenBao。controller 使用的 OpenBao API
+status 缺失不假定发生于正常重启。Instance 可重新探测能力；Database/Tenant 缺少绑定或
-address、提供给消费者的 OpenBao API address、auth mount、auth role 和 KV v2 mount
+操作确认时不能从外部同名对象推导所有权。按冲突/灾难恢复处理，不自动重建所有权表。
-属于部署配置，不属于任何 CR。两个 API address 可以相同；若 controller 使用集群内
-地址而外部消费者不能解析，则必须单独配置 consumer address。生产部署的 KV mount
-默认为 `kv`；开发环境可以配置为 OpenBao dev server 默认的 `secret`。长期 OpenBao
-Token 禁止写入 Deployment、CR 或镜像。
 
-### 8.2 管理凭据
+人工处理必须能看到：请求与资源身份、目标 Instance/database/role、失败步骤、已确认完成
+与结果不确定的操作、冲突原因、下一步核实建议。保留现场，不自动删除疑似残留或改密。
+管理员核实后可清理确定的残留再重试，或走显式导入；不能通过伪造 Ready/清空 status 强行继续。
 
-`PostgreSQLInstance` 只引用 controller 自身 namespace 中 Kubernetes Secret 的名称及
+## 9. 权限、凭据与扩展
-用户名、密码字段名，不允许指定 namespace 或 Bao path。endpoint 仍由 Instance 声明。
-平台管理员维护 ExternalSecret，将 OpenBao 管理凭据同步到该 Secret；controller 只读
-Secret，不创建或修改管理 Secret、其 ExternalSecret 或上游管理凭据。
 
-Instance 管理连接不直接访问 Bao，不负责管理密码轮换。已装配的凭据仍可访问
+动态供应继续使用一个兼任 database owner 的 LOGIN role；应用角色不得具备 superuser、
-PostgreSQL 且满足 registry／权限要求时，Bao 或 ESO 暂时不可用不使 Instance NotReady。
+CREATEDB、CREATEROLE 或 replication 权限。撤销 PUBLIC CONNECT，再授予目标角色；
-首次装配无法取得有效 Secret 时不能 Ready。检测到所引用 Secret 的有效用户名或密码
+不修改无关数据库和角色。identifier 匹配 `^[a-z][a-z0-9_]{0,62}$`，SQL 安全引用。
-变化时，controller 使用新值重建管理连接池并重新检查管理能力；仅 metadata 或无关
-字段变化不触发重建。刷新不依赖 Instance generation 变化，新连接验证失败按实际
-故障报告，不能用旧连接的成功结果证明新凭据可用。
-controller 不修改 PostgreSQL 密码、不回写 Secret，也不修改 Bao 管理凭据；数据库侧
-凭据变更由管理员负责。这是跟随已提供凭据的连接刷新，不是自动密码轮换。
-Tenant 凭据管理仍直接依赖 Bao。
 
-### 8.3 租户凭据
+请求扩展按实例实际可用集合判断，成功后只追加，不自动 DROP EXTENSION。
+可用列表查询失败按依赖错误处理；实际安装仍检查权限与结果。
 
-Tenant 不声明凭据 path。controller 根据部署级 KV mount、base path 和 Tenant 的
+应用密码使用安全随机源，只写 OpenBao；已有可信凭据可复用，不因失败生成第二份密码。
-namespace/name 推导唯一的 mount-relative path。base path 来自 controller 启动参数
+新建时先安全保存并回读凭据，再创建角色；凭据写入本身结果不确定也适用人工冲突规则。
-`--openbao-tenant-base-path`，默认 `postgresql-tenants`。最终路径为
+Kubernetes 应用由 ESO 投射同 namespace Secret，controller 不直接写明文 Secret。
-`<base-path>/<namespace>/<metadata.name>`。推导结果禁止以 `/` 开头，禁止包含空路径段、
-`.`、`..`，也禁止把 KV v2 HTTP API 的 `data` 或 `metadata` 层编码进路径。
 
-新 Tenant 的凭据建立顺序必须可从任意中断点恢复：
+凭据仍输出 username/password/database/host/hostaddr/port/sslmode 七键，不生成带密码 URI。
+Tenant status 提供 Secret 引用与无认证信息的 OpenBao API URL。
+mount/base path 属部署配置，Tenant 不得自选任意路径；原按 Tenant namespace/name 固定
+推导路径的规则需修订为可支持资源保留与重新绑定的定位协议，本轮不定字段或新路径格式。
+不得因换 Tenant、改部署参数或重新绑定就隐式搬迁凭据或改密。
 
-1. 验证 Instance、名称、extension 和目标 OpenBao 路径；
+TLS、OpenBao Kubernetes auth、controller/ESO 身份隔离、Secret 读取范围和防泄漏要求
-2. 确认目标 database、role 和 OpenBao 记录不存在，或能够验证为同一 Tenant
+见 [安全模型](security.md)。这些安全约束继续适用。
-   已创建的部分状态；
-3. 生成密码；
-4. 先创建带 controller 所有权 metadata 的 OpenBao KV v2 记录；
-5. 从 OpenBao 重新读取凭据；
-6. 使用该凭据创建作为 database owner 的 login role 和其他 PostgreSQL 资源；
-7. 用 login role 实际连接目标 database；
-8. 全部验证成功后将 Tenant 标记 Ready。
 
-若第 4 步成功、后续 PostgreSQL 操作失败，下一轮必须读取同一份 OpenBao 凭据继续，
+## 10. Conditions 与可观测性
-不得生成第二个密码。若 PostgreSQL 先存在而 OpenBao 记录不存在，controller 必须报告
-Conflict，不得擅自重置已有 role 密码。
 
-controller 必须在 PostgreSQL 管理 database 的专用 registry schema 中持久保存可验证的
+三类资源均提供唯一的 Ready Condition 及 observedGeneration，phase 只辅助表示阶段。
-Instance UID、Tenant UID 与 namespace/name 关联，不能只依赖会丢失的 CR status 判断
+Ready=True 必须有当前目标的实际验证；Database 已绑定不等于 Tenant 凭据交付已经完成。
-资源所有权。registry 必须可回读且不得改变数据库授权语义；database 或 role COMMENT
-不能作为权威所有权记录。
 
-默认写入字段固定为：
+至少区分 Reconciling、InvalidSpec、ImmutableField、DependencyUnavailable、
+AuthenticationFailed、InsufficientPrivileges、InstanceNotReady、Conflict、
+ProvisioningFailed、CredentialProjectionFailed。Released 应明确显示未可供重新绑定，
+具体 Condition Reason 由 API 细化，不假定仅靠 phase 判断授权。
 
-```text
+使用结构化日志、Events 和低基数失败分类 metrics；Condition 是面向使用者的主要诊断入口。
-username
+禁止在任何 CR、Event、日志、metric、trace 或测试输出中出现密码、Token、完整秘密响应。
-password
-database
-host
-hostaddr
-port
-sslmode
-```
 
-这些字段是 controller 的规范化输出合同。controller 不生成包含密码的 URI、JDBC URL
+## 11. 验收
-或应用专用键名。应用通过 ExternalSecret template、Helm values 或自身配置把原子字段
-映射为 `DATABASE_URL`、独立环境变量或配置文件；因此 URI escaping 和应用特有格式也
-由消费方负责。`host` 是 DNS 名称，`hostaddr` 是可直接连接的 IP；消费者自行选择其
-支持且可达的连接目标。PostgreSQL server 证书必须同时包含与 `host` 匹配的 DNS SAN
-和与 `hostaddr` 匹配的 IP SAN，使两种目标都能在 `verify-full` 下独立完成身份验证。
 
-### 8.4 凭据输出与 ExternalSecret
+| 场景 | 必须验证的结果 |
-
-controller 必须根据部署级 base path 推导 Tenant 的 KV path，Tenant 不能选择 mount 或
-任意远端路径。ExternalSecret 固定命名为
-`<instanceRef>-<metadata.name>-postgresql`。Tenant 可以通过
-`spec.credential.secretName` 指定目标 Kubernetes Secret 名称；省略时使用同一默认名。
-自定义名称只需是合法 Kubernetes Secret 名称，不限制命名内容；两者均与 Tenant 位于
-同一 namespace。
-
-controller 必须创建同 namespace ExternalSecret，从固定的 ClusterSecretStore 读取七个
-原子字段。ExternalSecret 及目标 Secret 的名称通过 Tenant status 暴露。controller
-不得直接读取 OpenBao 密码后写入 Kubernetes Secret。
-
-Tenant status 还必须提供完整、可由外部消费者使用的 OpenBao KV v2 API URL。URL 可以
-包含 consumer API address、mount 和 secret path，但不得包含 Token、密码或其他认证
-信息。默认 `kubectl get` 表格显示目标 Secret 名称；完整 OpenBao URL 通过
-`kubectl get postgresqltenant <name> -o yaml` 获取，避免表格列过长。
-
-OpenBao metadata 必须能够标识 Tenant UID、namespace/name 和 Instance，使 controller
-区分自己的残留记录与外部记录。任何凭据值都不得进入日志、Event、Condition、metric
-label、trace、CR spec/status 或测试快照。
-
-## 9. Reconcile 行为
-
-系统采用最终一致性模型。Kubernetes、PostgreSQL、OpenBao 和 ESO 可以短暂处于不同
-阶段；controller 不尝试实现跨系统事务，而是以 Kubernetes CR `status.phase` 作为
-工作流 checkpoint，通过幂等外部操作和每轮回读验证最终收敛。
-
-两个 CR 的状态机权威记录都在 `status.phase`。controller 根据 phase 选择下一项候选
-动作，但 phase 不能替代外部状态检查：执行前后仍须回读 PostgreSQL catalog、registry、
-OpenBao 和 Kubernetes/ESO。外部写入成功但 status 更新失败时，下一轮必须识别已完成
-事实并推进 phase，不得重复生成密码或报告虚假冲突。
-
-status 丢失时，controller 必须从 registry 的所有权记录和各外部系统实际状态保守重建
-phase。若 status 被伪造或领先于实际状态，controller 必须纠正到安全阶段并补齐资源，
-不能跳过验证。registry 不保存或驱动协调 phase。
-
-Instance phase 按当前 generation 表示连接与初始化进度：
-
-```text
-Pending -> Validating -> InitializingRegistry -> Ready
-(any phase) --------------------------------> Deleting
-```
-
-spec generation 改变后可以从 `Ready` 回到 `Validating`。Tenant phase 如下：
-
-```text
-Pending -> Planned -> CredentialCreated -> RoleCreated -> DatabaseCreated
-        -> ExternalSecretCreated -> CredentialProjected -> Ready -> Deleting
-```
-
-失败不增加 `Failed` phase；phase 保留在无法推进的步骤，由 `Ready=False` 的 Reason 和
-message 表达 `Conflict`、认证失败或依赖不可用。Retain 删除完成后 CR 已不存在，因此
-没有持久的 `Retained` phase。
-
-每轮 Tenant reconcile 必须按以下逻辑执行：
-
-```text
-读取 Tenant
-  -> 读取 Instance
-  -> 校验不可变字段与输入
-  -> 检查 Instance Ready
-  -> 读取 OpenBao 与 PostgreSQL 实际状态
-  -> 检测冲突或部分完成状态
-  -> 执行非破坏性补齐
-  -> 使用应用凭据验证登录
-  -> 创建并验证 ExternalSecret/Secret 投射
-  -> 回读实际状态
-  -> 更新 status
-```
-
-要求：
-
-- 所有步骤必须幂等；
-- 每个外部写入前必须先在 CR status 持久化足够的操作意图，写入后必须回读并推进
-  `status.phase`；
-- 暂时性网络、锁和依赖错误必须重试；
-- 输入错误、资源冲突和禁止操作不得忙循环重试，只在 generation 或依赖状态变化后
-  重试；
-- 未知外部资源不得被修改、接管或删除；
-- 用户从 `spec.extensions` 移除 extension 时不得执行卸载，必须报告该字段在 v1alpha1
-  中只允许追加；
-- controller 重启不得影响已经签发的应用密码；
-- `status` 丢失后必须可以从 registry、PostgreSQL、OpenBao 和 Kubernetes/ESO 重建。
-
-## 10. Condition 合同
-
-两个资源都必须提供唯一的 `Ready` Condition。可以增加辅助 Condition，但调用方只需
-依赖 `Ready`。
-
-| 状态 | 含义 |
 | --- | --- |
-| `Ready=Unknown` | 正在首次观察或 reconcile，尚无结论 |
+| Instance 登记与重验 | 无 registry 依赖；真实凭据/TLS/管理权限检查 |
-| `Ready=False` | 当前 generation 未达到合同要求 |
+| 动态供应与重复 reconcile | 独立资源记录、排他绑定、密码不变、实际登录与投射成功 |
-| `Ready=True` | 当前 generation 已回读验证成功 |
+| 显式导入 | 无数据/密码/owner 隐式修改；错误目标及未经授权申请被拒绝 |
+| 同名未知资源 | Conflict，原数据库/角色/凭据不变 |
+| 并发申请与单边绑定 | 最多一个使用者；失败方不能开始危险外部操作 |
+| controller 重启 | 已确认步骤正常继续；不确定创建报告人工可诊断冲突 |
+| Retain 与 namespace/Tenant 删除 | Database 不被 GC，外部数据保留，Released 不自动复用 |
+| 人工重新绑定 | 旧 UID 不继承使用权；确认数据及凭据/旧访问处置后才能交付 |
+| Delete 每步中断 | finalizer 保留，可重试，不误删未知/共享/未纳管对象 |
+| 依赖稍后出现/权限恢复 | 安全重试，过期观察不授权写入 |
+| status/备份恢复不一致 | 不凭同名推导归属，明确人工处理范围 |
+| 泄漏与权限 | canary 不出现在输出；namespace 用户不能导入/回收他人资源 |
 
-Condition 必须带正确的 `observedGeneration`。资源自身的
+纯规则用单元测试；schema/CEL/status/watch/resourceVersion/绑定事件链用 envtest；
-`status.observedGeneration` 只在当前 generation 完成一次有结论的 reconcile 后更新。
+真实 PostgreSQL/OpenBao 验证后端行为；GC、ESO 与完整交付用具备相应控制器的测试集群。
-
+envtest 不运行 GC/ESO，不能据此宣称这两类验收完成。详细测试与实现差距见
-最低 Reason 集合：
+[开发文档](development.md)。导入不是数据迁移，dump/restore 仍是可选路径，见
-
+[迁移文档](migration.md)。
-| Reason | 适用资源 | 含义 |
-| --- | --- | --- |
-| `Reconciling` | 两者 | 尚在处理 |
-| `Ready` | 两者 | 当前 generation 已验证 |
-| `InvalidSpec` | 两者 | 输入不满足规格 |
-| `DependencyUnavailable` | 两者 | PostgreSQL 或 OpenBao 暂时不可用 |
-| `AuthenticationFailed` | Instance | 管理凭据或 TLS 验证失败 |
-| `InsufficientPrivileges` | Instance | 管理 role 缺少必要权限 |
-| `InstanceNotReady` | Tenant | 引用的 Instance 未 Ready |
-| `Conflict` | Tenant | 目标名称或 OpenBao 路径已被其他主体占用 |
-| `ProvisioningFailed` | Tenant | 可重试的创建/验证失败 |
-| `CredentialProjectionFailed` | Tenant | ESO 或目标 Secret 未达到期望状态 |
-
-Condition message 必须适合人类排障，但禁止包含连接串密码、Token 或完整 Secret 数据。
-
-## 11. 删除与保留
-
-### 11.1 Retain
-
-`Retain` 是默认策略：
-
-- 删除 Tenant CR 不得删除 database、role、extension 或 OpenBao 记录；
-- controller 不得因外部依赖不可用而永久阻止 Retain CR 删除；
-- 保留资源必须继续携带原 Tenant UID 和 namespace/name 的所有权记录，但在 CR 删除后
-  明确处于 unmanaged 状态；
-- 重新创建同名 Tenant 会产生新的 UID，必须因已有资源不属于新 UID 而报告 Conflict；
-- v1alpha1 不提供重新关联、import 或 adoption；恢复管理必须使用第 12 节的迁移流程，
-  或等待后续版本定义显式纳管协议。
-
-### 11.2 Delete
-
-用户在创建 Tenant 时显式设置 `deletionPolicy: Delete`，表示删除 CR 时授权永久清理
-该 Tenant 的外部资源。controller 必须使用 finalizer，并按以下顺序处理：
-
-1. 再次验证 database、role 和 OpenBao 记录都属于当前 Tenant UID；
-2. 删除 ExternalSecret，并确认目标 Kubernetes Secret 已删除；
-3. 禁止该 login role 建立新连接；
-4. 终止该 database 的现有连接；
-5. 删除 database，database 内 extension 随之删除；
-6. 删除 login role；
-7. 删除 OpenBao KV 记录及其可恢复版本；
-8. 回读确认外部资源均不存在；
-9. 删除 controller registry 记录；
-10. 移除 finalizer，允许 Kubernetes 删除 CR。
-
-任一步失败都必须保持 finalizer 并从安全检查开始重试。controller 禁止使用
-`CASCADE` 删除无法证明属于该 Tenant 的依赖对象。若 Instance 或 OpenBao 永久丢失，
-管理员可以在核实外部状态后手工移除 finalizer；该逃生操作必须在运维 runbook 中明确
-标记为可能遗留资源。
-
-v1alpha1 不自动检查备份，也不承诺恢复被 `Delete` 删除的数据。显式选择 Delete 的
-用户承担数据销毁语义；默认 Retain 用于避免普通误删。
-
-## 12. 现有环境迁移
-
-v1alpha1 不接管现有 database 或 role，但必须提供可重复、可回滚的迁移 runbook。对每
-个现有应用租户，推荐的停机迁移顺序是：
-
-1. 盘点 database、role、owner、grant 和 extension，并完成可恢复备份；
-2. 创建逻辑备份，必须使用可映射到新 owner 的格式，避免恢复旧 role ownership；
-3. 停止应用写入并确认没有活动写事务；
-4. 完成最终逻辑备份；
-5. 将旧 database 和 role 重命名为带迁移时间戳的保留名称，释放最终名称；
-6. 创建 `PostgreSQLTenant`，由 controller 创建最终 database、role 和 OpenBao 凭据；
-7. 等待 Tenant Ready；
-8. 以新 owner 恢复逻辑备份，并验证 row count、schema、extension 和应用权限；
-9. 让 ESO 投射新凭据，重启或重新部署应用；
-10. 验证应用读写后结束维护窗口；
-11. 保留旧 database、role 和备份直到回滚窗口结束，再由管理员手工清理。
-
-回滚时停止新应用写入、恢复原名称或连接配置，并重新使用旧凭据。迁移工具不得把旧
-密码、管理凭据或 dump 文件提交到 Git。真实命令、锁定方式和各现有应用验证项见
-[`migration.md`](migration.md)，并必须在实现首个可用版本前通过临时 PostgreSQL 实例
-演练。
-
-## 13. 安全要求
-
-1. 所有 PostgreSQL 与 OpenBao 网络访问必须支持超时和 context cancellation。
-2. homelab 部署必须通过 Deployment 挂载的共享 CA bundle 验证 TLS server identity；
-   该 bundle 的信任根来自 OpenBao PKI，但不得包含 CA 私钥。Instance 默认使用
-   `verify-full`，其 host 必须与服务器证书名称匹配。开发环境可以显式使用 `disable`
-   明文连接。
-3. PostgreSQL 管理 role 应使用满足本规格的最小权限，不应使用 PostgreSQL
-   superuser；若 extension 安装需要额外权限，必须单独记录例外。
-4. controller 的 OpenBao policy 仅覆盖受管租户 KV 操作，不授予管理凭据路径权限。
-   管理凭据的 ESO 同步身份与应用凭据的 ESO 读取身份隔离。controller 只在自身
-   namespace 获得管理 Secret 读取权限，不因此扩大跨 namespace Secret data 访问范围。
-5. namespace 用户不得修改 cluster-scoped Instance。
-6. 所有 identifier、extension name 和引用字段必须在发起外部调用前校验。
-7. controller 不得通过 shell 或 `psql` 子进程执行用户输入。
-8. 错误包装、结构化日志和 tracing 必须经过 Secret 泄露测试。
-
-详细威胁模型和部署 policy 见 [`security.md`](security.md)。
-
-## 14. 可观测性要求
-
-v1alpha1 至少必须提供：
-
-- Kubernetes Events：开始 provisioning、成功及需要人工处理的失败；
-- 结构化日志：resource namespace/name、Instance、generation、阶段和错误类别；
-- controller-runtime 默认 reconcile metrics；
-- 不包含 database、role、OpenBao path 等无界用户输入的低基数失败分类 metric。
-
-日志和 metrics 的存在不能代替 Condition；Condition 是 API 使用者判断状态的主要方式。
-
-## 15. 验收标准
-
-实现 v1alpha1 第一条完整纵向切片前，测试必须覆盖：
-
-1. 有效 Instance 可以建立 TLS 管理连接并变为 Ready。
-2. PostgreSQL 管理能力不可用时 Instance Ready=False，恢复后自动变为 Ready；已有
-   管理凭据可正常使用时，Bao／ESO 故障不单独影响 Instance Ready。首次装配缺少有效
-   管理 Secret 时不能 Ready；Tenant 的 Bao 操作失败按其自身依赖故障报告。
-3. 有效 Tenant 创建 database、作为 owner 的 login、grant、extension 和 OpenBao
-   记录。
-4. 应用凭据可以实际连接且不能创建其他 database/role。
-5. 相同 generation 重复 reconcile 不改变密码、不重复创建资源。
-6. controller 在每个外部写入步骤后中断，重启后都能继续并得到相同最终状态。
-7. 预先存在且不属于当前 Tenant UID 的 database、role 或 OpenBao path 导致
-   Conflict，且不修改已有资源。
-8. 目标实例实际不支持的 extension 在供应外部写入前被拒绝；扩展列表查询失败时
-   按依赖故障处理，不报告为不支持。安装结果仍须回读验证。
-9. status 被清空后可以从两个外部事实来源重建。
-10. 删除 Retain Tenant 后外部资源仍存在且不再受管；重新创建同名 Tenant 报告
-    Conflict。
-11. 日志、Event、Condition、metric 和 CR 中不存在生成的密码或管理凭据。
-12. 两个 namespace 对同一 Instance 申请相同名称时，只有第一个成功，第二个报告
-    Conflict。
-13. 删除 Delete Tenant 时，任一步骤失败都可重试，且最终删除 database、login role、
-    OpenBao KV 历史和 finalizer。
-14. 使用迁移 runbook 可以把一个现有 database 转移到新建的受管 database，并在回滚
-    窗口内恢复旧服务。
-15. Tenant 只有在 ExternalSecret Ready、目标 Secret 存在且应用凭据实际可登录后才
-    Ready。
-16. Tenant status 同时提供 Kubernetes Secret reference 和不含认证信息的 OpenBao API
-    URL。
-17. DNS 不可用时，使用输出的 `hostaddr` 可以连接 PostgreSQL；server 证书同时覆盖
-    `host` 的 DNS SAN 和 `hostaddr` 的 IP SAN，两种连接目标均可通过 `verify-full`。
-18. 两个 CR 的 `status.phase` 都能反映当前协调步骤；清空 status 后可以从外部事实重建，
-    且伪造或过期 phase 不会使 controller 跳过验证或外部操作。
-
-单元测试验证纯决策逻辑，adapter 集成测试使用 Docker PostgreSQL/OpenBao，controller
-集成测试使用 envtest，完整网络路径使用 Kind E2E。
-
-## 16. 已确认决策
-
-- v1alpha1 使用一个同时作为 database owner 的 login role，不创建额外 NOLOGIN owner。
-- v1alpha1 不接管任意现有资源，但必须提供并演练 dump/restore 迁移路径。
-- v1alpha1 同时实现默认 `Retain` 和显式 `Delete`；Delete 必须有 finalizer、所有权验证
-  和完整清理路径。
-- OpenBao KV v2 mount 和 base path 是 controller 部署配置，mount 默认 `kv`，base path
-  由 `--openbao-tenant-base-path` 配置并默认 `postgresql-tenants`；Tenant 不能选择 mount
-  或任意远端 path，controller 根据 namespace/name 推导记录路径。
-- 租户 KV 记录固定写入 `username/password/database/host/hostaddr/port/sslmode` 七个
-  原子字段；
-  controller 不生成连接 URI，应用负责映射和拼装自身配置。
-- PostgreSQL TLS 使用 controller Deployment 挂载的共享 CA bundle。OpenBao PKI 是
-  CA 权威并继续签发、续期 PostgreSQL server 证书；controller 只消费公开 trust
-  bundle，不接触 CA 私钥。bundle 可以由 ConfigMap 或现有证书同步机制投射，不允许
-  Tenant 或 Instance 选择其他 CA；开发环境可以显式使用 `sslMode: disable`。
-- 每个 PostgreSQLInstance 在其管理 database 中维护 controller 专用 registry schema。
-  registry 是受管资源所有权、安装身份和 Retain 后 unmanaged 标记的权威记录；两个
-  CR 的 `status.phase` 是 controller 状态机的权威 checkpoint，Instance status 不聚合
-  Tenant 清单。
-- PostgreSQL database 和 role identifier 必须匹配 `^[a-z][a-z0-9_]{0,62}$`，不支持
-  需要双引号的大小写或特殊字符名称。
-- External Secrets Operator 是 v1alpha1 的运行依赖。controller 管理同 namespace
-  ExternalSecret，但不直接写明文 Secret；Tenant status 同时输出目标 Secret reference
-  和供非 Kubernetes 消费者使用的 OpenBao API URL。
-- PostgreSQLInstance 同时声明 DNS `host` 和 IP `hostaddr`；PostgreSQL server 证书必须
-  同时包含对应 DNS SAN 和 IP SAN，消费者自行选择连接目标。
-
-## 17. 批准状态
-
-2026-09-14 确认 extension 判定修订：v1alpha1 使用实例实际可安装列表，不实现管理员
-allowlist；后续可按需引入策略。现有 allowedExtensions 字段尚待 API 实现移除。
-
-2026-09-13 已确认管理连接修订：Instance 引用 controller namespace 内的管理 Secret，
-管理员维护 ExternalSecret，由 ESO 同步；controller 不再从 Bao 直接读取管理凭据。
-此项是已批准行为，现有 API types 与实现尚待后续修改。
-
-具体设计决策和本文整体已于 2026-09-10 获得批准，可以进入 API reference、测试和
-实现阶段。同日确认状态机修订：两个 CR 的 `status.phase` 是 controller 工作流的权威
-checkpoint；PostgreSQL registry 只承担所有权、安装身份和保留状态。
-
-## 18. 与当前脚手架的已知差异
-
-当前 API skeleton 至少需要以下调整：
-
-- 删除 Tenant 自选 OpenBao path 的能力，改由部署级 mount、base path 和 Tenant
-  identity 推导，并修正当前包含 `kv/` 前缀的示例；
-- 增加 controller 部署级 OpenBao KV mount 和 TLS 配置；
-- 增加部署级 OpenBao consumer address、ClusterSecretStore 和 KV base path 配置；
-- 删除独立 `ownerRole` 字段，使 login role 成为 database owner；
-- 为 Instance 增加 `hostaddr`，为 Tenant 增加目标 Secret 配置及 Secret/Bao URL 输出
-  status；
-- 按已确认的 identifier 合同收紧校验；
-- 增加 PostgreSQL controller registry，记录基于 UID 的所有权、安装身份和保留状态；
-- 修正凭据 type 中遗留的 rotation 注释；
-- 使 Condition、不可变字段和 extension 追加语义具备 API 校验或明确的 reconcile
-  结果。
-
-这些是规格批准后的实现工作，不属于本规格本身。

docs/decisions/0008-merge-postgresql-tenant-operator.md

@@ -3,6 +3,10 @@
 - 状态：Accepted
 - 日期：2026-09-20
 
+2026-09-24 修订：[ADR-0009](0009-database-resource-and-claim.md) 已明确替代本文对 ownership
+registry、任意 status 丢失自动恢复及原 Retain 合同的沿用要求。Database 合并归属、来源保护、
+无旧部署兼容负担及其他仍适用的安全边界继续有效；以下保留当时迁移决策的历史背景。
+
 ## 背景
 
 独立仓库 `postgresql-tenant-operator` 已经为 homelab 共享 PostgreSQL 设计了

docs/decisions/0009-database-resource-and-claim.md

@@ -0,0 +1,65 @@
+# ADR-0009：分离 Database 资源与 Tenant 申请
+
+- 状态：Accepted（资源模型与生命周期）；API 字段细节待评审
+- 日期：2026-09-24
+- 依据：维护者本轮设计讨论；本决定部分替代 [ADR-0008](0008-merge-postgresql-tenant-operator.md)
+  对 ownership registry、自动恢复与 Retain 的沿用要求，不改变 Database 合并归属。
+
+## 问题
+
+原模型让 Tenant 同时表示用户申请和外部资源生命周期，又用 PostgreSQL registry 在 Tenant
+删除后保留所有权。它把简单的一对多关系扩展成额外持久化协议，并为“外部创建成功但 status
+未写入”承诺自动认领恢复。这里并没有自动恢复所有不确定结果的产品要求；清楚报告冲突、
+保留现场并允许人工处理是可接受的合同。
+
+Kubernetes status 存储在 API/etcd 中，不是 controller 重启即丢失的内存。外部操作与 API
+写入之间确实存在失败窗口，但不因此引入第二套所有权数据库或模拟跨系统事务。
+
+## 参考与取舍
+
+参考 Kubernetes 官方 [Persistent Volumes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/)：
+资源独立于申请存在，绑定排他；Retain 释放后需要人工处理；已有资源可以静态登记。
+同时参考 [owner references](https://kubernetes.io/docs/concepts/overview/working-with-objects/owners-dependents/)
+与 [finalizers](https://kubernetes.io/docs/concepts/overview/working-with-objects/finalizers/) 的生命周期边界。
+
+采用这些模式，不直接使用 PV/PVC 类型，不实现 CSI 协议，不引入 StorageClass、容量匹配、
+调度器、通用 Claim、事件总线或额外 registry。Instance 是资源来源与管理入口，PostgreSQL
+adapter 承担类似驱动的访问职责；Instance 本身不是 CSI 驱动。
+
+## 决策
+
+- Instance 对应多个独立 Database；每个 Database 同时最多绑定一个 Tenant，Tenant 最多绑定
+  一个 Database。Tenant 是用户申请，不再直接承担持久资源的全部生命周期。
+- Database 是新增 Kubernetes 资源；本文采用 PostgreSQLDatabase 作为工作名称，具体字段、
+  scope 与短名称在 API 评审中确定，不从类比自动推导。
+- 动态供应先建立资源记录；已有数据库只能由管理员显式登记导入。仅发现同名数据库不是授权。
+- Database 自带 instanceRef，手工登记不依赖 Tenant。动态申请由 Tenant 选择 Instance；
+  引用已有 Database 的 Tenant 从资源获取 Instance，不重复声明另一份来源。
+- Retain 默认保留 Database 与外部资源；Tenant 删除后资源进入 Released，保留旧绑定身份，
+  不自动重新分配。管理员处理数据、账号权限与凭据后，才可授权重新绑定。
+- 回收策略在 Database 一侧。Delete 必须具备明确管理范围、删除授权、finalizer 和回读；
+  导入不隐含授权改密码、改 owner、撤权或删除。
+- Kubernetes CR 保存资源身份、绑定与操作进度，PostgreSQL catalog 保存实际数据库状态；
+  不再维护 PostgreSQL ownership registry，不把 registry 初始化或回读作为 Instance Ready 条件。
+- 普通依赖失败继续 reconcile；同名未知资源、创建结果无法确认时报告 Conflict，停止对相关
+  资源的危险操作，提供人工诊断。已有可靠记录支持的幂等步骤可以继续，不将每次重启都变成冲突。
+- status 不承诺在任意删除后自动重建所有权。灾难恢复按备份与人工核实处理。
+- Database 不受 Tenant 的级联 GC 控制；Instance 删除也不能级联删除 Database 或业务数据。
+
+## 保留的合同与未决项
+
+管理 Secret 来源、凭据变化后刷新连接、TLS、实际扩展观察、OpenBao 应用凭据与 ESO 投射、
+最小权限和分层集成验证继续适用。单 database、单 login owner 的首版使用场景不变。
+
+Database 对 role/凭据的具体管理边界、持久凭据定位与重新授权方式、资源 scope、绑定字段、
+预留及并发绑定的 API 更新协议需在 API/实现切片前细化。旧的 Tenant namespace/name 固定
+凭据路径不能未经评估直接用于跨 Tenant 重新绑定；不为填满字段表而默认授权搬迁或改密。
+
+## 实施边界
+
+本次只修订设计。现有 registry adapter、Instance 中的 registry 判定及相关测试是待撤换的旧实现，
+不是新合同的前提；未提交的 registry inspection 不继续接入。后续按新规格撤除这些依赖，
+再实现 Database 资源、绑定、导入与回收的纵向切片，不保留未部署实现的兼容层。
+
+详见 [系统规格](../database/specification.md)、[领域模型](../database/domain-model.md)、
+[API 设计状态](../database/api-reference.md)和[测试合同](../database/development.md)。

go.mod

@@ -3,6 +3,7 @@ module git.ddupan.top/panxiao81/ayatori
 go 1.27.1
 
 require (
+	github.com/jackc/pgx/v5 v5.11.0
 	k8s.io/api v0.37.0
 	k8s.io/apimachinery v0.37.0
 	k8s.io/client-go v0.37.0
@@ -11,6 +12,7 @@ require (
 
 require (
 	cel.dev/expr v0.25.1 // indirect
+	github.com/Masterminds/semver/v3 v3.5.0 // indirect
 	github.com/antlr4-go/antlr/v4 v4.13.1 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/blang/semver/v4 v4.0.0 // indirect
@@ -44,6 +46,9 @@ require (
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee // indirect
@@ -68,14 +73,14 @@ require (
 	go.uber.org/multierr v1.11.0 // indirect
 	go.uber.org/zap v1.27.1 // indirect
 	go.yaml.in/yaml/v2 v2.4.4 // indirect
-	go.yaml.in/yaml/v3 v3.0.4 // indirect
+	go.yaml.in/yaml/v3 v3.0.5 // indirect
 	golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f // indirect
 	golang.org/x/net v0.57.0 // indirect
 	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/sync v0.22.0 // indirect
 	golang.org/x/sys v0.47.0 // indirect
 	golang.org/x/term v0.45.0 // indirect
-	golang.org/x/text v0.40.0 // indirect
+	golang.org/x/text v0.41.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
 	gomodules.xyz/jsonpatch/v2 v2.4.0 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20260526163538-3dc84a4a5aaa // indirect

go.sum

@@ -1,7 +1,7 @@
 cel.dev/expr v0.25.1 h1:1KrZg61W6TWSxuNZ37Xy49ps13NUovb66QLprthtwi4=
 cel.dev/expr v0.25.1/go.mod h1:hrXvqGP6G6gyx8UAHSHJ5RGk//1Oj5nXQ2NI02Nrsg4=
-github.com/Masterminds/semver/v3 v3.4.0 h1:Zog+i5UMtVoCU8oKka5P7i9q9HgrJeGzI9SA1Xbatp0=
+github.com/Masterminds/semver/v3 v3.5.0 h1:kQceYJfbupGfZOKZQg0kou0DgAKhzDg2NZPAwZ/2OOE=
-github.com/Masterminds/semver/v3 v3.4.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
+github.com/Masterminds/semver/v3 v3.5.0/go.mod h1:4V+yj/TJE1HU9XfppCwVMZq3I84lprf4nC11bSS5beM=
 github.com/antlr4-go/antlr/v4 v4.13.1 h1:SqQKkuVZ+zWkMMNkjy5FZe5mr5WURWnlpmOuzYWrPrQ=
 github.com/antlr4-go/antlr/v4 v4.13.1/go.mod h1:GKmUxMtwp6ZgGwZSva4eWPC5mS6vUAmOABFgjdkM7Nw=
 github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
@@ -91,14 +91,18 @@ github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0 h1:5VipnvEpbqr2gA2VbM+nYVbkIF2
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.29.0/go.mod h1:Hyl3n6Twe1hvtd9XUXDec4pTvgMSEixRuQKPTMH2bNs=
 github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.11.0 h1:IzBBtyK9AHqf98cctWFifYSci2hgQR/cd56wB4p+ogg=
+github.com/jackc/pgx/v5 v5.11.0/go.mod h1:mal1tBGAFfLHvZzaYh77YS/eC6IX9OWbRV1QIIM0Jn4=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
 github.com/klauspost/compress v1.19.0 h1:sXLILfc9jV2QYWkzFOPWStmcUVH2RHEB1JCdY2oVvCQ=
 github.com/klauspost/compress v1.19.0/go.mod h1:cwPg85FWrGar70rWktvGQj8/hthj3wpl0PGDogxkrSQ=
-github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
-github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
-github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
-github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
 github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
 github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
@@ -126,8 +130,6 @@ github.com/prometheus/common v0.70.0 h1:bcpru3tWPVnxGnETLgOV5jbp/JRXgYEyv65CuBLA
 github.com/prometheus/common v0.70.0/go.mod h1:S/SFasQmgGiYH6C81LKCtYa8QACgthGg5zxL2udV7SY=
 github.com/prometheus/procfs v0.21.1 h1:GljZCt+zSTS+NZq88cyQ1LjZ+RCHp3uVuabBWA5+OJI=
 github.com/prometheus/procfs v0.21.1/go.mod h1:aB55Cww9pdSJVHk0hUf0inxWyyjPogFIjmHKYgMKmtY=
-github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
-github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
 github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
@@ -138,6 +140,7 @@ github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+
 github.com/stretchr/objx v0.5.3 h1:jmXUvGomnU1o3W/V5h2VEradbpJDwGrzugQQvL0POH4=
 github.com/stretchr/objx v0.5.3/go.mod h1:rDQraq+vQZU7Fde9LOZLr8Tax6zZvy4kuNKF+QYS+U0=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
 github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
@@ -170,12 +173,13 @@ go.uber.org/zap v1.27.1 h1:08RqriUEv8+ArZRYSTXy1LeBScaMpVSTBhCeaZYfMYc=
 go.uber.org/zap v1.27.1/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
 go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
 go.yaml.in/yaml/v2 v2.4.4/go.mod h1:gMZqIpDtDqOfM0uNfy0SkpRhvUryYH0Z6wdMYcacYXQ=
-go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
+go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
 golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f h1:W3F4c+6OLc6H2lb//N1q4WpJkhzJCK5J6kUi1NTVXfM=
 golang.org/x/exp v0.0.0-20260410095643-746e56fc9e2f/go.mod h1:J1xhfL/vlindoeF/aINzNzt2Bket5bjo9sdOYzOsU80=
-golang.org/x/mod v0.37.0 h1:vF1DjpVEshcIqoEaauuHebaLk1O1forxjxBaVn884JQ=
+golang.org/x/mod v0.38.0 h1:MECBjubtXD7yj4HrhIUcywNaGeNVUdfVnxmPajOk4yk=
-golang.org/x/mod v0.37.0/go.mod h1:m8S8VeM9r4dzDwjrKO0a1sZP3YjeMamRRlD+fmR2Q/0=
+golang.org/x/mod v0.38.0/go.mod h1:V6Xz0pq8TQ3dGqVQ1FVHuelZpAL0uNhSkk9ogYP3c40=
 golang.org/x/net v0.57.0 h1:K5+3DljvIuDG9/Jv9rvyMywYNFCQ9RSUY6OOTTkT+tE=
 golang.org/x/net v0.57.0/go.mod h1:KpXc8iv+r3XplLAG/f7Jsf9RPszJzdR0f58q9vGOuEU=
 golang.org/x/oauth2 v0.36.0 h1:peZ/1z27fi9hUOFCAZaHyrpWG5lwe0RJEEEeH0ThlIs=
@@ -186,12 +190,12 @@ golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
 golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
 golang.org/x/term v0.45.0 h1:NwWyBmoJCbfTHpxrWoZ9C6/VxOf7ic219I8xZZFdrf0=
 golang.org/x/term v0.45.0/go.mod h1:9aqxs0blBcrm/n0L9QW0aRVD+ktan8ssZromtqJC43w=
-golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
+golang.org/x/text v0.41.0 h1:vz/seA0lnX87Othu2f/0L24RcgrXD9/YFTSuGjj3rH8=
-golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
+golang.org/x/text v0.41.0/go.mod h1:jvf1O8ajNzZqhSrQBPbutR/EB83Cc0CFrezNQIwbb5M=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
-golang.org/x/tools v0.47.0 h1:7Kn5x/d1svx/PzryTsqeoZN4TZwqeH5pGWjefhLi/1Q=
+golang.org/x/tools v0.48.0 h1:3+hClM1aLL5mjMKm5ovokw9epgRXPuu2tILgismM6RE=
-golang.org/x/tools v0.47.0/go.mod h1:dFHnyTvFWY212G+h7ZY4Vsp/K3U4/7W9TyVaAul8uCA=
+golang.org/x/tools v0.48.0/go.mod h1:08xX0orndb/F7jJxGDicx061tyd5pcMto75YMAXr6lk=
 gomodules.xyz/jsonpatch/v2 v2.4.0 h1:Ci3iUJyx9UeRx7CeFN8ARgGbkESwJK+KB9lLcWxY/Zw=
 gomodules.xyz/jsonpatch/v2 v2.4.0/go.mod h1:AH3dM2RI6uoBZxn3LVrfvJ3E0/9dG4cSrbuBJT4moAY=
 gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4=
@@ -205,12 +209,11 @@ google.golang.org/grpc v1.82.1/go.mod h1:yzTZ1TB1Z3SG+LIYaI+WiE8D5+PZ3ArnrSp8zF3
 google.golang.org/protobuf v1.36.12-0.20260120151049-f2248ac996af h1:+5/Sw3GsDNlEmu7TfklWKPdQ0Ykja5VEmq2i817+jbI=
 google.golang.org/protobuf v1.36.12-0.20260120151049-f2248ac996af/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
-gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
-gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
 gopkg.in/evanphx/json-patch.v4 v4.13.0 h1:czT3CmqEaQ1aanPc5SdlgQrrEIb8w/wwCvWWnfEbYzo=
 gopkg.in/evanphx/json-patch.v4 v4.13.0/go.mod h1:p8EYWUEYMpynmqDbY58zCKCFZw8pRWMG4EsWvDvM72M=
 gopkg.in/inf.v0 v0.9.1 h1:73M5CoZyi3ZLMOyDlQh031Cx6N9NDJ2Vvfl76EDAgDc=
 gopkg.in/inf.v0 v0.9.1/go.mod h1:cWUDdTG/fYaXco+Dcufb5Vnc6Gp2YChqWtbxRZE0mXw=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 k8s.io/api v0.37.0 h1:Z//Vj9N7RA/yS2sDmxyeo7h+RR4zbUrd2vrd3Z0TbB4=

internal/database/adapter/kubernetes/credentials.go

@@ -0,0 +1,68 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package kubernetes 提供 Database 所需的 Kubernetes API 薄适配。
+package kubernetes
+
+import (
+	"context"
+	"errors"
+
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/util/validation"
+	typedcore "k8s.io/client-go/kubernetes/typed/core/v1"
+	"k8s.io/client-go/rest"
+
+	"git.ddupan.top/panxiao81/ayatori/internal/database/application"
+	"git.ddupan.top/panxiao81/ayatori/internal/database/domain/instance"
+)
+
+// SecretCredentials 直接读取 API server，不将 Secret 数据纳入共享 informer cache。
+// namespace 在装配时固定，Instance 不能选择跨 namespace 读取。
+type SecretCredentials struct {
+	secrets typedcore.SecretInterface
+}
+
+func NewSecretCredentials(config *rest.Config, namespace string) (*SecretCredentials, error) {
+	if config == nil || len(validation.IsDNS1123Label(namespace)) != 0 {
+		return nil, errors.New("valid controller namespace and API configuration required")
+	}
+	client, err := typedcore.NewForConfig(config)
+	if err != nil {
+		return nil, application.ErrCredentialsUnavailable
+	}
+	return &SecretCredentials{secrets: client.Secrets(namespace)}, nil
+}
+
+func (r *SecretCredentials) Read(ctx context.Context, ref instance.CredentialReference) (application.Credentials, error) {
+	if err := ref.Validate(); err != nil {
+		return application.Credentials{}, application.ErrCredentialsInvalid
+	}
+	keys := ref.Values()
+	secret, err := r.secrets.Get(ctx, keys.Name, metav1.GetOptions{})
+	if err != nil {
+		return application.Credentials{}, application.ErrCredentialsUnavailable
+	}
+	return decode(secret, keys)
+}
+
+func decode(secret *corev1.Secret, keys instance.CredentialReferenceValues) (application.Credentials, error) {
+	if secret.DeletionTimestamp != nil {
+		return application.Credentials{}, application.ErrCredentialsUnavailable
+	}
+	return application.NewCredentials(string(secret.Data[keys.UsernameKey]), string(secret.Data[keys.PasswordKey]))
+}

internal/database/adapter/postgresql/connector.go

@@ -0,0 +1,108 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package postgresql 使用 pgxpool 提供 PostgreSQL 能力的薄适配。
+package postgresql
+
+import (
+	"context"
+	"crypto/tls"
+	"errors"
+	"net"
+	"net/url"
+	"strconv"
+
+	"github.com/jackc/pgx/v5/pgconn"
+	"github.com/jackc/pgx/v5/pgxpool"
+
+	"git.ddupan.top/panxiao81/ayatori/internal/database/application"
+	"git.ddupan.top/panxiao81/ayatori/internal/database/domain/instance"
+)
+
+// Connector 不读取 Secret、不决定连接何时替换；池本身由 pgxpool 实现。
+type Connector struct {
+	RootCert string
+}
+
+type database struct {
+	pool *pgxpool.Pool
+}
+
+func (*database) String() string     { return "[redacted PostgreSQL database]" }
+func (d *database) GoString() string { return d.String() }
+func (d *database) Close() {
+	d.pool.Close()
+}
+
+func (c Connector) Connect(ctx context.Context, endpoint instance.Endpoint, credentials application.Credentials) (application.Database, error) {
+	if err := endpoint.Validate(); err != nil {
+		return nil, err
+	}
+	if credentials.Username() == "" || credentials.Password() == "" {
+		return nil, application.ErrCredentialsInvalid
+	}
+	endpointValues := endpoint.Values()
+	query := url.Values{
+		"sslmode":          {string(endpointValues.TLSMode)},
+		"connect_timeout":  {"5"},
+		"application_name": {"ayatori-database-management"},
+	}
+	if c.RootCert != "" {
+		query.Set("sslrootcert", c.RootCert)
+	}
+	connectionURL := url.URL{
+		Scheme:   "postgresql",
+		Host:     net.JoinHostPort(endpointValues.Host, strconv.Itoa(endpointValues.Port)),
+		Path:     "/" + endpointValues.ManagementDatabase,
+		User:     url.UserPassword(credentials.Username(), credentials.Password()),
+		RawQuery: query.Encode(),
+	}
+	config, err := pgxpool.ParseConfig(connectionURL.String())
+	if err != nil {
+		return nil, application.ErrConnection
+	}
+	// pgx 不实现 libpq hostaddr；复用其 LookupFunc 扩展点，TLS 验证身份仍采用 host。
+	config.ConnConfig.LookupFunc = func(context.Context, string) ([]string, error) {
+		return []string{endpointValues.HostAddr}, nil
+	}
+	config.ConnConfig.Fallbacks = nil
+	pool, err := pgxpool.NewWithConfig(ctx, config)
+	if err != nil {
+		return nil, safeError(err, application.ErrConnection)
+	}
+	if err := pool.Ping(ctx); err != nil {
+		pool.Close()
+		return nil, safeError(err, application.ErrConnection)
+	}
+	return &database{pool: pool}, nil
+}
+
+func safeError(err, fallback error) error {
+	if errors.Is(err, context.Canceled) {
+		return context.Canceled
+	}
+	if errors.Is(err, context.DeadlineExceeded) {
+		return context.DeadlineExceeded
+	}
+	var pgerr *pgconn.PgError
+	if errors.As(err, &pgerr) && (pgerr.Code == "28P01" || pgerr.Code == "28000") {
+		return application.ErrAuthentication
+	}
+	if _, ok := errors.AsType[*tls.CertificateVerificationError](err); ok {
+		return application.ErrAuthentication
+	}
+	return fallback
+}

internal/database/adapter/postgresql/credentials_integration_test.go

@@ -0,0 +1,231 @@
+//go:build integration
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package postgresql_test
+
+import (
+	"context"
+	"errors"
+	"os/exec"
+	"sync"
+	"testing"
+	"time"
+
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+
+	"git.ddupan.top/panxiao81/ayatori/internal/database/adapter/postgresql"
+	"git.ddupan.top/panxiao81/ayatori/internal/database/application"
+	"git.ddupan.top/panxiao81/ayatori/internal/database/domain/instance"
+)
+
+func TestManagementSecretScopeAndMissingDependencyRecovery(t *testing.T) {
+	fixture := newCredentialFixture(t)
+	reference := fixture.target.Definition().AdminCredential()
+
+	fixture.createSecret(t, "unrelated")
+	if _, err := fixture.reader.Read(fixture.ctx, reference); !errors.Is(err, application.ErrCredentialsUnavailable) {
+		t.Fatal("a Secret in another namespace satisfied the reference")
+	}
+	if _, err := fixture.service.ObserveVersion(fixture.ctx, fixture.target); !errors.Is(err, application.ErrCredentialsUnavailable) {
+		t.Fatal("missing Secret did not fail closed")
+	}
+
+	fixture.createSecret(t, controllerNamespace)
+	if _, err := fixture.deniedReader.Read(fixture.ctx, reference); !errors.Is(err, application.ErrCredentialsUnavailable) {
+		t.Fatal("API server did not enforce Secret RBAC")
+	}
+	fixture.observeVersion(t)
+
+	fixture.updateSecret(t, func(secret *corev1.Secret) {
+		delete(secret.Data, "credential")
+	})
+	if _, err := fixture.service.ObserveVersion(fixture.ctx, fixture.target); !errors.Is(err, application.ErrCredentialsInvalid) {
+		t.Fatal("missing credential field reused a cached connection")
+	}
+	fixture.updateSecret(t, func(secret *corev1.Secret) {
+		secret.Data["credential"] = []byte(fixturePassword)
+	})
+	fixture.observeVersion(t)
+
+	err := fixture.client.CoreV1().Secrets(controllerNamespace).Delete(fixture.ctx, secretName, metav1.DeleteOptions{})
+	if err != nil {
+		t.Fatal("cannot delete fixture Secret")
+	}
+	if _, err := fixture.service.ObserveVersion(fixture.ctx, fixture.target); !errors.Is(err, application.ErrCredentialsUnavailable) {
+		t.Fatal("deleted Secret retained access")
+	}
+}
+
+func TestEffectiveCredentialChangesReplaceConnection(t *testing.T) {
+	fixture := newCredentialFixture(t)
+	fixture.createSecret(t, controllerNamespace)
+	fixture.observeVersion(t)
+	originalBackend := fixture.backendIDs(t)
+	if originalBackend == "" {
+		t.Fatal("management connection not visible in PostgreSQL")
+	}
+
+	fixture.updateSecret(t, func(secret *corev1.Secret) {
+		secret.Labels = map[string]string{"changed": "true"}
+		secret.Data["unrelated"] = []byte("ignored")
+	})
+	fixture.observeVersion(t)
+	if fixture.backendIDs(t) != originalBackend {
+		t.Fatal("metadata or unrelated fields rebuilt the connection")
+	}
+
+	// 先改变 Secret、暂不改变服务器密码：旧连接必须失效，新认证必须失败。
+	fixture.updateSecret(t, func(secret *corev1.Secret) {
+		secret.Data["credential"] = []byte(rotatedPassword)
+	})
+	version, err := fixture.service.ObserveVersion(fixture.ctx, fixture.target)
+	if !errors.Is(err, application.ErrAuthentication) || version != "" {
+		t.Fatal("old connection bypassed changed credentials")
+	}
+
+	fixture.queryPostgres(t, "ALTER ROLE postgres PASSWORD '"+rotatedPassword+"'")
+	fixture.observeVersion(t)
+	if fixture.backendIDs(t) == originalBackend {
+		t.Fatal("password rotation reused the old backend")
+	}
+
+	fixture.updateSecret(t, func(secret *corev1.Secret) {
+		secret.Data["login"] = []byte("nonexistent")
+	})
+	if _, err := fixture.service.ObserveVersion(fixture.ctx, fixture.target); !errors.Is(err, application.ErrAuthentication) {
+		t.Fatal("username change did not require a new authentication")
+	}
+	fixture.updateSecret(t, func(secret *corev1.Secret) {
+		secret.Data["login"] = []byte(fixtureUser)
+	})
+	fixture.observeVersion(t)
+}
+
+func TestObservationDiscardsResultWhenCredentialsChange(t *testing.T) {
+	fixture := newCredentialFixture(t)
+	fixture.createSecret(t, controllerNamespace)
+
+	reads := 0
+	fixture.gate.beforeRead = func() {
+		reads++
+		if reads == 2 {
+			fixture.updateSecret(t, func(secret *corev1.Secret) {
+				secret.Data["credential"] = []byte(rotatedPassword)
+			})
+		}
+	}
+
+	observation, err := fixture.service.ObserveMetadata(fixture.ctx, fixture.target)
+	if !errors.Is(err, application.ErrCredentialsChanged) {
+		t.Fatal("in-flight rotation was not detected")
+	}
+	if observation.Version() != "" {
+		t.Fatal("observation returned data obtained with stale credentials")
+	}
+	requested := instance.NewExtensionSet([]string{fixtureExtension})
+	if observation.Extensions().Check(requested).Decision != instance.ExtensionSupportUnobserved {
+		t.Fatal("observation returned extension support obtained with stale credentials")
+	}
+	if fixture.backendIDs(t) != "" {
+		t.Fatal("stale connection was retained after rotation")
+	}
+}
+
+func TestConnectionReleaseAndServiceRestart(t *testing.T) {
+	fixture := newCredentialFixture(t)
+	fixture.createSecret(t, controllerNamespace)
+	fixture.observeVersion(t)
+
+	fixture.service.Forget(fixture.target.Identity().Name())
+	if fixture.backendIDs(t) != "" {
+		t.Fatal("Forget retained a connection")
+	}
+	fixture.observeVersion(t)
+
+	fixture.service.Close()
+	fixture.service.Close()
+	if _, err := fixture.service.ObserveVersion(fixture.ctx, fixture.target); !errors.Is(err, application.ErrClosed) {
+		t.Fatal("closed service accepted work")
+	}
+
+	restarted, err := application.NewInstanceService(fixture.reader, postgresql.Connector{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(restarted.Close)
+	if _, err := restarted.ObserveVersion(fixture.ctx, fixture.target); err != nil {
+		t.Fatal("new service could not recover from stored Secret", err)
+	}
+
+	// 此 fixture 未启用 TLS；各加密模式均不得偷偷回退到明文连接。
+	for _, mode := range []instance.TLSMode{instance.TLSRequire, instance.TLSVerifyCA, instance.TLSVerifyFull} {
+		securedTarget := target(t, fixture.port, mode)
+		if _, err := restarted.ObserveVersion(fixture.ctx, securedTarget); err == nil {
+			t.Fatal("TLS policy silently downgraded to plaintext")
+		}
+	}
+}
+
+func TestConcurrentVersionObservations(t *testing.T) {
+	fixture := newCredentialFixture(t)
+	fixture.createSecret(t, controllerNamespace)
+
+	var workers sync.WaitGroup
+	for range 4 {
+		workers.Go(func() {
+			version, err := fixture.service.ObserveVersion(fixture.ctx, fixture.target)
+			if err != nil || version == "" {
+				t.Error("concurrent observation failed", err)
+			}
+		})
+	}
+	workers.Go(func() {
+		fixture.service.Forget(fixture.target.Identity().Name())
+	})
+	workers.Wait()
+	fixture.observeVersion(t)
+}
+
+func TestManagementConnectionRecoversAfterTimeout(t *testing.T) {
+	fixture := newCredentialFixture(t)
+	fixture.createSecret(t, controllerNamespace)
+	fixture.observeVersion(t)
+
+	if err := exec.CommandContext(fixture.ctx, "docker", "pause", fixture.containerID).Run(); err != nil {
+		t.Fatal("cannot pause isolated PostgreSQL fixture")
+	}
+	// 即使断言失败，也先恢复容器，再由 fixture 按原 ID 清理。
+	t.Cleanup(func() {
+		cleanupContext, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+		defer cancel()
+		_ = exec.CommandContext(cleanupContext, "docker", "unpause", fixture.containerID).Run()
+	})
+
+	queryContext, cancel := context.WithTimeout(fixture.ctx, 500*time.Millisecond)
+	version, err := fixture.service.ObserveVersion(queryContext, fixture.target)
+	cancel()
+	if err == nil || version != "" {
+		t.Fatal("timed out PostgreSQL observation returned a successful result")
+	}
+
+	if err := exec.CommandContext(fixture.ctx, "docker", "unpause", fixture.containerID).Run(); err != nil {
+		t.Fatal("cannot resume isolated PostgreSQL fixture")
+	}
+	fixture.observeVersion(t)
+}

internal/database/adapter/postgresql/fixture_integration_test.go

@@ -0,0 +1,333 @@
+//go:build integration
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package postgresql_test
+
+import (
+	"context"
+	"errors"
+	"os/exec"
+	"regexp"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/client-go/kubernetes"
+	"sigs.k8s.io/controller-runtime/pkg/envtest"
+
+	secretadapter "git.ddupan.top/panxiao81/ayatori/internal/database/adapter/kubernetes"
+	"git.ddupan.top/panxiao81/ayatori/internal/database/adapter/postgresql"
+	"git.ddupan.top/panxiao81/ayatori/internal/database/application"
+	"git.ddupan.top/panxiao81/ayatori/internal/database/domain/instance"
+)
+
+const (
+	fixtureHost         = "fixture.invalid"
+	fixtureUser         = "postgres"
+	fixtureExtension    = "plpgsql"
+	dockerExec          = "exec"
+	fixtureImage        = "postgres@sha256:18cfe3ef5e6815560c98237d6216d1e5119702fb0f3894c8785dd58b8bbe5d73"
+	fixturePassword     = "AYATORI-TEST-ONLY-initial-password"
+	rotatedPassword     = "AYATORI-TEST-ONLY-rotated-password"
+	controllerNamespace = "database-controller"
+	secretName          = "management"
+)
+
+// fixture 不接受外部 DSN，只创建自己的临时容器并按确切 ID 清理。
+func postgresFixture(t *testing.T, ctx context.Context) (string, int) {
+	t.Helper()
+	output, err := exec.CommandContext(ctx, "docker", "run", "--rm", "-d", "-p", "127.0.0.1::5432",
+		"-e", "POSTGRES_PASSWORD="+fixturePassword, fixtureImage).Output()
+	if err != nil {
+		t.Fatalf("cannot start isolated PostgreSQL fixture: %s", fixtureCommandError(err))
+	}
+	id := strings.TrimSpace(string(output))
+	if !regexp.MustCompile(`^[a-f0-9]{64}$`).MatchString(id) {
+		t.Fatal("unexpected container identifier")
+	}
+	t.Cleanup(func() {
+		cleanup, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+		defer cancel()
+		if exec.CommandContext(cleanup, "docker", "rm", "-f", id).Run() != nil {
+			t.Error("fixture cleanup failed")
+		}
+	})
+	output, err = exec.CommandContext(ctx, "docker", "inspect", "--format", `{{(index (index .NetworkSettings.Ports "5432/tcp") 0).HostPort}}`, id).Output()
+	if err != nil {
+		t.Fatalf("cannot inspect fixture port: %s", fixtureCommandError(err))
+	}
+	port, err := strconv.Atoi(strings.TrimSpace(string(output)))
+	if err != nil {
+		t.Fatal("invalid fixture port")
+	}
+	// 初次 init 的临时服务器只监听 Unix socket，必须等最终 TCP listener。
+	for exec.CommandContext(ctx, "docker", dockerExec, id, "pg_isready", "-h", "127.0.0.1", "-U", fixtureUser).Run() != nil {
+		select {
+		case <-ctx.Done():
+			t.Fatal("fixture startup timed out")
+		case <-time.After(200 * time.Millisecond):
+		}
+	}
+	return id, port
+}
+
+// Output 将 stderr 保存在 ExitError 中；保留诊断，但不打印命令参数和测试密码。
+func fixtureCommandError(err error) string {
+	detail := err.Error()
+	if exitErr, ok := errors.AsType[*exec.ExitError](err); ok {
+		detail += ": " + strings.TrimSpace(string(exitErr.Stderr))
+	}
+	redactor := strings.NewReplacer(
+		fixturePassword, "[REDACTED]",
+		rotatedPassword, "[REDACTED]",
+	)
+	return redactor.Replace(detail)
+}
+
+func TestFixtureCommandErrorPreservesDiagnosticsAndRedactsPasswords(t *testing.T) {
+	tests := []struct {
+		name string
+		err  error
+		want string
+	}{
+		{
+			name: "missing docker executable",
+			err:  &exec.Error{Name: "docker", Err: exec.ErrNotFound},
+			want: "executable file not found",
+		},
+		{
+			name: "daemon failure from stderr",
+			err:  &exec.ExitError{Stderr: []byte("Cannot connect to the Docker daemon")},
+			want: "Cannot connect to the Docker daemon",
+		},
+		{
+			name: "passwords in stderr",
+			err:  &exec.ExitError{Stderr: []byte("failure: " + fixturePassword + " " + rotatedPassword)},
+			want: "failure: [REDACTED] [REDACTED]",
+		},
+		{
+			name: "password in error text",
+			err:  errors.New("failure: " + fixturePassword),
+			want: "failure: [REDACTED]",
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			detail := fixtureCommandError(tt.err)
+			if !strings.Contains(detail, tt.want) {
+				t.Fatalf("diagnostic lost expected information: %q", tt.want)
+			}
+			if strings.Contains(detail, fixturePassword) || strings.Contains(detail, rotatedPassword) {
+				t.Fatal("diagnostic exposed a fixture password")
+			}
+		})
+	}
+}
+
+func target(t *testing.T, port int, mode instance.TLSMode) instance.ObservationTarget {
+	t.Helper()
+	id, err := instance.NewIdentity("fixture-uid", "fixture")
+	if err != nil {
+		t.Fatal(err)
+	}
+	revision, err := instance.NewRevision(1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	endpoint, err := instance.NewEndpoint(instance.EndpointValues{
+		Host:               fixtureHost,
+		HostAddr:           "127.0.0.1",
+		Port:               port,
+		ManagementDatabase: fixtureUser,
+		TLSMode:            mode,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	ref, err := instance.NewCredentialReference(instance.CredentialReferenceValues{
+		Name:        secretName,
+		UsernameKey: "login",
+		PasswordKey: "credential",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	definition, err := instance.NewDefinition(endpoint, ref)
+	if err != nil {
+		t.Fatal(err)
+	}
+	value, err := instance.NewObservationTarget(id, revision, definition)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return value
+}
+
+// 在真实读取前设置屏障，确定性验证观测期间 Secret 变化；实际数据仍来自 API server。
+type gatedReader struct {
+	application.CredentialReader
+	beforeRead func()
+}
+
+func (r *gatedReader) Read(ctx context.Context, ref instance.CredentialReference) (application.Credentials, error) {
+	if r.beforeRead != nil {
+		r.beforeRead()
+	}
+	return r.CredentialReader.Read(ctx, ref)
+}
+
+// credentialFixture 为每个场景创建独立 API server、PostgreSQL 和应用服务。
+type credentialFixture struct {
+	ctx          context.Context
+	client       *kubernetes.Clientset
+	reader       *secretadapter.SecretCredentials
+	deniedReader *secretadapter.SecretCredentials
+	gate         *gatedReader
+	service      *application.InstanceService
+	target       instance.ObservationTarget
+	containerID  string
+	port         int
+}
+
+func newCredentialFixture(t *testing.T) *credentialFixture {
+	t.Helper()
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	t.Cleanup(cancel)
+
+	environment := &envtest.Environment{}
+	config, err := environment.Start()
+	if err != nil {
+		t.Fatal("envtest startup failed", err)
+	}
+	t.Cleanup(func() {
+		if err := environment.Stop(); err != nil {
+			t.Error("envtest cleanup failed", err)
+		}
+	})
+
+	client, err := kubernetes.NewForConfig(config)
+	if err != nil {
+		t.Fatal("cannot create test client")
+	}
+	for _, namespace := range []string{controllerNamespace, "unrelated"} {
+		_, err := client.CoreV1().Namespaces().Create(
+			ctx,
+			&corev1.Namespace{Name: namespace},
+			metav1.CreateOptions{},
+		)
+		if err != nil {
+			t.Fatal("cannot create fixture namespace")
+		}
+	}
+
+	reader, err := secretadapter.NewSecretCredentials(config, controllerNamespace)
+	if err != nil {
+		t.Fatal(err)
+	}
+	user, err := environment.AddUser(envtest.User{Name: "without-secret-access"}, config)
+	if err != nil {
+		t.Fatal(err)
+	}
+	deniedReader, err := secretadapter.NewSecretCredentials(user.Config(), controllerNamespace)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	containerID, port := postgresFixture(t, ctx)
+	gate := &gatedReader{CredentialReader: reader}
+	service, err := application.NewInstanceService(gate, postgresql.Connector{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(service.Close)
+
+	return &credentialFixture{
+		ctx:          ctx,
+		client:       client,
+		reader:       reader,
+		deniedReader: deniedReader,
+		gate:         gate,
+		service:      service,
+		target:       target(t, port, instance.TLSDisable),
+		containerID:  containerID,
+		port:         port,
+	}
+}
+
+func (f *credentialFixture) createSecret(t *testing.T, namespace string) {
+	t.Helper()
+	secret := &corev1.Secret{
+		Name: secretName,
+		Data: map[string][]byte{
+			"login":      []byte(fixtureUser),
+			"credential": []byte(fixturePassword),
+		},
+	}
+	if _, err := f.client.CoreV1().Secrets(namespace).Create(f.ctx, secret, metav1.CreateOptions{}); err != nil {
+		t.Fatal("cannot create fixture Secret")
+	}
+}
+
+func (f *credentialFixture) updateSecret(t *testing.T, change func(*corev1.Secret)) {
+	t.Helper()
+	secrets := f.client.CoreV1().Secrets(controllerNamespace)
+	secret, err := secrets.Get(f.ctx, secretName, metav1.GetOptions{})
+	if err != nil {
+		t.Fatal("cannot read fixture Secret")
+	}
+	change(secret)
+	if _, err := secrets.Update(f.ctx, secret, metav1.UpdateOptions{}); err != nil {
+		t.Fatal("cannot update fixture Secret")
+	}
+}
+
+func (f *credentialFixture) observeVersion(t *testing.T) {
+	t.Helper()
+	version, err := f.service.ObserveVersion(f.ctx, f.target)
+	if err != nil {
+		t.Fatal("version observation failed", err)
+	}
+	if version == "" {
+		t.Fatal("successful observation returned an empty version")
+	}
+}
+
+func (f *credentialFixture) queryPostgres(t *testing.T, sql string) string {
+	t.Helper()
+	output, err := exec.CommandContext(
+		f.ctx, "docker", dockerExec, f.containerID,
+		"psql", "-U", fixtureUser, "-tAc", sql,
+	).Output()
+	if err != nil {
+		t.Fatal("fixture SQL failed")
+	}
+	return strings.TrimSpace(string(output))
+}
+
+func (f *credentialFixture) backendIDs(t *testing.T) string {
+	t.Helper()
+	return f.queryPostgres(t, `
+		SELECT pid
+		FROM pg_stat_activity
+		WHERE application_name = 'ayatori-database-management'
+		ORDER BY pid
+	`)
+}

internal/database/adapter/postgresql/metadata.go

@@ -0,0 +1,48 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package postgresql
+
+import (
+	"context"
+
+	"git.ddupan.top/panxiao81/ayatori/internal/database/application"
+)
+
+// 使用 pg_catalog 限定名称，避免管理账号的 search_path 改变查询来源。
+// 一个语句读取版本和可用列表；ARRAY 子查询在无行时返回空数组，而非 NULL。
+// 不查询 pg_extension：已安装集合不能代表服务器提供的全部扩展。
+const inspectMetadataStatement = `
+SELECT
+    pg_catalog.current_setting('server_version'),
+    ARRAY(
+        SELECT name::text
+        FROM pg_catalog.pg_available_extensions
+        ORDER BY name
+    )`
+
+func (d *database) InspectMetadata(ctx context.Context) (application.DatabaseMetadata, error) {
+	var metadata application.DatabaseMetadata
+	err := d.pool.QueryRow(ctx, inspectMetadataStatement).Scan(
+		&metadata.Version,
+		&metadata.AvailableExtensions,
+	)
+	if err != nil {
+		// 不返回部分结果，也不把查询失败转换为“成功观察到空列表”。
+		return application.DatabaseMetadata{}, safeError(err, application.ErrObservation)
+	}
+	return metadata, nil
+}

internal/database/adapter/postgresql/metadata_integration_test.go

@@ -0,0 +1,116 @@
+//go:build integration
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package postgresql_test
+
+import (
+	"errors"
+	"testing"
+
+	corev1 "k8s.io/api/core/v1"
+
+	"git.ddupan.top/panxiao81/ayatori/internal/database/application"
+	"git.ddupan.top/panxiao81/ayatori/internal/database/domain/instance"
+)
+
+func TestMetadataObservesAvailableExtensionsWithoutInstalling(t *testing.T) {
+	f := newCredentialFixture(t)
+	f.createSecret(t, controllerNamespace)
+	if installed := f.queryPostgres(t, "SELECT count(*) FROM pg_catalog.pg_extension WHERE extname = 'hstore'"); installed != "0" {
+		t.Fatal("fixture unexpectedly has hstore installed")
+	}
+	// 提供同名遮蔽对象，验证 adapter 不依赖管理账号可修改的 search_path。
+	f.queryPostgres(t, "CREATE VIEW public.pg_available_extensions AS SELECT 'fake_extension'::name AS name")
+	f.queryPostgres(t, "ALTER ROLE postgres SET search_path = public, pg_catalog")
+	schemasBefore := f.queryPostgres(t, "SELECT string_agg(nspname, ',' ORDER BY nspname) FROM pg_catalog.pg_namespace")
+	observed, err := f.service.ObserveMetadata(f.ctx, f.target)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !observed.Target().Matches(f.target) || observed.Version() == "" {
+		t.Fatal("metadata was not bound to the current target")
+	}
+	requested := instance.NewExtensionSet([]string{"hstore", fixtureExtension})
+	if observed.Extensions().Check(requested).Decision != instance.ExtensionsAccepted {
+		t.Fatal("available but uninstalled extension was omitted")
+	}
+	unsupported := instance.NewExtensionSet([]string{"fake_extension", "HSTORE"})
+	check := observed.Extensions().Check(unsupported)
+	if check.Decision != instance.ExtensionsUnsupported || len(check.Unsupported) != 2 {
+		t.Fatal("metadata accepted shadowed or case-normalized extension names")
+	}
+	if installed := f.queryPostgres(t, "SELECT count(*) FROM pg_catalog.pg_extension WHERE extname = 'hstore'"); installed != "0" {
+		t.Fatal("metadata observation installed an extension")
+	}
+	if schemas := f.queryPostgres(t, "SELECT string_agg(nspname, ',' ORDER BY nspname) FROM pg_catalog.pg_namespace"); schemas != schemasBefore {
+		t.Fatal("metadata observation changed database schemas")
+	}
+
+	aggregate, err := instance.Reconstitute(f.target, instance.Snapshot{}, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := aggregate.ObserveExtensions(observed.Target(), observed.Extensions()); err != nil {
+		t.Fatal(err)
+	}
+	if aggregate.CheckExtensions(requested).Decision != instance.ExtensionsAccepted {
+		t.Fatal("domain rejected observed extension availability")
+	}
+	if err := aggregate.RequireProvisioningReady(); err == nil {
+		t.Fatal("extension availability incorrectly authorized provisioning")
+	}
+}
+
+func TestMetadataPermissionFailureAndRecovery(t *testing.T) {
+	f := newCredentialFixture(t)
+	f.createSecret(t, controllerNamespace)
+	// 低权限账号也能读取可用列表；这不能证明具备 role/database/extension 管理权限。
+	f.queryPostgres(t, "CREATE ROLE metadata_reader LOGIN PASSWORD '"+fixturePassword+"'")
+	f.updateSecret(t, func(secret *corev1.Secret) {
+		secret.Data["login"] = []byte("metadata_reader")
+	})
+	if flags := f.queryPostgres(t, "SELECT rolsuper, rolcreaterole, rolcreatedb FROM pg_catalog.pg_roles WHERE rolname = 'metadata_reader'"); flags != "f|f|f" {
+		t.Fatal("metadata reader unexpectedly has management privileges")
+	}
+	requested := instance.NewExtensionSet([]string{fixtureExtension})
+	observed, err := f.service.ObserveMetadata(f.ctx, f.target)
+	if err != nil || observed.Extensions().Check(requested).Decision != instance.ExtensionsAccepted {
+		t.Fatalf("read-only account could not observe metadata: %v", err)
+	}
+
+	// 仅操作本测试独占容器的 catalog ACL；失败不能转换成“不支持任何扩展”。
+	f.queryPostgres(t, "REVOKE SELECT ON pg_catalog.pg_available_extensions FROM PUBLIC")
+	failed, err := f.service.ObserveMetadata(f.ctx, f.target)
+	if !errors.Is(err, application.ErrObservation) {
+		t.Fatalf("metadata permission failure was not reported safely: %v", err)
+	}
+	if failed.Version() != "" || failed.Target().Validate() == nil {
+		t.Fatal("permission failure returned partial metadata")
+	}
+	if failed.Extensions().Check(requested).Decision != instance.ExtensionSupportUnobserved {
+		t.Fatal("permission failure returned an observed empty set")
+	}
+	if f.backendIDs(t) != "" {
+		t.Fatal("failed metadata connection was retained")
+	}
+	f.queryPostgres(t, "GRANT SELECT ON pg_catalog.pg_available_extensions TO PUBLIC")
+	recovered, err := f.service.ObserveMetadata(f.ctx, f.target)
+	if err != nil || recovered.Extensions().Check(requested).Decision != instance.ExtensionsAccepted {
+		t.Fatalf("metadata observation did not recover: %v", err)
+	}
+}

internal/database/adapter/postgresql/tls_integration_test.go

@@ -0,0 +1,140 @@
+//go:build integration
+
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package postgresql_test
+
+import (
+	"context"
+	"crypto/ecdsa"
+	"crypto/elliptic"
+	"crypto/rand"
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"encoding/pem"
+	"math/big"
+	"net"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"git.ddupan.top/panxiao81/ayatori/internal/database/adapter/postgresql"
+	"git.ddupan.top/panxiao81/ayatori/internal/database/application"
+	"git.ddupan.top/panxiao81/ayatori/internal/database/domain/instance"
+)
+
+func fixtureCertificate(t *testing.T) (string, string) {
+	t.Helper()
+	key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
+	if err != nil {
+		t.Fatal(err)
+	}
+	cert := &x509.Certificate{
+		SerialNumber:          big.NewInt(1),
+		Subject:               pkix.Name{CommonName: fixtureHost},
+		NotBefore:             time.Now().Add(-time.Hour),
+		NotAfter:              time.Now().Add(time.Hour),
+		DNSNames:              []string{fixtureHost},
+		IPAddresses:           []net.IP{net.ParseIP("127.0.0.1")},
+		IsCA:                  true,
+		BasicConstraintsValid: true,
+		KeyUsage:              x509.KeyUsageCertSign | x509.KeyUsageDigitalSignature,
+		ExtKeyUsage:           []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
+	}
+	der, err := x509.CreateCertificate(rand.Reader, cert, cert, &key.PublicKey, key)
+	if err != nil {
+		t.Fatal(err)
+	}
+	encodedKey, err := x509.MarshalECPrivateKey(key)
+	if err != nil {
+		t.Fatal(err)
+	}
+	dir := t.TempDir()
+	certPath := filepath.Join(dir, "server.crt")
+	keyPath := filepath.Join(dir, "server.key")
+	if err := os.WriteFile(certPath, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: der}), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(keyPath, pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: encodedKey}), 0600); err != nil {
+		t.Fatal(err)
+	}
+	return certPath, keyPath
+}
+
+func TestPostgreSQLTLSHostIdentity(t *testing.T) {
+	const psql = "psql"
+	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+	defer cancel()
+	id, port := postgresFixture(t, ctx)
+	certPath, keyPath := fixtureCertificate(t)
+	commands := [][]string{
+		{"cp", certPath, id + ":/tmp/server.crt"},
+		{"cp", keyPath, id + ":/tmp/server.key"},
+		{dockerExec, "-u", "0", id, "chown", "postgres:postgres", "/tmp/server.crt", "/tmp/server.key"},
+		{dockerExec, id, psql, "-U", fixtureUser, "-c", "ALTER SYSTEM SET ssl_cert_file='/tmp/server.crt'"},
+		{dockerExec, id, psql, "-U", fixtureUser, "-c", "ALTER SYSTEM SET ssl_key_file='/tmp/server.key'"},
+		{dockerExec, id, psql, "-U", fixtureUser, "-c", "ALTER SYSTEM SET ssl=on"},
+		{dockerExec, id, psql, "-U", fixtureUser, "-c", "SELECT pg_reload_conf()"},
+	}
+	for _, args := range commands {
+		if exec.CommandContext(ctx, "docker", args...).Run() != nil {
+			t.Fatal("TLS fixture setup failed")
+		}
+	}
+	credentials, err := application.NewCredentials(fixtureUser, fixturePassword)
+	if err != nil {
+		t.Fatal(err)
+	}
+	connector := postgresql.Connector{RootCert: certPath}
+	endpoint := target(t, port, instance.TLSVerifyFull).Definition().Endpoint()
+	db, err := connector.Connect(ctx, endpoint, credentials)
+	if err != nil {
+		t.Fatal("trusted DNS SAN connection failed", err)
+	}
+	if metadata, err := db.InspectMetadata(ctx); err != nil || metadata.Version == "" {
+		db.Close()
+		t.Fatal("TLS metadata read failed", err)
+	}
+	db.Close()
+	values := endpoint.Values()
+	values.Host = "127.0.0.1"
+	ipEndpoint, err := instance.NewEndpoint(values)
+	if err != nil {
+		t.Fatal(err)
+	}
+	db, err = connector.Connect(ctx, ipEndpoint, credentials)
+	if err != nil {
+		t.Fatal("trusted IP SAN connection failed", err)
+	}
+	db.Close()
+	values.Host = "wrong.invalid"
+	wrongEndpoint, err := instance.NewEndpoint(values)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if db, err := connector.Connect(ctx, wrongEndpoint, credentials); err == nil {
+		db.Close()
+		t.Fatal("wrong TLS hostname accepted")
+	}
+	otherCA, _ := fixtureCertificate(t)
+	if db, err := (postgresql.Connector{RootCert: otherCA}).Connect(ctx, endpoint, credentials); err == nil {
+		db.Close()
+		t.Fatal("wrong CA accepted")
+	}
+}

internal/database/application/credentials.go

@@ -0,0 +1,58 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package application 定义 Database 用例与适配器之间的边界。
+package application
+
+import (
+	"context"
+	"errors"
+
+	"git.ddupan.top/panxiao81/ayatori/internal/database/domain/instance"
+)
+
+var (
+	ErrCredentialsUnavailable = errors.New("management credentials unavailable")
+	ErrCredentialsInvalid     = errors.New("management credentials invalid")
+)
+
+// Credentials 只存在于应用与连接适配器内存，不进入领域对象或持久化状态。
+type Credentials struct {
+	username string
+	password string
+}
+
+func NewCredentials(username, password string) (Credentials, error) {
+	if username == "" || password == "" {
+		return Credentials{}, ErrCredentialsInvalid
+	}
+	return Credentials{username: username, password: password}, nil
+}
+
+func (c Credentials) Username() string { return c.username }
+func (c Credentials) Password() string { return c.password }
+func (c Credentials) String() string   { return "[redacted management credentials]" }
+func (c Credentials) GoString() string { return c.String() }
+
+// MarshalJSON 显式隐藏内容，避免未来字段调整意外改变日志或序列化行为。
+func (c Credentials) MarshalJSON() ([]byte, error) {
+	return []byte(`"[redacted management credentials]"`), nil
+}
+
+// CredentialReader 返回本次读取的有效值；metadata 不参与凭据相等比较。
+type CredentialReader interface {
+	Read(context.Context, instance.CredentialReference) (Credentials, error)
+}

internal/database/application/credentials_test.go

@@ -0,0 +1,70 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package application
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+	"testing"
+)
+
+const testUsername = "test-user"
+
+func TestCredentialsRejectEmptyValues(t *testing.T) {
+	for _, values := range [][2]string{
+		{"", "test-password"},
+		{testUsername, ""},
+		{"", ""},
+	} {
+		if _, err := NewCredentials(values[0], values[1]); err != ErrCredentialsInvalid {
+			t.Fatal("empty credential was accepted")
+		}
+	}
+}
+
+func TestCredentialAndServiceFormattingIsRedacted(t *testing.T) {
+	const canary = "SECRET-CANARY-never-log-this"
+	credentials, err := NewCredentials(canary, canary)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if credentials.Username() != canary || credentials.Password() != canary {
+		t.Fatal("explicit credential access changed values")
+	}
+
+	service, err := NewInstanceService(&sourceStub{credentials: credentials}, &connectorStub{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(service.Close)
+
+	encoded, err := json.Marshal(credentials)
+	if err != nil {
+		t.Fatal(err)
+	}
+	outputs := []string{
+		string(encoded),
+		fmt.Sprintf("%v %+v %#v", credentials, credentials, credentials),
+		fmt.Sprintf("%v %+v %#v", service, service, service),
+	}
+	for _, output := range outputs {
+		if strings.Contains(output, canary) {
+			t.Fatal("formatting leaked credential data")
+		}
+	}
+}

internal/database/application/instance_service.go

@@ -0,0 +1,185 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package application
+
+import (
+	"context"
+	"errors"
+	"sync"
+
+	"git.ddupan.top/panxiao81/ayatori/internal/database/domain/instance"
+)
+
+var (
+	ErrConnection         = errors.New("management connection unavailable")
+	ErrAuthentication     = errors.New("management authentication failed")
+	ErrObservation        = errors.New("management observation failed")
+	ErrCredentialsChanged = errors.New("management credentials changed during observation")
+	ErrClosed             = errors.New("instance service closed")
+)
+
+// Database 与 Connector 复用原项目 internal/instance/service.go 的能力边界。
+// Metadata 只查询版本与可用扩展，不能产生领域 Ready。
+type Database interface {
+	InspectMetadata(context.Context) (DatabaseMetadata, error)
+	Close()
+}
+
+type Connector interface {
+	Connect(context.Context, instance.Endpoint, Credentials) (Database, error)
+}
+
+type entry struct {
+	target      instance.ObservationTarget
+	credentials Credentials
+	database    Database
+}
+
+// InstanceService 由原 Service 迁移：连接复用与释放属于应用装配，不属于 SQL adapter。
+// 保留原实现串行操作的约束，防止 Close 与查询并发；controller 停止 worker 后调用 Close。
+// 不缓存能力观察，不把连接存活等同于 Ready。凭据每轮重新读取，而非只在引用变化时读取。
+type InstanceService struct {
+	mu        sync.Mutex
+	source    CredentialReader
+	connector Connector
+	entries   map[string]*entry
+	closed    bool
+}
+
+func NewInstanceService(source CredentialReader, connector Connector) (*InstanceService, error) {
+	if source == nil || connector == nil {
+		return nil, errors.New("credential source and connector required")
+	}
+	return &InstanceService{
+		source:    source,
+		connector: connector,
+		entries:   make(map[string]*entry),
+	}, nil
+}
+
+func (s *InstanceService) String() string   { return "[redacted instance service]" }
+func (s *InstanceService) GoString() string { return s.String() }
+
+// ObserveVersion 是完整 metadata 读取的便捷入口，不再维护另一条连接或查询路径。
+func (s *InstanceService) ObserveVersion(ctx context.Context, target instance.ObservationTarget) (string, error) {
+	observation, err := s.ObserveMetadata(ctx, target)
+	return observation.Version(), err
+}
+
+// ObserveMetadata 返回当前目标和凭据下的版本与扩展；任何失败均丢弃全部结果。
+// 调用者仍需使用 CR resourceVersion 保存前提防止 spec 并发修改；本方法不建立跨系统事务。
+func (s *InstanceService) ObserveMetadata(ctx context.Context, target instance.ObservationTarget) (MetadataObservation, error) {
+	if err := target.Validate(); err != nil {
+		return MetadataObservation{}, err
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if s.closed {
+		return MetadataObservation{}, ErrClosed
+	}
+	if err := ctx.Err(); err != nil {
+		return MetadataObservation{}, err
+	}
+
+	// 先读取有效凭据。读取失败时不得继续使用缓存中的旧连接。
+	name := target.Identity().Name()
+	credentials, err := s.source.Read(ctx, target.Definition().AdminCredential())
+	if err != nil {
+		s.release(name)
+		return MetadataObservation{}, credentialError(err)
+	}
+	if credentials.username == "" || credentials.password == "" {
+		s.release(name)
+		return MetadataObservation{}, ErrCredentialsInvalid
+	}
+
+	// 连接身份与有效值均未变化时复用 pgxpool；generation 本身不要求换池。
+	current := s.entries[name]
+	if current != nil && (current.target.Identity() != target.Identity() ||
+		current.target.Definition() != target.Definition() || current.credentials != credentials) {
+		s.release(name)
+		current = nil
+	}
+	if current == nil {
+		database, err := s.connector.Connect(ctx, target.Definition().Endpoint(), credentials)
+		if err != nil {
+			return MetadataObservation{}, err
+		}
+		current = &entry{
+			target:      target,
+			credentials: credentials,
+			database:    database,
+		}
+		s.entries[name] = current
+	}
+
+	metadata, err := current.database.InspectMetadata(ctx)
+	if err != nil {
+		s.release(name)
+		return MetadataObservation{}, err
+	}
+	if metadata.Version == "" {
+		s.release(name)
+		return MetadataObservation{}, ErrObservation
+	}
+
+	// 回读后再检查凭据，避免把轮换前取得的结果交给新凭据的调用链。
+	latest, err := s.source.Read(ctx, target.Definition().AdminCredential())
+	if err != nil {
+		s.release(name)
+		return MetadataObservation{}, credentialError(err)
+	}
+	if latest != credentials {
+		s.release(name)
+		return MetadataObservation{}, ErrCredentialsChanged
+	}
+	return MetadataObservation{
+		target:     target,
+		version:    metadata.Version,
+		extensions: instance.ObserveExtensionSupport(metadata.AvailableExtensions),
+	}, nil
+}
+
+func credentialError(err error) error {
+	if errors.Is(err, ErrCredentialsInvalid) {
+		return ErrCredentialsInvalid
+	}
+	return ErrCredentialsUnavailable
+}
+
+// Forget 只释放本地连接；不删除数据库，不替代 Instance finalizer。
+func (s *InstanceService) Forget(name string) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.release(name)
+}
+
+func (s *InstanceService) release(name string) {
+	if current := s.entries[name]; current != nil {
+		current.database.Close()
+	}
+	delete(s.entries, name)
+}
+
+func (s *InstanceService) Close() {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.closed = true
+	for name := range s.entries {
+		s.release(name)
+	}
+}

internal/database/application/instance_service_test.go

@@ -0,0 +1,249 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package application
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"git.ddupan.top/panxiao81/ayatori/internal/database/domain/instance"
+)
+
+const serviceTestPassword = "test-only"
+
+// 延续源项目 Service 测试，用于穷举身份与装配失败；真实行为由 adapter 集成测试验证。
+type sourceStub struct {
+	credentials Credentials
+	err         error
+}
+
+func (s *sourceStub) Read(context.Context, instance.CredentialReference) (Credentials, error) {
+	return s.credentials, s.err
+}
+
+type databaseStub struct {
+	closes   int
+	err      error
+	metadata DatabaseMetadata
+}
+
+func (d *databaseStub) InspectMetadata(context.Context) (DatabaseMetadata, error) {
+	return d.metadata, d.err
+}
+func (d *databaseStub) Close() {
+	d.closes++
+}
+
+type connectorStub struct {
+	databases []*databaseStub
+	err       error
+}
+
+func (c *connectorStub) Connect(context.Context, instance.Endpoint, Credentials) (Database, error) {
+	if c.err != nil {
+		return nil, c.err
+	}
+	db := &databaseStub{
+		metadata: DatabaseMetadata{
+			Version:             "17",
+			AvailableExtensions: []string{"plpgsql"},
+		},
+	}
+	c.databases = append(c.databases, db)
+	return db, nil
+}
+
+func serviceTarget(t *testing.T, uid, host, secret string, generation int64) instance.ObservationTarget {
+	t.Helper()
+	id, err := instance.NewIdentity(uid, "shared")
+	if err != nil {
+		t.Fatal(err)
+	}
+	revision, err := instance.NewRevision(generation)
+	if err != nil {
+		t.Fatal(err)
+	}
+	endpoint, err := instance.NewEndpoint(instance.EndpointValues{
+		Host:               host,
+		HostAddr:           "127.0.0.1",
+		Port:               5432,
+		ManagementDatabase: "postgres",
+		TLSMode:            instance.TLSDisable,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	ref, err := instance.NewCredentialReference(instance.CredentialReferenceValues{
+		Name:        secret,
+		UsernameKey: "user",
+		PasswordKey: "pass",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	definition, err := instance.NewDefinition(endpoint, ref)
+	if err != nil {
+		t.Fatal(err)
+	}
+	target, err := instance.NewObservationTarget(id, revision, definition)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return target
+}
+
+func TestInstanceConnectionIdentity(t *testing.T) {
+	source := &sourceStub{credentials: Credentials{username: testUsername, password: serviceTestPassword}}
+	connector := &connectorStub{}
+	service, err := NewInstanceService(source, connector)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer service.Close()
+	ctx := context.Background()
+	cases := []struct {
+		name            string
+		target          instance.ObservationTarget
+		wantConnections int
+	}{
+		{"initial connection", serviceTarget(t, "uid-1", "first", "admin", 1), 1},
+		{"generation alone", serviceTarget(t, "uid-1", "first", "admin", 2), 1},
+		{"endpoint changed", serviceTarget(t, "uid-1", "second", "admin", 3), 2},
+		{"reference changed", serviceTarget(t, "uid-1", "second", "replacement", 4), 3},
+		{"same name with new UID", serviceTarget(t, "uid-2", "second", "replacement", 1), 4},
+	}
+	for _, testCase := range cases {
+		observation, err := service.ObserveMetadata(ctx, testCase.target)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !observation.Target().Matches(testCase.target) {
+			t.Fatalf("%s: observation was bound to a previous target", testCase.name)
+		}
+		if len(connector.databases) != testCase.wantConnections {
+			t.Fatalf("%s: got %d connections, want %d", testCase.name, len(connector.databases), testCase.wantConnections)
+		}
+	}
+	for _, db := range connector.databases[:3] {
+		if db.closes != 1 {
+			t.Fatal("replaced connection not closed exactly once")
+		}
+	}
+	service.Forget("shared")
+	service.Forget("shared")
+	if connector.databases[3].closes != 1 {
+		t.Fatal("forget did not close exactly once")
+	}
+}
+
+func TestMetadataObservationFreshnessAndFailure(t *testing.T) {
+	source := &sourceStub{credentials: Credentials{username: testUsername, password: serviceTestPassword}}
+	connector := &connectorStub{}
+	service, err := NewInstanceService(source, connector)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer service.Close()
+	ctx := context.Background()
+	target := serviceTarget(t, "metadata-uid", "first", "admin", 1)
+	observed, err := service.ObserveMetadata(ctx, target)
+	if err != nil || observed.Version() != "17" || !observed.Target().Matches(target) {
+		t.Fatalf("metadata observation: %v", err)
+	}
+	requested := instance.NewExtensionSet([]string{"plpgsql"})
+	if observed.Extensions().Check(requested).Decision != instance.ExtensionsAccepted {
+		t.Fatal("extension list was not observed")
+	}
+
+	// 连接可以复用，但每轮必须重新查询；旧观察还必须与 adapter 的可变 slice 脱离。
+	database := connector.databases[0]
+	database.metadata.AvailableExtensions[0] = "replacement"
+	if observed.Extensions().Check(requested).Decision != instance.ExtensionsAccepted {
+		t.Fatal("adapter mutation changed a completed observation")
+	}
+	refreshed, err := service.ObserveMetadata(ctx, target)
+	if err != nil || refreshed.Extensions().Check(requested).Decision != instance.ExtensionsUnsupported {
+		t.Fatalf("extension list was cached across observations: %v", err)
+	}
+	database.metadata.AvailableExtensions = nil
+	empty, err := service.ObserveMetadata(ctx, target)
+	if err != nil || empty.Extensions().Check(requested).Decision != instance.ExtensionsUnsupported {
+		t.Fatalf("successful empty list was treated as unobserved: %v", err)
+	}
+
+	// 即使 adapter 附带部分数据，错误仍使整个观察失效。
+	database.err = ErrObservation
+	failed, err := service.ObserveMetadata(ctx, target)
+	if !errors.Is(err, ErrObservation) || failed.Version() != "" || failed.Target().Validate() == nil {
+		t.Fatal("failed query returned a bound observation")
+	}
+	if failed.Extensions().Check(requested).Decision != instance.ExtensionSupportUnobserved {
+		t.Fatal("failed query was interpreted as an empty extension list")
+	}
+	if _, err := service.ObserveMetadata(ctx, target); err != nil {
+		t.Fatalf("retry after query failure: %v", err)
+	}
+	connector.databases[1].metadata.Version = ""
+	if _, err := service.ObserveMetadata(ctx, target); !errors.Is(err, ErrObservation) {
+		t.Fatal("missing server version was accepted as complete metadata")
+	}
+}
+
+func TestInstanceAssemblyFailureRecovery(t *testing.T) {
+	ctx := context.Background()
+	target := serviceTarget(t, "uid-1", "first", "admin", 1)
+	source := &sourceStub{
+		credentials: Credentials{username: testUsername, password: serviceTestPassword},
+		err:         errors.New("unsafe source error"),
+	}
+	connector := &connectorStub{err: ErrConnection}
+	service, err := NewInstanceService(source, connector)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer service.Close()
+	if version, err := service.ObserveVersion(ctx, target); version != "" || !errors.Is(err, ErrCredentialsUnavailable) {
+		t.Fatal("unsafe source error escaped")
+	}
+	source.err = nil
+	if version, err := service.ObserveVersion(ctx, target); version != "" || !errors.Is(err, ErrConnection) {
+		t.Fatal("connection failure returned evidence")
+	}
+	connector.err = nil
+	if _, err := service.ObserveVersion(ctx, target); err != nil {
+		t.Fatal(err)
+	}
+	connector.databases[0].err = ErrObservation
+	if version, err := service.ObserveVersion(ctx, target); version != "" || !errors.Is(err, ErrObservation) {
+		t.Fatal("failed query returned evidence")
+	}
+	if connector.databases[0].closes != 1 {
+		t.Fatal("failed connection retained")
+	}
+	if _, err := service.ObserveVersion(ctx, target); err != nil {
+		t.Fatal("retry failed", err)
+	}
+	service.Close()
+	service.Close()
+	if connector.databases[1].closes != 1 {
+		t.Fatal("shutdown did not close once")
+	}
+	if _, err := service.ObserveVersion(ctx, target); !errors.Is(err, ErrClosed) {
+		t.Fatal("closed service accepted work")
+	}
+}

internal/database/application/metadata.go

@@ -0,0 +1,40 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package application
+
+import "git.ddupan.top/panxiao81/ayatori/internal/database/domain/instance"
+
+// DatabaseMetadata 是一次只读查询的事实，不包含管理权限或完整就绪结论。
+// AvailableExtensions 是服务器提供的可用列表，不是已安装列表或安装授权。
+type DatabaseMetadata struct {
+	Version             string
+	AvailableExtensions []string
+}
+
+// MetadataObservation 只在查询成功且有效凭据再次核对一致后产生。
+// target 绑定本次调用，而非连接最初创建时的 generation；零值表示没有观察。
+type MetadataObservation struct {
+	target     instance.ObservationTarget
+	version    string
+	extensions instance.ExtensionSupport
+}
+
+func (o MetadataObservation) Target() instance.ObservationTarget { return o.target }
+func (o MetadataObservation) Version() string                    { return o.version }
+func (o MetadataObservation) Extensions() instance.ExtensionSupport {
+	return o.extensions
+}

internal/database/domain/instance/instance.go

@@ -22,11 +22,10 @@ import "errors"
 type Phase string
 
 const (
-	PhasePending              Phase = "Pending"
+	PhasePending    Phase = "Pending"
-	PhaseValidating           Phase = "Validating"
+	PhaseValidating Phase = "Validating"
-	PhaseInitializingRegistry Phase = "InitializingRegistry"
+	PhaseReady      Phase = "Ready"
-	PhaseReady                Phase = "Ready"
+	PhaseDeleting   Phase = "Deleting"
-	PhaseDeleting             Phase = "Deleting"
 )
 
 type Readiness string
@@ -38,22 +37,22 @@ const (
 )
 
 // Snapshot contains persisted observations only, without credentials or live evidence.
-// Failure detail mapping will be added with capability assessment, not intent transitions.
 type Snapshot struct {
 	Phase            Phase
 	ObservedRevision int64
 	Readiness        Readiness
 	ReportedVersion  string
+	Failure          Failure
 }
 
 // Instance protects registration state and pure lifecycle transitions.
 // Reconstitution does not establish live capability evidence, even for a Ready snapshot.
-// This initial slice deliberately exposes no operation that authorizes provisioning.
 type Instance struct {
 	target     ObservationTarget
 	snapshot   Snapshot
 	deleting   bool
 	extensions ExtensionSupport
+	evidence   *CapabilityObservation
 }
 
 func Reconstitute(target ObservationTarget, snapshot Snapshot, deleting bool) (*Instance, error) {
@@ -61,7 +60,7 @@ func Reconstitute(target ObservationTarget, snapshot Snapshot, deleting bool) (*
 		return nil, err
 	}
 	switch snapshot.Phase {
-	case PhasePending, PhaseValidating, PhaseInitializingRegistry, PhaseReady, PhaseDeleting:
+	case PhasePending, PhaseValidating, PhaseReady, PhaseDeleting:
 	default:
 		snapshot.Phase = PhasePending
 		snapshot.Readiness = Unknown
@@ -85,6 +84,8 @@ func (i *Instance) BeginValidation() error {
 	i.snapshot.Phase = PhaseValidating
 	i.snapshot.Readiness = Unknown
 	i.extensions = ExtensionSupport{}
+	i.evidence = nil
+	i.snapshot.Failure = NoFailure
 	return nil
 }
 
@@ -100,6 +101,8 @@ func (i *Instance) BeginDeletion() error {
 	i.snapshot.Phase = PhaseDeleting
 	i.snapshot.Readiness = Unknown
 	i.extensions = ExtensionSupport{}
+	i.evidence = nil
+	i.snapshot.Failure = NoFailure
 	return nil
 }
 

internal/database/domain/instance/instance_extensions_test.go

@@ -29,10 +29,10 @@ func TestInstanceAcceptsExtensionObservationForCurrentTarget(t *testing.T) {
 	target := value.Target()
 	snapshot := value.Snapshot()
 
-	if err := value.ObserveExtensions(target, instance.ObserveExtensionSupport([]string{"pg_trgm"})); err != nil {
+	if err := value.ObserveExtensions(target, instance.ObserveExtensionSupport([]string{testTrigram})); err != nil {
 		t.Fatal(err)
 	}
-	if got := value.CheckExtensions(instance.NewExtensionSet([]string{"pg_trgm"})); got.Decision != instance.ExtensionsAccepted {
+	if got := value.CheckExtensions(instance.NewExtensionSet([]string{testTrigram})); got.Decision != instance.ExtensionsAccepted {
 		t.Fatalf("CheckExtensions() = %v, want accepted", got)
 	}
 	if value.Snapshot() != snapshot {
@@ -52,20 +52,20 @@ func TestInstanceRejectsExtensionObservationForDifferentTarget(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	if err := value.ObserveExtensions(different, instance.ObserveExtensionSupport([]string{"pg_trgm"})); err == nil {
+	if err := value.ObserveExtensions(different, instance.ObserveExtensionSupport([]string{testTrigram})); err == nil {
 		t.Fatal("observation for a different target was accepted")
 	}
-	if got := value.CheckExtensions(instance.NewExtensionSet([]string{"pg_trgm"})); got.Decision != instance.ExtensionSupportUnobserved {
+	if got := value.CheckExtensions(instance.NewExtensionSet([]string{testTrigram})); got.Decision != instance.ExtensionSupportUnobserved {
 		t.Fatalf("rejected observation changed support: %v", got)
 	}
 }
 
 func TestInstanceClearsExtensionObservationAcrossLifecycleBoundaries(t *testing.T) {
-	requested := instance.NewExtensionSet([]string{"pg_trgm"})
+	requested := instance.NewExtensionSet([]string{testTrigram})
 
 	t.Run("validation", func(t *testing.T) {
 		value := lifecycleInstance(t, instance.Snapshot{Phase: instance.PhaseReady}, false)
-		if err := value.ObserveExtensions(value.Target(), instance.ObserveExtensionSupport([]string{"pg_trgm"})); err != nil {
+		if err := value.ObserveExtensions(value.Target(), instance.ObserveExtensionSupport([]string{testTrigram})); err != nil {
 			t.Fatal(err)
 		}
 		if err := value.BeginValidation(); err != nil {
@@ -78,7 +78,7 @@ func TestInstanceClearsExtensionObservationAcrossLifecycleBoundaries(t *testing.
 
 	t.Run("deletion", func(t *testing.T) {
 		value := lifecycleInstance(t, instance.Snapshot{Phase: instance.PhaseReady}, true)
-		if err := value.ObserveExtensions(value.Target(), instance.ObserveExtensionSupport([]string{"pg_trgm"})); err == nil {
+		if err := value.ObserveExtensions(value.Target(), instance.ObserveExtensionSupport([]string{testTrigram})); err == nil {
 			t.Fatal("deleting instance accepted a new observation")
 		}
 		if err := value.BeginDeletion(); err != nil {
@@ -92,8 +92,8 @@ func TestInstanceClearsExtensionObservationAcrossLifecycleBoundaries(t *testing.
 
 func TestInstanceCanExplicitlyInvalidateExtensionObservation(t *testing.T) {
 	value := lifecycleInstance(t, instance.Snapshot{Phase: instance.PhaseValidating}, false)
-	requested := instance.NewExtensionSet([]string{"pg_trgm"})
+	requested := instance.NewExtensionSet([]string{testTrigram})
-	if err := value.ObserveExtensions(value.Target(), instance.ObserveExtensionSupport([]string{"pg_trgm"})); err != nil {
+	if err := value.ObserveExtensions(value.Target(), instance.ObserveExtensionSupport([]string{testTrigram})); err != nil {
 		t.Fatal(err)
 	}
 	if err := value.ObserveExtensions(value.Target(), instance.ExtensionSupport{}); err != nil {

internal/database/domain/instance/instance_test.go

@@ -39,7 +39,7 @@ func lifecycleInstance(t *testing.T, snapshot instance.Snapshot, deleting bool)
 // Acceptance: docs/database/domain-instance.md §3, checkpoint reconstruction and intent-only transitions.
 func TestReconstituteCheckpoints(t *testing.T) {
 	for _, phase := range []instance.Phase{
-		instance.PhasePending, instance.PhaseValidating, instance.PhaseInitializingRegistry,
+		instance.PhasePending, instance.PhaseValidating,
 		instance.PhaseReady, instance.PhaseDeleting,
 	} {
 		snapshot := instance.Snapshot{Phase: phase, ObservedRevision: 1, Readiness: instance.Ready, ReportedVersion: "17"}
@@ -97,7 +97,7 @@ func TestDeletionRequiresRequestAndPreventsValidation(t *testing.T) {
 		t.Fatal("rejected deletion mutated state")
 	}
 	for _, phase := range []instance.Phase{
-		instance.PhasePending, instance.PhaseValidating, instance.PhaseInitializingRegistry,
+		instance.PhasePending, instance.PhaseValidating,
 		instance.PhaseReady, instance.PhaseDeleting,
 	} {
 		snapshot.Phase = phase

internal/database/domain/instance/readiness.go

@@ -0,0 +1,162 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package instance
+
+import "errors"
+
+// Failure 只表示安全类别；驱动错误、凭据和 Condition 文案留在应用边界。
+type Failure uint8
+
+const (
+	NoFailure Failure = iota
+	ObservationIncomplete
+	DependencyUnavailable
+	AuthenticationFailed
+	InsufficientPrivileges
+)
+
+// CheckResult 的零值表示未观察，不能视为成功。
+type CheckResult uint8
+
+const (
+	CheckUnobserved CheckResult = iota
+	CheckPassed
+	CheckUnavailable
+	CheckAuthenticationFailed
+	CheckInsufficientPrivileges
+)
+
+// ManagementChecks 分别记录所需能力；SQL 探测和同轮次关联由 adapter/application 保证。
+// Extensions 不代表任意扩展均可安装；具体请求仍需支持检查、执行及回读。
+type ManagementChecks struct {
+	Connection CheckResult
+	Metadata   CheckResult
+	Roles      CheckResult
+	Databases  CheckResult
+	Grants     CheckResult
+	Extensions CheckResult
+}
+
+func (c ManagementChecks) failure() Failure {
+	for _, check := range []CheckResult{c.Connection, c.Metadata, c.Roles, c.Databases, c.Grants, c.Extensions} {
+		switch check {
+		case CheckPassed:
+		case CheckUnavailable:
+			return DependencyUnavailable
+		case CheckAuthenticationFailed:
+			return AuthenticationFailed
+		case CheckInsufficientPrivileges:
+			return InsufficientPrivileges
+		default:
+			return ObservationIncomplete
+		}
+	}
+	return NoFailure
+}
+
+// CapabilityObservation 是值对象，不包含连接、凭据或可变集合。
+type CapabilityObservation struct {
+	target  ObservationTarget
+	version string
+	checks  ManagementChecks
+}
+
+func NewCapabilityObservation(
+	target ObservationTarget,
+	version string,
+	checks ManagementChecks,
+) (CapabilityObservation, error) {
+	if err := target.Validate(); err != nil {
+		return CapabilityObservation{}, err
+	}
+	return CapabilityObservation{target: target, version: version, checks: checks}, nil
+}
+
+func (o CapabilityObservation) managementFailure() Failure {
+	if failure := o.checks.failure(); failure != NoFailure {
+		return failure
+	}
+	if o.version == "" {
+		return ObservationIncomplete
+	}
+	return NoFailure
+}
+
+func (i *Instance) acceptObservation(o CapabilityObservation, phase Phase) error {
+	if !i.target.Matches(o.target) {
+		return errors.New("capability observation target does not match instance")
+	}
+	if i.deleting || i.snapshot.Phase != phase {
+		return errors.New("capability observation is not allowed in current lifecycle")
+	}
+	return nil
+}
+
+func (i *Instance) fail(failure Failure) {
+	i.evidence = nil
+	i.extensions = ExtensionSupport{}
+	i.snapshot.Readiness = NotReady
+	i.snapshot.Failure = failure
+	i.snapshot.ObservedRevision = i.target.Revision().Value()
+}
+
+// AssessManagement 根据本轮完整能力观察完成验证，不执行外部写入。
+func (i *Instance) AssessManagement(o CapabilityObservation) error {
+	if err := i.acceptObservation(o, PhaseValidating); err != nil {
+		return err
+	}
+	i.assessComplete(o)
+	return nil
+}
+
+func (i *Instance) assessComplete(o CapabilityObservation) {
+	if failure := o.managementFailure(); failure != NoFailure {
+		i.fail(failure)
+		return
+	}
+	i.snapshot = Snapshot{
+		Phase:            PhaseReady,
+		ObservedRevision: i.target.Revision().Value(),
+		Readiness:        Ready,
+		ReportedVersion:  o.version,
+	}
+	i.evidence = &o
+}
+
+// AssessReadiness 每轮接收完整事实，失败立即撤销本轮供应能力。
+func (i *Instance) AssessReadiness(o CapabilityObservation) error {
+	if err := i.acceptObservation(o, PhaseReady); err != nil {
+		return err
+	}
+	if i.snapshot.ObservedRevision != i.target.Revision().Value() {
+		return i.BeginValidation()
+	}
+	if o.managementFailure() != NoFailure {
+		i.snapshot.Phase = PhaseValidating
+	}
+	i.assessComplete(o)
+	return nil
+}
+
+// RequireProvisioningReady 仅检查 Instance 前置条件，不授予 Tenant 所有权或外部写入许可。
+func (i *Instance) RequireProvisioningReady() error {
+	if i.deleting || i.evidence == nil || i.snapshot.Phase != PhaseReady || i.snapshot.Readiness != Ready ||
+		i.snapshot.ObservedRevision != i.target.Revision().Value() {
+		return errors.New("instance is not ready for provisioning")
+	}
+	return nil
+}

internal/database/domain/instance/readiness_test.go

@@ -0,0 +1,266 @@
+/*
+Copyright 2026.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package instance_test
+
+import (
+	"testing"
+
+	"git.ddupan.top/panxiao81/ayatori/internal/database/domain/instance"
+)
+
+const testServerVersion = "17.6"
+
+func completeChecks() instance.ManagementChecks {
+	return instance.ManagementChecks{
+		Connection: instance.CheckPassed, Metadata: instance.CheckPassed,
+		Roles: instance.CheckPassed, Databases: instance.CheckPassed,
+		Grants: instance.CheckPassed, Extensions: instance.CheckPassed,
+	}
+}
+
+func capability(t *testing.T, value *instance.Instance, checks instance.ManagementChecks) instance.CapabilityObservation {
+	t.Helper()
+	o, err := instance.NewCapabilityObservation(value.Target(), testServerVersion, checks)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return o
+}
+
+func readyInstance(t *testing.T) *instance.Instance {
+	t.Helper()
+	i := lifecycleInstance(t, instance.Snapshot{Phase: instance.PhaseValidating}, false)
+	if err := i.AssessManagement(capability(t, i, completeChecks())); err != nil {
+		t.Fatal(err)
+	}
+	if err := i.RequireProvisioningReady(); err != nil {
+		t.Fatal(err)
+	}
+	return i
+}
+
+func TestReadinessRequiresCompleteReadBack(t *testing.T) {
+	i := lifecycleInstance(t, instance.Snapshot{}, false)
+	if err := i.BeginValidation(); err != nil {
+		t.Fatal(err)
+	}
+	if i.RequireProvisioningReady() == nil {
+		t.Fatal("validation intent authorized provisioning")
+	}
+	if err := i.AssessManagement(capability(t, i, instance.ManagementChecks{})); err != nil {
+		t.Fatal(err)
+	}
+	if snapshot := i.Snapshot(); snapshot.Phase != instance.PhaseValidating ||
+		snapshot.Readiness != instance.NotReady || snapshot.Failure != instance.ObservationIncomplete {
+		t.Fatalf("incomplete observation accepted: %+v", snapshot)
+	}
+	if i.RequireProvisioningReady() == nil {
+		t.Fatal("incomplete observation authorized provisioning")
+	}
+	if err := i.AssessManagement(capability(t, i, completeChecks())); err != nil {
+		t.Fatal(err)
+	}
+	snapshot := i.Snapshot()
+	if snapshot.Phase != instance.PhaseReady || snapshot.Readiness != instance.Ready ||
+		snapshot.ReportedVersion != testServerVersion ||
+		snapshot.ObservedRevision != i.Target().Revision().Value() {
+		t.Fatalf("complete management observation did not establish readiness: %+v", snapshot)
+	}
+	if err := i.RequireProvisioningReady(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// 重启只恢复 checkpoint；依赖稍后恢复时必须重新取得完整事实。
+func TestReadinessRecoveryAndInvalidation(t *testing.T) {
+	i := readyInstance(t)
+	restored, err := instance.Reconstitute(i.Target(), i.Snapshot(), false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if restored.RequireProvisioningReady() == nil {
+		t.Fatal("persisted Ready fabricated fresh evidence")
+	}
+	for range 2 {
+		if err := restored.AssessReadiness(capability(t, restored, completeChecks())); err != nil {
+			t.Fatal(err)
+		}
+		if err := restored.RequireProvisioningReady(); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := restored.BeginValidation(); err != nil {
+		t.Fatal(err)
+	}
+	if restored.RequireProvisioningReady() == nil {
+		t.Fatal("validation retained evidence")
+	}
+	deleted, err := instance.Reconstitute(i.Target(), i.Snapshot(), true)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if deleted.RequireProvisioningReady() == nil {
+		t.Fatal("deletion allowed provisioning")
+	}
+	if err := deleted.BeginDeletion(); err != nil {
+		t.Fatal(err)
+	}
+	if deleted.RequireProvisioningReady() == nil {
+		t.Fatal("deleting checkpoint allowed provisioning")
+	}
+}
+
+func TestEachManagementCheckIsRequired(t *testing.T) {
+	checkNames := []string{"connection", "metadata", "roles", "databases", "grants", "extensions"}
+	failures := []struct {
+		name   string
+		result instance.CheckResult
+		want   instance.Failure
+	}{
+		{"unobserved", instance.CheckUnobserved, instance.ObservationIncomplete},
+		{"unavailable", instance.CheckUnavailable, instance.DependencyUnavailable},
+		{"authentication", instance.CheckAuthenticationFailed, instance.AuthenticationFailed},
+		{"privileges", instance.CheckInsufficientPrivileges, instance.InsufficientPrivileges},
+		{"unknown", 255, instance.ObservationIncomplete},
+	}
+	for field, name := range checkNames {
+		for _, failure := range failures {
+			for _, phase := range []instance.Phase{instance.PhaseValidating, instance.PhaseReady} {
+				t.Run(name+"/"+failure.name+"/"+string(phase), func(t *testing.T) {
+					checks := completeChecks()
+					fields := []*instance.CheckResult{
+						&checks.Connection, &checks.Metadata, &checks.Roles,
+						&checks.Databases, &checks.Grants, &checks.Extensions,
+					}
+					*fields[field] = failure.result
+					value := lifecycleInstance(t, instance.Snapshot{Phase: phase}, false)
+					assess := value.AssessManagement
+					if phase == instance.PhaseReady {
+						value = readyInstance(t)
+						assess = value.AssessReadiness
+					}
+					if err := assess(capability(t, value, checks)); err != nil {
+						t.Fatal(err)
+					}
+					snapshot := value.Snapshot()
+					if snapshot.Phase != instance.PhaseValidating ||
+						snapshot.Readiness != instance.NotReady ||
+						snapshot.Failure != failure.want ||
+						snapshot.ObservedRevision != value.Target().Revision().Value() {
+						t.Fatalf("incorrect failed observation: %+v", snapshot)
+					}
+					if value.RequireProvisioningReady() == nil {
+						t.Fatal("failed check authorized provisioning")
+					}
+					// 依赖恢复后重新验证，不保留失败或旧就绪证据。
+					if err := value.AssessManagement(capability(t, value, completeChecks())); err != nil {
+						t.Fatal(err)
+					}
+					if err := value.RequireProvisioningReady(); err != nil {
+						t.Fatal("dependency recovery did not restore readiness", err)
+					}
+				})
+			}
+		}
+	}
+}
+
+func TestReadinessMethodsRejectWrongPhaseAndDeletion(t *testing.T) {
+	for _, deleting := range []bool{false, true} {
+		for _, phase := range []instance.Phase{instance.PhasePending, instance.PhaseValidating,
+			instance.PhaseReady, instance.PhaseDeleting} {
+			for _, operation := range []struct {
+				phase instance.Phase
+				apply func(*instance.Instance, instance.CapabilityObservation) error
+			}{
+				{instance.PhaseValidating, (*instance.Instance).AssessManagement},
+				{instance.PhaseReady, (*instance.Instance).AssessReadiness},
+			} {
+				if !deleting && operation.phase == phase {
+					continue
+				}
+				i := lifecycleInstance(t, instance.Snapshot{Phase: phase}, deleting)
+				before := i.Snapshot()
+				if err := operation.apply(i, capability(t, i, completeChecks())); err == nil {
+					t.Fatalf("phase %s deleting=%t accepted operation for %s", phase, deleting, operation.phase)
+				}
+				if i.Snapshot() != before {
+					t.Fatal("rejected operation mutated snapshot")
+				}
+			}
+		}
+	}
+}
+
+func TestOldGenerationObservationDoesNotReplaceEvidence(t *testing.T) {
+	i := readyInstance(t)
+	target := i.Target()
+	revision, err := instance.NewRevision(target.Revision().Value() + 1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	other, err := instance.NewObservationTarget(target.Identity(), revision, target.Definition())
+	if err != nil {
+		t.Fatal(err)
+	}
+	o, err := instance.NewCapabilityObservation(other, testServerVersion, completeChecks())
+	if err != nil {
+		t.Fatal(err)
+	}
+	before := i.Snapshot()
+	if err := i.AssessReadiness(o); err == nil || i.Snapshot() != before {
+		t.Fatal("mismatched generation observation was accepted")
+	}
+	if err := i.RequireProvisioningReady(); err != nil {
+		t.Fatal("rejected unrelated input changed previously accepted evidence", err)
+	}
+}
+
+func TestCapabilityInputsAndLifecycleGuards(t *testing.T) {
+	i := readyInstance(t)
+	if _, err := instance.NewCapabilityObservation(instance.ObservationTarget{}, testServerVersion,
+		completeChecks()); err == nil {
+		t.Fatal("invalid target accepted")
+	}
+	for _, method := range []func(instance.CapabilityObservation) error{
+		i.AssessManagement, i.AssessReadiness,
+	} {
+		before := i.Snapshot()
+		if err := method(instance.CapabilityObservation{}); err == nil || i.Snapshot() != before {
+			t.Fatal("mismatched observation accepted or mutated state")
+		}
+	}
+	old := i.Snapshot()
+	old.ObservedRevision = 0
+	changed := lifecycleInstance(t, old, false)
+	if err := changed.AssessReadiness(capability(t, changed, completeChecks())); err != nil {
+		t.Fatal(err)
+	}
+	if s := changed.Snapshot(); s.Phase != instance.PhaseValidating || s.ObservedRevision != 0 || s.Readiness != instance.Unknown {
+		t.Fatalf("changed generation accepted old checkpoint: %+v", s)
+	}
+	o, err := instance.NewCapabilityObservation(i.Target(), "", completeChecks())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := i.AssessReadiness(o); err != nil {
+		t.Fatal(err)
+	}
+	if i.Snapshot().Failure != instance.ObservationIncomplete {
+		t.Fatal("missing version accepted")
+	}
+}