@dsh-cc/compaction-pinning 0.9.5 → 0.9.6-rc.1

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/README.i18n.yaml CHANGED
@@ -2,5 +2,5 @@
2
2
  # side as of the last confirmed-consistent state. Both languages carry equal authority;
3
3
  # after editing either side, bring the other along and re-record with:
4
4
  # pnpm check:readme --write
5
- README.md: aed6e624d1787c8c094e3095e0881ad69adfe95a
6
- README.zh.md: 8c6ceee5e44c57cbce0487f7f7f4a3eac385e174
5
+ README.md: a6b35f5f2c3ae90342c9bc0e1813b57660f75591
6
+ README.zh.md: b011aec35fe8a7bc42e3c17319b974603cb2b998
package/README.md CHANGED
@@ -7,7 +7,7 @@ Governed-message pinning across compaction. Behavioral-governance messages — t
7
7
  ## How it works
8
8
 
9
9
  - **Capture:** one observation-only `session/event` listener. For every `user/message` whose `source.kind` is one of the configured kinds, the WHOLE message object (content blocks plus source metadata, by reference, never cloned or destructured) is stored in that session's ring together with its seq and timestamp. The ring is FIFO-bounded by entry count and by estimated message bytes; the oldest entries are evicted first.
10
- - **Restore:** the compaction's summary names the shadowed seqs; the pins among them are re-appended verbatim after the checkpoint commits, oldest first, each as its own append so source boundaries survive. Restored messages re-enter the ring naturally under a new seq, which makes re-shadowing self-healing rather than a loop.
10
+ - **Restore:** the compaction's summary names the shadowed seqs, and that summary is provisional evidence only, because the engine appends `compaction/summary` before the checkpoint commit. A per-`compactionId` restore schedule therefore has to settle before it drains, and only settled pins are re-appended verbatim, oldest first, each as its own append so source boundaries survive. Rule (a): a successful `compaction/end` for that id proves the checkpoint committed, so the pins drain in the same pass. Rule (b): with no `compaction/end` of any kind, a schedule becomes eligible once it has aged at least one turn and the checkpoint commit was actually witnessed by the replacement `user/message` citing the summary's seq; that witness gate keeps a summary-only phantom from being restored over a live original. An `end` carrying `error` cancels the schedule outright, and a schedule that never becomes eligible is garbage-collected after two turns. Restored messages re-enter the ring naturally under a new seq, which makes re-shadowing self-healing rather than a loop.
11
11
  - **Bounded:** two caps (entries and bytes) and a fixed kind list keep capture cheap and the restoration batch small. Nothing is appended from inside the event observer — restores drain from the agent's pre-step seam.
12
12
  - **Defaults:** on, with the two durable behavioral-constraint kinds. Turning the feature off stops capture and restore; a ring is never retroactively rebuilt.
13
13
 
@@ -31,6 +31,11 @@ Hot-read: the value is re-read on every message, so a settings edit applies imme
31
31
  }
32
32
  ```
33
33
 
34
+ ## API
35
+
36
+ - `createScheduleStore()` returns the per-session restore-schedule store (`arm`, `get`, `succeed`, `cancel`, `commit`, `isEligible`, `eligible`, `pending`, `drop`, `gcDead`, `clear`). `raiseTurn(state, turn)` raises the monotonic rule-(b) turn clock, and `RULE_B_TURNS` / `SCHEDULE_GC_TURNS` export the two windows.
37
+ - `getPinningHealth()` / `bumpPinningHealth(key, by?)` / `resetPinningHealth()` expose process-wide counters `captured`, `restored`, `evicted`, `dropped`. They exist for tests: no user-facing notice, no ledger, no durable record.
38
+
34
39
  ## Known gaps
35
40
 
36
41
  - **Resume-generation gap.** The ring is process memory. A compaction in a session that was resumed by this process can shadow pins this process never captured; the producer re-fires over time (turn-rule reminders especially), but the interim is unprotected. Reconstructing immediately-present pins from the session's own projection at mount is a possible later version, deliberately out of scope here.
package/README.zh.md CHANGED
@@ -7,7 +7,7 @@
7
7
  ## 工作方式
8
8
 
9
9
  - **捕获:** 一个纯观察的 `session/event` 监听器。对每条 `source.kind` 属于已配置种类的 `user/message`,把**整个**消息对象(内容块加 source 元数据,按引用保留,绝不克隆或解构)连同其 seq 与时间戳存入该会话的环形缓冲。缓冲按条目数和估算字节数做 FIFO 上限;最旧的条目先被淘汰。
10
- - **恢复:** 压缩的摘要会列出被遮蔽的 seq;其中的钉扎消息在检查点提交后按原 seq 升序逐字重新追加,每条各自追加一次,以便来源边界保留。恢复后的消息以新的 seq 自然重新进入环形缓冲,因此再次被遮蔽会自愈而不是死循环。
10
+ - **恢复:** 压缩的摘要会列出被遮蔽的 seq,而该摘要只是暂定证据,因为引擎在检查点提交之前就已追加 `compaction/summary`。因此每个 `compactionId` 对应一份恢复计划,必须先完成结算才能排空,只有已结算的钉扎消息才会按原 seq 升序逐字重新追加,每条各自追加一次,以便来源边界保留。规则 (a):该 id 收到一次成功的 `compaction/end` 即证明检查点已提交,钉扎消息在同一次排空中恢复。规则 (b):完全没有见到任何 `compaction/end` 时,计划需同时满足已老化至少一个回合、且检查点提交确实被目睹(引用摘要 seq 的替换 `user/message`)才具备资格;这道目睹门槛避免把只有摘要的幻影覆盖到仍然存活的原文之上。携带 `error` 的 `end` 直接取消该计划,始终无法具备资格的计划在两个回合后被垃圾回收。恢复后的消息以新的 seq 自然重新进入环形缓冲,因此再次被遮蔽会自愈而不是死循环。
11
11
  - **有界:** 两个上限(条目数与字节数)加一份固定种类表,让捕获开销低、恢复批次小。事件观察回调内绝不追加消息——恢复从代理的 pre-step 接缝排空。
12
12
  - **默认:** 开启,种类为两种持久的行为约束来源。关闭该功能会停止捕获与恢复;环形缓冲从不被回溯重建。
13
13
 
@@ -31,6 +31,11 @@
31
31
  }
32
32
  ```
33
33
 
34
+ ## API
35
+
36
+ - `createScheduleStore()` 返回每会话的恢复计划存储(`arm`、`get`、`succeed`、`cancel`、`commit`、`isEligible`、`eligible`、`pending`、`drop`、`gcDead`、`clear`)。`raiseTurn(state, turn)` 单调抬高规则 (b) 的回合时钟,`RULE_B_TURNS` / `SCHEDULE_GC_TURNS` 导出两个窗口。
37
+ - `getPinningHealth()` / `bumpPinningHealth(key, by?)` / `resetPinningHealth()` 暴露进程级计数器 `captured`、`restored`、`evicted`、`dropped`。它们只服务于测试:没有面向用户的通告、没有账本、没有持久记录。
38
+
34
39
  ## 已知缺口
35
40
 
36
41
  - **恢复代际缺口(resume-generation gap)。** 环形缓冲是进程内存。本进程恢复的会话里发生的压缩,可能遮蔽本进程从未捕获的钉扎消息;生产者会随时间重新触发(尤其回合规则提醒),但中间这段没有保护。挂载时从会话自身的投影重建当下已存在的钉扎消息,是后续版本的可行方向,此处刻意不做。
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@dsh-cc/compaction-pinning",
3
3
  "description": "Compaction governed-message pinning: capture governance-class user messages verbatim in a bounded per-session ring so summarization compaction cannot erase their durable effect mid-session; user-layer-only settings, default ON",
4
- "version": "0.9.5",
4
+ "version": "0.9.6-rc.1",
5
5
  "repository": {
6
6
  "type": "git",
7
7
  "url": "git+https://github.com/dsh-cc/dsh-cc.git",
@@ -25,10 +25,10 @@
25
25
  "@deepseek-ai/dsh-llm": ">=0.2.2-rc.1",
26
26
  "@deepseek-ai/dsh-session": ">=0.2.2-rc.1",
27
27
  "@deepseek-ai/schemastery": "^3.18.1",
28
- "@dsh-cc/settings": "^0.9.5"
28
+ "@dsh-cc/settings": "^0.9.6-rc.1"
29
29
  },
30
30
  "dependencies": {
31
- "@dsh-cc/settings": "^0.9.5"
31
+ "@dsh-cc/settings": "^0.9.6-rc.1"
32
32
  },
33
33
  "devDependencies": {
34
34
  "@deepseek-ai/cordis": "link:../../../../deepseek-harness/vendor/cordis",
@@ -42,8 +42,8 @@
42
42
  "@deepseek-ai/dsh-token-meter": "link:../../../../deepseek-harness/packages/llm/token-meter",
43
43
  "@deepseek-ai/schemastery": "link:../../../../deepseek-harness/vendor/schemastery",
44
44
  "vitest": "^4.1.8",
45
- "@dsh-cc/agent-loop-mock": "^0.1.0",
46
- "@dsh-cc/settings": "^0.9.5"
45
+ "@dsh-cc/settings": "^0.9.6-rc.1",
46
+ "@dsh-cc/agent-loop-mock": "^0.1.0"
47
47
  },
48
48
  "publishConfig": {
49
49
  "access": "public"