docs(BOR-453/BOR-454): OpenDAL Swift + FSKit research and BOR-455 path

docs/s3-mount-track/BOR-453-opendal-swift-binding.md

@@ -0,0 +1,67 @@
+# BOR-453 · OpenDAL Swift Binding 调研
+
+## 结论（先看）
+
+- **可行**：用 OpenDAL Rust 核心 + Swift 调用层构建 S3 mount 数据面是可行的。
+- **当前建议**：先做“最小可行 binding”（只覆盖 list/read/write/stat/delete），不要一开始追求全量 API。
+- **Google Drive 支持**：OpenDAL 后端本身支持范围在扩展中，但对 mount 场景应先以 S3 为主线，GDrive 作为后续后端接入，不放在 BOR-455 的首批验收。
+
+## 调研要点
+
+### 1) 绑定策略
+
+优先级建议：
+
+1. **C ABI 包一层 Rust facade**（推荐）
+   - Rust 暴露稳定 C 接口
+   - Swift 通过 modulemap/bridging header 调用
+   - 优点：边界清晰，便于控制错误码与内存管理
+
+2. 直接 Swift 调用更复杂 FFI（不推荐作为第一步）
+   - 开发速度慢，调试复杂度高
+
+### 2) API 最小面（BOR-455 需要）
+
+建议先封装以下方法：
+
+- `list(prefix)`
+- `read(path, range?)`
+- `write(path, bytes)`
+- `stat(path)`
+- `delete(path)`
+- `mkdir(path)`（如语义需要）
+
+这组接口已经足够支撑 mount POC 的主流程。
+
+### 3) 错误模型
+
+必须统一 error mapping，否则 FSKit 回调层会非常难维护：
+
+- OpenDAL 错误 → 内部错误码（如 NotFound / PermissionDenied / Timeout / Conflict）
+- 内部错误码 → FSKit 层可识别返回
+
+### 4) 性能/并发
+
+建议落地前就约束：
+
+- 读路径必须支持 range read
+- 写路径要有 chunk/stream 方案
+- 引入连接复用和重试策略（含 backoff）
+
+## 是否需要 fork
+
+- **短期**：不建议先 fork OpenDAL 主仓。先在本仓维护轻量 binding wrapper。
+- **中期**：若遇到必须改 OpenDAL 内核行为再评估 upstream PR / fork。
+
+## 对 BOR-455 的直接输入
+
+- 用 C ABI facade + Swift adapter 的两层结构
+- 先交付 S3 的 read/write/list 流程跑通
+- 暂不把 GDrive 纳入首批 mount DoD
+
+## 下一步清单
+
+- [ ] 建立 `OpenDALBridge` C 接口草案
+- [ ] Swift 侧 `ObjectStoreClient` 协议 + OpenDAL 实现
+- [ ] 错误码映射表（文档 + 单测）
+- [ ] list/read/write 三条 e2e 冒烟测试

docs/s3-mount-track/BOR-454-fskit.md

@@ -0,0 +1,66 @@
+# BOR-454 · FSKit 调研
+
+## 结论（先看）
+
+- **方向正确**：FSKit 是 macOS 挂载体验的关键层。
+- **执行策略**：先把 FS callback 和对象存储适配层解耦，不要让 FSKit 直接理解 S3 细节。
+- **首批目标**：先跑通 browse/read/write 基础路径，再补 rename/move/权限细节。
+
+## 调研要点
+
+### 1) 分层建议
+
+建议 3 层：
+
+1. **FSKitAdapter**
+   - 处理目录枚举、文件读取、写入、元信息回调
+2. **MountCore**
+   - 统一路径解析、缓存、错误转换
+3. **ObjectStoreClient**
+   - 对接 OpenDAL Swift binding（S3 后端）
+
+这样可以把平台 API 变动风险和存储后端变动风险隔离开。
+
+### 2) 最小回调闭环（POC）
+
+POC 阶段必须覆盖：
+
+- `list directory`
+- `read file`
+- `write file`
+- `stat metadata`
+
+可延后：
+
+- rename/move（跨目录语义复杂）
+- 批量操作优化
+- 高级权限映射
+
+### 3) 权限与沙盒
+
+关键点：
+
+- 权限模型需从 day-1 设计（最少权限）
+- 认证信息不能散落在 callback 层
+- 日志里严禁打印密钥/敏感头
+
+### 4) 一致性与缓存
+
+对象存储不是本地 POSIX 盘，需明确：
+
+- 列表与读取可能存在短暂不一致
+- 缓存策略要有 TTL 和失效机制
+- 写后读语义要在文档里定义清楚
+
+## 对 BOR-455 的直接输入
+
+- 先上“可跑通的 FSKitAdapter + Mock/OpenDAL adapter”
+- 先验证 Finder 侧最常见操作路径
+- 逐步补齐复杂文件系统语义
+
+## 下一步清单
+
+- [ ] FS callback -> MountCore 接口定义
+- [ ] 错误码映射（FS 层错误到业务错误）
+- [ ] 缓存策略（目录/元信息）
+- [ ] 小规模真实 bucket 冒烟（读写/并发）

docs/s3-mount-track/BOR-455-implementation-recommendation.md

@@ -0,0 +1,45 @@
+# BOR-455 实施建议（基于 BOR-453/BOR-454）
+
+## 推荐路线（可执行）
+
+### Phase 1（本周）：POC 可跑通
+
+目标：先打通主路径，不追求完整文件系统语义。
+
+- 建 `ObjectStoreClient` 协议（Swift）
+- 接 `OpenDALBridge` 最小 API（list/read/write/stat）
+- 建 `FSKitAdapter`，打通 browse/read/write
+- 完成最小冒烟脚本 + 手工验证清单
+
+### Phase 2（下周）：稳定性补强
+
+- 错误码映射统一
+- 缓存与失效策略
+- 并发读写压测（小规模）
+- rename/move 基础支持
+
+### Phase 3：产品化
+
+- 凭据管理标准化
+- 观测指标（耗时/错误率/重试）
+- 更完整的文件系统语义覆盖
+
+## 风险清单
+
+1. **FS 语义差异风险**（对象存储 vs 本地盘）
+2. **错误映射不一致导致的用户侧异常行为**
+3. **并发/缓存导致的短暂不一致**
+4. **密钥与权限边界处理不当**
+
+## 决策建议
+
+- 先合并 POC 骨架，再迭代完善
+- 不在首批阶段引入 GDrive 等额外后端
+- 以 BOR-455 为主线，把 BOR-453/454 作为设计约束来源
+
+## 验收建议（BOR-455）
+
+- [ ] Finder/挂载入口可触达
+- [ ] list/read/write 主流程可用
+- [ ] 明确记录“已验证/未验证”项
+- [ ] 文档可指导他人在本机复现

docs/s3-mount-track/README.md

@@ -0,0 +1,5 @@
+# S3 Mount Track Notes
+
+- `BOR-453-opendal-swift-binding.md`
+- `BOR-454-fskit.md`
+- `BOR-455-implementation-recommendation.md`