# ADR 0003: CAS 核心接口与错误边界冻结

**状态**：已接受  
**日期**：2026-06-28  
**关联实现**：`../../../core/src/repositories/cas_repository.rs`、`../../../crates/bat-cas-engine/src/repository.rs`、`../../../infrastructure/src/cas/filesystem.rs`

---

## 背景

CAS 是资源同步、资源版本共享、AssetBundle 缓存、Patch 回滚和本地对象存储的基础能力。当前阶段需要冻结 CAS V1 对外接口，避免后续 Manifest、Resource Repository 和 CLI 开发时继续改动底层边界。

---

## 决策

CAS V1 对外领域接口继续使用 `bat_core::repositories::cas_repository::CasRepository`，并冻结以下语义：

1. `store(data)` 存储对象并增加引用计数。
2. `get(id)` 读取对象并校验 Hash。
3. `exists(id)` 只表达对象文件存在性，不增加引用。
4. `add_reference(id)` 增加已存在对象引用。
5. `remove_reference(id)` 减少引用计数，引用计数不得低于 0。
6. `get_reference_count(id)` 返回持久化引用计数。
7. `gc()` 删除引用计数为 0 的对象及其元数据。
8. `store_from_file()` 和 `export_to_file()` 保留为领域接口默认便捷方法。

---

## 错误映射

`bat-cas-engine::CasError` 在 infrastructure 适配层映射为 `bat_core::Error`：

1. `Io` -> `Error::Io`
2. `ObjectNotFound` -> `Error::NotFound`
3. `HashMismatch` -> `Error::InvalidArgument`
4. `InvalidHash` -> `Error::InvalidArgument`
5. `ReferenceUnderflow` -> `Error::InvalidArgument`
6. `Database` -> `Error::Other`
7. `Other` -> `Error::Other`

该映射保证应用层可以只依赖 `bat-core` 的错误边界，不直接泄漏 CAS 引擎内部错误类型。

---

## 后果

1. 后续 Go CLI/API 只能通过领域仓储接口、稳定 SDK 或进程边界调用 CAS，不直接依赖对象目录结构；FFI 仅作为可选实现方式。
2. CAS V1 后续可以替换元数据后端，但不能改变领域接口语义。
3. 如果以后需要 dry-run GC、批量引用更新或流式存储，应作为新接口扩展，不破坏当前 trait。