@c956180462/awbs 0.0.1

package/docs/FULL_CHAIN.md

@@ -0,0 +1,295 @@
+# AWBS 全链路文档
+
+本文档描述 AWBS 初版的完整运行链路。它关注一件事：
+
+```text
+开放文件系统中的业务内容
+  -> 被投影成 agent 工作空间
+  -> 产出 changeset
+  -> 经过 authority 认证
+  -> 推进 AWBS trusted chain
+```
+
+AWBS 不是沙箱系统。它不承诺阻止人或进程直接修改文件系统、Git HEAD 或工作区。AWBS 的承诺是：**只有 AWBS 可信链承认的 operation，才进入 AWBS 认证数据库事实。**
+
+## 1. 核心事实源
+
+AWBS 初版里有三类事实：
+
+```text
+业务事实
+  普通目录和文件
+
+版本事实
+  Git commit / tree / diff
+
+认证事实
+  .awbs/authority/*
+  refs/awbs/trusted
+```
+
+普通 Git `HEAD` 不等于 AWBS 认证数据库。当前工作区也不等于 AWBS 认证数据库。
+
+AWBS 认证数据库定义为：
+
+```text
+refs/awbs/trusted 指向的 Git commit 对应的 tree
++ sealed authority ledger 中可验证的 head entry
+```
+
+## 2. 初始化链路
+
+命令：
+
+```powershell
+awbs init
+```
+
+发生的事情：
+
+- 如果当前目录不是 Git repo，执行 `git init`。
+- 创建 `.awbs/` 基础结构。
+- 初始化 `.awbs/authority/repo.json`。
+- 生成 `.awbs/private/local.json`。
+- 创建 sealed authority catalog。
+- 写入 `.awbs/.gitignore`，忽略 index、views、changesets、private。
+
+随后用户需要创建初始 Git commit：
+
+```powershell
+git add .
+git commit -m "initialize database"
+```
+
+AWBS 不自动创建 initial commit，因为初始数据库内容应该由上层应用或用户明确决定。
+
+## 3. Authority Session 链路
+
+命令：
+
+```powershell
+'{"recoverySecret":"dev-recovery","controllerToken":"dev-controller"}' |
+  awbs authority session start --control-stdin
+```
+
+发生的事情：
+
+- host controller 通过 stdin 注入 `recoverySecret` 和 `controllerToken`。
+- AWBS 读取 `.awbs/private/local.json`。
+- 用 `recoverySecret` 加密 local material，写入 `recovery.seal.json`。
+- 启动同用户后台 session daemon。
+- 删除磁盘上的 `local.json`。
+- key 只保留在 daemon 内存中。
+
+可信写入命令不把 raw `controllerToken` 发给 daemon。CLI 会生成：
+
+```text
+controller proof
+  = HMAC(controllerToken, requestHash + nonce + createdAt)
+```
+
+daemon 会拒绝重复 nonce。可信写入成功响应必须带 response proof，CLI 验证后才承认成功。
+
+## 4. Trusted Chain Bootstrap
+
+命令：
+
+```powershell
+'dev-controller' | awbs ledger bootstrap --control-token-stdin
+```
+
+前提：
+
+- Git HEAD 存在。
+- 工作树干净。
+- authority session 可用。
+- controller capability 有效。
+
+发生的事情：
+
+- 当前 Git HEAD 被作为 `parentTrustedCommit`。
+- authority 创建第一条 ledger entry。
+- Git commit 写入 sealed ledger。
+- `refs/awbs/trusted` 指向 bootstrap 后的 commit。
+
+从这一刻起，AWBS 认证数据库不再跟着普通 HEAD 自动变化。
+
+## 5. 索引链路
+
+命令：
+
+```powershell
+awbs index rebuild
+awbs index query [term]
+```
+
+发生的事情：
+
+- AWBS 读取 `refs/awbs/trusted`。
+- 从 trusted commit 创建临时 Git worktree。
+- 扫描 trusted tree，而不是当前污染工作区。
+- 写入 `.awbs/index/files.sqlite`。
+- 使用 FTS5 索引 path 和 summary。
+
+索引是可重建材料，不是事实源。
+
+## 6. 摘要链路
+
+命令：
+
+```powershell
+awbs summary set B/draft.md --text "业务层写入的摘要"
+awbs summary get B/draft.md
+awbs summary list
+```
+
+原则：
+
+- AWBS 永远不内置 AI 摘要。
+- AWBS 不保存 AI API key。
+- AWBS 不配置模型、提示词或 provider。
+- 摘要由上层业务生成后写入 AWBS。
+
+`summary set` 会基于当前 trusted commit 计算目标文件 sha。文件内容变化后，旧 exact summary 不会静默套到新内容上。
+
+## 7. View Projection 链路
+
+命令：
+
+```powershell
+'dev-controller' |
+  awbs view create --out ..\awbs-workspace --read A --write B --control-token-stdin
+```
+
+发生的事情：
+
+- AWBS 读取当前 trusted commit。
+- 从 trusted tree 复制 `A/`、`B/` 到 workspace。
+- 保持原目录结构，不重命名。
+- 保存 baseline 到 `.awbs/views/<viewId>/baseline/`。
+- 创建 sealed view contract。
+- workspace 中写入 `.awbs-view.json`。
+
+权限事实源不是 workspace 里的 `.awbs-view.json`，而是 sealed view contract。
+
+系统路径永远不能作为业务路径投影：
+
+```text
+.git
+.awbs
+.awbs-view.json
+```
+
+大小写变体也会被拒绝。
+
+## 8. Workspace 工作链路
+
+agent 只在 workspace 中工作。它可以：
+
+- 新增允许写路径下的文件。
+- 修改允许写路径下的文件。
+- 删除允许写路径下的文件。
+- 误改只读路径。
+- 误建 `.git` / `.awbs` 等保留路径。
+
+AWBS 不阻止 workspace 中出现混乱。AWBS 控制的是：哪些变化可以进入认证数据库。
+
+## 9. Changeset Collect 链路
+
+命令：
+
+```powershell
+awbs changeset collect --workspace ..\awbs-workspace
+```
+
+发生的事情：
+
+- 读取 workspace `.awbs-view.json` 取得 viewId。
+- 回查 sealed view contract。
+- 比较 baseline 和 workspace。
+- 生成 `.awbs/changesets/<changesetId>/`。
+- 写入 `manifest.json`、`diff.patch`、`files/`。
+- 计算 `payloadHash` 和 `operationHash`。
+- 生成 sealed changeset receipt。
+
+只读路径或保留路径变化会进入 violations，changeset 状态为 `invalid`。
+
+## 10. Changeset Apply 链路
+
+命令：
+
+```powershell
+'dev-controller' |
+  awbs changeset apply <changesetId> --control-token-stdin
+```
+
+apply 前检查：
+
+- authority verify 无 sealed error。
+- changeset manifest 完整。
+- payload 文件 sha256 匹配。
+- payloadHash 匹配。
+- operationHash 匹配。
+- sealed receipt 匹配 manifest / payload。
+- view contract 未撤销。
+- changeset baseCommit 等于当前 trusted commit。
+- 所有变更都在 writePaths 内。
+
+成功后：
+
+- 将允许的文件变化写入目标 tree。
+- authority 记录 changeset apply ledger entry。
+- 修复 mirror。
+- Git commit。
+- 推进 `refs/awbs/trusted`。
+
+如果当前工作区被污染，AWBS 不在污染 HEAD 上继续写，而是从 trusted commit 创建临时 worktree 完成可信 apply。
+
+## 11. Audit 与 Clean Rebuild
+
+命令：
+
+```powershell
+awbs db audit
+awbs db clean-rebuild
+```
+
+`db audit` 报告：
+
+- HEAD 是否等于 trusted commit。
+- 工作树是否 dirty。
+- 是否存在外部 commits。
+- ledger 是否可验证。
+
+`db clean-rebuild`：
+
+- 从 trusted commit 克隆/检出干净目录。
+- 复制 `.awbs/private`。
+- 校验 authority。
+- 原目录整体改名为 backup。
+- 干净目录接管原路径。
+
+它不在污染目录里做复杂递归删除，也不自动 purge backup。
+
+## 12. 失败语义
+
+AWBS 初版坚持：
+
+```text
+失败不能伪装成功。
+```
+
+典型拒绝情况：
+
+- 未启动 trusted chain。
+- authority session 不可用。
+- controller proof 无效。
+- response proof 缺失或无效。
+- view 被 revoke。
+- changeset 修改只读路径。
+- changeset payload 被篡改。
+- sealed contract 被篡改。
+- base commit stale。
+- symlink 触达不明确文件边界。
+
+这些情况会显式失败，保留诊断，不推进 trusted chain。

package/docs/PRODUCT.md

@@ -0,0 +1,188 @@
+# AWBS 产品文档
+
+AWBS 是 **Agent Work Base Space** 的缩写。
+
+一句话定位：
+
+```text
+AWBS 是面向 agent 工作流的文件系统数据库底座。
+```
+
+它把普通文件系统作为数据库主体，把 Git 作为版本管理器，把某一步工作需要的文件投影成独立工作空间，再用 changeset 和 trusted authority layer 控制哪些变更能进入认证数据库。
+
+## AWBS 解决什么问题
+
+传统应用常常假设：
+
+- 数据结构稳定。
+- 表结构清晰。
+- 写入入口固定。
+- 用户行为可枚举。
+
+但 agent 工作流经常不是这样：
+
+- 输入开放。
+- 文件类型复杂。
+- 任务上下文不断变化。
+- agent 可能读写大量文件。
+- 上层业务不一定能提前设计好所有表结构。
+
+AWBS 解决的是：
+
+```text
+如何让 agent 在一个明确的工作空间里工作，
+并把它的产出以可审计、可拒绝、可重放的方式写回文件系统数据库。
+```
+
+## AWBS 不是什么
+
+AWBS 不是：
+
+- 沙箱系统。
+- 操作系统权限系统。
+- 传统 SQL 数据库。
+- AI 摘要服务。
+- 模型调度框架。
+- workflow 编排器。
+
+AWBS 不阻止人或程序直接修改磁盘文件。它只定义 AWBS 自己承认的数据库事实链。
+
+## 核心产品概念
+
+### 文件系统数据库
+
+业务数据就是普通目录和普通文件。
+
+```text
+project/
+  A/
+  B/
+  assets/
+  reports/
+```
+
+AWBS 不规定业务目录应该怎么组织。上层应用可以按小说、仿真、文档、代码、素材等业务自由设计目录。
+
+### Git 版本管理
+
+Git 保存文件历史、diff、commit 和 tree。
+
+AWBS 不重新发明文件版本系统，而是借用 Git 已经成熟的能力。
+
+### 工作空间视图
+
+某一步工作不一定需要看到整个数据库。
+
+AWBS 可以创建 copy-based workspace view：
+
+```text
+database trusted commit
+  -> selected paths
+  -> workspace
+```
+
+agent 在 workspace 中工作。workspace 可以混乱，但正式写回必须经过 changeset。
+
+### Changeset
+
+changeset 是 AWBS 的最小变更单元。
+
+它包含：
+
+- manifest。
+- diff。
+- payload files。
+- payloadHash。
+- operationHash。
+- sealed receipt。
+
+增、删、改都统一为 changeset。
+
+### Trusted Authority Layer
+
+AWBS 认证数据库不等于普通 Git HEAD。
+
+AWBS 认证数据库等于：
+
+```text
+refs/awbs/trusted
++ sealed authority ledger
+```
+
+只有 authority 承认的 changeset apply 才能推进 trusted chain。
+
+### Authority Session
+
+A 模式 authority session 会把本机 key 从磁盘移到后台 daemon 内存中。
+
+可信写入必须由 host controller 提供 controller capability。
+
+普通 workflow agent 可以生成请求和 changeset，但不能直接推进 AWBS 可信事实。
+
+## 当前已实现能力
+
+当前初版已经实现：
+
+- CLI 初始化。
+- Git repo 初始化。
+- 磁盘 SQLite + FTS5 索引。
+- 外部摘要读写接口。
+- copy-based view create / inspect / revoke。
+- sealed view contract。
+- changeset collect / inspect / apply。
+- read/write path 权限判断。
+- readonly violation 拒绝 apply。
+- changeset payload 防篡改。
+- hash-linked trusted ledger。
+- `refs/awbs/trusted` 可信链头。
+- authority verify / repair-mirrors。
+- A 模式 authority session。
+- controller proof / response proof。
+- db audit。
+- db clean-rebuild。
+- npm CLI 包形态。
+
+## 典型用户
+
+AWBS 适合：
+
+- 想让 agent 处理复杂项目文件的人。
+- 想把“文件系统作为数据库”产品化的人。
+- 需要 agent 分步读写上下文的工具作者。
+- 小说、仿真、文档、代码、素材等混合型工作流系统。
+- 想研究 agent trusted workflow 的开发者。
+
+AWBS 不适合：
+
+- 只需要简单 CRUD 表单的系统。
+- 需要强隔离安全沙箱的系统。
+- 需要高并发 OLTP 的业务数据库。
+- 希望内置 AI 摘要或模型服务的应用。
+
+## 产品边界
+
+长期边界：
+
+- AWBS 永远不内置 AI 摘要。
+- AWBS 不规定业务目录结构。
+- AWBS 不默认兼容开发期旧仓库，除非明确开 migration 任务。
+- AWBS 不把普通 Git HEAD 当作认证数据库。
+- AWBS 不承诺对抗 admin/root。
+
+## 当前阶段
+
+当前阶段可以称为：
+
+```text
+AWBS v0 trusted CLI prototype
+```
+
+它已经能作为公开初版发布、学习和试用。
+
+后续方向包括：
+
+- workflow / run / step 记录层。
+- 更强的 Authority Service。
+- OS keychain / 独立 OS 身份的 B 模式。
+- 更多业务写回策略和视图投影策略。
+- 更好的包发布和版本化流程。