dsh-knit 0.21.0 → 0.22.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +124 -0
- package/README.md +3 -2
- package/package.json +2 -2
- package/src/host/index-store.js +479 -0
- package/src/host/index.js +796 -68
- package/src/host/links.js +23 -10
- package/src/host/relations.js +12 -2
- package/test/fixture.mjs +50 -0
- package/test/index-incremental.test.mjs +504 -0
- package/test/index-store.test.mjs +340 -0
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,125 @@
|
|
|
3
3
|
本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
|
|
4
4
|
版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
|
|
5
5
|
|
|
6
|
+
## [0.22.0] - 2026-10-10
|
|
7
|
+
|
|
8
|
+
> **Incremental Context Index** —— 让**未变化的文件在进程重启后复用已有索引**,变化的文件
|
|
9
|
+
> **只重建它自己**,索引坏了 / 存储不在 / 版本不对时**明着退回全量扫描**,而不是悄悄交付
|
|
10
|
+
> 一份陈旧的 Context Pack。索引**只在那条检索真的用不着正文时才被查**(修法 ②)——
|
|
11
|
+
> 要正文的路径(相关检索)走的就是 v0.21 那条路,一个字都不多付。
|
|
12
|
+
> 旧格式的**遗留记录会被有界地清掉**(清理补丁),不会永远留在盘上白付装载成本。
|
|
13
|
+
> 这是**内部能力,不是用户可见功能**:UI 一行没改,没有索引面板、没有命中率、没有 Epoch。
|
|
14
|
+
> 硬约束照旧:**零模型 / 零网络 / 零新依赖 / 无构建步骤**(`node:crypto` 是内置模块)。
|
|
15
|
+
|
|
16
|
+
### 一句话结论(先审计,再动手)
|
|
17
|
+
|
|
18
|
+
Phase 0 审计推翻了这个版本号原本的卖点:**「未变化的文件不重读」v0.20/v0.21 早就做到了**
|
|
19
|
+
(进程内 `cache` 按 `mtime + size` 命中,暖扫的 `readFile` 恒为 0)。真正的缺口只有四个:
|
|
20
|
+
**跨进程重启要全量重读**、**`mtime + size` 是唯一的一致性证据**、**没有对账**、**没有降级叙事**。
|
|
21
|
+
所以这一版只补这四件事 —— 稳定模块(`relevance.js` 的 BM25 语义、`control.js`、关系投影)
|
|
22
|
+
一行未改,见 `01_ Knit PRD/Knit-v0.22-Phase0-审计.md`。
|
|
23
|
+
|
|
24
|
+
### 变化
|
|
25
|
+
|
|
26
|
+
- **新增 `src/host/index-store.js`**:索引的持久层,走 DSH 自己的 `ctx.storage` KV facet
|
|
27
|
+
(与 `control.js` 同一个后端、**各开各的单元** `knit_index`)。
|
|
28
|
+
· 布局 `per-record`(**不是** `single`):改一个文件只碰一个键,而不是重写整份索引;
|
|
29
|
+
· 键 = `rootHashOf(root) + base64url(rel)`(`per-record` 的键必须是 `[a-zA-Z0-9_-]+`);
|
|
30
|
+
**root 必须进键** —— 只用 `rel` 的话两个项目里的同名文件会抢同一个键互相覆盖(写测试时
|
|
31
|
+
抓到的真实故障);值里也带 `root`,读的一侧再过滤一遍;
|
|
32
|
+
· 记录 = `{root, rel, mtimeMs, size, headHash, title, summary, refs}`,
|
|
33
|
+
**`body` 永远不进索引**(正文一旦持久化,「同 mtime 同 size 的编辑」就会被静默交付成旧内容);
|
|
34
|
+
`refs` 是**抽取后的**引用 / 导入列表(`{md, any, imports}`,`md` 与 `any` 分开存 ——
|
|
35
|
+
`extractRefsWithLines()` 有每篇 500 条的截断,用一套近似另一套会在超限文件上改变目标集合,
|
|
36
|
+
破坏第 7 条验收)。**原文首部不进索引**:它只为关系投影服务,而关系投影要的只是这份列表;
|
|
37
|
+
· `INDEX_VERSION = 3` + `compatibleVersions: [1, 2]`:v1 记录缺 `headHash`、v2 记录存的是
|
|
38
|
+
`head` 而不是 `refs`,两者都读得进来、都过不了 `refsShapeOk()` 这一关,
|
|
39
|
+
于是当「没有可用记录」处理、下一轮重建 —— 迁移不需要任何专用代码;
|
|
40
|
+
· `canonicalRoot()` 在**进出两侧**都做 `realpathSync`:`/var/...` 与 `/private/var/...`
|
|
41
|
+
是同一个目录的两个字符串,只靠调用方守纪律就会「索引时灵时不灵且不报错」(也真的踩到了);
|
|
42
|
+
· 任何失败(没有存储 / unit 开不起来 / `malformed-medium` / 版本不符)⇒ 空 Map + 一个
|
|
43
|
+
`reason`,**绝不抛进检索路径**;`persisted` 只在读成功或写成功后才是 true。
|
|
44
|
+
- **`src/host/index.js` 的取数路径重写**:`readDoc()` / `readCode()` 这对「先查缓存再决定读不读」
|
|
45
|
+
的包装函数被删掉(留两份判定只会漂移),唯一读取路径是 `readDocFromDisk()` / `readCodeFromDisk()`。
|
|
46
|
+
每条候选现在走三选一:① 进程内 `cache` 命中(**单独计数**,这是 v0.20 就有的能力,不许算进
|
|
47
|
+
这一版的成绩)→ ② 索引记录可复用(`mtime + size` 当快速筛子,`headHash` 是可复核的第二证据)
|
|
48
|
+
→ ③ 整读 + 重解析 + 重算指纹。复用出来的条目 `body === ''`、`bodyReady: false`。
|
|
49
|
+
- **有界对账(没有 watcher)**:每轮抽验 `INDEX_VERIFY_PER_PASS = 8` 条复用项,按**游标轮转**
|
|
50
|
+
取样(不是每轮都核同一批),逐条读**头部**算指纹比对;对不上就重读该文件、就地改正并写回。
|
|
51
|
+
这是「`mtime`/`size` 不得作为可靠内容一致性的唯一证据」的落实方式 —— 不是每次扫都重读一遍
|
|
52
|
+
(那等于没省),而是**读到的那一份永远能被指纹复核**。删除项也按同一个游标分批清理,
|
|
53
|
+
否则「1000 个文件全删掉」会变成一次 O(N) 写风暴。
|
|
54
|
+
- **修法 ②(2026-10-10):索引只在那条路真的用不着正文时才查。** `collectDocs()` 现在接受
|
|
55
|
+
`{index: false}`;相关检索那条路(`scan()` 里 `mode === 'relevance'`)显式传它,于是
|
|
56
|
+
**不装载、不对账、不写回**索引 —— 因为 BM25 的 `df` / `avgdl` 都是正文的函数,那些记录
|
|
57
|
+
反正会被立刻整读补回正文,唯一净效果是**多付一次索引装载**(每条记录一个文件 open + read
|
|
58
|
+
+ `JSON.parse`,实测 600 条约 60–75 ms,且这个成本与记录里的载荷大小**几乎无关**)。
|
|
59
|
+
低层 API 不替调用方做这个决定:不传 `options.index` 仍然查索引(工具、测试、基准的语料阶段
|
|
60
|
+
就是这样)。这一轮没查索引时读数记 `skipped: true` / `reason: 'index-skipped'`,
|
|
61
|
+
与「这个进程没有存储」的 `no-storage` **分开报**,否则两种 0 混成一个数就没法排查了。
|
|
62
|
+
- **目录级 memo**:同一轮扫描里目录的 `readdir` 结果按**目录自身 mtime** 复用;
|
|
63
|
+
新增/删除/重命名会更新父目录 mtime,而**改动已有文件不会**(APFS 实测),
|
|
64
|
+
所以每个候选文件仍然**逐条重新 `stat`** —— memo 只省 `readdir`,不省变更检测。
|
|
65
|
+
- **`hydrateBodies()` 必须跑在 `rankByRelevance()` 之前**:复用路径上没有正文,而 BM25 的
|
|
66
|
+
`avgdl` 与 `df` 都是正文的函数;顺序错了,「索引开 / 关」两份 Context Pack 就对不上。
|
|
67
|
+
这是正确性问题,不是优化顺序。
|
|
68
|
+
- **实测(`node tools/index-benchmark.mjs`,合成语料、mtime 固定)**:语料阶段(`collectDocs`)
|
|
69
|
+
的整读次数在**重启后**从 `100 / 500 / 600 / 700 / 700`(N=100…10000)降到 **8** 条
|
|
70
|
+
(= 抽验预算,与规模无关),读入量从 `25 / 126 / 154 / 183 / 183 KiB` 降到 **1.9 KiB**;
|
|
71
|
+
改一个文件只重读 **1** 篇;新增/删除/重命名后索引项同步增删且不返回过期结果;
|
|
72
|
+
「索引开 / 关」两份 Context Pack 的指纹逐字相同(`parity-on = parity-off`)。
|
|
73
|
+
三次重复的中位数与计数型读数逐次一致(`c.read` 冷 `100/500/600/700/700`、暖恒 `8`、
|
|
74
|
+
`touch` 恒 `9`;parity 指纹 **12/12 次**完全相同),不是「碰巧一致」。
|
|
75
|
+
- **最终同口径实测(12 次重复取中位数;N=1000、每篇另加 8 KiB 填充 ⇒ 600 个文件 / 13.45 MiB,平均 22.4 KiB/篇)**:
|
|
76
|
+
两条检索序要分开说,因为它们**走的路不一样**。
|
|
77
|
+
· **相关序(面板默认,要正文)—— 生产形状下没有回归**:`--shape scan`(一次检索 = 新进程
|
|
78
|
+
首次取数)warm **259.4 ms** vs `nostorage`(等价 v0.21)**242.6 ms**,而计数**逐项相同**
|
|
79
|
+
(`readFiles` 600 / 读入 13453 KiB / `readdir` 21 / 复用 0)—— 因为这条路上索引**根本没被查**
|
|
80
|
+
(`index-skipped`)。差距在噪声内,且路径就是同一条。
|
|
81
|
+
· **时间序 / 无关键词(不吃正文)—— 这才是这一版真正省下来的地方**:同形状 warm **106.0 ms**
|
|
82
|
+
vs `nostorage` **216.2 ms**(**2.04×**),整读 **8** 次 vs **600** 次、读入 **179 KiB** vs
|
|
83
|
+
**13453 KiB**(**约 75×** 更少),复用 600 条、其中 8 条按指纹抽验过。
|
|
84
|
+
⚠️ 报告里必须写明的一件事:**旧的历史形状(`--shape collect`,先单独跑一次 `collectDocs`
|
|
85
|
+
再跑检索)会给出误导性的读数** —— 那个形状下同一份语料被取两遍,于是 warm 的账会拆成
|
|
86
|
+
「语料阶段 93.2ms(省了)+ 检索 219.3ms(补正文)」而 `nostorage` 是「214.7 + 47.6」,
|
|
87
|
+
两列相加看起来仍慢 1.19×。那**不是生产行为**:真实的一轮相关检索没有那个预热的
|
|
88
|
+
`collectDocs`。1.31× 那条旧结论来自这个形状,修法 ② 之后它已经不成立。
|
|
89
|
+
取舍、复现命令与逐条读数见 `01_ Knit PRD/Knit-v0.22-实现与基准报告.md`,
|
|
90
|
+
- **清理补丁(2026-10-10,真机复验之后;裁决 F)**:真机 `~/.dsh/storages/knit_index/files`
|
|
91
|
+
里查出 **164 条记录,键全部是旧格式**(`base64url(rel)`,没有 root 指纹),其中 **152 条是存
|
|
92
|
+
16 KiB 原文首部的 v2 记录**(共 **1.7 MiB**,平均 10.7 KiB/条)。它们对**任何**工作区都不可用
|
|
93
|
+
(`refsShapeOk()` 判不过 ⇒ 每轮重建),但本版的写入路径只写
|
|
94
|
+
`rootHashOf(root) + base64url(rel)` ⇒ **永远覆盖不到这些键**。`compatibleVersions: [1, 2]`
|
|
95
|
+
本意是「读得进来、下一轮重建」,代价却是**永久残留**:`loadAll()` 每次都要为它们付钱,
|
|
96
|
+
而装载成本正比于**记录条数**(600 条小记录 60 ms ≈ 600 条肥记录 75 ms)。修法:
|
|
97
|
+
`read()` 用 `keyFitsRecord(key, row)`(键必须是 `recordKey()` 的形状**且** 16 位之后解回来
|
|
98
|
+
**逐字等于这条记录自己的 `rel`** —— 只查 hex 前缀不够,`relToKey()` 的字符集本身就含 `a-f`/`0-9`)
|
|
99
|
+
把不合规的键收进清理队列,`write()` 在**本轮本来就要写盘时**顺手删,上界
|
|
100
|
+
**`INDEX_CLEAN_PER_WRITE = 32` 条/次**(与对账的 `INDEX_VERIFY_PER_PASS = 8` 同一条纪律:
|
|
101
|
+
不许为了维护索引把一次检索拖长)。删除幂等 ⇒ 不需要事务,中途失败下一轮接着删;真实工作区
|
|
102
|
+
164 条 ⇒ **6 轮写盘内清完**。同源的键一律放行(包括**别的 root 的合法记录**),实测真机 164 条里
|
|
103
|
+
同源 **0** 条 ⇒ 清理对象与活记录零重叠。**证伪**:把 `unit.deleteRecord()` 那行换成 `void key`
|
|
104
|
+
⇒ 新增的 2 项恰好变红(`pass 14 / fail 2`),恢复后 16/16。
|
|
105
|
+
⚠️ 一处如实记录的小浪费:其中 12 条键不合规而内容仍可用(`refs` 在、mtime+size+headHash 相符),
|
|
106
|
+
它们在**同一轮里先被复用、再被删掉**,下一轮多付 12 次读盘重建 —— 正确性不受影响(内容可重新推导),
|
|
107
|
+
一次性、只发生在迁移期。
|
|
108
|
+
决策见 `Knit-决策记录.md` 的裁决 A / A′ / D / E / F。
|
|
109
|
+
- **测试**:`npm test` **697 → 728 项**,新增 `test/index-store.test.mjs`(持久层 16 项:键/指纹/
|
|
110
|
+
隔离/降级/**清理与上界**)与 `test/index-incremental.test.mjs`(端到端:§6 七条验收逐条可证伪,
|
|
111
|
+
含两条**证伪用例** —— ① 把抽验预算设成 0,同 `mtime` 同 `size` 的改写必然漏掉;
|
|
112
|
+
② 相关序必须 `skipped: true` 且不装载索引,时间序必须真的复用)。
|
|
113
|
+
两个文件都已挂进 `package.json` 的 `scripts.test` 显式清单。
|
|
114
|
+
|
|
115
|
+
### 刻意不做
|
|
116
|
+
|
|
117
|
+
- **不做索引状态 Dashboard**、不新增任何 UI 区块、不改列表与工具栏;
|
|
118
|
+
- 不把内部索引 revision 暴露成第二种用户可见的 Epoch;
|
|
119
|
+
- **不引入 `fs.watch`**:`recursive` 跨平台语义不一致、丢事件是必然(`git checkout` / 分支切换 /
|
|
120
|
+
批量操作 / 外部编辑),它只能加速不能当权威 —— 权威是每轮的有界对账。这条明确记为「未做」;
|
|
121
|
+
- 不引入 SQLite / 常驻服务 / 新依赖,不建立云端索引,不改变 Context Pack 排名算法与关系语义;
|
|
122
|
+
- 不为「让索引看起来有用」而在要正文的路径上查索引:那一条路按需查询,宁可这一次完全不碰它;
|
|
123
|
+
- **未发布**:`package.json` 版本已到 `0.22.0`,但**没有 `npm publish`、没有打 tag**。
|
|
124
|
+
|
|
6
125
|
## [0.21.0] - 2026-10-08
|
|
7
126
|
|
|
8
127
|
> **Relations & Context Control** —— **原 v0.21 与 原 v0.22 合并成一个版本**(用户 2026-10-08 拍板:
|
|
@@ -121,6 +240,11 @@
|
|
|
121
240
|
- `src/host/tool.js` 与面板**同源**:同一条任务下,面板每项关系的前 2 条与工具侧逐字相同
|
|
122
241
|
(`test/tool.test.mjs` 的跨面守卫,把工具里的截断拿掉即变红)。
|
|
123
242
|
|
|
243
|
+
> ✅ **2026-10-09 已发布**:轻量 tag `v0.21.0` = 发布提交 `af7a9a39995d080381217e7f84121f17e15445d5`;npm `latest = 0.21.0`、`gitHead` = 同一个提交、共 **18 个**版本;registry 真包 **56 文件 / 637 155 B tarball / 1 870 085 B 解包 / shasum `a536984cfd908c8f1a3b117f1e4c0062e1d619a6`**;OIDC 可信发布 + provenance(`/slsa.dev/provenance/v1`,workflow run `37875191973`,19 s);GitHub Release 正文取自本节(前置「更新后必须重启 DSH」与「新增写动作 `POST /knit/api/control`」两条),`publishedAt 2026-10-09T02:39:05Z`。
|
|
244
|
+
> **解包净室自测 697/0**(v0.20.0 那条 `tools/` 包装缺陷不复现;判据 = 真 `npm pack` 产物解包后跑 `npm test`)。
|
|
245
|
+
>
|
|
246
|
+
> ⚠️ **这一行不在已发布的 tarball 里** —— 它在 publish 成功之后才写进来(下次 `npm view` 看到的是这份仓库里的文件)。
|
|
247
|
+
|
|
124
248
|
## [0.20.0] - 2026-10-07
|
|
125
249
|
|
|
126
250
|
> **Deep Context Retrieval**。核心体验从「任务 → 相关文件」升级为
|
package/README.md
CHANGED
|
@@ -739,7 +739,7 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
|
|
|
739
739
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
740
740
|
cd dsh-knit
|
|
741
741
|
|
|
742
|
-
npm test #
|
|
742
|
+
npm test # 728 项,零依赖,不需要先 npm install
|
|
743
743
|
node tools/clean-room-test.mjs # 发版前闸门:npm pack → 解包 → 在解包目录里再跑一遍测试
|
|
744
744
|
```
|
|
745
745
|
|
|
@@ -765,10 +765,11 @@ knit/
|
|
|
765
765
|
│ ├── host/passage.js # 内容片段层:切分 / 片段打分 / 行号映射(纯函数,零 I/O)
|
|
766
766
|
│ ├── host/context.js # 上下文装配:Context Pack 三层(纯函数,零 I/O)
|
|
767
767
|
│ ├── host/control.js # 固定 / 排除:纯逻辑 + 可选 ctx.storage 持久化
|
|
768
|
+
│ ├── host/index-store.js # 增量索引持久层:per-record KV + 头部指纹 + 降级 + 遗留键清理(v0.22)
|
|
768
769
|
│ ├── host/feedback.js # 使用反馈:读时归因 / Context Epoch / Delta(纯逻辑,只读事件流)
|
|
769
770
|
│ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
|
|
770
771
|
│ └── client/client.js # 双宿主注册 + 面板 UI
|
|
771
|
-
└── test/ #
|
|
772
|
+
└── test/ # 728 项测试
|
|
772
773
|
├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线 + Deep Context 四指标
|
|
773
774
|
└── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
|
|
774
775
|
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-knit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.22.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Task-aware workspace context retrieval and lifecycle tracking for DeepSeek Harness. Finds the documents, source files and media most relevant to the current conversation, organises them into a Context Pack (primary / supporting / related) in the sidebar with inline preview, and tracks which of them were actually read and what changed afterwards. Zero model calls, zero network, nothing leaves the machine.",
|
|
6
6
|
"main": "./src/host/index.js",
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
],
|
|
25
25
|
"scripts": {
|
|
26
26
|
"agents:budget": "node tools/agents-budget.mjs",
|
|
27
|
-
"test": "node --test test/host.test.mjs test/host-http.test.mjs test/client.test.mjs test/tier1.test.mjs test/entry.test.mjs test/i18n.test.mjs test/icon.test.mjs test/path.test.mjs test/peek.test.mjs test/eval.test.mjs test/tool.test.mjs test/label.test.mjs test/links.test.mjs test/relations.test.mjs test/control.test.mjs test/security.test.mjs test/context.test.mjs test/context-eval.test.mjs test/feedback.test.mjs test/context-delta.test.mjs test/context-feedback-eval.test.mjs test/context-effectiveness.test.mjs test/document-lifecycle.test.mjs test/classification.test.mjs test/code-context.test.mjs test/deep-context.test.mjs test/deep-eval.test.mjs test/deep-scale.test.mjs"
|
|
27
|
+
"test": "node --test test/host.test.mjs test/host-http.test.mjs test/client.test.mjs test/tier1.test.mjs test/entry.test.mjs test/i18n.test.mjs test/icon.test.mjs test/path.test.mjs test/peek.test.mjs test/eval.test.mjs test/tool.test.mjs test/label.test.mjs test/links.test.mjs test/relations.test.mjs test/control.test.mjs test/security.test.mjs test/context.test.mjs test/context-eval.test.mjs test/feedback.test.mjs test/context-delta.test.mjs test/context-feedback-eval.test.mjs test/context-effectiveness.test.mjs test/document-lifecycle.test.mjs test/classification.test.mjs test/code-context.test.mjs test/deep-context.test.mjs test/deep-eval.test.mjs test/deep-scale.test.mjs test/index-store.test.mjs test/index-incremental.test.mjs"
|
|
28
28
|
},
|
|
29
29
|
"dsh": {
|
|
30
30
|
"bundle": {
|
|
@@ -0,0 +1,479 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* v0.22 · 增量上下文索引的**持久层**。
|
|
3
|
+
*
|
|
4
|
+
* 这个模块只做一件事:把「一个工作区里每个候选文件是谁、什么时候变的、头部指纹是什么」
|
|
5
|
+
* 存进 DSH 自己的存储(`ctx.storage` 的 KV facet),让**进程重启后**不必重读、重解析
|
|
6
|
+
* 未变化的文件。**它不参与排序,不缓存正文。**
|
|
7
|
+
*
|
|
8
|
+
* ── 三条硬约束(来源:`Knit-v0.22-Phase0-审计.md` §4 §5)────────────────
|
|
9
|
+
*
|
|
10
|
+
* 1. **不存正文,也不存原文首部**(裁决 A + 修法 ①,见决策记录)。
|
|
11
|
+
* 索引值 = `{root, rel, mtimeMs, size, headHash, title, summary, refs}`:
|
|
12
|
+
* · `body`(整篇正文)**永远不进索引** —— 正文永远来自当次读取 ⇒ 不可能出现
|
|
13
|
+
* 「持久化的正文与磁盘漂移」这类静默错误;
|
|
14
|
+
* · `head`(16KB 原文首部)**也不进索引**,改存 `refs` = **抽取后的**引用/导入列表
|
|
15
|
+
* (Markdown 存 `extractRefsWithLines()` 的 `{raw, line}`:`{md, any}` 两套,
|
|
16
|
+
* 默认口径与 `anyExt` 各一套,分别喂给引用图与关系投影;代码存 `importsOf()` 的
|
|
17
|
+
* `{spec, line}`)。理由:两个下游消费者(`relations.js` / `buildLinkGraph()`)
|
|
18
|
+
* **只要抽取结果,不要原文** —— 存 16KB 原文会让索引体积 ≈ 源码体积,
|
|
19
|
+
* 而 `KvUnit` 只有 `loadAll()`(没有按需取单条),于是每一次要用索引的扫描
|
|
20
|
+
* 都要为「加载一份和源码一样大的 JSON」付钱(实测让默认的相关检索在重启后
|
|
21
|
+
* 比 v0.21 慢 1.31×)。抽取结果小一个量级,这个代价随之消失。
|
|
22
|
+
*
|
|
23
|
+
* ⚠️ `{md, any}` 两套都存、不合并成一套,是**语义精确性**的要求:引用图用的是
|
|
24
|
+
* `extractRefs()` 的默认口径(只认 `.md` 目标),关系投影用 `anyExt: true`
|
|
25
|
+
* (还要认 md→代码)。两者各有自己的 `MAX_REFS_PER_DOC = 500` 截断点,
|
|
26
|
+
* 用一套去近似另一套会在「引用数超过上限」的文件上产生不同的目标集合 ——
|
|
27
|
+
* 那正好是 §6 第 7 条(索引开/关必须一致)会被破坏的地方。
|
|
28
|
+
*
|
|
29
|
+
* 2. **按 canonical workspace root 隔离**。`rel` 只在工作区内唯一 ⇒ 不同工作区的同名
|
|
30
|
+
* 相对路径必须能区分。做法:**键 = `rootHashOf(root) + base64url(rel)`,值里也带
|
|
31
|
+
* `root`**,读的一侧再按 `value.root === root` 过滤一遍。root 进键是必需的
|
|
32
|
+
* (只用 rel 会让两个项目里的同名文件抢同一个键、互相覆盖,见 `recordKey()`),
|
|
33
|
+
* 过滤是第二道 —— 键告诉「这是哪个项目」,值里的 root 则是可读的自证。
|
|
34
|
+
*
|
|
35
|
+
* **归一放在这里,不指望调用方守纪律**:`canonicalRoot()` 每次进出都做一次
|
|
36
|
+
* `realpathSync`(根不存在时兜底原值)。理由是实测过的真实故障:macOS 的
|
|
37
|
+
* `/var/folders/...` 与 `/private/var/folders/...` 是同一个目录的两个字符串,
|
|
38
|
+
* `scan()` 走 `hostPathOf()` 拿到后者、而工具/测试直接用前者调 `collectDocs()`
|
|
39
|
+
* ⇒ 同一个键被两个 `root` 值轮流覆盖,`value.root === root` 过滤随最后一次写入
|
|
40
|
+
* 摇摆,**索引时灵时不灵且完全不报错**。隔离是 §5② 的硬要求,不能只靠调用方。
|
|
41
|
+
*
|
|
42
|
+
* 3. **任何失败都不许抛进检索路径**。存储不存在、unit 版本不匹配、介质损坏、权限错误
|
|
43
|
+
* ⇒ `persisted: false` + 一个 `reason`,读返回空 Map,写返回 false。调用方据此退回
|
|
44
|
+
* 现有的全量扫描路径 —— 那是**正常降级**,不是异常分支。
|
|
45
|
+
*
|
|
46
|
+
* 4. **遗留记录确实会被清掉**(清理补丁,v0.22 实施期)。`compatibleVersions` 让老记录
|
|
47
|
+
* 「读得进来」,代价是它们在存储里**永久残留**:新版本的写入路径只会写带 root 指纹的
|
|
48
|
+
* 新键,**永远覆盖不到** `base64url(rel)` 这种旧键。真机上实测到过 164 条这样的残留
|
|
49
|
+
* (v0.21/v0.22 开发期写入的,对任何工作区都已不可用,却让每次 `loadAll()` 都多付一遍
|
|
50
|
+
* 钱 —— 600 条小记录约 60 ms,正比于**条数**而不是字节数)。
|
|
51
|
+
* 做法:`read()` 把「键与记录不同源」(`keyFitsRecord()`)的键收进清理队列,
|
|
52
|
+
* `write()` 在**本轮本来就要写盘时**顺手删掉,每次最多 `INDEX_CLEAN_PER_WRITE = 32` 条。
|
|
53
|
+
* 删除幂等,所以不需要事务:中途失败,下一轮接着删。
|
|
54
|
+
*
|
|
55
|
+
* ── 为什么 `per-record` 而不是 `single` ────────────────────────────────
|
|
56
|
+
*
|
|
57
|
+
* `single` 布局整单元一个文档:改一个文件就要重写整份索引(1000 文件 ≈ 数百 KB),
|
|
58
|
+
* 与提示词 §4「已变化文件仅重建对应文件索引」直接冲突。`per-record` 下增删改各只碰
|
|
59
|
+
* 一个文件,正好对上索引的访问模式。代价是键必须满足 `[a-zA-Z0-9_-]+` ⇒ base64url。
|
|
60
|
+
*
|
|
61
|
+
* @module index-store
|
|
62
|
+
*/
|
|
63
|
+
|
|
64
|
+
import { createHash } from 'node:crypto'
|
|
65
|
+
import { realpathSync } from 'node:fs'
|
|
66
|
+
|
|
67
|
+
/** 存储单元名。必须匹配 `UNIT_NAME_RE = /^[a-z][a-z0-9_]*$/`(`dsh-storage` 的真实正则)。 */
|
|
68
|
+
export const INDEX_UNIT = 'knit_index'
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* 索引 schema 版本。
|
|
72
|
+
*
|
|
73
|
+
* v1 → v2:v1 的记录没有 `headHash`(只有 `mtimeMs + size` 这一条一致性证据),
|
|
74
|
+
* 而 v0.22 的立论之一就是「不许只靠 mtime+size」。
|
|
75
|
+
* v2 → v3(修法 ①):v2 的记录存的是 16KB 原文首部 `head`,v3 改存抽取后的 `refs`。
|
|
76
|
+
*
|
|
77
|
+
* 声明的 `compatibleVersions` 让老记录**读得进来**,但缺 `headHash`(v1)或
|
|
78
|
+
* 缺 `refs`(v2)的记录一律视为**未验证**、下一轮直接重建 —— 迁移因此不需要任何
|
|
79
|
+
* 专用代码,也不需要一次性重写整份索引(`recordUsable()` 是唯一的判定处)。
|
|
80
|
+
*/
|
|
81
|
+
export const INDEX_VERSION = 3
|
|
82
|
+
|
|
83
|
+
/** 表名(单表:一个工作区的全部文件记录)。 */
|
|
84
|
+
export const INDEX_TABLES = ['files']
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* 一次写盘最多顺手清掉多少条「键与记录不同源」的遗留记录(清理补丁)。
|
|
88
|
+
*
|
|
89
|
+
* 为什么必须有上界:清理是**维护索引**的动作,不是这次检索结果的一部分 ——
|
|
90
|
+
* 与对账(每轮扫描最多抽验 `INDEX_VERIFY_PER_PASS = 8` 条)同一条纪律,
|
|
91
|
+
* 不许为了它把一次检索拖长。32 条/次在真机的 164 条残留上 6 轮内清完,
|
|
92
|
+
* 稳态下这个数永远是 0。
|
|
93
|
+
*/
|
|
94
|
+
export const INDEX_CLEAN_PER_WRITE = 32
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* 读一个文件头部多少个字节做指纹。
|
|
98
|
+
*
|
|
99
|
+
* 与 `index.js` 的 `HEAD_BYTES = 16 * 1024` 同口径 —— 指纹要覆盖的正是**参与解析与
|
|
100
|
+
* 引用关系抽取的那段字节**。指纹只对**已经读进内存**的头部做哈希,**绝不额外读盘**。
|
|
101
|
+
*/
|
|
102
|
+
export const INDEX_HEAD_BYTES = 16 * 1024
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* 相对路径 → 存储键。
|
|
106
|
+
*
|
|
107
|
+
* `per-record` 布局把键当成路径片段,必须匹配 `[a-zA-Z0-9_-]+`;`rel` 里有 `/`、`.`、
|
|
108
|
+
* 空格、中文,全都不合法。`base64url` 的输出恰好落在 `[A-Za-z0-9_-]` 内。
|
|
109
|
+
*
|
|
110
|
+
* @param {string} rel - 工作区相对路径(`/` 分隔)
|
|
111
|
+
* @returns {string} 存储键
|
|
112
|
+
*/
|
|
113
|
+
export function relToKey(rel) {
|
|
114
|
+
return Buffer.from(String(rel), 'utf8').toString('base64url')
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* 存储键 → 相对路径(诊断与测试用;生产路径不信这个,信值里的 `rel`)。
|
|
119
|
+
* @param {string} key - 存储键
|
|
120
|
+
* @returns {string} 相对路径,解不开返回空串
|
|
121
|
+
*/
|
|
122
|
+
export function keyToRel(key) {
|
|
123
|
+
try {
|
|
124
|
+
return Buffer.from(String(key).slice(ROOT_HASH_CHARS), 'base64url').toString('utf8')
|
|
125
|
+
} catch {
|
|
126
|
+
return ''
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/** root 指纹占多少个 hex 字符(定长 ⇒ 键可无歧义切分)。 */
|
|
131
|
+
export const ROOT_HASH_CHARS = 16
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* 工作区根的短指纹。
|
|
135
|
+
* @param {string} root - canonical 工作区根
|
|
136
|
+
* @returns {string} 16 个 hex 字符
|
|
137
|
+
*/
|
|
138
|
+
export function rootHashOf(root) {
|
|
139
|
+
return createHash('sha256').update(String(root), 'utf8').digest('hex').slice(0, ROOT_HASH_CHARS)
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* `(工作区根, 相对路径)` → 存储键。
|
|
144
|
+
*
|
|
145
|
+
* ⚠️ **键里必须带 root 指纹,不能只用 `base64url(rel)`**。这是写测试时抓到的一个真
|
|
146
|
+
* 故障:只用 rel 的话,两个工作区里同名的 `a.md` 会**共用一个键**,谁后写谁留下
|
|
147
|
+
* —— 读的一侧虽然靠 `value.root` 过滤守住了「不返回别的项目的内容」,但先前那个
|
|
148
|
+
* 工作区的记录被**覆盖**掉了,于是每在两个项目间切一次就整份重建一次,而且
|
|
149
|
+
* `put`/`del` 的差量会互相打架。带上 root 指纹后两个工作区的记录**共存**,
|
|
150
|
+
* 与 `control.js` 用 `root + NUL + rel` 当键是同一种语义。
|
|
151
|
+
*
|
|
152
|
+
* 拼接不用分隔符:`base64url` 的字符集含 `-` 和 `_`,任何分隔符都可能出现在后半段
|
|
153
|
+
* 里。指纹**定长 16 hex**,于是 `keyToRel()` 直接 `slice(16)` 即可无歧义还原。
|
|
154
|
+
*
|
|
155
|
+
* @param {string} root - canonical 工作区根
|
|
156
|
+
* @param {string} rel - 工作区相对路径(`/` 分隔)
|
|
157
|
+
* @returns {string} 存储键
|
|
158
|
+
*/
|
|
159
|
+
export function recordKey(root, rel) {
|
|
160
|
+
return rootHashOf(root) + relToKey(rel)
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
/**
|
|
164
|
+
* 键与记录是否**同源** —— 即这个键是不是 `recordKey()` 写出来的。
|
|
165
|
+
*
|
|
166
|
+
* ⚠️ **不能只看前 16 个字符是不是 hex**:`relToKey()` 的输出字符集
|
|
167
|
+
* (`[A-Za-z0-9_-]`)本身就包含 `a-f`/`0-9`,旧键完全可能恰好以 16 个 hex 字符开头,
|
|
168
|
+
* 只查前缀会把它误判成新格式、于是永不清理。这里再加一条「16 位之后解回来必须
|
|
169
|
+
* 逐字等于记录自己的 `rel`」—— 对新格式恒真,对旧键实际不可能。
|
|
170
|
+
*
|
|
171
|
+
* 存在的理由见模块头注释第 4 条:老记录读得进来是**故意的**,但它们必须能被清掉。
|
|
172
|
+
*
|
|
173
|
+
* @param {string} key - 存储里取出的键
|
|
174
|
+
* @param {Record<string, unknown>} row - 同一个键下的值
|
|
175
|
+
* @returns {boolean} 键与记录是否同源
|
|
176
|
+
*/
|
|
177
|
+
function keyFitsRecord(key, row) {
|
|
178
|
+
if (typeof key !== 'string' || key.length <= ROOT_HASH_CHARS) return false
|
|
179
|
+
for (let i = 0; i < ROOT_HASH_CHARS; i += 1) {
|
|
180
|
+
const c = key.charCodeAt(i)
|
|
181
|
+
const isDigit = c >= 48 && c <= 57
|
|
182
|
+
const isHex = c >= 97 && c <= 102
|
|
183
|
+
if (!isDigit && !isHex) return false
|
|
184
|
+
}
|
|
185
|
+
if (typeof row.rel !== 'string' || row.rel === '') return false
|
|
186
|
+
return keyToRel(key) === row.rel
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/**
|
|
190
|
+
* 对一段**已在内存里**的文本算内容指纹。
|
|
191
|
+
*
|
|
192
|
+
* ⚠️ 它的作用不是密码学安全,而是「内容变了但 mtime/size 没变」时的第二道证据
|
|
193
|
+
* (提示词 §4:mtime/size 不得作为可靠内容一致性的**唯一**证据)。取 sha256 的前
|
|
194
|
+
* 8 字节(16 hex 字符)足够区分工作区内的文件内容,且让每条记录小到可以忽略。
|
|
195
|
+
*
|
|
196
|
+
* @param {string} text - 文件头部文本
|
|
197
|
+
* @returns {string} 16 个 hex 字符
|
|
198
|
+
*/
|
|
199
|
+
export function headHashOf(text) {
|
|
200
|
+
return createHash('sha256').update(String(text), 'utf8').digest('hex').slice(0, 16)
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* 一条索引记录是否**可用于跳过读盘**。
|
|
205
|
+
*
|
|
206
|
+
* 判定只有一条:元信息齐 + 有指纹。缺任何一项 ⇒ `false` ⇒ 调用方老老实实读盘重建。
|
|
207
|
+
* 这是「证据到之前不说自己知道」在索引层的落实。
|
|
208
|
+
*
|
|
209
|
+
* @param {unknown} record - 存储里取出的值
|
|
210
|
+
* @param {{mtimeMs:number, size:number, headHash:string}} observed - 本次 stat 实测值
|
|
211
|
+
* @returns {boolean} 是否可复用
|
|
212
|
+
*/
|
|
213
|
+
export function recordMatches(record, observed) {
|
|
214
|
+
if (!record || typeof record !== 'object') return false
|
|
215
|
+
const row = /** @type {Record<string, unknown>} */ (record)
|
|
216
|
+
if (typeof row.headHash !== 'string' || row.headHash.length === 0) return false
|
|
217
|
+
if (typeof row.mtimeMs !== 'number' || typeof row.size !== 'number') return false
|
|
218
|
+
if (row.mtimeMs !== observed.mtimeMs || row.size !== observed.size) return false
|
|
219
|
+
return row.headHash === observed.headHash
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* 一条记录的 `refs` 字段是否是**可用的抽取结果**。
|
|
224
|
+
*
|
|
225
|
+
* 形状(`refsForHead()` 产出):Markdown = `{md: [{raw, line}], any: [{raw, line}]}`;
|
|
226
|
+
* 代码 = `{imports: [{spec, line}]}`。**空数组是合法的**(这个文件确实一条引用都没有);
|
|
227
|
+
* 字段**缺失**则不可用 —— 「抽出来是空的」与「旧版记录还没重算」必须能区分,
|
|
228
|
+
* 否则 v2 记录会被当成「没有引用」而不是「要重建」,重启后关系会静默少掉。
|
|
229
|
+
*
|
|
230
|
+
* @param {unknown} refs - 记录上的 `refs`
|
|
231
|
+
* @returns {boolean} 是否可用
|
|
232
|
+
*/
|
|
233
|
+
export function refsShapeOk(refs) {
|
|
234
|
+
if (!refs || typeof refs !== 'object' || Array.isArray(refs)) return false
|
|
235
|
+
const row = /** @type {Record<string, unknown>} */ (refs)
|
|
236
|
+
const keys = ['md', 'any', 'imports'].filter((k) => row[k] !== undefined)
|
|
237
|
+
if (keys.length === 0) return false
|
|
238
|
+
for (const k of keys) {
|
|
239
|
+
const list = row[k]
|
|
240
|
+
if (!Array.isArray(list)) return false
|
|
241
|
+
for (const hit of list) {
|
|
242
|
+
if (!hit || typeof hit !== 'object') return false
|
|
243
|
+
const item = /** @type {Record<string, unknown>} */ (hit)
|
|
244
|
+
const raw = typeof item.raw === 'string' ? item.raw : item.spec
|
|
245
|
+
if (typeof raw !== 'string' || raw === '') return false
|
|
246
|
+
}
|
|
247
|
+
}
|
|
248
|
+
return true
|
|
249
|
+
}
|
|
250
|
+
|
|
251
|
+
/**
|
|
252
|
+
* 把工作区根归一成 canonical 形态(展开符号链接)。
|
|
253
|
+
*
|
|
254
|
+
* 见模块头注释第 2 条:隔离必须由这一层自己保证,不能只靠调用方传对路径。
|
|
255
|
+
* 路径不存在时兜底返回原值 —— 索引允许为空,不值得为归一化抛错。
|
|
256
|
+
*
|
|
257
|
+
* @param {string} path - 工作区根
|
|
258
|
+
* @returns {string} canonical 路径
|
|
259
|
+
*/
|
|
260
|
+
export function canonicalRoot(path) {
|
|
261
|
+
try {
|
|
262
|
+
return realpathSync(path)
|
|
263
|
+
} catch {
|
|
264
|
+
// 路径不存在 / 无权限 ⇒ 保持原字符串。索引本身允许为空,不值得为归一化抛错。
|
|
265
|
+
return String(path)
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
/**
|
|
270
|
+
* 创建索引存储。
|
|
271
|
+
*
|
|
272
|
+
* 形状与 `src/host/control.js:188` 的 `createControlStore()` 一致,理由一样:Knit 的宿主
|
|
273
|
+
* 半边不许因为「存储没接上」而抛错。`persisted` **只在读成功或写成功后**才是 true。
|
|
274
|
+
*
|
|
275
|
+
* @param {{backend?: object|null}} [options] - `backend.kv.open(descriptor)` 是唯一依赖
|
|
276
|
+
* @returns {{persisted:boolean, reason:string, cleaned:number, read:Function, write:Function, flush:Function}}
|
|
277
|
+
*/
|
|
278
|
+
export function createIndexStore(options = {}) {
|
|
279
|
+
// ⚠️ 显式传 `null` 时默认参数不生效(`apply()` 启动那一刻就是 `null`),
|
|
280
|
+
// 所以这里再收一道 —— 「没有存储」是**正常路径**,不是 TypeError。
|
|
281
|
+
const backend = options && options.backend
|
|
282
|
+
const kv = backend && typeof backend === 'object' ? backend.kv : null
|
|
283
|
+
if (!kv || typeof kv.open !== 'function') {
|
|
284
|
+
return {
|
|
285
|
+
persisted: false,
|
|
286
|
+
reason: 'no-storage',
|
|
287
|
+
cleaned: 0,
|
|
288
|
+
read: async () => new Map(),
|
|
289
|
+
write: async () => false,
|
|
290
|
+
flush: async () => false,
|
|
291
|
+
}
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
let opening = null
|
|
295
|
+
let writes = Promise.resolve()
|
|
296
|
+
/** 每个 root 上一次读/写后的键集合 —— 写的时候只写差量。 */
|
|
297
|
+
const lastWritten = new Map()
|
|
298
|
+
/** 上次 `read()` 看到的「键与记录不同源」的键(清理补丁),等下一次写盘顺手清掉。 */
|
|
299
|
+
let staleKeys = new Set()
|
|
300
|
+
|
|
301
|
+
const openUnit = () => {
|
|
302
|
+
if (!opening) {
|
|
303
|
+
opening = Promise.resolve()
|
|
304
|
+
.then(() => kv.open({
|
|
305
|
+
name: INDEX_UNIT,
|
|
306
|
+
version: INDEX_VERSION,
|
|
307
|
+
tables: INDEX_TABLES,
|
|
308
|
+
hasGlobal: false,
|
|
309
|
+
// 见模块头注释「为什么 per-record」。
|
|
310
|
+
layout: 'per-record',
|
|
311
|
+
// v1(缺 headHash)/ v2(存的是 head 而不是 refs)记录都读得进来,
|
|
312
|
+
// 但过不了 `recordUsable()` ⇒ 视为未验证,下一轮重建。
|
|
313
|
+
compatibleVersions: [1, 2],
|
|
314
|
+
}))
|
|
315
|
+
.then((unit) => unit)
|
|
316
|
+
.catch(() => null) // version-mismatch / malformed-medium / 不支持 ⇒ 当空
|
|
317
|
+
}
|
|
318
|
+
return opening
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
const store = {
|
|
322
|
+
persisted: false,
|
|
323
|
+
reason: 'unproven',
|
|
324
|
+
/**
|
|
325
|
+
* 累计清掉了多少条「键与记录不同源」的遗留记录(清理补丁,**累计**值)。
|
|
326
|
+
*
|
|
327
|
+
* 刻意不塞进 `indexStatsFor()`:`write()` 是 fire-and-forget,那一刻计数可能
|
|
328
|
+
* 还没落地,报进统计就会是「有时对、有时落后一轮」的读数。清理的证据看这里
|
|
329
|
+
* (测试断言)与真机上的记录条数下降。
|
|
330
|
+
*/
|
|
331
|
+
cleaned: 0,
|
|
332
|
+
/**
|
|
333
|
+
* 读一个工作区的索引。任何失败 ⇒ 空 Map(调用方退回全量扫描),绝不抛。
|
|
334
|
+
* @param {string} root - canonical 工作区根
|
|
335
|
+
* @returns {Promise<Map<string, object>>} rel → 记录
|
|
336
|
+
*/
|
|
337
|
+
read: async (rawRoot) => {
|
|
338
|
+
const root = canonicalRoot(rawRoot)
|
|
339
|
+
try {
|
|
340
|
+
const unit = await openUnit()
|
|
341
|
+
if (!unit) {
|
|
342
|
+
store.persisted = false
|
|
343
|
+
store.reason = 'open-failed'
|
|
344
|
+
return new Map()
|
|
345
|
+
}
|
|
346
|
+
const all = await unit.loadAll()
|
|
347
|
+
const tables = (all && all.tables) || {}
|
|
348
|
+
const rows = (tables[INDEX_TABLES[0]] && typeof tables[INDEX_TABLES[0]] === 'object')
|
|
349
|
+
? tables[INDEX_TABLES[0]]
|
|
350
|
+
: {}
|
|
351
|
+
const out = new Map()
|
|
352
|
+
const keys = new Set()
|
|
353
|
+
const stale = new Set()
|
|
354
|
+
for (const [key, value] of Object.entries(rows)) {
|
|
355
|
+
if (!value || typeof value !== 'object') continue
|
|
356
|
+
const row = /** @type {Record<string, unknown>} */ (value)
|
|
357
|
+
if (typeof row.rel !== 'string' || row.rel.length === 0) continue
|
|
358
|
+
// 清理补丁:键不是 `recordKey()` 的形状 ⇒ 旧格式(或损坏键)的残留。
|
|
359
|
+
// 它们对**任何**工作区都不可用(本版本的写入路径永远覆盖不到它们),
|
|
360
|
+
// 所以判定放在 root 过滤**之前**:它们本来就不属于任何当前工作区。
|
|
361
|
+
const fits = keyFitsRecord(key, row)
|
|
362
|
+
if (!fits) stale.add(key)
|
|
363
|
+
// 工作区隔离:同一张表里装着所有工作区,靠值里的 root 过滤。
|
|
364
|
+
if (row.root !== root) continue
|
|
365
|
+
// ⚠️ **只有同源的键**才算「本工作区已落盘的键」。旧格式键永远不会由本版本写出,
|
|
366
|
+
// 把它们算进来会让下面清理时的 `keys.has()` 守卫永远拦住自己(写测试时踩到过)。
|
|
367
|
+
if (fits) keys.add(key)
|
|
368
|
+
out.set(row.rel, row)
|
|
369
|
+
}
|
|
370
|
+
lastWritten.set(root, keys)
|
|
371
|
+
staleKeys = stale
|
|
372
|
+
store.persisted = true
|
|
373
|
+
store.reason = 'ok'
|
|
374
|
+
return out
|
|
375
|
+
} catch {
|
|
376
|
+
store.persisted = false
|
|
377
|
+
store.reason = 'read-failed'
|
|
378
|
+
return new Map()
|
|
379
|
+
}
|
|
380
|
+
},
|
|
381
|
+
/**
|
|
382
|
+
* 写差量:只新增 / 覆盖 / 删除这一轮真正变化的记录。
|
|
383
|
+
*
|
|
384
|
+
* fire-and-forget(与 `control.js` 同策略):写失败就记一笔并保持内存态,
|
|
385
|
+
* 不重试风暴;下一轮扫描会再试一次。
|
|
386
|
+
*
|
|
387
|
+
* @param {string} root - canonical 工作区根
|
|
388
|
+
* @param {{put?: Array<object>, del?: string[]}} diff - `put` 带 `rel` 的记录数组,`del` 是 rel 数组
|
|
389
|
+
* @returns {Promise<boolean>} 是否落盘成功
|
|
390
|
+
*/
|
|
391
|
+
write: async (rawRoot, diff) => {
|
|
392
|
+
const root = canonicalRoot(rawRoot)
|
|
393
|
+
const puts = (diff && Array.isArray(diff.put)) ? diff.put : []
|
|
394
|
+
const dels = (diff && Array.isArray(diff.del)) ? diff.del : []
|
|
395
|
+
writes = writes.then(async () => {
|
|
396
|
+
const unit = await openUnit()
|
|
397
|
+
if (!unit) {
|
|
398
|
+
store.persisted = false
|
|
399
|
+
store.reason = 'open-failed'
|
|
400
|
+
return false
|
|
401
|
+
}
|
|
402
|
+
const keys = lastWritten.get(root) || new Set()
|
|
403
|
+
for (const record of puts) {
|
|
404
|
+
if (!record || typeof record.rel !== 'string' || !record.rel) continue
|
|
405
|
+
const key = recordKey(root, record.rel)
|
|
406
|
+
await unit.putRecord(INDEX_TABLES[0], key, { ...record, root })
|
|
407
|
+
keys.add(key)
|
|
408
|
+
}
|
|
409
|
+
for (const rel of dels) {
|
|
410
|
+
const key = recordKey(root, rel)
|
|
411
|
+
// 幂等:删一个不存在的键是 no-op,所以这里不必先查存在性。
|
|
412
|
+
await unit.deleteRecord(INDEX_TABLES[0], key)
|
|
413
|
+
keys.delete(key)
|
|
414
|
+
}
|
|
415
|
+
lastWritten.set(root, keys)
|
|
416
|
+
// 清理补丁:顺手清掉上次 `read()` 记下的遗留键。只在「本轮本来就要写盘」时执行
|
|
417
|
+
// (不为清理单独触发一次写),每次有上界,删不存在的键是 no-op(所以幂等)。
|
|
418
|
+
let cleaned = 0
|
|
419
|
+
for (const key of staleKeys) {
|
|
420
|
+
if (cleaned >= INDEX_CLEAN_PER_WRITE) break
|
|
421
|
+
// 防御的是「读与写之间这条键被本工作区重新合法写下」这个窗口;不可用的残留键
|
|
422
|
+
// 按定义进不了 `keys`(`keyFitsRecord()` 只放行同源的键)。
|
|
423
|
+
if (keys.has(key)) continue
|
|
424
|
+
await unit.deleteRecord(INDEX_TABLES[0], key)
|
|
425
|
+
staleKeys.delete(key)
|
|
426
|
+
cleaned += 1
|
|
427
|
+
}
|
|
428
|
+
if (cleaned > 0) store.cleaned += cleaned
|
|
429
|
+
store.persisted = true
|
|
430
|
+
store.reason = 'ok'
|
|
431
|
+
return true
|
|
432
|
+
}).catch(() => {
|
|
433
|
+
store.persisted = false
|
|
434
|
+
store.reason = 'write-failed'
|
|
435
|
+
return false
|
|
436
|
+
})
|
|
437
|
+
return writes
|
|
438
|
+
},
|
|
439
|
+
/**
|
|
440
|
+
* 等写链排空(测试与「退出前收尾」用)。生产中不 await。
|
|
441
|
+
* @returns {Promise<boolean>} 排空后的结果
|
|
442
|
+
*/
|
|
443
|
+
flush: async () => {
|
|
444
|
+
try {
|
|
445
|
+
await writes
|
|
446
|
+
return true
|
|
447
|
+
} catch {
|
|
448
|
+
return false
|
|
449
|
+
}
|
|
450
|
+
},
|
|
451
|
+
}
|
|
452
|
+
return store
|
|
453
|
+
}
|
|
454
|
+
|
|
455
|
+
/**
|
|
456
|
+
* DSH 会在**同一个进程里反复加载插件**,而 kv 单元只允许一个活句柄
|
|
457
|
+
* (同名 unit 未关闭再 open 会 reject)。每个加载各建一个 store 的话,只有第一次
|
|
458
|
+
* 开得成,而模块级变量会被最后一次加载覆盖 ⇒ **活跃实例恰恰是打不开的那个**
|
|
459
|
+
* (v0.21 在 `control.js` 上真的踩到过这条,见 `AGENTS.md` 与 `knit/CHANGELOG.md`)。
|
|
460
|
+
*
|
|
461
|
+
* 修法与 `sharedControlRegistry()` 同源:把登记表挂在**后端对象自己**的
|
|
462
|
+
* `Symbol.for('dsh-knit.index')` 上 —— 后端是 DSH 传进来的同一个对象,
|
|
463
|
+
* 因此跨加载次数稳定共享。
|
|
464
|
+
*
|
|
465
|
+
* @param {object|null} backend - `backend.kv.open` 可用的后端
|
|
466
|
+
* @returns {object|null} 共享的 index store(后端不可用时为 null)
|
|
467
|
+
*/
|
|
468
|
+
export function sharedIndexStore(backend) {
|
|
469
|
+
if (!backend || typeof backend !== 'object') return null
|
|
470
|
+
const key = Symbol.for('dsh-knit.index')
|
|
471
|
+
if (backend[key]) return backend[key]
|
|
472
|
+
const store = createIndexStore({ backend })
|
|
473
|
+
try {
|
|
474
|
+
Object.defineProperty(backend, key, { value: store, enumerable: false, configurable: true })
|
|
475
|
+
} catch {
|
|
476
|
+
return store
|
|
477
|
+
}
|
|
478
|
+
return store
|
|
479
|
+
}
|