attention-manifest-protocol 0.4.2 → 0.4.4

package/CHANGELOG.zh-CN.md

@@ -7,9 +7,42 @@
 
 ## [未发布]
 
+### 新增
+
+- Agent 工作区：`File`/`Directory` 树、分页读、CAS 原子写、策略化大纲、import/export/dependency 图与 Office（DOCX/XLSX/PPTX，DOC/XLS/PPT/PUB/ACCDB best-effort）解析。
+- Session 模块：`ses_` 身份、一次性 bearer 令牌、TTL、暂停/撤销/rotate、fork、每会话上下文隔离与配额；SQLite 适配器 `SqliteWorkspaceSessionStore` / `SqliteWorkspaceSessionContextStore`。
+- `src/hook` 组合层：`useRead`、`useWrite`、`useDiff`、`useParse`、`useDependency`、`useExportation`、`useImportation`、`useOutline`、`useCode`、`useProject`；除 `useWrite` 外只读，并记录 `hook_runs`。
+- `amp_tool_filesystem_*` 十个工具与 `amp_tool_globalfs_*` 全局命名适配器；`amp_service_filesystem` / `amp_protocol_filesystem`。
+- 无损只读语法树：`amp_tool_filesystem_ast`、`useAst`、`src/syntax/syntaxTree.ts` 与 `src/syntax/syntaxRegistry.ts`；语言/Token/节点类别由注册中心管理，全部 token 保留 UTF-8 字节与行范围，不执行目标文件。`syntaxTreeCheck` 8 例，完整 verify 135/135。
+- SQLite 表：`workspace_sessions`、`session_roots`、`session_context`、`file_nodes`、`file_annotations`、`file_writes`、`file_outlines`、`file_imports`、`file_exports`、`file_dependencies`、`hook_runs`。
+- 数据结构：`Trie`、`ByteLineIndex`（SegmentTree 前缀和）、`OutlineIndex`（AST + Trie + SegmentTree）。
+- 大纲策略覆盖代码（TS/JS/Python/Java/C/C++/C#/Go/Rust）、Vue、项目清单（npm/Maven/Gradle/CMake/Cargo/Go/pyproject/Make）、文章（Markdown/TeX/plain text）、HTML/CSS/SCSS/Sass/XML/OPML 与 Office；`outlineCoverageCheck` 74 例逐项验证。
+- 大纲关键字注册：`OutlineKeywordRegistry` 注册变量/函数/类型/导入/修饰符/控制/字面量关键字；全局变量/常量、全局函数、类属性/方法、`static` 属性/方法均成为节点，`modifiers` 返回 `static`/`public` 等链。
+- `src/context` 新增 `ContextPackage`/`ContextBuilder`/`relevance`：预算装配、关系闭包、省略项、Trie 路径前缀与 SegmentTree 行范围。
+- 工具源码文件名统一为 lowerCamelCase：`tools/` 下 148 个短横线文件重命名并修复全部引用，`archCheck` 增加命名规则。
+- 职责与交互分配：`responsibility-assignment`（职责、RACI、权限/预算/窗口衰减、接受、证据验收与级联撤销）与 `interaction-binding`（参与方、协议角色、模式混合、节奏、升级与交接），附 Schema、示例、账本、`delegation`/`result-contract`/`receipt`/`message` 的可选引用，以及 `assignment-check` / `interaction-binding-check`。
+- `src/discover`：`HostCatalog` 用于登记宿主的项目、插件、服务、工具与模块；`buildDiscoveryTree` 在获准的 workspace 快照上返回一棵有界结构树。项目节点带描述、用途与简介；文件节点带模块分类（`service`/`tool`/`controller`/`route`/`repository`/`model`/`config`/`test`/`middleware`/`component`/`util`）、扩展名与最多三条有界内容片段。新增 `amp_tool_workspace_discover` 工具供 agent 调用；`discover-check` 与 `discover-agent-check` 覆盖树、内容匹配、宿主目录、授权过滤与工具响应外层。
+- `src/fingerprint`：对「摘要覆盖哪些内容」的唯一定义。`fingerprintBytes`、`fingerprintText`、`fingerprintString`、`fingerprintNumber`、`fingerprintJson`、`fingerprintFile`、`fingerprintFileMeta` 与 `fingerprintTree` 各自返回一个引用，携带算法、`kind`、策略、载荷大小与摘要；`verify`/`matches` 比较全部四个字段，而不是只比对裸十六进制字符串；`rawDigest`/`rawHex`/`rawTextDigest` 集中提供不带帧的内容寻址形式。目录树使用域分隔的 Merkle 叶与节点（RFC 6962 形状），并对文件的字节哈希，因此两个不同的二进制文件不再可能共用一个模块摘要。`fingerprint-check` 覆盖 47 个用例，包括与 `node:crypto` 的对拍以及历史碰撞。
+- `src/naming`：冻结的 ID 表、带解析器与格式化器的 `amp_<kind>_<component>[_<leaf>]` 文法、v0.5 兼容别名，以及带稳定摘要的 catalog（`buildCatalog`/`verifyCatalog`）。`naming-check` 覆盖 26 个用例。
+- `tools/fingerprintCheck.ts` 与 `tools/namingCheck.ts` 已接入 `npm run verify`；两者也都是可独立运行的脚本。
+
 ### 变更
 
 - 将项目说明收敛到中英文 README；评测汇总只保留 JSON 格式。
+- 工具 ID 现在为 `amp_tool_workspace_capabilities|tree|query|relations|materialize|read|release|discover`。`amp_workspace_*` 拼写在一个 minor 版本内仍作为输入别名接受，并报告在 `deprecatedAliases` 中；`tools/list` 只通告规范 ID。
+- 工作区响应的 `protocol` 值现在为 `amp_protocol_workspace`，`serverInfo.name` 为 `amp_service_workspace`；`server/discover` 与 `initialize` 也携带 `serviceId` 与 catalog 概要。`WorkspaceProtocolAliases` 导出旧的 `amp.workspace` 值，供仍要比较它的宿主使用。
+- 工作区协议接口从 `src/context/workspaceProtocol.ts` 移到 `src/protocol/workspace.ts`；`src/context/index.ts` 重新导出它，因此根入口不变。
+- `canonical()` 现在拒绝未配对代理项与 `-0`，与 RFC 8785 §3.2.2.2 及附录 B 一致。确实想「把 `-0` 当作 `0`」的调用方，必须向新的 `canonicalJson` 传入 `{ negativeZero: "as-zero" }`。不含这两种形状的值产生的字节与之前完全相同。
+- `src/fingerprint/json.ts` 委托给这个唯一的编码器，不再保留第二份 JCS 规则副本。
+- `ContentStore` 与工作区完整性检查现在通过 `rawTextDigest`/`parseShort` 派生并校验引用，`registry/content.ts` 改为对文件字节哈希，而不是对解码后的文本哈希。只含 UTF-8 内容的目录树，其模块摘要保持不变。
+
+### 修复
+
+- `src/semantic/canonical.ts`、`src/fingerprint/file.ts` 与 `src/fingerprint/tree.ts` 中的非法 UTF-8 字节（损坏的长破折号）已修复，`read` 工具与严格解码器不再拒绝这些源文件。
+- 大纲 Office 段的字节范围改为按文档序号比例映射，避免所有 section 都落在 `0..0`；`fileOutlineCheck` 覆盖该行为。
+- Office 文件不再在 import/export/dependency 中报 `binary_file`，而是解析 hyperlink/external link/formula/embedded 引用。
+- 对含未配对代理项的字符串哈希时，`TextEncoder` 会替换它，因而得到与 `U+FFFD` 相同的摘要。`rawTextHex`、`fingerprintString` 与严格规范化 JSON 现在拒绝该输入，而不是把两个不同的值塌缩成一个。
+- 目录内容摘要曾由 `readFile(path, "utf8")` 计算，因此不是合法 UTF-8 的文件（例如 `0x80` 与 `0x81`）会解码成同一个替换字符并共用摘要。现在改为按字节哈希。
 
 ## [0.4.2] - 2026-10-29
 
@@ -33,7 +66,7 @@
 
 ### 修复
 
-- 声明文件改用 JavaScript 扩展名。`tsc` 只会为 `.js` 输出重写相对 `.ts` 导入，因此由 `tools/rewrite-declaration-extensions.ts` 重写 `.d.ts`，若仍残留 TypeScript 扩展名则构建失败。
+- 声明文件改用 JavaScript 扩展名。`tsc` 只会为 `.js` 输出重写相对 `.ts` 导入，因此由 `tools/rewriteDeclarationExtensions.ts` 重写 `.d.ts`，若仍残留 TypeScript 扩展名则构建失败。
 
 ## [0.4.0] - 2026-10-29
 
@@ -81,7 +114,7 @@
   并保留八种旧场景到五种规范场景、`inspire` 到 `diverge` 的显式桥接。
 - `docs/governance.md`、`governance.schema.json`（清单与凭据）、两个可校验示例
   （`attention-manifest.json`、`switch-credential.json`）。
-- `tools/governance-check.ts`（19 项）与 `tools/governed-task-check.ts`（5 项），
+- `tools/governanceCheck.ts`（19 项）与 `tools/governedTaskCheck.ts`（5 项），
   已接入 `npm run verify`。
 - `src/runtime/governedTask.ts`：把清单验签、凭据校验、法务审计、账本扣款、黑板回执与
   控制决策套在 `CognitiveRuntime` 外面；拒绝路径在模型调用之前返回。已用真实 DeepSeek
@@ -98,10 +131,10 @@
 - 治理审计链（`src/governance/audit.ts`）：清单、凭据、回执、扣款、法务、工作流、切换与
   runtime 回合均可追加到只追加哈希链；`verify()` 检测改写/重排/截断，`open({ sink })` 重开时
   先验链。`GovernedTask` 可注入 `audit`，结算后自动写 `runtime.turn`。
-- `tools/audit-check.ts`（2 项）验证跨对象记录、重开、篡改与损坏拒绝，已接入 `npm run verify`。
-- `tools/cooperation-check.ts`（13 项）已接入 `npm run verify`；`governance-check` 增至 21 项，
+- `tools/auditCheck.ts`（2 项）验证跨对象记录、重开、篡改与损坏拒绝，已接入 `npm run verify`。
+- `tools/cooperationCheck.ts`（13 项）已接入 `npm run verify`；`governance-check` 增至 21 项，
   新增对伪造签名、负额度、冻结撤销、归档门禁、控制 NaN、未知 effect、私域引用泄漏的回归断言。
-- `tools/live-governance-eval.ts`（`npm run governance-live`）：接入 DeepSeek 做质量、token 与边界评测。
+- `tools/liveGovernanceEval.ts`（`npm run governance-live`）：接入 DeepSeek 做质量、token 与边界评测。
   质量用确定性 rubric + 严格 judge；token 记录 input/output/cache/cost、账本扣款与预算上限；
   边界覆盖危机升级、过期清单、过期凭据、法务冻结、预算耗尽、提示注入泄漏、多 Agent 越界与超限。
   报告写入 `docs/probes/governance-live.json`，key 只从环境变量读取。
@@ -125,7 +158,7 @@
 - 新增 `compaction.schema.json`（检查点与剪枝计划）、两个可校验示例
   （`checkpoint.json`、`prune-plan.json`），以及含 P-1 至 P-7 不变量的
   `docs/compaction.md`。
-- 新增 `tools/compaction-check.ts`（15 项断言），已接入 `npm run verify`。
+- 新增 `tools/compactionCheck.ts`（15 项断言），已接入 `npm run verify`。
 - 概念经济。`pruneConcept()` 为一个概念的体量设上限：重复示例折叠为更典型的那条；超过
   `maxExamples` 的示例从最不典型的一端裁掉；`minExamples` 作为下限，保证概念仍有实例。
   关系先去重，提供解析器时删除悬空目标，外延只折叠完全重复项。定义、内涵、反例与
@@ -133,11 +166,11 @@
 - `compactConceptHistory()` 保留 head 与 `keepVersions`，其余版本压缩为
   `concept-checkpoint`。版本号不连续或保留窗口覆盖全部版本时拒绝压缩。不变量 C-1 至 C-4
   记录在 `docs/compaction.md` §6。
-- 新增 `concept-compaction.schema.json`、两个可校验示例，以及 `tools/concept-check.ts`
+- 新增 `concept-compaction.schema.json`、两个可校验示例，以及 `tools/conceptCheck.ts`
   （14 项断言），已接入 `npm run verify`。
 - `src/structure/priority.ts`：基于比较堆的稳定 `PriorityQueue`；可按 key 以 O(log n)
   重新定级与删除的 `IndexedPriorityQueue`；按整数优先级分桶、桶内 FIFO 的 `BucketQueue`；
-  以及有界选取的 `TopK`。`tools/priority-check.ts` 含 27 个用例（包括与稳定排序模型对拍的
+  以及有界选取的 `TopK`。`tools/priorityCheck.ts` 含 27 个用例（包括与稳定排序模型对拍的
   随机差分检查），以 `npm run priority-check` 运行，并接入 `npm run verify`。
 
 ### 变更

package/README.md

@@ -1,171 +1,250 @@
-# Attention Manifest Protocol (AMP)
-
-**English** · [简体中文](README.zh-CN.md) · [Changelog](CHANGELOG.md)
-
-AMP is a metacognitive protocol for agents: declare knowledge and obligations, allocate finite attention, obtain evidence, and record costs and outcomes. The reference implementation is version `0.4.2`, requires **Node.js 24 or later**, and uses Apache-2.0.
-
-## Architecture
-
-| Component | Responsibility |
-| --- | --- |
-| Warrant Ledger | Claims, evidence, hypotheses, unknowns, concepts and plans: why believe a conclusion? |
-| Attention Ledger | Frames, budgets, receipts and interruptions: where was attention spent? |
-| Manifest | Durable, signable identity, capabilities, commitments and limits |
-| Attention | Select candidates and record why they matter |
-| Frame | Freeze one allocation with refs, budgets and explicit exclusions (`ignored`) |
-| Context | Materialize summaries, relations and bounded detail access |
-| Receipt | Record actual costs and outcomes for audit and calibration |
-| Compaction | Prune cold or superseded objects with a reason, then replace a verified prefix with a checkpoint |
-
-```text
-Attention → Frame → Context → Receipt → Ledger
-```
-
-Context combines a structural tree and typed relationships. Project dependencies, imports, calls and references are descriptive and may contain cycles; `depends` separately denotes prerequisites. Relations do not automatically widen a Frame. Summaries retain provenance/revision information; content-addressed detail reads verify hashes. Structure and provenance do not by themselves prove factual correctness.
-
-## Implemented capabilities
-
-- T0–T4 evidence tiers, confidence limits, revision, falsifiability, preregistration and abstention.
-- Budgeted attention, explicit exclusions, interrupts, leases, delegation and merge/arbitration.
-- Signed manifests/credentials, governance workflows, tool gates, authenticated local/HTTP communication, audit chains and persistence adapters.
-- MCP execution, schema-validated arguments, digest pinning and legacy fallback; A2A discovery and messages.
-- Project trees, project dependency graphs, partial TS/JS import/call/reference graphs and lexical knowledge retrieval.
-- Structured Markdown/TXT/DOCX/XLSX/PPTX and TeX/LaTeX/BibTeX input with native source locations and summary/detail separation.
-- `amp.workspace` v1 agent service, seven tools, local runtime integration and MCP stdio.
-- Compaction and pruning at two levels. `planPrune()` decides every drop with a reason and a revisit condition; `compactLedger()` replaces a verified cold prefix with a checkpoint, `verifyCompaction()` re-derives that commitment, and compaction refuses to bury an entry the retained tail still cites. `pruneConcept()` and `compactConceptHistory()` apply the same discipline to concept content and version history.
-
-Offline parsers live in `tools/support/`. The runtime stays database-free and uses ports; persistence adapters are separate. Concrete contracts remain in [schemas](docs/schemas/), [examples](docs/examples/) and executable [checks](tools/).
-
-## Quick start
-
-```sh
-npm ci
-npm run build
-npm run verify
-npm run scenario
-```
-
-## Library usage
-
-`npm install attention-manifest-protocol` ships the compiled ESM build in `lib/` with its declarations, alongside the source, JSON Schemas and executable checks. Node.js 24 or later is required. The root entry exposes the documented protocol surfaces; every module is also reachable as a subpath.
-
-```js
-import { generateSigningKey, signManifest, verifyManifest } from "attention-manifest-protocol";
-import { Ledger } from "attention-manifest-protocol/ledger";
-import { sha256Hex } from "attention-manifest-protocol/semantic/sha256.js";
-```
-
-| Specifier | Resolves to |
-| --- | --- |
-| `attention-manifest-protocol` | `lib/index.js`: attention, context, frame, ledger, manifest, receipt and warrant |
-| `attention-manifest-protocol/<module>` | `lib/<module>/index.js` for every module under `src/` |
-| `attention-manifest-protocol/<module>/<file>.js` | one compiled module |
-| `attention-manifest-protocol/schemas/<name>.json` | the JSON Schema from `docs/schemas/` |
-
-`npm run build:lib` rebuilds `lib/` and `prepublishOnly` runs it before publishing. The build compiles only the library; the Vite demo entry (`src/main.ts`) is not part of it.
-
-Focused checks: `npm run workspace-agent-check`, `workspace-context-check`, `document-context-check`, `tex-context-check`, `governance-check`, `typecheck` and `typecheck:tools`. `verify` runs the full chain and both type checks. Evaluation inputs/reports remain in [docs/eval](docs/eval/) and [docs/probes](docs/probes/) as JSON; fixture and recorded-probe results are not independent human studies or production-quality evidence.
-
-## Agent tools
-
-The `amp.workspace` v1 response contains `protocol`, `version`, `revision`, `ok`, and either `data` or `error`. Both adapters share input schemas; the [protocol types](src/context/workspaceProtocol.ts) define the response envelope. Except capability discovery, each business tool requires the current `revision`.
-
-| Tool | Purpose |
-| --- | --- |
-| `amp_workspace_capabilities` | Discover permitted projects, registered Frames, tools and limits |
-| `amp_workspace_tree` | Page project roots or structural children with native source locations |
-| `amp_workspace_query` | Retrieve candidate IDs by lexical AND search and bounded graph traversal |
-| `amp_workspace_relations` | Page typed dependency/call/reference relations and sources |
-| `amp_workspace_materialize` | Materialize a host-registered Frame into a bounded Context |
-| `amp_workspace_read` | Read a CAS-verified detail page for an explicitly allocated visible target |
-| `amp_workspace_release` | Release a read handle without refunding or reopening its Frame |
-
-### MCP stdio
-
-```sh
-npm run workspace-agent-demo
-npm run workspace-agent -- --config .cache/workspace-agent.local
-```
-
-For an MCP client, start Node directly to keep package-manager banners out of stdout. Replace absolute paths with your checkout location:
-
-```json
-{
-  "mcpServers": {
-    "amp-workspace": {
-      "command": "node",
-      "args": [
-        "R:/project/attention-manifest-protocol/tools/workspace-agent-server.ts",
-        "--config",
-        "R:/project/attention-manifest-protocol/.cache/workspace-agent.local"
-      ]
-    }
-  }
-}
-```
-
-The trusted host bootstrap contains `version: 1`, `agentId`, explicit `projectIds`, a `WorkspaceSnapshot`, `contents` mapping CAS refs to text, `frames`, and optional lower `limits`. Contents are hash-checked at startup. The demo uses example inputs; real hosts pass their authorized inventory to `scanStructuredWorkspace` in [documentScanner.ts](tools/support/documentScanner.ts).
-
-The stdio adapter reads configuration only at startup; new snapshots/Frames require a new host configuration and instance. It accepts newline-delimited JSON-RPC, limits messages to 1 MiB and configuration to 64 MiB, and never executes tools carried in notifications. It supports `initialize` for `2025-11-25` / `2025-06-18` and the repository's `2026-07-28` stateless discovery/metadata profile; other versions are not claimed as tested.
-
-### Local runtime
-
-```ts
-import { WorkspaceAgentService } from "./src/context/index.ts";
-import { ToolRegistry, registerWorkspaceTools, WorkspaceToolExecutor } from "./src/module/index.ts";
-
-const workspace = new WorkspaceAgentService({
-    agentId: frame.agent,
-    projectIds: ["project:packages/app"],
-    snapshot,
-    store,
-});
-workspace.registerFrame(frame, snapshot.revision);
-const tools = new ToolRegistry();
-registerWorkspaceTools(tools, workspace);
-const toolExecutor = new WorkspaceToolExecutor(workspace, existingExecutor);
-```
-
-The host provides the Frame, snapshot, ContentStore and fallback executor; pass `tools` / `toolExecutor` to `CognitiveRuntime`. Registration, revocation and Receipt settlement are host APIs, unavailable to the model.
-
-### Scope, lifecycle and limits
-
-Discovery/query return metadata and candidates, not authorization. Hosts fix project scope and register selected Frames. Only active targets admitted to the view permit detail reads; ancestor summaries do not grant whole-file access. Workspace IDs are extension-local keys, not global Ledger identities. Full Frame validation, signatures and policy checks remain host responsibilities.
-
-Identical materialization requests reuse a Context without recharging summaries; changed parameters are rejected. Release/revocation invalidates the read handle but retains pending settlement. Hosts use `pendingSettlements()` and `settle(contextId, receipt)` to obtain an archived ContextSnapshot. This state is in memory; hosts must persist audit/recovery data.
-
-Defaults: 128 registered Frames, 32 live read Contexts, 8000 estimated summary tokens, 8000 UTF-16 units per detail page, 131072 units per successful response and 1000 business calls. Query depth is at most 10; results/pages at most 100. Hosts may lower limits. Summary text and successful detail pages share the Frame's remaining estimated token budget; repeat reads cost budget and release does not refund it. Discovery, JSON wrapping and later model consumption are excluded from that estimate; actual usage belongs in Receipts.
-
-Detail offsets use UTF-16 units; `nextOffset: null` ends pagination. Reassemble structured JSON detail before parsing. CAS verification reads the full detail before paging, so response bounds do not imply bounded storage I/O. Runtime messages retain complete JSON up to `maxToolResultChars` (default 1048576, configurable down to 128); oversize results return `tool_result_too_large`, while logs retain a 4000-character preview.
-
-Service errors: `invalid_arguments`, `unknown_tool`, `revision_mismatch`, `not_available`, `frame_unavailable`, `budget_exhausted`, `capacity_exceeded`, `response_too_large`, `integrity_failure`, `internal_error`. Oversize responses fail instead of truncating structured content.
-
-## Repository layout
-
-| Path | Contents |
-| --- | --- |
-| [src/context](src/context/) | Context lifecycle, tree/graph projections, CAS, workspace facts and agent service |
-| [src/module](src/module/) | LLM/tool ports, MCP adapters and execution policies |
-| [src/runtime](src/runtime/) | Agent turn/tool loop and governance integration |
-| [src/governance](src/governance/) | Manifests, credentials, budgets, workflows, signing and audit |
-| [src/structure](src/structure/) | Maps, trees, queues, priority indexes, filters, AST and LRU |
-| [src](src/) | Other attention, evidence, ledger, policy, kernel and persistence domains |
-| [tools](tools/) | TypeScript checks, offline scanners, demos and probes |
-| [docs/schemas](docs/schemas/) / [docs/examples](docs/examples/) | Machine-readable contracts and protocol examples |
-| [docs/eval](docs/eval/) / [docs/probes](docs/probes/) | Evaluation inputs and JSON reports |
-
-## Code style
-
-ESLint checks semantic/style constraints; Prettier handles layout. Commands: `npm run lint`, `lint:fix`, `format:check`, `format`, `style-check`. Configuration lives in [eslint.config.mts](eslint.config.mts) and [prettier.config.mts](prettier.config.mts); local rules/printer live under `tools/`.
-
-Declare variable types explicitly; use arrow functions instead of `function`, semicolons, four-space indentation, double quotes and template strings. Keep parameters/type parameters on one line, use braces for control flow, `typeof(value)` and `=== (void 0)`. Locals/parameters and function values use lowerCamelCase; module-level data uses PascalCase. Comments use multiline JSDoc except tool directives. Historical files retain lint/format migration debt; functional verification does not imply a clean repository-wide style check.
-
-## Boundaries and evidence
-
-Static dependency extraction is partial; missing edges do not prove independence. Markdown/TeX scanners do not implement all macros or semantics. Summaries, graphs and long contexts require multi-hop, cross-document and changing-information evaluations. Relevant primary sources include [LaRA](https://proceedings.mlr.press/v267/li25dv.html), [GraphRAG-Bench](https://arxiv.org/abs/2506.05690), [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) and [RFC 6920](https://www.rfc-editor.org/rfc/rfc6920.html); they do not establish AMP's own effectiveness.
-
-Sandbox isolation, multi-tenancy, interactive OAuth, production deployment and real external-agent interoperability remain outside the completed reference implementation. Human research inspires design but does not prove identical model mechanisms or capacity constants. Provenance proves integrity, not truth or authority to act.
-
-## License and history
-
-[Apache License 2.0](LICENSE), copyright 2026 Eloy Kim; retain [NOTICE](NOTICE), license and attribution notices when redistributing. History: [CHANGELOG.md](CHANGELOG.md) and [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md).
+# Attention Manifest Protocol (AMP)
+
+**English** · [简体中文](README.zh-CN.md) · [Changelog](CHANGELOG.md)
+
+AMP is a metacognitive protocol for agents: declare knowledge and obligations, allocate finite attention, obtain evidence, and record costs and outcomes. The reference implementation is version `0.4.2`, requires **Node.js 24 or later**, and uses Apache-2.0.
+
+## Architecture
+
+| Component | Responsibility |
+| --- | --- |
+| Warrant Ledger | Claims, evidence, hypotheses, unknowns, concepts and plans: why believe a conclusion? |
+| Attention Ledger | Frames, budgets, receipts and interruptions: where was attention spent? |
+| Manifest | Durable, signable identity, capabilities, commitments and limits |
+| Assignment | Bind duties, authority, budget and interaction contracts to agents |
+| Attention | Select candidates and record why they matter |
+| Frame | Freeze one allocation with refs, budgets and explicit exclusions (`ignored`) |
+| Context | Materialize summaries, relations and bounded detail access |
+| Session | Bearer-bound identity, roots, permissions, TTL and context isolation |
+| Filesystem | File/Directory tree, paged reads/writes, outlines, import/export/dependency graphs and Office parsing |
+| Hook | Agent-facing composition: `useRead`/`useWrite`/`useDiff`/`useParse`/`useOutline`, read-only except write |
+| Receipt | Record actual costs and outcomes for audit and calibration |
+| Compaction | Prune cold or superseded objects with a reason, then replace a verified prefix with a checkpoint |
+| Fingerprint | One definition of what a digest covers; algorithm and normalisation policy travel with the digest |
+| Naming | One grammar for protocol, service and tool identity, with a parser and a catalog digest |
+
+```text
+Attention → Frame → Context → Receipt → Ledger
+```
+
+Context combines a structural tree and typed relationships. Project dependencies, imports, calls and references are descriptive and may contain cycles; `depends` separately denotes prerequisites. Relations do not automatically widen a Frame. Summaries retain provenance/revision information; content-addressed detail reads verify hashes. Structure and provenance do not by themselves prove factual correctness.
+
+## Implemented capabilities
+
+- T0–T4 evidence tiers, confidence limits, revision, falsifiability, preregistration and abstention.
+- Budgeted attention, explicit exclusions, interrupts, leases, delegation and merge/arbitration.
+- Responsibility and interaction assignment: RACI-style duty bindings with authority/budget/window attenuation, acceptance, evidence-based discharge and cascade revoke; interaction contracts with protocol roles, mode mix, cadence, escalation and handoff.
+- Signed manifests/credentials, governance workflows, tool gates, authenticated local/HTTP communication, audit chains and persistence adapters.
+- MCP execution, schema-validated arguments, digest pinning and legacy fallback; A2A discovery and messages.
+- Project trees, project dependency graphs, partial TS/JS import/call/reference graphs and lexical knowledge retrieval.
+- Agent workspace: a `File`/`Directory` tree (fingerprint, charset, bigint lines/bytes, timestamps, description/summary/purpose); paged reads, CAS atomic writes, strategy-based outlines (code/project/prose/Office); import/export/dependency graphs (Tarjan SCC, topological order, bounded closure); Session identity and context isolation; a `src/hook` composition layer; SQLite entities and repositories.
+- Host discovery: one structural tree over authorized projects, internal modules (service/tool/controller/route/repository/model/config/test/...), file names, bounded content matches, and host-registered plugins/services/tools. Project nodes carry description, purpose and summary.
+- Structured Markdown/TXT/DOCX/XLSX/PPTX and TeX/LaTeX/BibTeX input with native source locations and summary/detail separation.
+- `amp_protocol_workspace` v1 agent service, eight tools, local runtime integration and MCP stdio.
+- Fingerprints with an explicit policy: RFC 8785 canonical JSON for values, byte-level hashing for files, domain-separated Merkle roots for directory trees, and a `verify` that compares algorithm, kind and policy instead of a bare hex string. Unpaired surrogates and `-0` are rejected rather than silently rewritten.
+- One naming table for protocol, service and tool identity (`amp_protocol_*` / `amp_service_*` / `amp_tool_*`) with a grammar, a parser and a signed catalog digest, so dispatch, pinning and audit share one spelling.
+- Compaction and pruning at two levels. `planPrune()` decides every drop with a reason and a revisit condition; `compactLedger()` replaces a verified cold prefix with a checkpoint, `verifyCompaction()` re-derives that commitment, and compaction refuses to bury an entry the retained tail still cites. `pruneConcept()` and `compactConceptHistory()` apply the same discipline to concept content and version history.
+
+Offline parsers live in `tools/support/`. The runtime stays database-free and uses ports; persistence adapters are separate. Concrete contracts remain in [schemas](docs/schemas/), [examples](docs/examples/) and executable [checks](tools/).
+
+### Responsibility and interaction
+
+`responsibility-assignment` binds duties, RACI, authority, budget, window and evidence to an assignee; `interaction-binding` fixes the parties, protocol roles, mode mix, cadence, escalation and handoff state for a conversation. Both are checked by `assignment-check` and `interaction-binding-check`, and their contracts live in [docs/schemas](docs/schemas/). `AssignmentLedger`'s `onRevoke` hook can call `BindingLedger.revokeForAssignment()` so an assignment revocation cascades to its bindings.
+
+### Discovery
+
+`amp_tool_workspace_discover` returns one structural tree over the authorized projects. File nodes carry a module kind (`service`, `tool`, `controller`, `route`, `repository`, `model`, `config`, `test`, `middleware`, `component`, `util`), an extension and bounded content matches. Hosts register project descriptions, purposes, summaries, plugins, services and tools through `HostCatalog`; project metadata is attached to project nodes, and an unregistered project falls back to its workspace summary. Discovery is read-only, never widens `projectIds`, and returns snippets as discovery evidence rather than as a Frame-allocated detail read.
+
+## Quick start
+
+```sh
+npm ci
+npm run build
+npm run verify
+npm run scenario
+```
+
+## Library usage
+
+`npm install attention-manifest-protocol` ships the compiled ESM build in `lib/` with its declarations, alongside the source, JSON Schemas and executable checks. Node.js 24 or later is required. The root entry exposes the documented protocol surfaces; every module is also reachable as a subpath.
+
+```js
+import { generateSigningKey, signManifest, verifyManifest } from "attention-manifest-protocol";
+import { Ledger } from "attention-manifest-protocol/ledger";
+import { sha256Hex } from "attention-manifest-protocol/semantic/sha256.js";
+import { fingerprintText, fingerprintTree, verify } from "attention-manifest-protocol/fingerprint";
+import { ToolIds, parseId } from "attention-manifest-protocol/naming";
+```
+
+| Specifier | Resolves to |
+| --- | --- |
+| `attention-manifest-protocol` | `lib/index.js`: attention, assignment, context, discover, frame, ledger, manifest, receipt and warrant |
+| `attention-manifest-protocol/<module>` | `lib/<module>/index.js` for every module under `src/` |
+| `attention-manifest-protocol/<module>/<file>.js` | one compiled module |
+| `attention-manifest-protocol/schemas/<name>.json` | the JSON Schema from `docs/schemas/` |
+
+`npm run build:lib` rebuilds `lib/` and `prepublishOnly` runs it before publishing. The build compiles only the library; the Vite demo entry (`src/main.ts`) is not part of it.
+
+Focused checks: `npm run workspace-agent-check`, `workspace-project-check`, `workspace-diff-check`, `workspace-reactive-diff-check` and the `workspace-*-boundary-check` suites, `workspace-context-check`, `document-context-check`, `tex-context-check`, `governance-check`, `assignment-check`, `interaction-binding-check`, `discover-check`, `discover-agent-check`, `typecheck` and `typecheck:tools`. `verify` runs the full chain and both type checks. Evaluation inputs/reports remain in [docs/eval](docs/eval/) and [docs/probes](docs/probes/) as JSON; fixture and recorded-probe results are not independent human studies or production-quality evidence.
+
+## Agent tools
+
+The `amp_protocol_workspace` v1 response contains `protocol`, `version`, `revision`, `ok`, and either `data` or `error`. Both adapters share input schemas; the [protocol types](src/protocol/workspace.ts) define the response envelope. Except capability discovery, each business tool requires the current `revision`. Tool names come from the frozen naming table in [`src/naming/`](src/naming/); the pre-0.5 `amp_workspace_*` spellings are still accepted as input aliases and are listed under `deprecatedAliases` in the capabilities response. Every workspace tool is also mirrored as `amp_tool_global_<leaf>` over the host's complete authorized project set.
+
+| Tool | Purpose |
+| --- | --- |
+| `amp_tool_workspace_capabilities` | Discover permitted projects, registered Frames, tools and limits |
+| `amp_tool_workspace_tree` | Page project roots or structural children with native source locations |
+| `amp_tool_workspace_query` | Retrieve candidate IDs by lexical AND search and bounded graph traversal |
+| `amp_tool_workspace_relations` | Page typed dependency/call/reference relations and sources |
+| `amp_tool_workspace_discover` | Return one structural tree of authorized projects, modules, file names, bounded content matches and host components |
+| `amp_tool_workspace_materialize` | Materialize a host-registered Frame into a bounded Context |
+| `amp_tool_workspace_read` | Page a CAS-verified detail by character offset, 1-based lines or UTF-8 bytes; carries `importation`/`exportation`, the relative files it imports and the relative files importing it |
+| `amp_tool_workspace_write` | Replace project content by whole node, line range or UTF-8 byte range; host-gated, CAS and dry-run; returns the same `importation`/`exportation` |
+| `amp_tool_workspace_project` | Detect the project brand from manifest/lockfile evidence and run one host-approved `build`/`compile`/`run`/`test` command |
+| `amp_tool_workspace_outline` | One cascading outline: project → directory → file → symbol/knowledge, with 1-based ranges and bounded depth |
+| `amp_tool_workspace_dependency` | Project-level dependencies and dependents with the declaring source and method |
+| `amp_tool_workspace_reactive_read` | Proxy-backed workspace tree whose properties materialize lazily and are cached |
+| `amp_tool_workspace_reactive_write` | Set a node property (`summary`/`label`/`tags`) and refresh the affected cache; `content` uses the guarded write path |
+| `amp_tool_workspace_diff_read` | Comparable project tree carrying content revisions and byte/line metrics |
+| `amp_tool_workspace_diff_write` | Whole-file, 1-based line-splice or UTF-8 byte-splice write with the resulting line diff and hunks |
+| `amp_tool_workspace_release` | Release a read handle without refunding or reopening its Frame |
+
+`read` and `write` both need an explicitly allocated, materialized target; ancestors and discovery snippets do not grant it. `importation` lists the relative files the target's file imports (bare specifiers go to `external`, whose `externalTotal`/`externalTruncated` make the `maxFileLinks` cut visible) and `exportation` lists the relative files that import it, so an edit can be scoped without a second relation query. After a write to a file, a symbol or knowledge page extracted from it answers `stale_detail` until the host refreshes the snapshot, so stale bytes are never served with a current-looking revision. `write` never touches the file system itself: the host supplies a write port in `WorkspaceServiceOptions.writer`, and without one the call fails with `write_unavailable` while `dryRun` still previews the edit.
+
+`project` detection is offline (manifest and lockfile file names only); an execution action hands exactly one command from the brand table to `WorkspaceServiceOptions.runner`, and the agent can never supply command text. `reactive_read`/`reactive_write` add a per-service annotation overlay and child-index cache: a write bumps `cacheVersion` and reports every invalidated ancestor. `diff_read` exposes the content revision of each file so two snapshots can be compared without bodies; `diff_write` applies whole-file, line or byte splices and returns the resulting hunks, reusing the write port, CAS and dry-run.
+
+### Filesystem tools
+
+`amp_tool_filesystem_*` is bound to one authenticated Session; the bearer token never appears in a tool argument. Every tool except `write` is read-only.
+
+| Tool | Purpose |
+| --- | --- |
+| `amp_tool_filesystem_session` | Current identity, roots, permissions, remaining TTL and quotas |
+| `amp_tool_filesystem_file` | One File/Directory node; `depth`/`offset`/`limit` bound the subtree |
+| `amp_tool_filesystem_directory` | Flat listing of direct children |
+| `amp_tool_filesystem_read` | 1-based line page with fingerprint, charset and the next line |
+| `amp_tool_filesystem_write` | Atomic write; create/overwrite/upsert/append, CAS, dry-run |
+| `amp_tool_filesystem_outline` | Structural outline with `query`/`startLine`/`endLine` filters |
+| `amp_tool_filesystem_import` | Outgoing, incoming or two-way imports |
+| `amp_tool_filesystem_export` | Exported symbols, signatures and re-export edges |
+| `amp_tool_filesystem_dependency` | Cycles, topological order and bounded closures |
+| `amp_tool_filesystem_ast` | Lossless syntax tree: every non-whitespace token, declaration/markup hierarchy, UTF-8/line ranges; read-only, never executes |
+
+The global variant is `amp_tool_globalfs_*`, a naming adapter in [src/global/filesystem.ts](src/global/filesystem.ts) that grants no new root or permission. Outline nodes carry `isFile`/`isDirectory`/`file?`/`directory?`/`path` (for example `add.py#add`) and `range` (UTF-8 bytes plus 1-based lines as bigint; decimal strings on the wire). Strategies cover code, Vue, project manifests, Markdown/TeX/plain text, CSS/SCSS/Sass, HTML, XML/OPML and Office; Office parsing covers DOCX/XLSX/PPTX and treats DOC/XLS/PPT/PUB/ACCDB as best-effort CFB.
+
+### Hooks
+
+`src/hook` packages the same read-only operations as stateful, subscribable composition functions; only `useWrite` mutates:
+
+```ts
+import { useRead, useWrite, useDiff } from "attention-manifest-protocol/hook";
+
+const read = useRead(session);
+await read.run({ path: "src/main.ts", maxLines: 80, includeLineNumbers: true });
+const write = useWrite(session);
+await write.run({ path: "src/new.ts", content: "export const value = 1;\n", mode: "create" });
+const diff = useDiff(session);
+await diff.run({ path: "src/new.ts", before: "" });
+```
+
+`useParse` is module-specific (`useOutlineParse`, `useImportationParse`, `useExportationParse`, `useDependencyParse`, `useCodeParse`, `useProjectParse`, `useAstParse`); `useCode`/`useProject` are composed models and `useAst` returns the lossless read-only syntax tree. A cache hit re-checks the session revision, and runs can be recorded in `hook_runs`.
+
+### MCP stdio
+
+```sh
+npm run workspace-agent-demo
+npm run workspace-agent -- --config .cache/workspace-agent.local
+```
+
+For an MCP client, start Node directly to keep package-manager banners out of stdout. Replace absolute paths with your checkout location:
+
+```json
+{
+  "mcpServers": {
+    "amp-workspace": {
+      "command": "node",
+      "args": [
+        "R:/project/attention-manifest-protocol/tools/workspaceAgentServer.ts",
+        "--config",
+        "R:/project/attention-manifest-protocol/.cache/workspace-agent.local"
+      ]
+    }
+  }
+}
+```
+
+The trusted host bootstrap contains `version: 1`, `agentId`, explicit `projectIds`, a `WorkspaceSnapshot`, `contents` mapping CAS refs to text, `frames`, optional lower `limits`, and optional `discovery.projects` / `discovery.components` for host-registered descriptions and components. Contents are hash-checked at startup. The demo uses example inputs; real hosts pass their authorized inventory to `scanStructuredWorkspace` in [documentScanner.ts](tools/support/documentScanner.ts).
+
+The stdio adapter reads configuration only at startup; new snapshots/Frames require a new host configuration and instance. It accepts newline-delimited JSON-RPC, limits messages to 1 MiB and configuration to 64 MiB, and never executes tools carried in notifications. It supports `initialize` for `2025-11-25` / `2025-06-18` and the repository's `2026-07-28` stateless discovery/metadata profile; other versions are not claimed as tested.
+
+### Local runtime
+
+```ts
+import { WorkspaceAgentService } from "./src/context/index.ts";
+import { ToolRegistry, registerWorkspaceTools, WorkspaceToolExecutor } from "./src/module/index.ts";
+
+const workspace = new WorkspaceAgentService({
+    agentId: frame.agent,
+    projectIds: ["project:packages/app"],
+    snapshot,
+    store,
+});
+workspace.registerFrame(frame, snapshot.revision);
+const tools = new ToolRegistry();
+registerWorkspaceTools(tools, workspace);
+const toolExecutor = new WorkspaceToolExecutor(workspace, existingExecutor);
+```
+
+The host provides the Frame, snapshot, ContentStore and fallback executor; pass `tools` / `toolExecutor` to `CognitiveRuntime`. Registration, revocation and Receipt settlement are host APIs, unavailable to the model.
+
+### Scope, lifecycle and limits
+
+Discovery/query return metadata and candidates, not authorization. Hosts fix project scope and register selected Frames. Only active targets admitted to the view permit detail reads; ancestor summaries do not grant whole-file access. Workspace IDs are extension-local keys, not global Ledger identities. Full Frame validation, signatures and policy checks remain host responsibilities.
+
+Identical materialization requests reuse a Context without recharging summaries; changed parameters are rejected. Release/revocation invalidates the read handle but retains pending settlement. Hosts use `pendingSettlements()` and `settle(contextId, receipt)` to obtain an archived ContextSnapshot. This state is in memory; hosts must persist audit/recovery data.
+
+Defaults: 128 registered Frames, 32 live read Contexts, 8000 estimated summary tokens, 8000 UTF-16 units per detail page, 131072 units per successful response and 1000 business calls. Query depth is at most 10; results/pages at most 100. Hosts may lower limits. Summary text and successful detail pages share the Frame's remaining estimated token budget; repeat reads cost budget and release does not refund it. Discovery, JSON wrapping and later model consumption are excluded from that estimate; actual usage belongs in Receipts.
+
+Detail offsets use UTF-16 units; `nextOffset: null` ends pagination. Reassemble structured JSON detail before parsing. CAS verification reads the full detail before paging, so response bounds do not imply bounded storage I/O. Runtime messages retain complete JSON up to `maxToolResultChars` (default 1048576, configurable down to 128); oversize results return `tool_result_too_large`, while logs retain a 4000-character preview.
+
+Service errors: `invalid_arguments`, `unknown_tool`, `revision_mismatch`, `not_available`, `frame_unavailable`, `budget_exhausted`, `capacity_exceeded`, `response_too_large`, `integrity_failure`, `internal_error`. Oversize responses fail instead of truncating structured content.
+
+## Repository layout
+
+| Path | Contents |
+| --- | --- |
+| [src/semantic](src/semantic/) | Base primitives with no policy: strict SHA-256, canonical JSON and the I-JSON predicate |
+| [src/fingerprint](src/fingerprint/) | Algorithms, preimage framing, policies, refs, verification, files and Merkle trees |
+| [src/naming](src/naming/) | The frozen id table, the id grammar, compatibility aliases and the catalog digest |
+| [src/context](src/context/) | Context lifecycle, tree/graph projections, CAS, workspace facts, context assembly and agent service |
+| [src/session](src/session/) | Identity, tokens, TTL, context isolation, fork/revoke/rotate |
+| [src/file](src/file/) | File/Directory tree, metadata, paged reads, atomic writes, session runtime/service, module graphs and ZIP/CFB containers |
+| [src/syntax](src/syntax/) | Charset detection/encoding, byte/line indexing, syntax registry and lossless read-only syntax trees |
+| [src/outline](src/outline/) | Code/document outlines, range and label indexes, keyword/strategy registries, React/Shell/SQL/Visual Basic strategies and Office parsing |
+| [src/hook](src/hook/) | Agent-facing composition hooks and run records |
+| [src/protocol](src/protocol/) | Wire contracts: envelopes, A2A, channels and the `amp_protocol_workspace` surface |
+| [src/module](src/module/) | LLM/tool ports, MCP adapters and execution policies |
+| [src/runtime](src/runtime/) | Agent turn/tool loop and governance integration |
+| [src/governance](src/governance/) | Manifests, credentials, budgets, workflows, signing and audit |
+| [src/structure](src/structure/) | Maps, trees, queues, priority indexes, filters, AST and LRU |
+| [src](src/) | Other attention, evidence, ledger, policy, kernel and persistence domains |
+| [tools](tools/) | TypeScript checks, offline scanners, demos and probes |
+| [docs/schemas](docs/schemas/) / [docs/examples](docs/examples/) | Machine-readable contracts and protocol examples |
+| [docs/eval](docs/eval/) / [docs/probes](docs/probes/) | Evaluation inputs and JSON reports |
+
+## Code style
+
+ESLint checks semantic/style constraints; Prettier handles layout. Commands: `npm run lint`, `lint:fix`, `format:check`, `format`, `style-check`. Configuration lives in [eslint.config.mts](eslint.config.mts) and [prettier.config.mts](prettier.config.mts); local rules/printer live under `tools/`.
+
+Declare variable types explicitly; use arrow functions instead of `function`, semicolons, four-space indentation, double quotes and template strings. Keep parameters/type parameters on one line, use braces for control flow, `typeof(value)` and `=== (void 0)`. Locals/parameters and function values use lowerCamelCase; module-level data uses PascalCase; source file names use lowerCamelCase starting with a lowercase letter (for example `workspaceService.ts`, `fileGraph.ts`) and never hyphens, while SQL identifiers keep the existing snake_case. Comments use multiline JSDoc except tool directives. Historical files retain lint/format migration debt; functional verification does not imply a clean repository-wide style check.
+
+## Boundaries and evidence
+
+Static dependency extraction is partial; missing edges do not prove independence. Markdown/TeX scanners do not implement all macros or semantics. Summaries, graphs and long contexts require multi-hop, cross-document and changing-information evaluations. Relevant primary sources include [LaRA](https://proceedings.mlr.press/v267/li25dv.html), [GraphRAG-Bench](https://arxiv.org/abs/2506.05690), [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) and [RFC 6920](https://www.rfc-editor.org/rfc/rfc6920.html); they do not establish AMP's own effectiveness.
+
+Sandbox isolation, multi-tenancy, interactive OAuth, production deployment and real external-agent interoperability remain outside the completed reference implementation. Human research inspires design but does not prove identical model mechanisms or capacity constants. Provenance proves integrity, not truth or authority to act.
+
+## License and history
+
+[Apache License 2.0](LICENSE), copyright 2026 Eloy Kim; retain [NOTICE](NOTICE), license and attribution notices when redistributing. History: [CHANGELOG.md](CHANGELOG.md) and [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md).