@c956180462/awbs 0.0.1

package/TASK_007_TRUSTED_OPERATION_ENTRY.md

@@ -0,0 +1,129 @@
+# AWBS 007：可信操作入口与只读/修复拆分
+
+## Summary
+
+007 的目标是把 AWBS 可信写入收束成更清楚的语义入口。
+
+AWBS 不信任“谁声称自己是应用”。AWBS 只信任：
+
+```text
+controller capability
++ authority session
++ verified operation
+```
+
+也就是说：
+
+```text
+Workflow Actor 可以产出请求和 changeset。
+Host Controller 才能授权可信操作。
+```
+
+AWBS 不防止宿主应用主动把控制权交给 agent；那属于宿主应用授权错误。AWBS 要防的是未获 controller capability 的 workflow actor 绕过可信链。
+
+## Actor Model
+
+```text
+Workflow Actor
+  普通 agent / 大 agent / 工作流步骤。
+  可以在 workspace 中工作。
+  可以生成 changeset。
+  可以读取诊断和索引。
+  不能直接推进 AWBS 可信事实。
+
+Host Controller
+  上层应用的非 AI 控制层 / 人类确认层 / 服务端控制层。
+  持有 controllerToken。
+  决定是否创建 view、撤销 view、修复 mirror、apply changeset。
+```
+
+如果宿主应用把 controllerToken 暴露给 agent，AWBS 会把这个请求视为已授权请求。AWBS 不伪装自己还能阻止这种宿主授权错误。
+
+当前实现中，controllerToken 不直接进入 session IPC。CLI 用 controllerToken 派生 HMAC proof，并把 proof 绑定到：
+
+```text
+method
+root
+args
+nonce
+createdAt
+```
+
+session daemon 在内存中记录已使用 nonce，拒绝重放。可信写入的成功响应也必须由 daemon 签回 response proof；CLI 验证后才承认操作成功。这样即使 `.awbs/private/session.json` 被篡改指向一个假 endpoint，假 endpoint 也不能伪造“可信写入成功”。
+
+## Trusted Operation Entry
+
+Authority Service 不应暴露底层写入原语。
+
+禁止把它设计成：
+
+```text
+sign(rawHash)
+appendLedgerEntry(rawEntry)
+createViewContract(rawContract)
+```
+
+应当收束成语义操作：
+
+```text
+bootstrapTrustedChain
+createView
+revokeView
+sealChangesetReceipt
+recordChangesetApply
+repairMirrors
+```
+
+这些操作必须在 Authority 内部重新检查当前 authority 状态，并由 Authority 自己完成密封写入、ledger 记录或 mirror 重建。
+
+## Verify / Repair Boundary
+
+`verify` 是只读诊断。
+
+```text
+verify:
+  读取 sealed payload
+  读取 mirror
+  报告 mirror mismatch / seal error / ledger error
+  不写任何文件
+```
+
+`repair` 是显式维护写入。
+
+```text
+repair-mirrors:
+  需要 controllerToken
+  从 sealed payload 重建 mirror
+  可写 view-events.jsonl
+```
+
+不能让一个看似只读的检查命令偷偷修复 mirror。否则 AWBS 会出现隐藏写入通道。
+
+## `.awbs` Boundary
+
+`.awbs` 是 AWBS 系统目录，不是业务数据目录。
+
+```text
+.awbs/authority
+.awbs/private
+.awbs/index
+.awbs/views
+.awbs/changesets
+.awbs/summaries
+```
+
+这些目录不进入 agent workspace。agent 需要的上下文应被投影成普通业务文件，而不是直接读取 AWBS 自己的系统材料。
+
+## Implementation Result
+
+007 完成后：
+
+- session daemon 不接受 `createViewContract` / `appendLedgerEntry` 这类低层写入 method。
+- session daemon 只接受绑定仓库或同一 Git common dir 下的临时 worktree。
+- controller capability 通过 nonce HMAC proof 表达，不把 raw token 发给 session endpoint。
+- controller proof 不能重放，可信写入成功响应必须带 response proof。
+- `authority verify` 不修复 mirror。
+- `authority repair-mirrors` 必须带 `--control-token-stdin`。
+- view create、view revoke、changeset apply 仍通过 controller capability 走语义操作。
+- 普通 inspect / collect / query / verify 不需要 controller token。
+- `.awbs` / `.git` 作为系统路径按大小写无关方式拒绝投影和写回。

package/bin/awbs.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/cli.ts";

package/docs/DEVELOPMENT_LEARNING.md

@@ -0,0 +1,319 @@
+# AWBS 开发学习文档
+
+本文档面向想阅读 AWBS 源码、理解设计演进、fork 后继续改造的人。
+
+AWBS 当前是一个 Node/TypeScript CLI 原型。它没有 build step，依赖 Node.js 24 直接运行 `.ts` 文件。
+
+## 1. 学习顺序
+
+建议按这个顺序读：
+
+```text
+README.md
+  -> docs/PRODUCT.md
+  -> docs/FULL_CHAIN.md
+  -> AWBS_CORE_DESIGN.md
+  -> TASK_001_VIEW_AUTHORITY.md
+  -> TASK_003_AUTHORITY_LEDGER_AND_DB_AUDIT.md
+  -> TASK_004_TRUSTED_AUTHORITY_LAYER.md
+  -> TASK_005_AUTHORITY_SESSION.md
+  -> TASK_006_TRUST_BOUNDARY_HARDENING.md
+  -> TASK_007_TRUSTED_OPERATION_ENTRY.md
+  -> src/
+  -> tests/
+```
+
+`AWBS_USER_DISCUSSION_NOTES.md` 是原始讨论记录，适合了解思想来源，但不进入 npm 包。
+
+## 2. 架构分层
+
+当前源码分四层：
+
+```text
+CLI Adapter
+  src/cli.ts
+
+Application Use Cases
+  src/usecases/*
+
+Domain Contracts
+  src/domain/*
+
+Ports / Infrastructure Adapters
+  src/ports/*
+  src/adapters/*
+```
+
+`src/runtime.ts` 负责组装默认运行时。
+
+## 3. CLI 层
+
+入口：
+
+```text
+src/cli.ts
+```
+
+职责：
+
+- 解析命令行参数。
+- 读取 stdin 中的 controller token / recovery secret。
+- 创建 runtime。
+- 调用 use case。
+- 格式化输出。
+
+CLI 不应该直接 import 具体 infrastructure adapter。这个约束由 `tests/architecture.test.ts` 覆盖。
+
+## 4. Use Case 层
+
+主要文件：
+
+```text
+src/usecases/init.ts
+src/usecases/index.ts
+src/usecases/view.ts
+src/usecases/changeset.ts
+src/usecases/authority.ts
+src/usecases/session.ts
+src/usecases/ledger.ts
+src/usecases/db.ts
+src/usecases/trusted-chain.ts
+```
+
+Use case 层负责业务流程编排。它不应该把密封算法、SQLite 细节、Git 命令细节写死在自己里面。
+
+## 5. Domain 层
+
+主要文件：
+
+```text
+src/domain/types.ts
+src/domain/authority-types.ts
+src/domain/session-types.ts
+src/domain/paths.ts
+src/domain/path-policy.ts
+src/domain/session-proof.ts
+src/domain/hash.ts
+src/domain/constants.ts
+src/domain/errors.ts
+```
+
+这里定义：
+
+- manifest 类型。
+- authority 类型。
+- session 类型。
+- path policy。
+- controller proof。
+- hash / canonical JSON。
+- 常量和错误类型。
+
+路径策略是安全边界的一部分。`.git`、`.awbs`、`.awbs-view.json` 不能作为业务数据路径。
+
+## 6. Ports 层
+
+主要接口：
+
+```text
+FileDatabasePort
+GitPort
+IndexStorePort
+SummaryStorePort
+AuthorityPort
+AuthoritySessionPort
+```
+
+Ports 的作用是让 use case 依赖能力，而不是依赖具体实现。
+
+## 7. Adapters 层
+
+当前 adapters：
+
+```text
+GitCliAdapter
+LocalFileDatabaseAdapter
+SqliteIndexStoreAdapter
+FileSummaryStoreAdapter
+SealedAuthorityAdapter
+LocalAuthoritySessionAdapter
+SessionAuthorityClientAdapter
+AutoAuthorityAdapter
+```
+
+重点：
+
+- Git 操作统一走 `GitCliAdapter`。
+- 文件扫描、copy、remove 统一走 `LocalFileDatabaseAdapter`。
+- SQLite 索引走 `SqliteIndexStoreAdapter`。
+- sealed authority 走 `SealedAuthorityAdapter`。
+- session daemon 走 `LocalAuthoritySessionAdapter`。
+
+## 8. Trusted Chain 机制
+
+AWBS 认证数据库不等于 Git HEAD。
+
+可信链由两部分表达：
+
+```text
+.awbs/authority/ledger.seal.json
+refs/awbs/trusted
+```
+
+ledger entry 使用：
+
+- `previousEntryHash`
+- `entryHash`
+- `operationHash`
+- `parentTrustedCommit`
+- `baseCommit`
+- `changesetPayloadHash`
+- `authorityContractHash`
+
+`ledger verify` 会重算 hash chain。
+
+## 9. Authority Session 机制
+
+session start：
+
+- 读入 `.awbs/private/local.json`。
+- 写出 `recovery.seal.json`。
+- 启动 hidden detached daemon。
+- 删除 `local.json`。
+
+可信写入：
+
+- CLI 从 stdin 读取 controller token。
+- 生成 nonce HMAC controller proof。
+- daemon 验证 proof。
+- daemon 拒绝重复 nonce。
+- daemon 执行语义 operation。
+- daemon 签回 response proof。
+- CLI 验证 response proof。
+
+daemon 不提供 `sign(rawHash)`。
+
+## 10. Changeset 机制
+
+changeset collect 生成：
+
+```text
+.awbs/changesets/<changesetId>/
+  manifest.json
+  diff.patch
+  files/
+  receipt.seal.json
+```
+
+apply 前会验证：
+
+- payload sha256。
+- payloadHash。
+- operationHash。
+- sealed receipt。
+- sealed view contract。
+- current trusted commit。
+- write path 权限。
+
+任何验证失败都不能写入数据库。
+
+## 11. 索引和摘要
+
+索引：
+
+```text
+.awbs/index/files.sqlite
+```
+
+摘要：
+
+```text
+.awbs/summaries/files.jsonl
+```
+
+摘要边界是长期设计边界：
+
+```text
+AWBS 永远不内置 AI 摘要。
+```
+
+如果要接 AI 摘要，应由上层应用生成摘要，再调用 AWBS summary 接口写入。
+
+## 12. 测试结构
+
+当前测试：
+
+```text
+tests/architecture.test.ts
+tests/cli.test.ts
+tests/authority.test.ts
+tests/trusted-chain.test.ts
+tests/hardening.test.ts
+tests/session.test.ts
+```
+
+覆盖：
+
+- CLI 闭环。
+- SQLite 索引。
+- summary。
+- view authority。
+- changeset apply。
+- trusted chain。
+- clean rebuild。
+- session。
+- 对抗路径。
+- symlink 拒绝。
+- payload 篡改。
+- session endpoint 伪成功。
+
+运行：
+
+```powershell
+npm test
+```
+
+测试使用串行执行，避免 Windows 上并发启动过多 authority session daemon。
+
+## 13. 开发原则
+
+AWBS 的核心开发原则：
+
+- 输入开放，落地受控。
+- 失败不能伪成功。
+- 普通 HEAD 不等于认证数据库。
+- workspace 可以混乱，trusted chain 不能混乱。
+- 权限事实源不能在 workspace 明文里。
+- summary 不是 AWBS 的 AI 能力。
+- 不默认兼容开发期旧仓库，除非明确开 migration 任务。
+- 不用一堆特例替代底层机制。
+
+## 14. 发布流程
+
+发布前：
+
+```powershell
+npm test
+node src\cli.ts --help
+npm pack --dry-run
+git diff --check
+```
+
+首次 npm 发布需要登录：
+
+```powershell
+npm adduser
+npm publish --access public
+```
+
+`awbs` 包名当前可用性需要发布前再次用 npm registry 确认。
+
+## 15. 后续可做方向
+
+可能的后续任务：
+
+- workflow / run / step 记录。
+- `applyVerifiedOperation` 更彻底的 Authority Service 化。
+- B 模式：OS keychain / 独立系统账号 / 本地服务。
+- npm release workflow。
+- JSONL / SQLite 导出调试命令。
+- 更正式的版本迁移策略。