dsh-jev-prune 0.1.0

package/assets/two-layers.svg

@@ -0,0 +1,118 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="330" viewBox="0 0 1200 330" role="img" aria-label="The two layers: tool-result trimming keeps head/tail verbatim, receipt compaction replaces a spent read-only pair with a code-computed receipt">
+  <defs>
+    <linearGradient id="rule" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0" stop-color="#4CC9F0" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#F0A868" stop-opacity="0.55"/>
+    </linearGradient>
+  </defs>
+
+  <rect x="0" y="0" width="1200" height="330" rx="14" fill="#0B1220"/>
+  <rect x="0.5" y="0.5" width="1199" height="329" rx="13.5" fill="none" stroke="#1E2A38"/>
+  <rect x="28" y="0" width="300" height="3" rx="1.5" fill="url(#rule)"/>
+
+  <g font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, 'DejaVu Sans Mono', monospace">
+
+    <!-- 行标题 -->
+    <g font-size="14" fill="#7D8B9A" text-anchor="end">
+      <text x="176" y="60">surface</text>
+      <text x="176" y="148">after layer 1</text>
+      <text x="176" y="236">after layer 2</text>
+    </g>
+
+    <!-- 受保护的写类调用 -->
+    <text x="641" y="22" font-size="12" fill="#F0BE8A">write-type → never compacted</text>
+    <line x1="625" y1="27" x2="848" y2="27" stroke="#F0A868" stroke-opacity="0.45" stroke-dasharray="4 4"/>
+
+    <!-- 第一行：完整 surface -->
+    <g>
+      <rect x="192" y="32" width="86" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="235" y="59" font-size="15" fill="#B6C2CF" text-anchor="middle">user</text>
+
+      <rect x="285" y="32" width="118" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="344" y="59" font-size="15" fill="#B6C2CF" text-anchor="middle">call · read</text>
+
+      <rect x="410" y="32" width="208" height="44" rx="8" fill="#4CC9F0" fill-opacity="0.08" stroke="#4CC9F0" stroke-opacity="0.38"/>
+      <text x="514" y="59" font-size="15" fill="#9FDCF2" text-anchor="middle">16489 chars out</text>
+
+      <rect x="625" y="32" width="112" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="681" y="59" font-size="15" fill="#B6C2CF" text-anchor="middle">call · edit</text>
+
+      <rect x="744" y="32" width="104" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="796" y="59" font-size="15" fill="#B6C2CF" text-anchor="middle">applied</text>
+
+      <rect x="855" y="32" width="118" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="914" y="59" font-size="15" fill="#B6C2CF" text-anchor="middle">call · read</text>
+
+      <rect x="980" y="32" width="196" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="1078" y="59" font-size="15" fill="#B6C2CF" text-anchor="middle">3200 chars out</text>
+    </g>
+
+    <!-- 箭头 1 -->
+    <g stroke="#4CC9F0" stroke-opacity="0.75" stroke-width="1.6" fill="none">
+      <path d="M514 82 L514 106"/>
+      <path d="M509 101 L514 107 L519 101"/>
+    </g>
+    <text x="536" y="100" font-size="13" fill="#7FD9F5">layer 1 · result trimming — middle cut; head 600 / tail 200 kept verbatim</text>
+
+    <!-- 第二行：裁中间之后 -->
+    <g>
+      <rect x="192" y="120" width="86" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="235" y="147" font-size="15" fill="#B6C2CF" text-anchor="middle">user</text>
+
+      <rect x="285" y="120" width="118" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="344" y="147" font-size="15" fill="#B6C2CF" text-anchor="middle">call · read</text>
+
+      <g>
+        <rect x="410" y="120" width="208" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+        <rect x="472" y="124" width="84" height="36" rx="5" fill="#F0A868" fill-opacity="0.10" stroke="#F0A868" stroke-opacity="0.40" stroke-dasharray="4 3"/>
+        <line x1="472" y1="122" x2="472" y2="162" stroke="#5C6B7A" stroke-dasharray="3 3"/>
+        <line x1="556" y1="122" x2="556" y2="162" stroke="#5C6B7A" stroke-dasharray="3 3"/>
+        <text x="441" y="147" font-size="12" fill="#B6C2CF" text-anchor="middle">head</text>
+        <text x="514" y="147" font-size="12" fill="#F0BE8A" text-anchor="middle">trimmed</text>
+        <text x="587" y="147" font-size="12" fill="#B6C2CF" text-anchor="middle">tail</text>
+      </g>
+
+      <rect x="625" y="120" width="112" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="681" y="147" font-size="15" fill="#B6C2CF" text-anchor="middle">call · edit</text>
+
+      <rect x="744" y="120" width="104" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="796" y="147" font-size="15" fill="#B6C2CF" text-anchor="middle">applied</text>
+
+      <rect x="855" y="120" width="118" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="914" y="147" font-size="15" fill="#B6C2CF" text-anchor="middle">call · read</text>
+
+      <rect x="980" y="120" width="196" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="1078" y="147" font-size="15" fill="#B6C2CF" text-anchor="middle">3200 chars out</text>
+    </g>
+
+    <!-- 箭头 2 -->
+    <g stroke="#F0A868" stroke-opacity="0.75" stroke-width="1.6" fill="none">
+      <path d="M514 170 L514 194"/>
+      <path d="M509 189 L514 195 L519 189"/>
+    </g>
+    <text x="536" y="188" font-size="13" fill="#F0BE8A">layer 2 · receipt compaction — spent read-only pair replaced by a receipt</text>
+
+    <!-- 第三行：整对移出，换回执 -->
+    <g>
+      <rect x="192" y="208" width="86" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="235" y="235" font-size="15" fill="#B6C2CF" text-anchor="middle">user</text>
+
+      <rect x="285" y="208" width="233" height="44" rx="8" fill="#F0A868" fill-opacity="0.09" stroke="#F0A868" stroke-opacity="0.55" stroke-dasharray="6 4"/>
+      <text x="401" y="235" font-size="13" fill="#F0BE8A" text-anchor="middle">receipt · read → 16489 chars</text>
+
+      <rect x="525" y="208" width="112" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="581" y="235" font-size="15" fill="#B6C2CF" text-anchor="middle">call · edit</text>
+
+      <rect x="644" y="208" width="104" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="696" y="235" font-size="15" fill="#B6C2CF" text-anchor="middle">applied</text>
+
+      <rect x="755" y="208" width="118" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="814" y="235" font-size="15" fill="#B6C2CF" text-anchor="middle">call · read</text>
+
+      <rect x="880" y="208" width="196" height="44" rx="8" fill="#16212E" stroke="#24313F"/>
+      <text x="978" y="235" font-size="15" fill="#B6C2CF" text-anchor="middle">3200 chars out</text>
+    </g>
+
+    <text x="192" y="298" font-size="12" fill="#5C6B7A">every receipt line is computed by code — tool name, command, path, output characters, seq. No model inference.</text>
+  </g>
+</svg>

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: jev-prune
+      name: dsh-jev-prune

package/demo/README.md

@@ -0,0 +1,23 @@
+# Deterministic behavior demonstration
+
+The 24-second [GIF](../assets/demo.gif) presents captured outputs from the real plugin `apply()`, intercepted pruner, receipt injector, `jev_compact_now` and `jev_restore`. A simulated host and fixed judge scores make the run reproducible without credentials or remote inference. This is not a live DSH screen recording or a judge-quality benchmark.
+
+The runner deliberately uses `keepMode: 'absolute'`, `compactMode: 'absolute'`, `compactThreshold: 0.2`, a lowered 1,000-character minimum and zero recent-node protection to isolate these behaviors. Automatic compaction is off until the manual tool is invoked. These are demonstration settings, not production defaults or configuration recommendations.
+
+1. Inspect three long read-only tool outputs.
+2. Trim two low-scored outputs; assert the high-scored output is unchanged.
+3. Invoke receipt compaction; assert the protected output remains on the surface.
+4. Retrieve a region checkpoint; assert archived text is returned without altering the surface.
+
+```bash
+npm ci
+node demo/run.mjs
+python -m pip install Pillow==10.2.0
+python demo/render.py
+```
+
+The runner exits non-zero on an assertion failure, and generates [JSON evidence](../assets/demo.json) plus an [asciinema v2 recording](../assets/demo.cast). Replay the latter with `asciinema play assets/demo.cast`. GIF scene timing is six seconds per stage; runtime output is captured by the runner, not fabricated by the renderer. Long/Unicode output is retained in JSON and cast; the GIF uses a compact ASCII presentation.
+
+Recovery here means read-only retrieval from a region summary checkpoint. Current retrieval caps each event at 4,000 UTF-16 units, does not reinsert events into the surface and cannot directly resolve layer-1 or mixed-batch replacement IDs. This demo does not exercise concurrent compaction, goal changes or live judge failures. See [review findings](../docs/review-2026-10-05.md).
+
+`fixtures.mjs` is a snapshot of the smoke-test host helpers. When event shapes change, update both fixtures and verify against a live host before claiming new compatibility.

package/demo/fixtures.mjs

@@ -0,0 +1,301 @@
+// Simulated DSH fixtures derived from smoke_apply.mjs; no live API calls.
+function makeSession(plan) {
+  const events = new Map()
+  let nextSeq = 1
+  const add = (type, data) => {
+    const seq = nextSeq++
+    events.set(seq, { seq, type, data })
+    return seq
+  }
+  const addStep = (tool, args, text) => {
+    const callId = `c${nextSeq + 1}`
+    const head = add('assistant/message', {
+      message: { content: [{ type: 'text', text: '看一下。' }, { type: 'tool-call', id: callId, name: tool, arguments: args }] },
+    })
+    const result = add('tool/result', {
+      message: { source: { callId }, content: [{ type: 'tool-result', content: [{ type: 'text', text }] }] },
+    })
+    return { head, result, tool }
+  }
+
+  add('user/message', { content: [{ type: 'text', text: '排查河牌底池计算，先摸结构。' }], source: { kind: 'user' } })
+  // 三步都必须在默认只读白名单内（read/grep/glob）——默认配置下 shell 工具进不了候选
+  const effectivePlan = plan ?? [
+    { tool: 'Read', args: { file_path: 'server/src/game/river.ts' }, chars: 6000 },
+    { tool: 'Grep', args: { pattern: 'basePot', path: 'server/src' }, chars: 4000 },
+    { tool: 'Glob', args: { pattern: '*.ts', path: 'server/src' }, chars: 6000 },
+  ]
+  const steps = []
+  for (const item of effectivePlan) {
+    if (item.interleave) {
+      // 插一条不含 tool-call 的 assistant 文本，把前后两组只读步骤**切成两段**，
+      // 这样 maxCompactionsPerPass > 1 才有第二个可压区间
+      add('assistant/message', { message: { content: [{ type: 'text', text: item.interleave }] } })
+    }
+    const fill = item.fill ?? 'a'
+    steps.push(addStep(item.tool, item.args, fill.repeat(item.chars)))
+  }
+  const step1 = steps[0]
+  const step2 = steps[1]
+  const step3 = steps[2]
+
+  const tail = add('assistant/message', { message: { content: [{ type: 'text', text: '继续。' }] } })
+
+  const appended = []
+  const session = {
+    seqs: { s1: step1.result, s2: step2.result, s3: step3.result },
+    steps: [step1, step2, step3],
+    tail,
+    appended,
+    // ⚠️ 刻意**不**提供 `.events`：实测活的 DSH 会话对象上 `session.events` 是 undefined，
+    // 只有 `eventAt(seq)` 与 `surface.nodes` 可用。假对象要复刻这个现实，
+    // 否则会掩盖"依赖 .events 的 bug"（那个 bug 让工具名索引在活宿主里建出 0 条）。
+    surface: { nodes: [...events.keys()] },
+    eventAt: (seq) => events.get(seq) ?? null,
+    deriveEventMessage: (event) => event.data.message,
+    append(type, data, options) {
+      const seq = nextSeq++
+      events.set(seq, { seq, type, data, ...options })
+      appended.push({ seq, type, data, options })
+      const op = options?.surfaceOp
+      if (op === 'append') {
+        session.surface.nodes.push(seq)
+      } else if (op?.op === 'replace') {
+        const start = session.surface.nodes.indexOf(op.startSeq)
+        const end = session.surface.nodes.indexOf(op.endSeq)
+        if (start < 0 || end < start) throw new Error(`fake surface replace: 非法区间 ${op.startSeq}-${op.endSeq}`)
+        session.surface.nodes.splice(start, end - start + 1, seq)
+      }
+      return { seq }
+    },
+  }
+  return session
+}
+
+/** 一个 assistant 消息并行发出 6 个 read，随后跟 6 个结果（issue #39 真实形态）。 */
+function makeBatchSession() {
+  const events = new Map()
+  let nextSeq = 1
+  const appended = []
+  const add = (type, data, options = {}) => {
+    const seq = nextSeq++
+    events.set(seq, { seq, type, data, ...options })
+    return seq
+  }
+  add('user/message', { content: [{ type: 'text', text: '批量读六个文件。' }], source: { kind: 'user' } })
+  const calls = Array.from({ length: 6 }, (_, i) => ({
+    type: 'tool-call', id: `batch-${i + 1}`, name: 'Read',
+    arguments: { file_path: `src/file-${i + 1}.js` },
+  }))
+  const head = add('assistant/message', {
+    message: { content: [{ type: 'text', text: '批量读取。' }, ...calls] },
+  })
+  const results = calls.map((call, i) => add('tool/result', {
+    message: {
+      source: { callId: call.id },
+      content: [{ type: 'tool-result', content: [{ type: 'text', text: String(i + 1).repeat(3000) }] }],
+    },
+  }))
+  add('assistant/message', { message: { content: [{ type: 'text', text: '继续。' }] } })
+  const session = {
+    seqs: Object.fromEntries(results.map((seq, i) => [`s${i + 1}`, seq])),
+    steps: [{ head, results }],
+    appended,
+    surface: { nodes: [...events.keys()] },
+    eventAt: (seq) => events.get(seq) ?? null,
+    deriveEventMessage: (event) => event.data.message,
+    append(type, data, options) {
+      const seq = add(type, data, options)
+      appended.push({ seq, type, data, options })
+      const op = options?.surfaceOp
+      if (op === 'append') session.surface.nodes.push(seq)
+      else if (op?.op === 'replace') {
+        const start = session.surface.nodes.indexOf(op.startSeq)
+        const end = session.surface.nodes.indexOf(op.endSeq)
+        if (start < 0 || end < start) throw new Error(`fake surface replace: 非法区间 ${op.startSeq}-${op.endSeq}`)
+        session.surface.nodes.splice(start, end - start + 1, seq)
+      }
+      return { seq }
+    },
+  }
+  return session
+}
+
+function makePruner() {
+  let pruneContentCalls = 0
+  return {
+    get pruneContentCalls() { return pruneContentCalls },
+    ctx: { tokenMeter: { estimateMessage: () => 123 } },
+    measureContent: (blocks) => blocks.reduce((n, b) => n + (b?.text ? Array.from(b.text).length : 0), 0),
+    // 与 DSH 同口径：超过阈值才裁；这里设成极高，模拟"体积启发式不动作"
+    pruneContent(blocks) {
+      pruneContentCalls += 1
+      const chars = blocks.reduce((n, b) => n + (b?.text ? Array.from(b.text).length : 0), 0)
+      if (chars <= 100000) return null
+      return blocks
+    },
+    /**
+     * 基线 pruneSession —— 忠实复刻 DSH 自带实现的循环与 append 协议。
+     * 插件会**接管**这个方法；这里的实现用来验证"接管前它是可用的"
+     * （插件的 guard 要求 pruner.pruneSession 是函数，否则拒绝接管）。
+     */
+    pruneSession(session) {
+      const pruned = []
+      let charsRemoved = 0
+      for (const seq of [...session.surface.nodes]) {
+        const event = session.eventAt(seq)
+        if (event?.type !== 'tool/result') continue
+        const original = session.deriveEventMessage(event)
+        const result = original?.content?.[0]
+        if (result == null) continue
+        const content = this.pruneContent(result.content)
+        if (content == null) continue
+        const before = this.measureContent(result.content)
+        const after = this.measureContent(content)
+        session.append('compaction/prune', {
+          shadowedRange: { start: seq, end: seq },
+          shadowedSeqs: [seq],
+          shadowedTokenCount: this.ctx.tokenMeter.estimateMessage(original),
+        })
+        session.append('tool/result',
+          { ...event.data, message: { ...original, content: [{ ...result, content }] } },
+          { surfaceOp: { op: 'replace', startSeq: seq, endSeq: seq }, sourceEventSeqs: [seq] })
+        pruned.push({ originalSeq: seq, charsBefore: before, charsAfter: after })
+        charsRemoved += before - after
+      }
+      return { pruned, charsRemoved }
+    },
+  }
+}
+
+/**
+ * 假 compaction 服务。行为对齐 DSH `BasicCompactionEngine` 的关键契约：
+ *   · `compactRegion` 内部通过 `this.summarize(...)` **动态派发**（所以我们猴补丁实例方法才有效）
+ *   · `summarize` 返回 `{ summary, provider, model }`，summary 是内容块数组
+ *   · 回执必须比被压缩的区间更小，否则后端会抛错（这里也照做）
+ */
+function makeCompaction(session) {
+  const calls = []
+  const summaries = []
+  return {
+    calls,
+    summaries,
+    async summarize(input, agent, signal) {
+      summaries.push({ input, injected: false })
+      return { summary: [{ type: 'text', text: '（基线模型摘要）' }], provider: 'fake', model: 'fake-model' }
+    },
+    async compactRegion(start, end, agent, signal) {
+      const nodes = session.surface.nodes
+      const startIdx = nodes.indexOf(start)
+      const endIdx = nodes.indexOf(end)
+      if (startIdx < 0 || endIdx < 0 || startIdx > endIdx) throw new Error(`compactRegion: 非法区间 ${start}-${end}`)
+      // 关键：模拟后端内部这一次动态派发 —— 猴补丁必须在这里被调用到
+      const summarized = await this.summarize({ messages: [] }, agent, signal)
+      const text = summarized.summary.map((b) => b.text ?? '').join('')
+      calls.push({ start, end, nodes: nodes.slice(startIdx, endIdx + 1), summary: text, provider: summarized.provider })
+      return {
+        compactionId: 'fake-compaction',
+        shadowedRange: { start, end },
+        shadowedSeqs: nodes.slice(startIdx, endIdx + 1),
+        shadowedTokenCount: 1234,
+        summary: summarized.summary,
+      }
+    },
+  }
+}
+
+function makeCtx({ pruner, session, compaction }) {
+  const handlers = new Map()
+  const registeredTools = []
+  const registeredCommands = []
+  const tokenMeter = {
+    measure: (s) => {
+      const nodes = (s?.surface?.nodes ?? []).map((seq) => {
+        const event = s.eventAt(seq)
+        const blocks = event?.data?.message?.content?.[0]?.content
+        const text = Array.isArray(blocks) ? blocks.map((b) => b.text ?? '').join('') : ''
+        return { seq, tokens: Math.ceil(text.length / 4), heuristicTokens: Math.ceil(text.length / 4) }
+      })
+      return { totalTokens: nodes.reduce((sum, n) => sum + n.tokens, 0), nodes }
+    },
+  }
+  const services = new Map([
+    ['toolResultPruner', pruner],
+    ['tokenMeter', tokenMeter],
+    ['compaction', compaction],
+    ['commands', { register: (c) => { registeredCommands.push(c); return c } }],
+  ])
+  const toolsService = { register: (t) => { registeredTools.push(t); return t } }
+  services.set('tools', toolsService)
+
+  return {
+    registeredTools,
+    registeredCommands,
+    handlers,
+    // Cordis 两种取法都要支持：ctx.get('x') 与 ctx.x
+    get: (n) => services.get(n) ?? null,
+    tools: toolsService,
+    commands: services.get('commands'),
+    tokenMeter,
+    compaction,
+    // 与 cordis 同构：同一事件可以有**多个**监听器，第三个参数（或 options.prepend）
+    // 决定插入队首还是队尾。此前这里只是 Map<event, fn> —— 第二个监听会**覆盖**第一个，
+    // 而且 prepend 被完全忽略。于是"判定钩子 prepend 到 compaction-basic 之前"这条
+    // 真实语义在测试里根本不存在（拆成两个监听后 30/72 项直接失败）。
+    // 假对象必须复刻宿主这个形状，否则测的是一套不存在的语义。
+    on: (evt, fn, options) => {
+      const prepend = typeof options === 'object' && options !== null
+        ? options.prepend === true
+        : options === true
+      const list = handlers.get(evt) ?? []
+      if (prepend) list.unshift(fn)
+      else list.push(fn)
+      handlers.set(evt, list)
+    },
+    /**
+     * 忠实复刻 cordis 的 waterfall（`agent/pre-step` 正是这类事件）：
+     * 最外层先跑，最后一个参数是内层 next；监听器**不调用 next() 即否决**后续链路
+     * （含宿主内建行为）。所以测试里不能"取一个 handler 直接调"——链上有几个监听、
+     * 谁先谁后，恰恰是这次要验证的东西。
+     */
+    waterfall: (name, ...args) => {
+      const cbs = [...(handlers.get(name) ?? [])]
+      const inner = args.pop()
+      const next = () => (cbs.shift() ?? inner)(...args)
+      args.push(next)
+      return next()
+    },
+    effect: (fn) => fn(),
+    logger: { info: () => {}, debug: () => {}, warn: () => {}, error: () => {} },
+  }
+}
+
+// ---------------------------------------------------------------- 假 Jev
+/**
+ * 只读概率、不看文本 —— 与真实现同语义。
+ * @param {Record<number, number>} resultPreset 结果可丢性 P(保留)
+ * @param {Record<number, number>} effectPreset 副作用 P(有副作用)
+ */
+function fakeJudge(resultPreset, effectPreset = {}) {
+  return {
+    ready: true,
+    requests: 0,
+    usage: { input_tokens: 0, output_tokens: 0 },
+    batch: (_state, questions) => [questions],
+    async ask(_state, questions) {
+      this.requests += 1
+      const out = {}
+      for (const id of Object.keys(questions)) {
+        const match = /^(result|effect)_s(\d+)$/.exec(id)
+        if (match == null) continue
+        const seq = Number(match[2])
+        const preset = match[1] === 'result' ? resultPreset : effectPreset
+        if (preset[seq] != null) out[id] = preset[seq]
+      }
+      return out
+    },
+  }
+}
+
+
+export { makeSession, makePruner, makeCtx, fakeJudge };

package/demo/render.py

@@ -0,0 +1,31 @@
+"""Render the captured demo output as an animated GIF. Requires Pillow."""
+import json
+import textwrap
+from pathlib import Path
+from PIL import Image, ImageDraw, ImageFont
+
+root = Path(__file__).resolve().parent.parent
+data = json.loads((root / 'assets/demo.json').read_text(encoding='utf-8'))
+font = ImageFont.load_default(size=19)
+title_font = ImageFont.load_default(size=26)
+frames = []
+for i, stage in enumerate(data['stages']):
+    image = Image.new('RGB', (1120, 640), '#0e1523')
+    draw = ImageDraw.Draw(image)
+    draw.rounded_rectangle((24, 24, 1096, 616), radius=18, fill='#182338', outline='#354764', width=2)
+    draw.text((48, 46), 'dsh-jev-prune | recorded deterministic run', font=title_font, fill='#f2f6ff')
+    draw.text((48, 90), 'REAL PLUGIN  /  SIMULATED HOST  /  FIXED JUDGE', font=font, fill='#8dc7ff')
+    draw.line((48, 130, 1070, 130), fill='#354764', width=2)
+    draw.text((48, 150), stage['title'], font=title_font, fill='#9eebc5')
+    y = 205
+    for line in stage['lines']:
+        # Render only ASCII in the GIF; full Unicode receipt stays in JSON/cast.
+        if not line.isascii():
+            line = '[Chinese receipt output captured verbatim in demo.json / demo.cast]'
+        for part in textwrap.wrap(line, width=88) or ['']:
+            draw.text((48, y), part, font=font, fill='#e4ebf6')
+            y += 29
+    draw.text((48, 576), f'{i+1}/4  |  No live API calls  |  Reproduce: node demo/run.mjs', font=font, fill='#98a8bf')
+    frames.append(image)
+frames[0].save(root / 'assets/demo.gif', save_all=True, append_images=frames[1:], duration=6000, loop=0, optimize=True)
+frames[-1].save(root / 'assets/demo-poster.png')

package/demo/run.mjs

@@ -0,0 +1,85 @@
+import assert from 'node:assert/strict';
+import {mkdirSync, writeFileSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {apply} from '../index.js';
+import {eventText} from '../src/state.js';
+import {makeSession,makePruner,makeCtx,fakeJudge} from './fixtures.mjs';
+
+const session=makeSession();
+const events=[...session.surface.nodes].map(seq=>session.eventAt(seq));
+session.snapshotEvents=()=>events;
+const append=session.append.bind(session);
+session.append=(...args)=>{const result=append(...args); events.push(session.eventAt(result.seq)); return result;};
+const original=eventText(session.eventAt(session.seqs.s1));
+const protectedOriginal=eventText(session.eventAt(session.seqs.s3));
+const pruner=makePruner();
+const compaction={
+  async summarize(){throw Error('Demo must inject a deterministic receipt');},
+  async compactRegion(start,end,agent,signal){
+    const nodes=session.surface.nodes;
+    const seqs=nodes.slice(nodes.indexOf(start),nodes.indexOf(end)+1);
+    const result=await this.summarize({messages:seqs.map(seq=>session.deriveEventMessage(session.eventAt(seq)))},agent,signal);
+    assert.equal(result.provider,'jev-receipt');
+    const compactionId='demo-region-1';
+    const record=session.append('compaction/summary',{compactionId,shadowedRange:{start,end},shadowedSeqs:seqs,summary:result.summary});
+    session.append('user/message',{source:{kind:'plugin',plugin:'compact',compactionId},content:result.summary},{surfaceOp:{op:'replace',startSeq:start,endSeq:end},sourceEventSeqs:seqs});
+    return {compactionId,shadowedSeqs:seqs,recordSeq:record.seq};
+  }
+};
+const ctx=makeCtx({session,pruner,compaction});
+const judge=fakeJudge({3:0.05,5:0.06,7:0.95},{3:0.05,5:0.05,7:0.9});
+apply(ctx,{judgeOn:'always',compactOn:'off',preserveRecent:0,compactPreserveRecent:0,compactMode:'absolute',compactThreshold:0.2,compactMinChars:1000,keepMode:'absolute',logLevel:'silent'},{judge});
+const exec={agent:{session,options:{}}};
+const stages=[];
+const stage=(title,lines)=>{stages.push({title,lines}); console.log('\n'+title+'\n'+lines.join('\n'));};
+stage('01 / Inspect long tool output',[
+  'REAL PLUGIN / SIMULATED DSH HOST / FIXED JUDGE SCORES',
+  'No live TypeSafe requests. No live-host compatibility claim.',
+  'Read s3: 6,000 characters; keep score 0.05',
+  'Read s7: 6,000 characters; keep score 0.95 (protected)',
+]);
+await ctx.waterfall('agent/pre-step',exec,()=>{});
+const trimmed=pruner.pruneSession(session);
+assert.equal(trimmed.pruned.length,2);
+assert.equal(eventText(session.eventAt(7)),protectedOriginal);
+const replacement=trimmed.pruned.find(row=>row.originalSeq===3);
+assert.ok(replacement);
+assert.ok(eventText(session.eventAt(replacement.replacementSeq)).length<original.length);
+stage('02 / Trim spent output; preserve useful evidence',[
+  'Actual pruneSession result: '+trimmed.pruned.length+' outputs trimmed',
+  's3: '+replacement.charsBefore+' -> '+replacement.charsAfter+' characters',
+  's7: unchanged, byte-for-byte equality assertion passed',
+  'Original s3 remains in the session event log',
+]);
+const compact=ctx.registeredTools.find(tool=>tool.name==='jev_compact_now');
+await compact.execute({},exec);
+const summary=events.find(event=>event.type==='compaction/summary');
+assert.ok(summary,'A real plugin receipt must be injected');
+stage('03 / Inject a deterministic region receipt',[
+  'jev_compact_now invoked the real registered tool',
+  'Provider: jev-receipt / Model: deterministic',
+  'Original region: s'+summary.data.shadowedRange.start+'-s'+summary.data.shadowedRange.end,
+  'Protected s7 remains on the surface',
+  ...eventText(summary).split('\n').slice(0,4),
+]);
+assert.ok(session.surface.nodes.includes(7));
+const restore=ctx.registeredTools.find(tool=>tool.name==='jev_restore');
+const before=[...session.surface.nodes];
+const restored=await restore.execute({seq:summary.seq},exec);
+assert.ok(restored.includes('a'.repeat(600)));
+assert.deepEqual(session.surface.nodes,before);
+stage('04 / Retrieve checkpoint text without changing the surface',[
+  'jev_restore({ seq: '+summary.seq+' }) returned hidden region text',
+  'Archived tool output excerpt found: assertion passed',
+  'Surface unchanged: assertion passed',
+  'Scope: REGION checkpoint only; each event is capped at 4,000 units',
+  'Layer-1 / partial-result IDs are not directly restorable yet',
+  'All demonstration assertions passed',
+]);
+const assets=fileURLToPath(new URL('../assets/',import.meta.url));
+mkdirSync(assets,{recursive:true});
+writeFileSync(assets+'demo.json',JSON.stringify({format:1,host:'simulated',judge:'fixed probabilities',liveApiCalls:0,stages,assertionsPassed:true},null,2)+'\n');
+const cast=[JSON.stringify({version:2,width:120,height:24,title:'dsh-jev-prune deterministic demo (simulated host)',env:{TERM:'xterm-256color'}})];
+stages.forEach((item,i)=>cast.push(JSON.stringify([i*6,'o','\u001b[2J\u001b[H'+item.title+'\r\n\r\n'+item.lines.join('\r\n')+'\r\n'])));
+cast.push(JSON.stringify([24,'o','\r\nDemo complete.\r\n']));
+writeFileSync(assets+'demo.cast',cast.join('\n')+'\n');

package/docs/ARCHITECTURE.md

@@ -0,0 +1,63 @@
+# Architecture
+
+`dsh-jev-prune` adds two context-reduction layers to DeepSeek Harness while keeping DSH's event log as the source of truth.
+
+```mermaid
+flowchart LR
+  J[jev.js\njudge client + token estimate]
+  P[prune.js\nlayer 1 decisions]
+  S[state.js\nDSH event projection]
+  R[receipt.js\nlayer 2 range selection]
+  I[index.js\nhost adapter + lifecycle]
+  S --> J
+  S --> P
+  R --> P
+  I --> J
+  I --> P
+  I --> S
+  I --> R
+```
+
+## Modules
+
+- `jev.js` owns the remote judge protocol, retry classification, batching, and local token estimation.
+- `prune.js` contains layer-1 pure logic: cached-verdict lookup, pressure-budget planning, code-point-safe slicing, and DSH-compatible replacement events.
+- `state.js` converts session events into the bounded state and questions sent to Jev. It also discovers tool names and selects candidates.
+- `receipt.js` contains layer-2 pure logic: tool-pair balance checks, evidence guards, two-axis eligibility, contiguous range selection, and deterministic receipt rendering.
+- `index.js` is the only host adapter. It resolves configuration, installs DSH hooks, owns per-session caches, invokes both layers, exposes tools/commands, and writes observability snapshots.
+
+The dependency direction stays toward the pure modules. Host APIs must remain in `index.js`; moving them into `prune.js` or `receipt.js` would make the safety logic harder to test outside DSH.
+
+## Runtime flow
+
+1. A prepended `agent/pre-step` hook builds the current state and asks Jev only for missing verdict axes.
+2. DSH's `compaction-basic` hook calls the synchronously overridden `toolResultPruner.pruneSession`. Layer 1 reads the verdict cache and replaces stale result bodies with head/marker/tail content.
+3. The normal second plugin hook selects read-only call/result pairs whose result and effect verdicts are both low. Fully eligible steps become balanced contiguous ranges; mixed parallel batches become per-result replacements matched by `callId`.
+4. Full ranges run through `compactRegion`. A one-use ownership token lets the temporary `summarize` override inject a deterministic receipt only for that transaction. Mixed batches use DSH's single-node shadow-price + `tool/result` replacement protocol, preserving every pair envelope and every rejected result.
+5. Original events remain in the session log. The surface points to replacement or compaction events, and `jev_restore` can retrieve the shadowed text.
+
+## State and identity
+
+Verdicts are held in a `WeakMap<session, Map<seq, verdict>>`. A layer-1 replacement receives a new seq and records the old seq in `sourceEventSeqs`; cache lookup follows that metadata so both layers keep the same judgment. In-memory verdicts are rebuilt after a process restart.
+
+The pressure ratio is also session-scoped. `judgePass` computes it asynchronously, and the synchronous layer-1 override consumes it later in the same pre-step chain.
+
+## Safety invariants
+
+- Never split an unbalanced tool-call/result range.
+- Never compact write-like tools; layer 2 uses a read-only allow-list plus a deny-list.
+- Preserve recent surface nodes independently for each layer.
+- Scan replacement source chains for error/assert/failure evidence.
+- Fall back conservatively when the context window, event shape, or judge result is unavailable.
+- Inject a receipt only when the active transaction owns the pending token.
+- Keep deterministic receipts factual: tool, arguments, seq, and output size; no model-generated conclusion.
+
+## Parallel batch boundary
+
+One assistant message may contain several parallel tool calls. They share one head event, and DSH 0.1.5's contiguous-range API cannot remove only a subset of those pairs. Mixed batches therefore compact eligible result bodies in place; only a fully eligible batch removes its assistant head and result nodes. This keeps the surface valid without fabricating assistant messages or depending on an unsupported multi-node insertion API.
+
+## Implementation reference
+
+Detailed configuration, gating, protocol history and troubleshooting moved to [the implementation reference](implementation.md). Measurement notes are in [measurements](measurements.md). The recorded [demo](../demo/README.md) runs real plugin code with a simulated host.
+
+The current fencing token supports claim-once behavior, but does not prove which external compaction owns a summary call. See [the reviewed limitations](review-2026-10-05.md) before using concurrent compaction.