> For AI agents: the complete documentation index is available at https://devcodex-labs.github.io/capability-graph/llms.txt, the full documentation bundle is available at https://devcodex-labs.github.io/capability-graph/llms-full.txt.

# 作用域、修订与完整性

可用

有效 Provider 范围是三层集合的交集：

```text
hostAllowedProviders
∩ integrationEnabledProviders
∩ requestProviderScope（若提供）
```

请求只能收窄，不能扩大宿主或集成配置。V1 的授权粒度是 Provider 集合；ID 前缀、父节点和分类是查询过滤，不是节点级授权。

“未被 Agent 选择”也不等于“被 scope 拒绝”。能力仍可在目录中被发现，Runtime `instanceOf` 也可引用它；只有知识查询必须限制在非空已选能力集合内。

Adapter 与 Core 在同一进程中运行，Provider scope 不是进程沙箱。接入层仍需负责用户、租户和项目授权。

例如宿主允许 `acme.http` 和 `acme.database`，集成只启用前者，那么请求加入后者不能扩大范围，会被拒绝。只选择 `acme.http` 中的 `route.validation` 是知识选择；同 Provider 的 `schema.request` 仍可被发现，它不是因此被禁止访问。

故障排查见 [配置与作用域](https://devcodex-labs.github.io/capability-graph/troubleshooting/open-and-configuration.md#%E4%BD%9C%E7%94%A8%E5%9F%9F%E4%B8%8E%E9%80%89%E6%8B%A9)。

## 修订模型

Static Revision 是经过完整校验的 Provider 静态快照身份。Runtime Revision 是 Adapter 对运行观察的身份，两者不能互换。

单 Provider 目录查询返回 `meta.staticRevision`；多 Provider 查询使用 `meta.staticRevisionByProvider`。后续绑定同一 Provider 的详情、关系、知识或 Runtime 查询可以传 `requiredStaticRevision`，保证一次任务继续使用同一静态视图。

例如 Acme 的目录返回修订 S1，Agent 选择验证能力后继续用 S1 读取知识。此时作者发布 S2，仍可读取的 previous 允许任务继续用 S1；若 S1 已退休，调用失败并要求重新发现，不能以 `provider.version = '0.1.0'` 替代 S1。

`reload()` 只有在新候选完整校验成功后才替换 current。Core 保留 current 和 previous：

- 刷新失败时，仍可读取的旧 current 保留，并通过 `refreshFailed` 暴露失败；
- 指定 previous 修订时可读取前一视图；
- 更旧或已不可读的指定修订返回 `CG_REVISION_MISMATCH`；
- 首次加载失败没有旧视图可回退。

Runtime 观察会记录依据的静态修订。仅身份相同但修订变化，不自动等于兼容。

## 结果完整性

查询成功不代表返回全集。消费结果时同时查看数据、`meta.completeness`、`warnings` 和游标。

| 状态          | 含义           | 调用方动作                   |
| ----------- | ------------ | ----------------------- |
| `complete`  | 当前请求范围内完整    | 可继续业务选择                 |
| `truncated` | 命中数量或页预算上限   | 使用 `nextCursor` 续页或收窄过滤 |
| `partial`   | 某些来源、分组或条目失败 | 保留正常项，检查 warning 和逐项错误  |

批量查询保留输入槽位，每个 `BatchItem` 都要检查 `ok`。单个 Provider 离线不应清空其他来源的合法结果；指定权威修订不可读则是查询级失败。

预算不会通过静默删除 `whenToUse` 或 `distinction` 制造“成功”。无法取得任何进展时返回 `CG_BUDGET_EXCEEDED`。实践见 [处理错误与部分结果](https://devcodex-labs.github.io/capability-graph/guides/errors-and-partial-results.md)。