attention-manifest-protocol 0.4.0 → 0.4.2

package/README.md

@@ -2,7 +2,7 @@
 
 **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.0`, requires **Node.js 24 or later**, and uses Apache-2.0.
+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
 
@@ -15,6 +15,7 @@ AMP is a metacognitive protocol for agents: declare knowledge and obligations, a
 | 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
@@ -31,6 +32,7 @@ Context combines a structural tree and typed relationships. Project dependencies
 - 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/).
 
@@ -43,6 +45,25 @@ 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

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](README.md) · **简体中文** · [更新日志](CHANGELOG.zh-CN.md)
 
-AMP 是供 agent 使用的元认知协议：声明知识和义务，分配有限注意力，获取证据，记录成本与结果。当前参考实现为 `0.4.0`，要求 **Node.js 24 或以上**，使用 Apache-2.0 许可证。
+AMP 是供 agent 使用的元认知协议：声明知识和义务，分配有限注意力，获取证据，记录成本与结果。当前参考实现为 `0.4.2`，要求 **Node.js 24 或以上**，使用 Apache-2.0 许可证。
 
 ## 架构
 
@@ -15,6 +15,7 @@ AMP 是供 agent 使用的元认知协议：声明知识和义务，分配有限
 | Frame | 固化本轮引用、预算和显式排除项 `ignored` |
 | Context | 将分配物化为摘要、关系与受限的详情读取 |
 | Receipt | 记录实际成本和结果，支持审计与校准 |
+| Compaction（压缩与剪枝） | 按明确理由剪掉冷数据或已失效对象，再用检查点替换已验证的前缀 |
 
 ```text
 Attention 选择 → Frame 固化 → Context 物化 → Receipt 结算 → Ledger
@@ -31,6 +32,7 @@ Context 使用结构树和类型化关系图。项目依赖、导入、调用与
 - 项目树、项目依赖图、TS/JS 的部分静态导入/调用/引用图，以及知识库词法检索。
 - Markdown、TXT、DOCX、XLSX、PPTX、TeX/LaTeX/BibTeX 的结构提取、原生定位与摘要/详情分层。
 - `amp.workspace` v1 服务、7 个 agent 工具、本地运行时接入与 MCP stdio 服务端。
+- 两层压缩与剪枝。`planPrune()` 为每次丢弃给出理由和回看条件；`compactLedger()` 用检查点替换已验证的冷前缀，`verifyCompaction()` 重新推导该承诺，且不会埋掉保留尾部仍然引用的条目。`pruneConcept()` 与 `compactConceptHistory()` 对概念内容和版本历史执行同样的约束。
 
 离线解析器位于 `tools/support/`；运行时通过端口接入数据，不依赖数据库，持久化适配器与运行时核心分离。具体契约见 [Schema](docs/schemas/)、[协议示例](docs/examples/) 与 [可执行检查](tools/)。
 
@@ -43,6 +45,25 @@ npm run verify
 npm run scenario
 ```
 
+## 作为库使用
+
+`npm install attention-manifest-protocol` 会安装 `lib/` 中的编译产物及其声明文件，同时附带源码、JSON Schema 与可执行检查。运行时要求 Node.js 24 及以上。包根入口提供文档中的协议核心接口，其余模块均可按子路径导入。
+
+```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";
+```
+
+| 说明符 | 解析结果 |
+| --- | --- |
+| `attention-manifest-protocol` | `lib/index.js`：attention、context、frame、ledger、manifest、receipt、warrant |
+| `attention-manifest-protocol/<module>` | `src/` 下每个模块对应 `lib/<module>/index.js` |
+| `attention-manifest-protocol/<module>/<file>.js` | 单个编译后的模块 |
+| `attention-manifest-protocol/schemas/<name>.json` | `docs/schemas/` 中的 JSON Schema |
+
+`npm run build:lib` 重新构建 `lib/`，发布前由 `prepublishOnly` 自动执行。该构建只编译库代码，Vite 演示入口（`src/main.ts`）不在其中。
+
 专项检查为 `npm run workspace-agent-check`、`workspace-context-check`、`document-context-check`、`tex-context-check`、`governance-check`、`typecheck` 与 `typecheck:tools`。`verify` 执行完整验证链和两份类型检查。评测输入/结果以 JSON 保存在 [docs/eval](docs/eval/) 与 [docs/probes](docs/probes/)，夹具与录制探针不等同于独立的人类研究或生产质量证明。
 
 ## Agent 工具

package/docs/probes/calibration-imported.json

@@ -1,141 +1,141 @@
-{
-  "generatedAt": "2026-10-28T19:55:20.031Z",
-  "annotationsPath": "docs/eval/annotations.json",
-  "audit": {
-    "cases": 52,
-    "annotations": 24,
-    "covered": 12,
-    "coverage": 0.23076923076923078,
-    "missing": [
-      "recorded:objective:bare:unique-rows:1",
-      "recorded:objective:bare:syllogism:2",
-      "recorded:objective:bare:array-expression:3",
-      "recorded:objective:bare:incident-minutes:4",
-      "recorded:objective:bare:bayes:5",
-      "recorded:context:bare:memory-penalty:6",
-      "recorded:context:bare:role-obligation:7",
-      "recorded:context:bare:attention-slots:8",
-      "recorded:context:bare:stress-level:9",
-      "recorded:context:bare:fabrication:10",
-      "recorded:objective:person:unique-rows:11",
-      "recorded:objective:person:syllogism:12",
-      "recorded:objective:person:array-expression:13",
-      "recorded:objective:person:incident-minutes:14",
-      "recorded:objective:person:bayes:15",
-      "recorded:context:person:memory-penalty:16",
-      "recorded:context:person:role-obligation:17",
-      "recorded:context:person:attention-slots:18",
-      "recorded:context:person:stress-level:19",
-      "recorded:context:person:fabrication:20",
-      "recorded:objective:person+attention:unique-rows:21",
-      "recorded:objective:person+attention:syllogism:22",
-      "recorded:objective:person+attention:array-expression:23",
-      "recorded:objective:person+attention:incident-minutes:24",
-      "recorded:objective:person+attention:bayes:25",
-      "recorded:context:person+attention:memory-penalty:26",
-      "recorded:context:person+attention:role-obligation:27",
-      "recorded:context:person+attention:attention-slots:28",
-      "recorded:context:person+attention:stress-level:29",
-      "recorded:context:person+attention:fabrication:30",
-      "recorded:objective:person+attention+scenario:unique-rows:31",
-      "recorded:objective:person+attention+scenario:syllogism:32",
-      "recorded:objective:person+attention+scenario:array-expression:33",
-      "recorded:objective:person+attention+scenario:incident-minutes:34",
-      "recorded:objective:person+attention+scenario:bayes:35",
-      "recorded:context:person+attention+scenario:memory-penalty:36",
-      "recorded:context:person+attention+scenario:role-obligation:37",
-      "recorded:context:person+attention+scenario:attention-slots:38",
-      "recorded:context:person+attention+scenario:stress-level:39",
-      "recorded:context:person+attention+scenario:fabrication:40"
-    ],
-    "duplicates": [],
-    "disagreements": [
-      {
-        "caseId": "replay:r-arith-2",
-        "labels": {
-          "incorrect": 1,
-          "correct": 1
-        }
-      },
-      {
-        "caseId": "replay:r-memory-2",
-        "labels": {
-          "incorrect": 1,
-          "correct": 1
-        }
-      }
-    ],
-    "annotators": [
-      "A",
-      "B"
-    ],
-    "pairwiseKappa": [
-      {
-        "left": "A",
-        "right": "B",
-        "kappa": 0.5714285714285715,
-        "common": 12
-      }
-    ],
-    "adjudicated": {
-      "replay:r-arith-1": "correct",
-      "replay:r-arith-2": null,
-      "replay:r-arith-3": "correct",
-      "replay:r-logic-1": "correct",
-      "replay:r-logic-2": "incorrect",
-      "replay:r-memory-1": "correct",
-      "replay:r-memory-2": null,
-      "replay:r-role-1": "correct",
-      "replay:r-attention-1": "correct",
-      "replay:r-bayes-1": "correct",
-      "replay:r-bayes-2": "incorrect",
-      "replay:r-context-1": "correct",
-      "recorded:objective:bare:unique-rows:1": null,
-      "recorded:objective:bare:syllogism:2": null,
-      "recorded:objective:bare:array-expression:3": null,
-      "recorded:objective:bare:incident-minutes:4": null,
-      "recorded:objective:bare:bayes:5": null,
-      "recorded:context:bare:memory-penalty:6": null,
-      "recorded:context:bare:role-obligation:7": null,
-      "recorded:context:bare:attention-slots:8": null,
-      "recorded:context:bare:stress-level:9": null,
-      "recorded:context:bare:fabrication:10": null,
-      "recorded:objective:person:unique-rows:11": null,
-      "recorded:objective:person:syllogism:12": null,
-      "recorded:objective:person:array-expression:13": null,
-      "recorded:objective:person:incident-minutes:14": null,
-      "recorded:objective:person:bayes:15": null,
-      "recorded:context:person:memory-penalty:16": null,
-      "recorded:context:person:role-obligation:17": null,
-      "recorded:context:person:attention-slots:18": null,
-      "recorded:context:person:stress-level:19": null,
-      "recorded:context:person:fabrication:20": null,
-      "recorded:objective:person+attention:unique-rows:21": null,
-      "recorded:objective:person+attention:syllogism:22": null,
-      "recorded:objective:person+attention:array-expression:23": null,
-      "recorded:objective:person+attention:incident-minutes:24": null,
-      "recorded:objective:person+attention:bayes:25": null,
-      "recorded:context:person+attention:memory-penalty:26": null,
-      "recorded:context:person+attention:role-obligation:27": null,
-      "recorded:context:person+attention:attention-slots:28": null,
-      "recorded:context:person+attention:stress-level:29": null,
-      "recorded:context:person+attention:fabrication:30": null,
-      "recorded:objective:person+attention+scenario:unique-rows:31": null,
-      "recorded:objective:person+attention+scenario:syllogism:32": null,
-      "recorded:objective:person+attention+scenario:array-expression:33": null,
-      "recorded:objective:person+attention+scenario:incident-minutes:34": null,
-      "recorded:objective:person+attention+scenario:bayes:35": null,
-      "recorded:context:person+attention+scenario:memory-penalty:36": null,
-      "recorded:context:person+attention+scenario:role-obligation:37": null,
-      "recorded:context:person+attention+scenario:attention-slots:38": null,
-      "recorded:context:person+attention+scenario:stress-level:39": null,
-      "recorded:context:person+attention+scenario:fabrication:40": null
-    }
-  },
-  "coverageGate": "0.9",
-  "points": 10,
-  "status": "refused",
-  "reason": "coverage 0.231 < 0.9",
-  "selection": null,
-  "activation": null
-}
+{
+  "generatedAt": "2026-10-28T19:55:20.031Z",
+  "annotationsPath": "docs/eval/annotations.json",
+  "audit": {
+    "cases": 52,
+    "annotations": 24,
+    "covered": 12,
+    "coverage": 0.23076923076923078,
+    "missing": [
+      "recorded:objective:bare:unique-rows:1",
+      "recorded:objective:bare:syllogism:2",
+      "recorded:objective:bare:array-expression:3",
+      "recorded:objective:bare:incident-minutes:4",
+      "recorded:objective:bare:bayes:5",
+      "recorded:context:bare:memory-penalty:6",
+      "recorded:context:bare:role-obligation:7",
+      "recorded:context:bare:attention-slots:8",
+      "recorded:context:bare:stress-level:9",
+      "recorded:context:bare:fabrication:10",
+      "recorded:objective:person:unique-rows:11",
+      "recorded:objective:person:syllogism:12",
+      "recorded:objective:person:array-expression:13",
+      "recorded:objective:person:incident-minutes:14",
+      "recorded:objective:person:bayes:15",
+      "recorded:context:person:memory-penalty:16",
+      "recorded:context:person:role-obligation:17",
+      "recorded:context:person:attention-slots:18",
+      "recorded:context:person:stress-level:19",
+      "recorded:context:person:fabrication:20",
+      "recorded:objective:person+attention:unique-rows:21",
+      "recorded:objective:person+attention:syllogism:22",
+      "recorded:objective:person+attention:array-expression:23",
+      "recorded:objective:person+attention:incident-minutes:24",
+      "recorded:objective:person+attention:bayes:25",
+      "recorded:context:person+attention:memory-penalty:26",
+      "recorded:context:person+attention:role-obligation:27",
+      "recorded:context:person+attention:attention-slots:28",
+      "recorded:context:person+attention:stress-level:29",
+      "recorded:context:person+attention:fabrication:30",
+      "recorded:objective:person+attention+scenario:unique-rows:31",
+      "recorded:objective:person+attention+scenario:syllogism:32",
+      "recorded:objective:person+attention+scenario:array-expression:33",
+      "recorded:objective:person+attention+scenario:incident-minutes:34",
+      "recorded:objective:person+attention+scenario:bayes:35",
+      "recorded:context:person+attention+scenario:memory-penalty:36",
+      "recorded:context:person+attention+scenario:role-obligation:37",
+      "recorded:context:person+attention+scenario:attention-slots:38",
+      "recorded:context:person+attention+scenario:stress-level:39",
+      "recorded:context:person+attention+scenario:fabrication:40"
+    ],
+    "duplicates": [],
+    "disagreements": [
+      {
+        "caseId": "replay:r-arith-2",
+        "labels": {
+          "incorrect": 1,
+          "correct": 1
+        }
+      },
+      {
+        "caseId": "replay:r-memory-2",
+        "labels": {
+          "incorrect": 1,
+          "correct": 1
+        }
+      }
+    ],
+    "annotators": [
+      "A",
+      "B"
+    ],
+    "pairwiseKappa": [
+      {
+        "left": "A",
+        "right": "B",
+        "kappa": 0.5714285714285715,
+        "common": 12
+      }
+    ],
+    "adjudicated": {
+      "replay:r-arith-1": "correct",
+      "replay:r-arith-2": null,
+      "replay:r-arith-3": "correct",
+      "replay:r-logic-1": "correct",
+      "replay:r-logic-2": "incorrect",
+      "replay:r-memory-1": "correct",
+      "replay:r-memory-2": null,
+      "replay:r-role-1": "correct",
+      "replay:r-attention-1": "correct",
+      "replay:r-bayes-1": "correct",
+      "replay:r-bayes-2": "incorrect",
+      "replay:r-context-1": "correct",
+      "recorded:objective:bare:unique-rows:1": null,
+      "recorded:objective:bare:syllogism:2": null,
+      "recorded:objective:bare:array-expression:3": null,
+      "recorded:objective:bare:incident-minutes:4": null,
+      "recorded:objective:bare:bayes:5": null,
+      "recorded:context:bare:memory-penalty:6": null,
+      "recorded:context:bare:role-obligation:7": null,
+      "recorded:context:bare:attention-slots:8": null,
+      "recorded:context:bare:stress-level:9": null,
+      "recorded:context:bare:fabrication:10": null,
+      "recorded:objective:person:unique-rows:11": null,
+      "recorded:objective:person:syllogism:12": null,
+      "recorded:objective:person:array-expression:13": null,
+      "recorded:objective:person:incident-minutes:14": null,
+      "recorded:objective:person:bayes:15": null,
+      "recorded:context:person:memory-penalty:16": null,
+      "recorded:context:person:role-obligation:17": null,
+      "recorded:context:person:attention-slots:18": null,
+      "recorded:context:person:stress-level:19": null,
+      "recorded:context:person:fabrication:20": null,
+      "recorded:objective:person+attention:unique-rows:21": null,
+      "recorded:objective:person+attention:syllogism:22": null,
+      "recorded:objective:person+attention:array-expression:23": null,
+      "recorded:objective:person+attention:incident-minutes:24": null,
+      "recorded:objective:person+attention:bayes:25": null,
+      "recorded:context:person+attention:memory-penalty:26": null,
+      "recorded:context:person+attention:role-obligation:27": null,
+      "recorded:context:person+attention:attention-slots:28": null,
+      "recorded:context:person+attention:stress-level:29": null,
+      "recorded:context:person+attention:fabrication:30": null,
+      "recorded:objective:person+attention+scenario:unique-rows:31": null,
+      "recorded:objective:person+attention+scenario:syllogism:32": null,
+      "recorded:objective:person+attention+scenario:array-expression:33": null,
+      "recorded:objective:person+attention+scenario:incident-minutes:34": null,
+      "recorded:objective:person+attention+scenario:bayes:35": null,
+      "recorded:context:person+attention+scenario:memory-penalty:36": null,
+      "recorded:context:person+attention+scenario:role-obligation:37": null,
+      "recorded:context:person+attention+scenario:attention-slots:38": null,
+      "recorded:context:person+attention+scenario:stress-level:39": null,
+      "recorded:context:person+attention+scenario:fabrication:40": null
+    }
+  },
+  "coverageGate": "0.9",
+  "points": 10,
+  "status": "refused",
+  "reason": "coverage 0.231 < 0.9",
+  "selection": null,
+  "activation": null
+}