common-memory-core 0.2.0

package/docs/v2-performance.md

@@ -0,0 +1,88 @@
+# V2 实现性能优化
+
+## 结果与范围
+
+保留五种触发和全部默认参数，仅修改 `src/v2/runtime.ts` 的 SQLite 访问路径。
+真实模型、Prompt、Markdown/回执协议、Writer、Pi 来源判断均未修改。无新依赖或正文 schema 迁移。
+
+本机配对微基准：
+
+| 场景 | 修改前 median（ms） | 修改后 median（ms） | 修改后 P95（ms） | 前/后耗时比 |
+|---|---:|---:|---:|---:|
+| 空闲检查：20 条历史 | 0.018 | 0.024 | 0.036 | 0.77× |
+| 空闲检查：20,000 条历史 | 6.942 | 0.032 | 0.045 | 214.00× |
+| 强制领取：6 条待处理 | 0.096 | 0.159 | 0.187 | 0.60× |
+| 自动领取：2,000 条积压 | 10.998 | 0.207 | 0.259 | 53.19× |
+| 首次打开旧库：20,000 条历史 | 0.304 | 11.119 | 13.143 | 0.03× |
+| 强制领取：2,000 条积压 | 12.419 | 0.241 | 0.331 | 51.48× |
+| 重复恢复：2 份已确认回执 | 0.321 | 0.345 | 0.568 | 0.93× |
+| 重复恢复：500 份已确认回执 | 16.893 | 17.998 | 20.593 | 0.94× |
+
+比例大于 1 表示加快，小于 1 表示变慢。这里的比值是**SQLite/文件系统局部操作**，
+不是端到端模型延迟、Token 成本或线上吞吐提升。
+
+## 修改
+
+1. 新增 `observations(state,id)`、非空 `jobId`、活跃 job 部分索引，避免历史记录拖慢队列查询。
+2. 已处理正文清理增加 `text IS NOT NULL`，避免反复 UPDATE 已清空正文；配合只索引尚有正文的部分索引。
+3. EXPLAIN 发现 SQLite 原先偏好 state 索引、仍扫描全部 processed；此条 UPDATE 现在显式指定 `observations_prunable`。
+4. claim 只解码本批容量的队首，不再把全部待处理正文复制到 JavaScript。
+5. 数量仍对全 pending 跨 Scope 判断；必要时用 SQLite UTF-8 BLOB 字节总和判断体积。
+6. 首尾时间仍按 Entry 入队 ID 选取，不改成时间 MIN/MAX；领取后检查剩余 pending 保留 flush 尾批。
+
+不缓存队列计数、不跳过 lease/CAS/权限/恢复校验。永久回执读取未优化，其波动不计作收益。
+
+## 代价与限制
+
+- 小库空闲检查约增加 **0.005 ms**，小批领取约增加 **0.063 ms**。新增索引维护和查询有固定成本，不隐瞒这个退化。
+- 首次打开现有 20k 历史库建索引，本机约增加 **10.8 ms**；之后重开不重复重建。
+- 索引占用额外空间并增加写入维护；本轮未测磁盘容量增长或大规模持续写入吞吐。
+- 500 份永久回执重复恢复仍约 18 ms，线性扫描风险未解决。为保留恢复/隐私保证，本轮没有以跳过确认回执验证换取速度。
+- 自动领取场景满足数量触发；不代表所有“未达到阈值”的小队列路径都同样加快。
+- 微基准样本为本地合成数据，9 个样本的 nearest-rank P95 等于最大样本，不是生产 P95 估计或统计显著性证明。
+
+## 方法
+
+- 修改前先构建并冻结完整 dist，随后再修改实现。基线源码摘要与完整编译树 manifest 保存在结果 JSON。
+- 每场景 2 次 warmup、9 个正式样本；基线/候选交替顺序，使用独立临时 dataRoot。
+- 造数不计时。空闲场景 20k processed body 已为 NULL；积压场景 2k × 4 KiB 完整 Turn，另含 20k 已完成 jobs。
+- 领取在外层事务中回滚，从同一初始队列反复测量；每次检查准确的前 6 个 ID、完整正文及剩余队列。
+- 除“首次打开旧库”外，构造器和建索引不计时；首次打开病例用旧实现建库，再计时新实现的第一次构造。
+- 恢复测量 constructor 之后的重复恢复，不是冷启动。模型 stub 在被调用时直接失败，实际网络调用为 0。
+- 环境：Node v24.16.0，linux / x64，AMD Ryzen 7 7800X3D 8-Core Processor。完整 OS、样本与摘要见 [配对结果](v2-performance-results.json)。
+
+## 行为与验证
+
+- 编辑实现前，新增 10 项行为回归在旧实现全部通过；2 项性能性质回归先失败（重复 NULL 更新、全量 pending 物化），实现后转绿；再增加实际 SQL 的 EXPLAIN 索引回归。
+- `npm run lint`：typecheck、静态边界通过。
+- `npm test`：14 文件、117 项通过。
+- `npm run build`、真实 tarball consumer、remote contract 测试通过。
+- **新旧实现各 720 次消融执行，原始队列轨迹与汇总逐项相同**；只允许代码摘要改变，不接受触发或尾批语义漂移；[等价证据](v2-performance-behavior-equivalence.json) 保存双边摘要。
+- 新回归覆盖中文、emoji、NUL、孤立 surrogate、跨 Scope 全局阈值、ID 首尾时钟回拨、flush 尾批、maxTurns 极值、重试批次冻结和精确清理截止。
+- 独立 critic 对计划及实现审查：**OKAY，无阻断项**；独立跑 4 个测试文件、30 项测试通过。
+
+## 复现
+
+当前实现测量：
+
+```sh
+npm run benchmark:v2
+```
+
+配对测量（提供冻结的旧 dist）：
+
+```sh
+npm run benchmark:v2 -- --baseline=/path/to/old/dist --output=docs/v2-performance-results.json
+```
+
+原始基线是未提交工作树快照，不能用本仓 HEAD 代替。
+保留的 `docs/v2-performance-baseline-runtime.js.txt` 是该次运行实际执行的旧 Runtime 模块。
+在本轮配套 dist 上复制整棵 dist、只替换 `v2/runtime.js`，并设置外层 package `type:module` 和
+依赖解析路径即可重建执行基线；恢复前须对照结果 JSON 确认其他执行模块摘要仍一致。
+源码映射并不用于此微基准，替换后它们不会自动退回旧版本；不能因此声称重建了逐字节相同编译树。
+若将来 Writer/其他模块变化，请使用完整旧快照，不混用不同版本。
+
+本轮附加文件：优化计划、基准脚本、基线/结果 JSON、旧 Runtime 文本快照、回归测试。
+不自动清理或测量任何真实用户数据库。
+
+最终证据复审：独立 critic 核对了新旧 Runtime 摘要、原始 JSON、报告数值及代价披露，结论 **OKAY，无阻断项**。

package/docs/v2-replacement-test-map.md

@@ -0,0 +1,14 @@
+# V2 regression replacement map
+
+Old Fact/Proposal/Review serialization, FTS/Recall/ranking/context pack, governance/Undo,
+Fact compiler/policy and old extraction scheduler tests are intentionally retired with
+their product surfaces, not interpreted as V2 successes.
+
+Preserved invariants are re-established under `tests/v2`: source authentication and
+ambiguous-delivery quarantine; durable delivered observations independent of assistant
+success; FIFO/retry/lease fencing; atomic Markdown/receipt recovery and CAS; unchanged
+Section bytes; invalid decisions produce zero canonical pollution; full-turn limits.
+Provider request bounds, credential protection, refusal/timeout/cancellation and local
+configuration privacy retain their dedicated existing adapter/config tests.
+
+Mocked maintenance responses test the contract/executor only, not model semantic quality.

package/docs/v2-verification.md

@@ -0,0 +1,49 @@
+# V2 交付验证 — 2026-09-05
+
+> 历史记录：Pi/Codex 读取频率、捕获、调度和退出行为已由 [会话接入](session-integration.md) 替代。下文旧验收不证明新会话链路。
+
+
+## 改动范围
+
+- `src/v2/`：Markdown、可恢复文件事务、统一 SQLite、混合调度、协议、Writer、Project Registry、安全错误码和 repository lock。
+- `src/pi-extension/`：durable delivery / stable entry 绑定、来源隔离、稳定边界和生命周期处理。
+- `src/config/`、`src/cli/`、`src/index.ts`：V2 配置、注册/status/flush/retry、Write-only 公共面。
+- `src/memory-manager/openai/`：复用 native fetch、超时/取消/有界响应，增加精确请求字节计算。
+- 移除旧 Fact/Proposal/Review/Recall/FTS/Undo、旧测试/fixture/schema 和失效文档。移除 yaml、ajv-formats、直接 typebox peer；不新增运行时依赖。Pi peer 锁定 0.84.4。
+
+## 新鲜执行证据
+
+- `npm ci`：成功；审计 0 vulnerabilities。
+- `npm run lint`：typecheck 与 27 个源文件边界检查通过。
+- `npm test`：12 文件，101 测试通过。
+- `npm run build`：通过。
+- `npm run test:consumer`：真正生成/解压 tarball，验证 typed consumer、包内 Maintainer、Writer 空队列、Pi 加载、CLI 启动；不存在旧 Fact/Recall 打包产物。
+- `npm run test:remote-contract`：4 文件，20 离线远程适配器协议测试通过；不是 live provider 调用。
+- `node scripts/evaluate-v2.mjs`：30 合成轨迹，每 Turn / fixed-six / Hybrid 三策略均最终状态 30/30、Scope error 0、retry 0。调用次数 210 / 60 / 60。
+- 重复三策略评测 10 次（900 个 trajectory-policy 执行），结果见 `v2-evaluation-repeat-results.json`。
+- `git diff --check`：通过。
+
+故障测试包括真实子进程在事务阶段强制退出、文件成功/DB回滚恢复、双进程同库竞争、过期旧 worker、人工编辑 CAS、暂存后修改、发布 marker 前 fencing、Project 注册撤销竞态、手工改名/删除后的遗忘/no-op、Section 来源继承隔离。
+
+## 独立审查
+
+- `code-reviewer` 独立 lane：APPROVE，最终增量复核包含注册重验、暂存后 CAS、snapshot journal.before、发布前 lease/取消校验；另复核银行卡扫描仅排除完整 UUID、中文邻接卡号和 UUID-shaped 凭据仍被保护；0 未解决问题，独立复跑 101 tests + lint 通过。
+- `architect` 独立 lane：WATCH，无未解决架构 BLOCK。
+- 合并审查结论：COMMENT（有已披露观察项，不宣称无风险 APPROVE）。
+
+## 未验证与观察项
+
+1. **真实模型语义质量未验证。** Scripted oracle 只证明协议/执行器与调度；Token 值 `tokensMeasured:false` 不是免费或真实用量。真实 provider 评测需显式 opt-in，未自动使用凭据或产生费用。
+2. **Pi 原始输入溯源边界。** 公共 API 无端到端原始输入 token；更早执行的扩展必须属于可信宿主，README 说明扩展排序。自动化使用真实类型与源码事件契约、fake host 驱动；未进行真人交互的 live Pi/远程模型联调。
+3. **长期规模。** 空队列不扫描历史回执；活跃恢复仍遍历永久回执，数据规模很大时需增量协调优化。
+4. **人工 Markdown 改动。** 标题身份失效时，保守清理该文档短期 processed evidence 缓冲与旧关联，不删除当前 Markdown 或其他文档。此行为以同一 DB 或文件回执事务恢复。
+5. 不迁移或自动清理任何旧用户 dataRoot；Forget 不等于删除 Pi transcript、介质安全擦除或永久禁止未来重述。
+
+## 评测稳定性修复记录
+
+最终复跑曾发现随机 UUID 数字段被旧 payment.card 规则误报，导致 scripted
+评测间歇失败（10 次复跑中 7 次含失败）。已增加完整 UUID 识别，仅对银行卡
+数字规则排除整个 UUID token，其余秘密规则仍检查原文；保留原卡号匹配规则，
+避免中文/Markdown 邻接的漏检。新增 12 项安全回归覆盖 UUID、中文卡号、
+空格/连字符卡号、UUID 与真实卡号混合、UUID-shaped API key。最终重复结果单独保存，
+不将早期偶然通过当作稳定性证据。

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "common-memory-core",
+  "version": "0.2.0",
+  "license": "MIT",
+  "description": "User-owned Markdown memory with durable maintenance, Pi integration and local stdio MCP access.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mr-remon219/common-memory.git"
+  },
+  "homepage": "https://github.com/Mr-remon219/common-memory#readme",
+  "bugs": {
+    "url": "https://github.com/Mr-remon219/common-memory/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "memory",
+    "agent-memory"
+  ],
+  "bin": {
+    "common-memory": "./dist/cli/main.js"
+  },
+  "engines": {
+    "node": "24.x"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    ".env.sample",
+    "README.md",
+    "docs",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./dist/pi-extension/index.js"
+    ]
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "npm run typecheck && node scripts/check-boundaries.mjs",
+    "test": "vitest run",
+    "test:fixtures": "vitest run tests/v2",
+    "test:recovery": "vitest run tests/v2",
+    "test:consumer": "node scripts/consumer-smoke.mjs",
+    "test:published": "node scripts/consumer-smoke.mjs --registry-version 0.2.0",
+    "test:remote-contract": "vitest run tests/memory-manager",
+    "prepack": "npm run build",
+    "release:check": "node scripts/check-release.mjs",
+    "prepublishOnly": "npm run release:check && npm run verify && npm run test:consumer",
+    "verify": "node scripts/verify.mjs",
+    "evaluate:v2": "npm run build && node scripts/evaluate-v2.mjs",
+    "ablate:v2": "npm run build && node scripts/ablate-v2.mjs --output=docs/v2-ablation-results.json",
+    "benchmark:v2": "npm run build && node scripts/benchmark-v2.mjs",
+    "test:provider-smoke": "node --test tests/scripts/provider-smoke.integration.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "@modelcontextprotocol/server": "2.0.0",
+    "ajv": "^8.17.1",
+    "typebox": "1.3.7",
+    "undici": "8.10.2",
+    "zod": "4.3.6"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.4"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}