dsh-memu-memory 1.1.3 → 1.2.0

package/tests/consolidation-fork.test.mjs

@@ -0,0 +1,357 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const home = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-memu-memory-fork-'))
+process.env.DSH_MEMU_HOME = home
+
+const state = await import('../lib/state.js')
+const { requestPrivateConsolidation, isConsolidating } = await import('../lib/private.js')
+
+test.after(() => {
+  try { fs.rmSync(home, { recursive: true, force: true }) } catch {}
+})
+
+// The manual path (the sidebar button, RPC generatePrivate) shares one entry point
+// with the idle sweep. Both now fork; neither may queue anything on the live agent,
+// because a queued followup is what the host renders as a pending draft above the
+// user's composer and what ends up as a permanent housekeeping turn in their chat.
+// The host contract this plugin must satisfy, mirrored from the runtime:
+// packages/core/session SessionStore.prepare() rebuilds a session header from a
+// fixed meta whitelist and `Session` then throws "seeded session requires an
+// inherited event count" when the count was not passed as a TOP-LEVEL option.
+// The host drops an unknown meta key silently; this fake refuses it loudly, so a
+// plugin that misplaces the field fails the test instead of dying in production.
+const META_KEYS = ['cwd', 'parentSession', 'isSeeded', 'origin', 'delegationDepth', 'agentPreset']
+
+function assertHostCreateAccepts(spec = {}) {
+  const meta = spec.meta ?? {}
+  const count = spec.inheritedEventCount
+  for (const key of Object.keys(meta)) {
+    if (!META_KEYS.includes(key)) {
+      throw new Error(`session meta "${key}" is not a header field: SessionStore.prepare() drops it`)
+    }
+  }
+  if (meta.isSeeded === true) {
+    if (spec.seed === undefined) throw new Error('seeded session requires an explicit constructor seed')
+    if (count === undefined) throw new Error('seeded session requires an inherited event count')
+  } else if (count !== undefined && count !== 0) {
+    throw new Error('unseeded session inherited event count must be 0')
+  }
+  // buildForkSeed() returns a seed object, not a bare array, so the length guard
+  // only applies to an array seed.
+  if (Array.isArray(spec.seed) && count !== undefined && count > spec.seed.length) {
+    throw new Error('session inherited event count exceeds its event log')
+  }
+  if (spec.agentOptions !== undefined) {
+    if (!spec.agentOptions || typeof spec.agentOptions.provider !== 'string' || typeof spec.agentOptions.model !== 'string') {
+      throw new Error('agentOptions must carry the parent provider and model')
+    }
+  }
+}
+
+function host({ live = false, whenIdle = null, parentOptions = { provider: 'test-provider', model: 'test-model' }, requestConfig = null, extraEvents = [], transcriptSize = 0, turnReason = { kind: 'completed' }, emitTurnEnd = true } = {}) {
+  const rec = { liveFollowups: [], created: [], forkFollowups: [], disposed: [], sessionHandlers: [] }
+  const tick = String.fromCharCode(96)
+  const receiptFence = (range, identity) => [tick + tick + tick + 'memu-consolidation-receipt', JSON.stringify({ version: 1, ...identity, status: 'completed', outcome: 'no_value', checkedRange: range, createdIds: [], updatedIds: [], heldIds: [], reasonCode: null, retryable: false }), tick + tick + tick].join('\n')
+  // 真实长会话的规模：补齐不产生证据的事件，只影响 fork 成本判定。
+  const padding = Math.max(0, transcriptSize - 3 - extraEvents.length)
+  const filler = Array.from({ length: padding }, (_, i) => ({ seq: 3 + extraEvents.length + i, type: 'todo/write', data: {} }))
+  const ctx = {
+    rec,
+    on: (name, handler) => {
+      if (name !== 'session/event') return () => {}
+      rec.sessionHandlers.push(handler)
+      return () => {
+        const index = rec.sessionHandlers.indexOf(handler)
+        if (index >= 0) rec.sessionHandlers.splice(index, 1)
+      }
+    },
+    get: (name) => {
+      if (name === 'agents') {
+        return {
+          get: (id) => (live
+            ? {
+                followup: (message) => rec.liveFollowups.push({ id, message }),
+                ...(parentOptions ? { options: parentOptions } : {}),
+                ...(requestConfig ? { session: { requestHeader: () => ({ config: requestConfig }) } } : {}),
+              }
+            : undefined),
+          create: async (spec) => {
+            assertHostCreateAccepts(spec)
+            rec.created.push(spec)
+            const childSession = { id: spec.sessionId }
+            return {
+              agent: {
+                session: childSession,
+                followup: (message) => {
+                  rec.forkFollowups.push({ child: spec.sessionId, message })
+                  if (emitTurnEnd) {
+                    if (turnReason?.kind === 'completed') {
+                      const throughSeq = 2 + extraEvents.length + padding
+                      for (const handler of rec.sessionHandlers) {
+                        handler(childSession, { type: 'assistant/message', seq: 99, data: { message: { content: [{ type: 'text', text: receiptFence({ fromSeq: 0, throughSeq }, state.getSessionBinding(spec.sessionId)) }] } } })
+                      }
+                    }
+                    for (const handler of rec.sessionHandlers) {
+                      handler(childSession, { type: 'turn/end', seq: 100, data: { turn: 1, reason: turnReason } })
+                    }
+                  }
+                },
+                whenIdle: whenIdle || (async () => {}),
+              },
+              dispose: async () => { rec.disposed.push(spec.sessionId) },
+            }
+          },
+        }
+      }
+      if (name === 'sessionQuery') {
+        return {
+          readSession: async () => ({
+            events: [
+              { seq: 0, type: 'user/message', data: { source: { kind: 'user' }, content: [{ type: 'text', text: '这个 fork 为什么一直建不起来，帮我看下' }] } },
+              { seq: 1, type: 'assistant/message', data: { message: { content: [{ type: 'tool-call', name: 'read', arguments: '{}' }] } } },
+              { seq: 2, type: 'assistant/message', data: { message: { content: [{ type: 'text', text: '看到了' }] } } },
+              ...extraEvents,
+              ...filler,
+            ],
+            session: { cwd: path.join(home, 'proj'), agentPreset: 'coding' },
+          }),
+        }
+      }
+      return undefined
+    },
+  }
+  return ctx
+}
+
+test('enabling local or remote vectors does not opt into remote summary', async () => {
+  const originalFetch = globalThis.fetch
+  let fetches = 0
+  globalThis.fetch = async () => { fetches += 1; throw new Error('summary API must not be called') }
+  try {
+    for (const vectorSource of ['local', 'api']) {
+      state.updateSettings({ memoryBackend: 'api', vectorSource })
+      const id = 'fork-vector-' + vectorSource
+      state.ensureSession(id, { cwd: path.join(home, id), agentPreset: 'coding' })
+      const ctx = host({ live: true })
+      const result = await requestPrivateConsolidation(ctx, id)
+      assert.equal(result.ok, true)
+      assert.equal(ctx.rec.created.length, 1, 'vector enable still delegates extraction to the conversation Agent')
+      assert.equal(ctx.rec.forkFollowups.length, 1)
+    }
+    assert.equal(fetches, 0)
+  } finally {
+    globalThis.fetch = originalFetch
+    state.updateSettings({ memoryBackend: 'agent', vectorSource: 'local' })
+  }
+})
+
+test('a live session is consolidated in a fork, not by queueing on itself', async () => {
+  const binding = state.ensureSession('fork-live', { cwd: path.join(home, 'proj'), agentPreset: 'coding' })
+  const parentOptions = { provider: 'test-provider', model: 'test-model', reasoningEffort: 'max', maxTokens: 262144 }
+  const ctx = host({ live: true, parentOptions })
+  const result = await requestPrivateConsolidation(ctx, 'fork-live')
+  assert.equal(result.ok, true)
+  assert.equal(result.settled, true)
+  assert.equal(ctx.rec.liveFollowups.length, 0, 'no queued draft on the live agent')
+  assert.equal(ctx.rec.created.length, 1, 'exactly one scratch fork')
+  assert.equal(ctx.rec.forkFollowups.length, 1, 'the fork does the work')
+  assert.equal(ctx.rec.disposed.length, 1, 'the fork is disposed')
+  const spec = ctx.rec.created[0]
+  assert.equal(spec.meta.parentSession, 'fork-live')
+  assert.equal(spec.meta.origin, 'subagent')
+  assert.equal(spec.meta.isSeeded, true)
+  assert.equal(spec.inheritedEventCount, 3, 'inherits the whole transcript as a top-level option')
+  assert.equal(Object.hasOwn(spec.meta, 'inheritedEventCount'), false, 'must not hide in the session meta: prepare() drops it')
+  assert.deepEqual(spec.agentOptions, parentOptions, 'the fork starts on the parent model route')
+  const child = state.getSessionBinding(spec.sessionId)
+  assert.equal(child, null, 'disposed worker binding is removed')
+  assert.equal(state.getSessionBinding('fork-live').lastSleepSeq, 2, 'only a completed turn advances the sleep cursor')
+  assert.equal(result.scanned, 3, 'report how much of the transcript was scanned')
+  assert.equal(result.fresh, 3, 'report how many events were new since the last consolidation')
+  assert.equal(result.wrote, 0, 'the fake fork writes nothing, but the metric must still be measured')
+})
+test('a live session inherits the route of its latest turn, not stale creation options', async () => {
+  state.ensureSession('fork-route', { cwd: path.join(home, 'proj-route'), agentPreset: 'coding' })
+  const ctx = host({
+    live: true,
+    parentOptions: { provider: 'creation', model: 'old-model' },
+    requestConfig: { provider: 'request', model: 'new-model', reasoningEffort: 'high', maxTokens: 32768 },
+  })
+  const result = await requestPrivateConsolidation(ctx, 'fork-route')
+  assert.equal(result.ok, true)
+  assert.deepEqual(ctx.rec.created[0].agentOptions, {
+    provider: 'request',
+    model: 'new-model',
+    reasoningEffort: 'high',
+    maxTokens: 32768,
+  }, 'requestHeader() is the route that served the parent, options can be stale')
+})
+
+test('a closed session inherits the last request/header event', async () => {
+  state.ensureSession('fork-closed', { cwd: path.join(home, 'proj-closed'), agentPreset: 'coding' })
+  const ctx = host({
+    live: false,
+    extraEvents: [
+      { seq: 3, type: 'request/header', data: { header: { config: { provider: 'old', model: 'old-model' } } } },
+      { seq: 4, type: 'request/header', data: { header: { config: { provider: 'latest', model: 'latest-model', reasoningEffort: 'low', maxTokens: 4096 } } } },
+    ],
+  })
+  const result = await requestPrivateConsolidation(ctx, 'fork-closed')
+  assert.equal(result.ok, true)
+  const spec = ctx.rec.created[0]
+  assert.equal(spec.inheritedEventCount, 5, 'the header events are part of the inherited log')
+  assert.deepEqual(spec.agentOptions, { provider: 'latest', model: 'latest-model', reasoningEffort: 'low', maxTokens: 4096 })
+})
+
+test('a session with no model source is refused before a doomed fork', async () => {
+  state.ensureSession('fork-no-model', { cwd: path.join(home, 'proj-no-model'), agentPreset: 'coding' })
+  const ctx = host({ live: true, parentOptions: null })
+  const result = await requestPrivateConsolidation(ctx, 'fork-no-model')
+  assert.equal(result.ok, false)
+  assert.match(result.error, /model\/provider/)
+  assert.equal(ctx.rec.created.length, 0, 'never create a fork that cannot resolve {{model}}')
+})
+
+test('a failed fork turn is reported as failure and does not advance the sleep cursor', async () => {
+  state.ensureSession('fork-turn-error', { cwd: path.join(home, 'proj-turn-error'), agentPreset: 'coding' })
+  const ctx = host({
+    live: true,
+    turnReason: { kind: 'error', error: { message: 'prompt variable "{{model}}" has no value for this assembly', code: 'UNKNOWN' } },
+  })
+  const result = await requestPrivateConsolidation(ctx, 'fork-turn-error')
+  assert.equal(result.ok, false)
+  assert.equal(result.settled, false)
+  assert.match(result.error, /fork turn ended error/)
+  assert.match(result.error, /prompt variable/)
+  assert.equal(state.getSessionBinding('fork-turn-error').lastSleepSeq, undefined, 'a failed turn must be retried, not marked asleep')
+  assert.equal(ctx.rec.disposed.length, 1, 'the failed fork is still disposed')
+  assert.equal(ctx.rec.sessionHandlers.length, 0, 'the failed fork listener is removed')
+})
+
+test('a fork that never reports turn/end is a failure, not a success', async () => {
+  state.ensureSession('fork-no-turn-end', { cwd: path.join(home, 'proj-no-turn-end'), agentPreset: 'coding' })
+  const ctx = host({ live: true, emitTurnEnd: false })
+  const result = await requestPrivateConsolidation(ctx, 'fork-no-turn-end')
+  assert.equal(result.ok, false)
+  assert.equal(result.settled, false)
+  assert.match(result.error, /no turn\/end/)
+  assert.equal(state.getSessionBinding('fork-no-turn-end').lastSleepSeq, undefined, 'without a turn/end event the cursor must not advance')
+  assert.equal(ctx.rec.disposed.length, 1, 'the unmatched fork is still disposed')
+  assert.equal(ctx.rec.sessionHandlers.length, 0, 'the listener is removed even when no turn/end arrives')
+})
+
+test('a fork still running at the deadline reports a timeout instead of silence', async () => {
+  state.ensureSession('fork-timeout', { cwd: path.join(home, 'proj-timeout'), agentPreset: 'coding' })
+  const ctx = host({ live: true, whenIdle: () => new Promise(() => {}) })
+  const result = await requestPrivateConsolidation(ctx, 'fork-timeout', { maxWaitMs: 30 })
+  assert.equal(result.ok, false)
+  assert.equal(result.timedOut, true)
+  assert.equal(result.settled, false)
+  // The settings button renders result.error and nothing else; an empty string
+  // there is why two clicks in a row looked like the button did nothing.
+  assert.match(result.error, /timed out after \d+s/)
+  assert.equal(state.getSessionBinding('fork-timeout').lastSleepSeq, undefined, 'a timeout must not advance the sleep cursor')
+  assert.equal(ctx.rec.disposed.length, 1, 'the timed-out fork is stopped')
+  assert.equal(ctx.rec.sessionHandlers.length, 0, 'the listener is removed on timeout')
+})
+
+test('a session already being consolidated is not forked twice', async () => {
+  state.ensureSession('fork-busy', { cwd: path.join(home, 'proj2'), agentPreset: 'coding' })
+  let release = null
+  const gate = new Promise((resolve) => { release = resolve })
+  const ctx = host({ live: true, whenIdle: () => gate })
+  const first = requestPrivateConsolidation(ctx, 'fork-busy')
+  await new Promise((resolve) => setTimeout(resolve, 20))
+  assert.equal(isConsolidating('fork-busy'), true)
+  const second = await requestPrivateConsolidation(ctx, 'fork-busy')
+  assert.equal(second.ok, false)
+  assert.equal(second.running, true)
+  assert.equal(ctx.rec.created.length, 1, 'the second call must not fork again')
+  release()
+  const done = await first
+  assert.equal(done.ok, true)
+  assert.equal(isConsolidating('fork-busy'), false)
+})
+
+test('two calls in the same tick fork once, not twice', async () => {
+  // The guard used to be checked before the first await and claimed only after
+  // readSession() and agents.create() resolved, so this exact pair raced past it
+  // and forked the same transcript twice on the real host.
+  state.ensureSession('fork-race', { cwd: path.join(home, 'proj3'), agentPreset: 'coding' })
+  let release = null
+  const gate = new Promise((resolve) => { release = resolve })
+  const ctx = host({ live: true, whenIdle: () => gate })
+  const both = Promise.all([
+    requestPrivateConsolidation(ctx, 'fork-race'),
+    requestPrivateConsolidation(ctx, 'fork-race'),
+  ])
+  await new Promise((resolve) => setTimeout(resolve, 20))
+  release()
+  const [a, b] = await both
+  assert.equal(ctx.rec.created.length, 1, 'exactly one scratch fork for the pair')
+  const outcomes = [a, b].map((r) => r.running === true ? 'running' : r.ok === true ? 'ok' : 'error').sort()
+  assert.deepEqual(outcomes, ['ok', 'running'], 'the loser is told the session is already being consolidated')
+})
+
+test('an unbound session is refused before any fork is attempted', async () => {
+  const ctx = host({ live: true })
+  const result = await requestPrivateConsolidation(ctx, 'fork-unbound')
+  assert.equal(result.ok, false)
+  assert.match(result.error, /not bound/)
+  assert.equal(ctx.rec.created.length, 0)
+  assert.equal(ctx.rec.liveFollowups.length, 0)
+})
+test('thin evidence holds the fork back until the starvation threshold', async () => {
+  state.ensureSession('fork-thin', { cwd: path.join(home, 'proj-thin'), agentPreset: 'coding' })
+  // 空闲 5 分钟：还在"短空闲"区间，证据又薄（一条短消息 + 一个工具调用），不唤醒。
+  state.setSessionBinding('fork-thin', { lastTurnAt: new Date(Date.now() - 5 * 60_000).toISOString() })
+  const ctx = host({ live: true })
+  const result = await requestPrivateConsolidation(ctx, 'fork-thin')
+  assert.equal(result.ok, true)
+  assert.equal(result.skipped, 'low-score')
+  assert.equal(ctx.rec.created.length, 0, 'a thin short-idle session must not pay for a fork')
+})
+
+test('starvation wakes a thin session so it can never be starved', async () => {
+  state.ensureSession('fork-starved', { cwd: path.join(home, 'proj-starved'), agentPreset: 'coding' })
+  state.setSessionBinding('fork-starved', { lastTurnAt: new Date(Date.now() - 40 * 60_000).toISOString() })
+  const ctx = host({ live: true })
+  const result = await requestPrivateConsolidation(ctx, 'fork-starved')
+  assert.equal(result.ok, true)
+  assert.equal(ctx.rec.created.length, 1, 'past the starvation threshold the check runs regardless of score')
+})
+
+test('a large transcript with nothing new since the cursor does not refork', async () => {
+  // 真机会话 5913 条事件、26MB 转录。游标停在末尾附近时，待整理区间只剩几条纯轮询：
+  // 没有新的真人回合，就没有可整理的证据，不该为此把整段转录重新种进 fork。
+  // （桩把填充事件全放在末尾，所以「大会话 + 末尾一句轻话」这种形态表达不出来；
+  //   另一侧「从未整理过就必须整理」由下一条用例覆盖。）
+  state.ensureSession('fork-large-thin', { cwd: path.join(home, 'proj-large'), agentPreset: 'coding' })
+  state.setSessionBinding('fork-large-thin', {
+    lastTurnAt: new Date(Date.now() - 40 * 60_000).toISOString(),
+    lastSleepSeq: 5905,
+  })
+  const ctx = host({ live: true, transcriptSize: 5913 })
+  const result = await requestPrivateConsolidation(ctx, 'fork-large-thin')
+  assert.equal(result.ok, true)
+  assert.equal(result.skipped, 'no-human-turn', 'the increment carries no human turn to consolidate')
+  assert.equal(result.settled, false, 'nothing was consolidated, so the cursor must not move')
+  assert.equal(ctx.rec.created.length, 0, 'no fork when the pending increment has no evidence')
+  assert.equal(state.getSessionBinding('fork-large-thin').lastSleepSeq, 5905, 'the cursor must not advance')
+})
+
+test('a large transcript that was never consolidated does fork, because the backlog is real', async () => {
+  // 同一条会话，但没有整理过：整段 5913 条事件都躺在 pending 里。
+  // 守卫要躲的是「为一句轻话重种整段转录」，不是「把从没整理过的大会话永远挡在门外」；
+  // 没有这条上界，长会话早期的决定永远进不了记忆——那不是省 token，是丢失。
+  state.ensureSession('fork-large-owed', { cwd: path.join(home, 'proj-large-owed'), agentPreset: 'coding' })
+  state.setSessionBinding('fork-large-owed', { lastTurnAt: new Date(Date.now() - 40 * 60_000).toISOString() })
+  const ctx = host({ live: true, transcriptSize: 5913 })
+  const result = await requestPrivateConsolidation(ctx, 'fork-large-owed')
+  assert.equal(result.ok, true, 'the backlog bound lets this one through')
+  assert.equal(ctx.rec.created.length, 1, 'a large unconsolidated backlog is worth exactly one fork')
+})

package/tests/consolidation-ledger.test.mjs

@@ -0,0 +1,298 @@
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const home = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-memu-memory-cons-ledger-'))
+process.env.DSH_MEMU_HOME = home
+
+const ledger = await import('../lib/consolidation-ledger.js')
+const receipt = await import('../lib/consolidation-receipt.js')
+
+test.after(() => {
+  try { fs.rmSync(home, { recursive: true, force: true }) } catch {}
+})
+
+let counter = 0
+function binding(patch = {}) {
+  counter += 1
+  return {
+    scopeKey: 'd:/proj',
+    libraryId: 'lib_test',
+    domain: 'rp',
+    useLibrary: true,
+    useGlobal: false,
+    memoryOwnerSessionId: 'owner-' + counter,
+    memoryContext: { channelId: 'ch-' + counter },
+    ...patch,
+  }
+}
+
+function snapshot(through = 20, from = 0) {
+  return { hash: 'hash-' + through + '-' + from, fromSeq: from, throughSeq: through, eventCount: through - from + 1, source: 'lease-live' }
+}
+
+// C 包第 5 条：checked/pending/inflight 三个边界分开记，一个失败不能把三个一起推错。
+
+test('a job holds a lease and a second job is refused while it is live', () => {
+  const sessionId = 'led-lease'
+  const first = ledger.beginJob({ sessionId, jobId: 'job-1', snapshot: snapshot(20), binding: binding() })
+  assert.equal(first.ok, true)
+  assert.ok(first.job.leaseUntil > Date.now())
+  assert.equal(first.job.scopeGeneration.length, 8)
+  const second = ledger.beginJob({ sessionId, jobId: 'job-2', snapshot: snapshot(20), binding: binding() })
+  assert.equal(second.ok, false)
+  assert.equal(second.reasonCode, 'lease-held')
+  assert.equal(second.jobId, 'job-1')
+})
+
+test('evidence advances the pending boundary only, never the checked one', () => {
+  const sessionId = 'led-pending'
+  const first = ledger.noteEvidence({ sessionId, fromSeq: 0, throughSeq: 12 })
+  assert.equal(first.changed, true)
+  assert.equal(first.pending.throughSeq, 12)
+  ledger.noteEvidence({ sessionId, fromSeq: 0, throughSeq: 30 })
+  const state = ledger.sessionState(sessionId)
+  assert.equal(state.pending.throughSeq, 30)
+  assert.equal(state.checked, null)
+  // 回退不会发生：更小的边界不会把 pending 拉回去。
+  ledger.noteEvidence({ sessionId, fromSeq: 0, throughSeq: 10 })
+  assert.equal(ledger.sessionState(sessionId).pending.throughSeq, 30)
+})
+
+test('a completed job advances checked and clears pending', () => {
+  const sessionId = 'led-complete'
+  ledger.noteEvidence({ sessionId, throughSeq: 18 })
+  ledger.beginJob({ sessionId, jobId: 'job-c', snapshot: snapshot(20), binding: binding() })
+  const done = ledger.completeJob({
+    sessionId, jobId: 'job-c', snapshot: snapshot(20),
+    covered: { fromSeq: 0, throughSeq: 20 },
+    status: 'completed', outcome: 'created', counts: { created: 2 },
+    receipt: { status: 'completed', outcome: 'created', reasonCode: null },
+  })
+  assert.equal(done.advanced, true)
+  assert.equal(done.checked.throughSeq, 20)
+  assert.equal(done.checked.status, 'completed')
+  assert.equal(done.checked.snapshotHash, 'hash-20-0')
+  assert.equal(done.pending, null, 'the whole pending range was covered')
+  const state = ledger.sessionState(sessionId)
+  assert.equal(state.inflight, null)
+  assert.equal(state.attempts, 0)
+  assert.equal(state.history.at(-1).status, 'completed')
+})
+
+test('a failed job keeps the range pending and backs off', () => {
+  const sessionId = 'led-fail'
+  ledger.beginJob({ sessionId, jobId: 'job-f', snapshot: snapshot(20), binding: binding() })
+  const failed = ledger.failJob({ sessionId, jobId: 'job-f', reasonCode: 'fork-turn-failed', error: 'boom' })
+  assert.equal(failed.pending.throughSeq, 20)
+  assert.ok(failed.retryAt, 'a retryable failure schedules a retry')
+  const state = ledger.sessionState(sessionId)
+  assert.equal(state.checked, null, 'a failure never advances the checked cursor')
+  assert.equal(state.lastReasonCode, 'fork-turn-failed')
+  assert.equal(state.attempts, 1)
+})
+
+test('only completed and reasoned skipped receipts may advance', () => {
+  for (const [status, reasonCode, expected] of [['completed', null, true], ['skipped', 'no-value', true], ['skipped', null, false], ['failed', 'receipt-missing', false], ['deferred', 'open-turn', false]]) {
+    const sessionId = 'led-status-' + status + '-' + String(reasonCode)
+    ledger.beginJob({ sessionId, jobId: 'job-s', snapshot: snapshot(9), binding: binding() })
+    const done = ledger.completeJob({ sessionId, jobId: 'job-s', snapshot: snapshot(9), covered: { fromSeq: 0, throughSeq: 9 }, status, outcome: 'no_value', reasonCode, retryable: true })
+    assert.equal(done.advanced, expected, status + '/' + String(reasonCode) + ' advance=' + expected)
+    const state = ledger.sessionState(sessionId)
+    assert.equal(state.checked === null, !expected)
+    if (!expected) assert.equal(state.pending.throughSeq, 9, 'the range stays pending for the next attempt')
+  }
+})
+
+test('a receipt cannot claim more than the snapshot covered', () => {
+  const sessionId = 'led-clamp'
+  ledger.beginJob({ sessionId, jobId: 'job-k', snapshot: snapshot(20), binding: binding() })
+  const done = ledger.completeJob({
+    sessionId, jobId: 'job-k', snapshot: snapshot(20),
+    covered: { fromSeq: 0, throughSeq: 99 },
+    status: 'completed', outcome: 'no_value',
+  })
+  assert.equal(done.advanced, false, 'out-of-range coverage is rejected, never clamped')
+  assert.equal(done.checked, null)
+})
+
+test('a partial cover keeps the rest pending', () => {
+  const sessionId = 'led-partial'
+  ledger.noteEvidence({ sessionId, throughSeq: 40 })
+  ledger.beginJob({ sessionId, jobId: 'job-p', snapshot: snapshot(40), binding: binding() })
+  const done = ledger.completeJob({ sessionId, jobId: 'job-p', snapshot: snapshot(40), covered: { fromSeq: 0, throughSeq: 25 }, status: 'completed', outcome: 'no_value' })
+  assert.equal(done.advanced, false)
+  assert.equal(done.checked, null, 'partial coverage must not advance checked')
+  assert.equal(done.pending.throughSeq, 40)
+  assert.equal(done.pending.fromSeq, 0)
+})
+
+test('an expired lease is recovered as a failure, not as a completed run', () => {
+  const sessionId = 'led-zombie'
+  const started = Date.now() - 60_000
+  ledger.beginJob({ sessionId, jobId: 'job-z', snapshot: snapshot(12), binding: binding(), now: started, leaseMs: 1_000 })
+  const recovered = ledger.recoverStaleJobs({ now: Date.now() })
+  assert.ok(recovered.some((row) => row.sessionId === sessionId))
+  const state = ledger.sessionState(sessionId)
+  assert.equal(state.inflight, null)
+  assert.equal(state.checked, null, 'an interrupted job proves nothing')
+  assert.equal(state.pending.throughSeq, 12, 'its range is pending again')
+  assert.equal(state.lastReasonCode, 'lease-expired')
+})
+
+test('a live lease is not recovered', () => {
+  const sessionId = 'led-live-lease'
+  ledger.beginJob({ sessionId, jobId: 'job-live', snapshot: snapshot(4), binding: binding() })
+  ledger.recoverStaleJobs({ now: Date.now() })
+  assert.ok(ledger.sessionState(sessionId).inflight, 'a job inside its lease keeps the session')
+})
+
+test('the operation key is stable and records what was settled', () => {
+  const args = { sessionId: 'led-op', libraryId: 'lib_test', snapshotHash: 'hash-20-0' }
+  const key = ledger.operationKey(args)
+  assert.equal(key, ledger.operationKey({ ...args }))
+  assert.notEqual(key, ledger.operationKey({ ...args, snapshotHash: 'hash-21-0' }))
+  assert.equal(ledger.findOperation('led-op', key), null)
+  ledger.recordOperation({ sessionId: 'led-op', key, outcome: 'completed', ids: ['mem-1'] })
+  const found = ledger.findOperation('led-op', key)
+  assert.equal(found.outcome, 'completed')
+  assert.deepEqual(found.ids, ['mem-1'])
+})
+
+test('two sessions do not overwrite each other in the ledger', () => {
+  ledger.beginJob({ sessionId: 'led-a', jobId: 'job-a', snapshot: snapshot(3), binding: binding() })
+  ledger.beginJob({ sessionId: 'led-b', jobId: 'job-b', snapshot: snapshot(7), binding: binding() })
+  assert.equal(ledger.sessionState('led-a').inflight.jobId, 'job-a')
+  assert.equal(ledger.sessionState('led-b').inflight.jobId, 'job-b')
+})
+
+test('the scope generation changes with the parent authorization', () => {
+  const base = binding()
+  const first = ledger.scopeGenerationOf(base)
+  assert.equal(first, ledger.scopeGenerationOf({ ...base }))
+  assert.notEqual(first, ledger.scopeGenerationOf({ ...base, libraryId: 'lib_other' }))
+  assert.notEqual(first, ledger.scopeGenerationOf({ ...base, useLibrary: false }))
+  assert.notEqual(first, ledger.scopeGenerationOf({ ...base, memoryContext: { channelId: 'other' } }))
+  assert.equal(ledger.scopeGenerationOf(null), null)
+})
+
+test('a corrupt ledger blocks writes instead of silently replacing it', () => {
+  const other = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-memu-memory-cons-corrupt-'))
+  const previous = process.env.DSH_MEMU_HOME
+  process.env.DSH_MEMU_HOME = other
+  try {
+    fs.writeFileSync(path.join(other, 'consolidation.json'), '{ not json', 'utf8')
+    assert.throws(() => ledger.beginJob({ sessionId: 'led-corrupt', jobId: 'job-x', snapshot: snapshot(1), binding: binding() }), /refusing to overwrite|not valid JSON|busy/i)
+    assert.equal(ledger.sessionState('led-corrupt').inflight, null)
+  } finally {
+    process.env.DSH_MEMU_HOME = previous
+    try { fs.rmSync(other, { recursive: true, force: true }) } catch {}
+  }
+})
+
+// ---- 结构化回执 ----
+
+function fence(json) {
+  const tick = String.fromCharCode(96)
+  return [tick + tick + tick + receipt.RECEIPT_TAG, JSON.stringify(json, null, 2), tick + tick + tick].join('\n')
+}
+
+test('a receipt without its fence block is missing, never guessed', () => {
+  const parsed = receipt.parseReceipt('我整理完了，写了两条记忆。')
+  assert.equal(parsed.ok, false)
+  assert.equal(parsed.reasonCode, 'receipt-missing')
+})
+
+test('malformed JSON and invalid shapes are distinguishable failures', () => {
+  const tick = String.fromCharCode(96) + String.fromCharCode(96) + String.fromCharCode(96)
+  const broken = [tick + receipt.RECEIPT_TAG, '{ "status": "completed", ', tick].join('\n')
+  assert.equal(receipt.parseReceipt(broken).reasonCode, 'receipt-malformed')
+  const badStatus = receipt.parseReceipt(fence({ status: 'done', outcome: 'created', createdIds: ['mem-1'] }))
+  assert.equal(badStatus.reasonCode, 'receipt-invalid')
+  assert.match(badStatus.detail, /status must be one of/)
+})
+
+test('created without ids, or skipped without a reasonCode, is invalid', () => {
+  assert.equal(receipt.parseReceipt(fence({ status: 'completed', outcome: 'created', createdIds: [] })).reasonCode, 'receipt-invalid')
+  assert.equal(receipt.parseReceipt(fence({ status: 'skipped', outcome: 'no_value' })).reasonCode, 'receipt-invalid')
+  const ok = receipt.parseReceipt(fence({ status: 'skipped', outcome: 'no_value', reasonCode: 'no-value', checkedRange: { fromSeq: 0, throughSeq: 4 } }))
+  assert.equal(ok.ok, true)
+})
+
+test('no_value cannot smuggle in written ids', () => {
+  const parsed = receipt.parseReceipt(fence({ status: 'completed', outcome: 'no_value', createdIds: ['mem-1'], checkedRange: { fromSeq: 0, throughSeq: 4 } }))
+  assert.equal(parsed.reasonCode, 'receipt-invalid')
+})
+
+test('the receipt is reconciled against the library, not taken on trust', () => {
+  const index = { entries: { 'mem-1': { status: 'active' }, 'mem-held': { status: 'pending_review' } } }
+  const parsed = receipt.parseReceipt(fence({
+    status: 'completed', outcome: 'created', createdIds: ['mem-1', 'mem-ghost'], checkedRange: { fromSeq: 0, throughSeq: 8 },
+  }))
+  assert.equal(parsed.ok, true)
+  const reconciled = receipt.reconcileReceipt({ receipt: parsed.receipt, index, beforeIds: new Set() })
+  assert.equal(reconciled.ok, false)
+  assert.match(reconciled.problems.join(' '), /mem-ghost/)
+})
+
+test('rewriting an existing id is an update, not a new memory', () => {
+  const index = { entries: { 'mem-1': { status: 'active', content: 'after' } } }
+  const parsed = receipt.parseReceipt(fence({ status: 'completed', outcome: 'created', createdIds: ['mem-1'], checkedRange: { fromSeq: 0, throughSeq: 4 } }))
+  const reconciled = receipt.reconcileReceipt({ receipt: parsed.receipt, index, beforeIds: new Set(['mem-1']), beforeEntries: { 'mem-1': receipt.entryFingerprint({ status: 'active', content: 'before' }) } })
+  assert.equal(reconciled.ok, true)
+  assert.deepEqual(reconciled.createdIds, [])
+  assert.deepEqual(reconciled.duplicateIds, ['mem-1'])
+  assert.equal(reconciled.outcome, 'updated')
+})
+
+test('an unchanged existing id cannot prove an update', () => {
+  const index = { entries: { 'mem-unchanged': { status: 'active', content: 'same' } } }
+  const parsed = receipt.parseReceipt(fence({ status: 'completed', outcome: 'updated', updatedIds: ['mem-unchanged'], checkedRange: { fromSeq: 0, throughSeq: 4 } }))
+  const reconciled = receipt.reconcileReceipt({
+    receipt: parsed.receipt,
+    index,
+    beforeIds: new Set(['mem-unchanged']),
+    beforeEntries: { 'mem-unchanged': receipt.entryFingerprint(index.entries['mem-unchanged']) },
+  })
+  assert.equal(reconciled.ok, false)
+  assert.match(reconciled.problems.join(' '), /no verified post-worker change/)
+})
+
+test('a held id must really be pending_review', () => {
+  const index = { entries: { 'mem-1': { status: 'active' } } }
+  const parsed = receipt.parseReceipt(fence({ status: 'completed', outcome: 'no_value', heldIds: ['mem-1'], checkedRange: { fromSeq: 0, throughSeq: 4 } }))
+  const reconciled = receipt.reconcileReceipt({ receipt: parsed.receipt, index })
+  assert.equal(reconciled.ok, false)
+  assert.match(reconciled.problems.join(' '), /not pending_review/)
+})
+
+test('decideCompletion: proof advances, guesswork does not', () => {
+  const index = { entries: { 'mem-7': { status: 'active' } } }
+  const good = receipt.decideCompletion({
+    text: fence({ status: 'completed', outcome: 'created', createdIds: ['mem-7'], checkedRange: { fromSeq: 0, throughSeq: 9 } }),
+    wrote: 1, index, beforeIds: new Set(),
+  })
+  assert.equal(good.advance, true)
+  assert.equal(good.outcome, 'created')
+  assert.deepEqual(good.counted, { created: 1, updated: 0, held: 0 })
+  const unverified = receipt.decideCompletion({ text: fence({ status: 'completed', outcome: 'created', createdIds: ['mem-404'], checkedRange: { fromSeq: 0, throughSeq: 9 } }), wrote: 0, index, beforeIds: new Set() })
+  assert.equal(unverified.advance, false)
+  assert.equal(unverified.reasonCode, 'receipt-unverified')
+  const silent = receipt.decideCompletion({ text: '我做了不少事情。', wrote: 0, index, beforeIds: new Set() })
+  assert.equal(silent.advance, false)
+  assert.equal(silent.reasonCode, 'receipt-missing')
+})
+
+test('decideCompletion never settles a silent worker on its own', () => {
+  // 结算空正文的规则已经上移到 private.js 的调用点：那里知道「worker 一个字没说、库里也没
+  // 多出条目」这一种情形（见 tests/consolidation-fork.test.mjs 与 tests/cycle.test.mjs）。
+  // 模块层只保留一个方向的保证：没有回执就不给凭证。
+  const silent = receipt.decideCompletion({ text: '', wrote: 0 })
+  assert.equal(silent.advance, false)
+  assert.equal(silent.reasonCode, 'receipt-missing')
+  const unattributed = receipt.decideCompletion({ text: '', wrote: 2 })
+  assert.equal(unattributed.advance, false)
+  assert.match(unattributed.error, /receipt|cannot settle/i)
+})