# CMP-62 backend restricted schema contract

日期：2026-03-31  
负责人：Senior Backend Engineer

## Goal

在不引入新持久化层或 migration 的前提下，补齐 shared inspect contract 对 PostgreSQL restricted schema 的可见性与错误语义，避免继续把 restricted schema 误判为 empty / hidden。

## Assessment

- `crates/db-core` / `crates/db-app` 当前 shared inspect payload 原本只有 schema 名称，没有权限可见性字段。
- PostgreSQL root inspect 之前基于 `information_schema.schemata`，restricted schema 会被直接省略。
- 显式 schema inspect 之前基于 `information_schema.tables`，restricted schema 会退化成空列表，和 empty schema 混淆。
- 当前仓库仍没有 app-owned persistence schema；本轮变更只涉及 shared contract、驱动语义和 CLI 可见输出。

## Scope

1. 为 schema root inspect 增加 item-level `availability` / `note`
2. PostgreSQL root inspect 改为保留 restricted schema 名称
3. PostgreSQL explicit schema inspect 在 restricted scope 上返回 inspect error，而非 empty
4. 同步 `TUI_BACKEND_CONTRACT.md` 与 `USABLE_APP_CLI_CONTRACT_SNAPSHOT.md`
5. 为 shared contract / driver / CLI 文本输出补最小测试

## Validation

```bash
export CARGO_HOME="$AGENT_HOME/.cargo"
export RUSTUP_HOME="$AGENT_HOME/.rustup"
export PATH="$AGENT_HOME/tools:$CARGO_HOME/bin:/paperclip/.cargo/bin:${PATH}"
unset CARGO_REGISTRIES_CRATES_IO_PROTOCOL
. "$CARGO_HOME/env"

cargo test -p db-core -p db-app -p db-drivers -p dbtool-cli
```

## Result

- shared inspect schema item 现可区分 `ready` 与 `restricted`
- PostgreSQL root inspect 不再静默隐藏 restricted schema
- PostgreSQL explicit schema inspect 不再把 restricted schema 误报为 empty
- 当前剩余缺口转为 consumer 侧消费与 live fixture 权限模型验证，不是持久化或 migration blocker