dsh-biocore 0.3.2 → 0.4.0

package/lib/index.js

@@ -28,6 +28,7 @@ import { SERIES_ROUTE_PATH, handleSeriesRoute } from './modules/series.js'
 import { readCacheStats } from './modules/cache-stats.js'
 import { startCoreWorker, stopCoreWorker } from './core-worker.js'
 import { runAutonomyTick } from './modules/autonomy.js'
+import { drainOutbox } from './modules/standby.js'
 import { queueSessionTurn } from './modules/turn-queue.js'
 import { makeCoreSessionListener, registerCoreTurn } from './modules/core-turn.js'
 import { migrateLegacyPluginData, PLUGIN_DATA_DIR, resolveDataDir } from './modules/data-dir.js'
@@ -193,6 +194,8 @@ export function readFullConfig(dataDir) {
     rerank: normalizeRerank(source.rerank),
     expression: normalizeExpression(source.expression),
     autonomy: normalizeAutonomy(source.autonomy),
+    standby: source.standby && typeof source.standby === 'object' ? source.standby : {},
+    standbyEnabled: source.standbyEnabled === true,
     sanitize_reply: source.sanitize_reply !== false,
   }
 }
@@ -389,6 +392,10 @@ function coreConfigPayload(dataDir) {
     rerank: config.rerank,
     expression: config.expression,
     autonomy: config.autonomy,
+    standby: {
+      ...(config.standby && typeof config.standby === 'object' ? config.standby : {}),
+      standby_enabled: config.standbyEnabled === true,
+    },
     sanitize_reply: config.sanitize_reply !== false,
     switches,
     recall_mode: 'query',
@@ -762,8 +769,10 @@ export async function handleStats(req, res, options) {
   } catch { reply = null }
   const body = Object.assign({ ok: false, reason: 'core_unavailable' },
     reply && typeof reply === 'object' ? reply : {})
+  // contract migration 1: the core computes cache stats; the legacy file is a
+  // read-only fallback for one week, never a source of new numbers.
   try {
-    if (typeof opts.dataDir === 'string' && opts.dataDir) {
+    if (!body.cache && typeof opts.dataDir === 'string' && opts.dataDir) {
       body.cache = readCacheStats(opts.dataDir)
     }
   } catch { /* display only */ }
@@ -992,6 +1001,26 @@ export function apply(ctx, config) {
     keep(() => { if (timer !== null) { clearInterval(timer); timer = null } })
   }
 
+  // task-215: standby is off by default; when on, the core writes the outbox
+  // and this adapter only drains it into results.
+  if (config && config.standbyEnabled === true) {
+    let standbyTimer = null
+    const standbyTick = async () => {
+      try {
+        await runtimeAction('standby_tick', {
+          store: resolveMemoryDir(dataDir),
+          data_dir: dataDir,
+          session_id: 'standby',
+          now: Date.now() / 1000,
+        })
+        drainOutbox(dataDir)
+      } catch { /* standby never disturbs a turn */ }
+    }
+    standbyTimer = setInterval(() => { void standbyTick() }, 5 * 60 * 1000)
+    if (typeof standbyTimer.unref === 'function') standbyTimer.unref()
+    keep(() => { if (standbyTimer !== null) { clearInterval(standbyTimer); standbyTimer = null } })
+  }
+
   return () => {
     for (const dispose of disposers) {
       try { if (typeof dispose === 'function') dispose() } catch { /* ignore */ }

package/lib/modules/standby.js

@@ -0,0 +1,61 @@
+/** task-215: adapter side of standby -- read outbox, record results only.
+ *
+ * The core writes <dataDir>/proactive/outbox.jsonl. This module never decides
+ * whether to speak and never sends externally; it records one execution result
+ * per outbox row into <dataDir>/proactive/results.jsonl.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+export function proactiveDir(dataDir) {
+  return join(String(dataDir || '').trim(), 'proactive')
+}
+
+export function outboxPath(dataDir) {
+  return join(proactiveDir(dataDir), 'outbox.jsonl')
+}
+
+export function resultsPath(dataDir) {
+  return join(proactiveDir(dataDir), 'results.jsonl')
+}
+
+function readLines(path) {
+  try {
+    if (!existsSync(path)) return []
+    return readFileSync(path, 'utf8').split('\n').filter(Boolean)
+  } catch {
+    return []
+  }
+}
+
+/** Record never-seen outbox rows; returns how many were recorded. */
+export function drainOutbox(dataDir, options) {
+  const opts = options || {}
+  const rows = readLines(outboxPath(dataDir))
+  const done = readLines(resultsPath(dataDir)).length
+  if (rows.length <= done) return { ok: true, recorded: 0, pending: 0 }
+  const path = resultsPath(dataDir)
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    for (let index = done; index < rows.length; index += 1) {
+      let row = {}
+      try { row = JSON.parse(rows[index]) } catch { row = {} }
+      appendFileSync(path, JSON.stringify({
+        ts: row.ts || 0,
+        index,
+        delivered: false,
+        reason: 'outbox_only',
+        result: { ok: true, external: false },
+      }) + '\n', 'utf8')
+    }
+    return { ok: true, recorded: rows.length - done, pending: 0 }
+  } catch {
+    return { ok: false, recorded: 0, pending: rows.length - done }
+  }
+}
+
+export function standbySummary(dataDir) {
+  const outbox = readLines(outboxPath(dataDir)).length
+  const results = readLines(resultsPath(dataDir)).length
+  return { pending: Math.max(0, outbox - results), outbox, results }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-biocore",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "description": "BioCore DSH UI: per-session state tab, standalone instrument panel, /api/biocore/state, session/event one_turn updates, /bio sync.",
   "main": "lib/index.js",

package/python/biocore_memory/store/tiering.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import time
 
-TIERING_ENABLED = False
+TIERING_ENABLED = True
 HOT_BUDGET = 80
 WARM_BUDGET = 200
 TIER_UNLIMITED = 10 ** 9
@@ -12,6 +12,7 @@ HOT_AGE_SECONDS = 24 * 3600
 WARM_AGE_SECONDS = 30 * 86400
 HOT_IMPORTANCE = 0.80
 HOT_HITS = 5
+HOT_EXIT_HITS = 3  # hysteresis: a hot entry leaves only below this
 
 
 def _num(entry, keys, default=0.0):
@@ -33,8 +34,12 @@ def _age(entry, now):
     return max(0.0, float(now) - last)
 
 
-def tier_of(entry, now=None):
-    """Return 'hot' | 'warm' | 'cold'; disabled tiering is neutral ('warm')."""
+def tier_of(entry, now=None, previous=None):
+    """Return 'hot' | 'warm' | 'cold'; disabled tiering is neutral ('warm').
+
+    Hysteresis (task-36): a hot entry stays hot until hits drop below
+    HOT_EXIT_HITS, so a value hovering at the boundary cannot flicker.
+    """
     if not TIERING_ENABLED or not isinstance(entry, dict):
         return "warm"
     try:
@@ -42,6 +47,12 @@ def tier_of(entry, now=None):
         age = _age(entry, stamp)
         importance = _num(entry, ("importance",), 0.5)
         hits = _num(entry, ("hits", "visits", "visit_count"), 0.0)
+        if previous == "hot":
+            if hits >= HOT_EXIT_HITS:
+                return "hot"
+            if age <= WARM_AGE_SECONDS or hits >= 2:
+                return "warm"
+            return "cold"
         if age <= HOT_AGE_SECONDS or importance >= HOT_IMPORTANCE or hits >= HOT_HITS:
             return "hot"
         if age <= WARM_AGE_SECONDS or hits >= 2:

package/python/biocore_model/sanitize.py

@@ -23,7 +23,12 @@ class ReplySanitizer:
 
     CONTROL_TAG_PATTERNS = [
         re.compile(r"<\s*(?:bc|biocore)\b[^>]*>.*?</\s*(?:bc|biocore)\s*>", re.I | re.S),
-        re.compile(r"<\s*(?:bc|biocore)\b[^>]*>[^\n]*", re.I),
+        re.compile(r"<\s*(?:bc|biocore)\b[^>]*>[^\n]*", re.I),
+    # Reminder tags are instructions for the model, never user-visible text.
+    re.compile(r"<\s*(?:system_reminder|reminder|system)\b[^>]*>.*?</\s*(?:system_reminder|reminder|system)\s*>", re.I | re.S),
+    re.compile(r"<\s*(?:system_reminder|reminder|system)\b[^>]*>[^\n]*", re.I),
+    # Models sometimes echo the instruction header verbatim.
+    re.compile(r"^\s*【[^】]*】\s*$", re.M),
         re.compile(r"<\s*(?:thinking|think|thought|reasoning|analysis)\b[^>]*>.*?</\s*(?:thinking|think|thought|reasoning|analysis)\s*>", re.I | re.S),
         re.compile(r"<\s*(?:thinking|think|thought|reasoning|analysis)\b[^>]*>[^\n]*", re.I),
         re.compile(r"<\s*(?:思考|分析|推理|内心独白)\s*>.*?</\s*(?:思考|分析|推理|内心独白)\s*>", re.S),

package/python/biocore_model/tests/test_cache_series.py

@@ -0,0 +1,137 @@
+# -*- coding: utf-8 -*-
+"""Contract migration 1: cache stats + series are computed by the core."""
+import json
+import tempfile
+import time
+import unittest
+from pathlib import Path
+
+from biocore_runtime import cache_stats, core_state, pipeline
+
+
+class CacheCase(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.data_dir = Path(self.tmp.name) / "data"
+        self.store = self.data_dir / "memory"
+        (self.store / "sessions").mkdir(parents=True)
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def event(self, **values):
+        row = {"prompt_tokens": 100, "output_tokens": 20,
+               "cache_read": 60, "cache_write": 40}
+        row.update(values)
+        return cache_stats.record_event(self.store, row,
+                                        now=values.pop("ts", time.time()))
+
+    def test_accumulates_events(self):
+        now = time.time()
+        cache_stats.record_event(self.store, {"prompt_tokens": 10,
+            "output_tokens": 2, "cache_read": 4, "cache_write": 1}, now=now)
+        cache_stats.record_event(self.store, {"prompt_tokens": 20,
+            "output_tokens": 3, "cache_read": 6, "cache_write": 2}, now=now)
+        out = cache_stats.compute(self.store, now=now)
+        self.assertEqual(out["turns"], 2)
+        self.assertEqual(out["prompt_tokens"], 30)
+        self.assertEqual(out["output_tokens"], 5)
+        self.assertEqual(out["cache_read"], 10)
+        self.assertEqual(out["cache_write"], 3)
+        self.assertEqual(out["source"], "usage_events")
+
+    def test_hit_rate_ratio(self):
+        now = time.time()
+        cache_stats.record_event(self.store, {"prompt_tokens": 100,
+            "output_tokens": 10, "cache_read": 75, "cache_write": 25}, now=now)
+        self.assertAlmostEqual(cache_stats.compute(self.store, now=now)["hit_rate"],
+                               0.75, places=4)
+
+    def test_hit_rate_falls_back_to_prompt_tokens(self):
+        now = time.time()
+        cache_stats.record_event(self.store, {"prompt_tokens": 100,
+            "output_tokens": 10, "cache_read": 50, "cache_write": 0}, now=now)
+        self.assertAlmostEqual(cache_stats.compute(self.store, now=now)["hit_rate"],
+                               0.5, places=4)
+
+    def test_hit_rate_zero_when_empty(self):
+        self.assertEqual(cache_stats.compute(self.store)["hit_rate"], 0.0)
+
+    def test_hit_rate_is_clamped(self):
+        now = time.time()
+        cache_stats.record_event(self.store, {"prompt_tokens": 10,
+            "output_tokens": 1, "cache_read": 50, "cache_write": 0}, now=now)
+        rate = cache_stats.compute(self.store, now=now)["hit_rate"]
+        self.assertGreaterEqual(rate, 0.0)
+        self.assertLessEqual(rate, 1.0)
+
+    def test_window_excludes_old_events(self):
+        now = time.time()
+        cache_stats.record_event(self.store, {"prompt_tokens": 10,
+            "cache_read": 5}, now=now - 8 * 86400)
+        cache_stats.record_event(self.store, {"prompt_tokens": 20,
+            "cache_read": 10}, now=now)
+        out = cache_stats.compute(self.store, now=now)
+        self.assertEqual(out["turns"], 1)
+        self.assertEqual(out["prompt_tokens"], 20)
+
+    def test_legacy_file_is_read_only_fallback(self):
+        now = time.time()
+        (self.data_dir / "cache_stats.json").write_text(json.dumps({
+            "turns": 4, "prompt_tokens": 400, "output_tokens": 40,
+            "cache_read": 200, "cache_write": 200, "hit_rate": 0.5,
+            "updated_at": now}), encoding="utf-8")
+        out = cache_stats.compute(self.store, now=now)
+        self.assertEqual(out["source"], "legacy_file")
+        self.assertEqual(out["turns"], 4)
+        self.assertEqual(out["hit_rate"], 0.5)
+
+    def test_usage_event_action_appends(self):
+        out = pipeline.dispatch("usage_event", {
+            "store": str(self.store), "prompt_tokens": 30,
+            "cache_read": 15, "cache_write": 5, "now": time.time()})
+        self.assertTrue(out["ok"])
+        self.assertEqual(out["cache"]["cache_read"], 15)
+
+    def test_stats_action_includes_core_cache(self):
+        cache_stats.record_event(self.store, {"prompt_tokens": 10,
+            "cache_read": 5, "cache_write": 5}, now=time.time())
+        out = pipeline.dispatch("stats", {"store": str(self.store)})
+        self.assertIn("cache", out)
+        self.assertEqual(out["cache"]["source"], "usage_events")
+        self.assertEqual(out["cache"]["hit_rate"], 0.5)
+
+
+class SeriesCase(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.data_dir = Path(self.tmp.name) / "data"
+        self.store = self.data_dir / "memory"
+        (self.store / "sessions").mkdir(parents=True)
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_empty_series_arrays(self):
+        out = pipeline.dispatch("series", {"store": str(self.store),
+                                           "data_dir": str(self.data_dir)})
+        self.assertTrue(out["ok"])
+        for key in ("ts", "v", "tension", "warmth", "heaviness", "clarity"):
+            self.assertIsInstance(out["series"][key], list)
+            self.assertEqual(out["series"][key], [])
+
+    def test_series_points_from_core_state(self):
+        path = core_state.path_for(data_dir=str(self.data_dir))
+        now = time.time()
+        core_state.apply(path, absolute={"v": 0.2, "stress": 0.4}, now=now)
+        core_state.apply(path, absolute={"v": 0.3, "stress": 0.2}, now=now + 60)
+        out = pipeline.dispatch("series", {"store": str(self.store),
+                                           "data_dir": str(self.data_dir),
+                                           "limit": 24})
+        self.assertTrue(out["points"])
+        self.assertLessEqual(len(out["points"]), 24)
+        self.assertEqual(len(out["series"]["ts"]), len(out["points"]))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/python/biocore_model/tests/test_lifecycle.py

@@ -0,0 +1,153 @@
+# -*- coding: utf-8 -*-
+"""task-36 + task-78: tier hysteresis, reconsolidation, minimal repair loop."""
+import json
+import tempfile
+import time
+import unittest
+from pathlib import Path
+
+from biocore_memory.store import tiering
+from biocore_runtime import lifecycle, pipeline
+
+
+def write_json(path, data):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
+
+
+def entry(i, text="记得这件事", ts=None, hits=1, importance=0.5):
+    return {"id": i, "text": text, "role": "user",
+            "ts": ts or (time.time() - 3600), "importance": importance,
+            "hits": hits}
+
+
+class Case(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.data_dir = Path(self.tmp.name) / "data"
+        self.store = self.data_dir / "memory"
+        (self.store / "sessions" / "s1").mkdir(parents=True)
+        self.persona = Path(self.tmp.name) / "missing.json"
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def write_entries(self, entries):
+        write_json(self.store / "sessions" / "s1" / "memory.json",
+                   {"entries": entries})
+        return entries
+
+    def read_entries(self):
+        return json.loads((self.store / "sessions" / "s1" / "memory.json")
+                          .read_text(encoding="utf-8"))["entries"]
+
+    def payload(self, **extra):
+        data = {"store": str(self.store), "session_id": "s1",
+                "persona_profile": str(self.persona)}
+        data.update(extra)
+        return data
+
+
+class TierTest(Case):
+    def test_enter_hot_at_five_hits(self):
+        self.assertEqual(tiering.tier_of(entry("a", hits=5), now=time.time()),
+                         "hot")
+
+    def test_stays_hot_between_three_and_five(self):
+        now = time.time()
+        self.assertEqual(tiering.tier_of(entry("a", hits=4), now=now,
+                                         previous="hot"), "hot")
+
+    def test_exits_hot_below_three(self):
+        now = time.time()
+        self.assertNotEqual(tiering.tier_of(entry("a", hits=2), now=now,
+                                            previous="hot"), "hot")
+
+    def test_tick_counts_entered_exited(self):
+        now = time.time()
+        old_ts = time.time() - 3 * 86400
+        rows = [entry("a", hits=5), entry("b", hits=2, ts=old_ts)]
+        first = lifecycle.tier_tick(self.store, rows, now=now)
+        self.assertEqual(first["counts"]["hot"], 1)
+        rows[0]["hits"] = 1
+        second = lifecycle.tier_tick(self.store, rows, now=now + 1)
+        self.assertGreaterEqual(second["exited"], 1)
+        summary = lifecycle.tier_summary(self.store)
+        self.assertIn("hot", summary)
+        self.assertIn("exited", summary)
+
+
+class ReconsolidationTest(Case):
+    def test_updates_recalled_entry(self):
+        now = time.time()
+        self.write_entries([entry("a", "苹果很甜", hits=1)])
+        lifecycle.record_recall(self.store, "s1", ["a"], now=now)
+        result = lifecycle.reconsolidate(self.store, now=now + 60)
+        self.assertEqual(result["updated"], 1)
+        row = self.read_entries()[0]
+        self.assertGreater(row.get("regenerated_at", 0), 0)
+        self.assertEqual(row.get("reconsolidation_count"), 1)
+        self.assertGreater(row.get("importance", 0), 0.5)
+        self.assertEqual(len(self.read_entries()), 1)
+
+    def test_idempotent_second_call(self):
+        now = time.time()
+        self.write_entries([entry("a", hits=1)])
+        lifecycle.record_recall(self.store, "s1", ["a"], now=now)
+        lifecycle.reconsolidate(self.store, now=now + 60)
+        again = lifecycle.reconsolidate(self.store, now=now + 61)
+        self.assertEqual(again["updated"], 0)
+        self.assertGreaterEqual(again["skipped"], 1)
+
+    def test_window_expires(self):
+        now = time.time()
+        self.write_entries([entry("a", hits=1)])
+        lifecycle.record_recall(self.store, "s1", ["a"], now=now - 7 * 3600)
+        result = lifecycle.reconsolidate(self.store, now=now)
+        self.assertEqual(result["updated"], 0)
+        self.assertEqual(result["reason"], "window")
+
+    def test_no_recall_ids(self):
+        self.write_entries([entry("a")])
+        result = lifecycle.reconsolidate(self.store, now=time.time())
+        self.assertEqual(result["updated"], 0)
+
+
+class RepairTest(Case):
+    def test_arm_and_consume_once(self):
+        now = time.time()
+        self.assertTrue(lifecycle.arm_repair(self.store, "boundary", now=now))
+        lines = lifecycle.repair_lines(self.store, now=now + 1)
+        self.assertTrue(lines)
+        self.assertTrue(any("修复" in line for line in lines))
+        self.assertEqual(lifecycle.repair_lines(self.store, now=now + 2), [])
+
+    def test_cooldown_blocks_rearm(self):
+        now = time.time()
+        lifecycle.arm_repair(self.store, "boundary", now=now)
+        lifecycle.repair_lines(self.store, now=now + 1)
+        self.assertFalse(lifecycle.arm_repair(self.store, "boundary",
+                                             now=now + 2))
+
+    def test_expired_repair_returns_empty(self):
+        now = time.time()
+        lifecycle.arm_repair(self.store, "boundary", now=now)
+        self.assertEqual(lifecycle.repair_lines(self.store,
+                                                now=now + 31 * 60), [])
+
+    def test_state_exposes_lifecycle(self):
+        now = time.time()
+        self.write_entries([entry("a", hits=5)])
+        lifecycle.record_recall(self.store, "s1", ["a"], now=now)
+        lifecycle.tier_tick(self.store, [entry("a", hits=5)], now=now)
+        pipeline.dispatch("turn_end", self.payload(
+            user_text="好", assistant_text="嗯。", capture=False))
+        body = pipeline.dispatch("state", self.payload())["state"]
+        self.assertIn("tiers", body)
+        self.assertIn("reconsolidation", body)
+        self.assertIn("repair", body)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/python/biocore_model/tests/test_retrieval_plus.py

@@ -0,0 +1,143 @@
+# -*- coding: utf-8 -*-
+"""task-62: normalized channels, chunks, shards, predictive exploration."""
+import json
+import tempfile
+import time
+import unittest
+from pathlib import Path
+
+from biocore_runtime import pipeline, retrieval_plus as rp
+
+
+def entry(i, text, ts=None):
+    return {"id": i, "text": text, "role": "user",
+            "ts": ts if ts is not None else time.time()}
+
+
+class Case(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.data_dir = Path(self.tmp.name) / "data"
+        self.store = self.data_dir / "memory"
+        (self.store / "sessions" / "s1").mkdir(parents=True)
+        self.now = time.time()
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+
+class NormalizeTest(Case):
+    def test_min_max(self):
+        self.assertEqual(rp.normalize([0.0, 5.0, 10.0]), [0.0, 0.5, 1.0])
+
+    def test_flat_positive_is_one(self):
+        self.assertEqual(rp.normalize([2.0, 2.0]), [1.0, 1.0])
+
+    def test_flat_zero_is_zero(self):
+        self.assertEqual(rp.normalize([0.0, 0.0]), [0.0, 0.0])
+
+    def test_channels_are_independent(self):
+        rows = [entry("a", "苹果 苹果 苹果"), entry("b", "香蕉")]
+        ranked = rp.rank(self.store, "s1", "苹果", rows, now=self.now)
+        by_id = {item["entry"]["id"]: item for item in ranked}
+        self.assertEqual(by_id["a"]["channels"]["bm25"], 1.0)
+        self.assertEqual(by_id["b"]["channels"]["bm25"], 0.0)
+        self.assertIn("vector", by_id["a"]["channels"])
+
+
+class ChunkTest(Case):
+    def test_sentences_split(self):
+        chunks = rp.split_chunks("第一句。第二句！第三句？")
+        self.assertEqual(len(chunks), 3)
+
+    def test_index_persists(self):
+        rp.build_chunks(self.store, [entry("a", "第一句。第二句。")])
+        doc = json.loads((self.data_dir / "retrieval" / "chunks.json")
+                         .read_text(encoding="utf-8"))
+        self.assertIn("a", doc["entries"])
+        self.assertEqual(len(doc["entries"]["a"]["chunks"]), 2)
+
+    def test_best_chunk_snippet(self):
+        rows = [entry("a", "今天很累。苹果很甜，想再买一次。")]
+        ranked = rp.rank(self.store, "s1", "苹果", rows, now=self.now)
+        self.assertIn("苹果", ranked[0]["chunk"])
+        self.assertGreaterEqual(ranked[0]["chunk_hits"], 1)
+
+
+class ShardTest(Case):
+    def test_session_shard(self):
+        shards = rp.assign_shards(self.store, [entry("a", "x")], session_id="s1")
+        self.assertEqual(shards["a"], "s-s1")
+        self.assertTrue((self.data_dir / "retrieval" / "shards"
+                         / "s-s1.json").exists())
+
+    def test_month_shard_without_session(self):
+        row = entry("a", "x", ts=time.mktime((2024, 3, 15, 12, 0, 0, 0, 0, -1)))
+        shards = rp.assign_shards(self.store, [row])
+        self.assertEqual(shards["a"], "2024-03")
+
+    def test_rollover_over_cap(self):
+        rows = [entry(str(index), "x") for index in range(5)]
+        shards = rp.assign_shards(self.store, rows, session_id="s1", limit=2)
+        names = list(shards.values())
+        self.assertEqual(names.count("s-s1"), 2)
+        self.assertIn("s-s1-r1", names)
+        self.assertIn("s-s1-r2", names)
+
+
+class PredictionTest(Case):
+    def test_expectation_weights(self):
+        rp.record_query(self.store, "苹果 咖啡")
+        rp.record_query(self.store, "苹果 咖啡 甜")
+        rows = [entry("expected", "苹果 咖啡"), entry("novel", "维修 螺丝")]
+        ranked = rp.rank(self.store, "s1", "苹果", rows, now=self.now)
+        by_id = {item["entry"]["id"]: item for item in ranked}
+        self.assertGreater(by_id["novel"]["expectation_weight"],
+                           by_id["expected"]["expectation_weight"])
+
+    def test_topic_history_bounded(self):
+        for index in range(25):
+            rp.record_query(self.store, "话题%d" % index)
+        doc = json.loads((self.data_dir / "topic_history.json")
+                         .read_text(encoding="utf-8"))
+        self.assertEqual(len(doc["turns"]), 20)
+
+    def test_off_fallback(self):
+        rows = [entry("a", "苹果"), entry("b", "香蕉")]
+        ranked = rp.rank(self.store, "s1", "苹果", rows, now=self.now,
+                         enabled=False)
+        self.assertEqual([item["entry"]["id"] for item in ranked], ["a", "b"])
+        self.assertEqual(ranked[0]["reason"], "fallback")
+
+
+class DebugTest(Case):
+    def test_debug_rows_and_state(self):
+        rows = [entry("a", "苹果很甜"), entry("b", "香蕉")]
+        ranked = rp.rank(self.store, "s1", "苹果", rows, now=self.now)
+        rp.record_debug(self.store, "苹果", ranked, now=self.now)
+        summary = rp.summary(self.store)
+        self.assertEqual(summary["query"], "苹果")
+        for key in ("channels", "reason", "chunk", "chunk_hits", "shard"):
+            self.assertIn(key, summary["rows"][0])
+        body = pipeline.dispatch("state", {
+            "store": str(self.store), "session_id": "s1",
+            "persona_profile": str(Path(self.tmp.name) / "missing.json")})["state"]
+        self.assertIn("recall_debug", body)
+
+    def test_switch_off_keeps_engine_order(self):
+        rows = [entry("old", "苹果 很甜", ts=self.now - 100),
+                entry("new", "苹果 今天", ts=self.now)]
+        (self.store / "sessions" / "s1" / "memory.json").write_text(
+            json.dumps({"entries": rows}), encoding="utf-8")
+        on = pipeline.inject_block("s1", str(self.store), query="苹果",
+                                   mode="query", top_k=2)
+        path = self.data_dir / "core_config.json"
+        path.write_text(json.dumps({"switches": {"retrieval_plus": False}}),
+                        encoding="utf-8")
+        off = pipeline.inject_block("s1", str(self.store), query="苹果",
+                                    mode="query", top_k=2)
+        self.assertEqual(len(on["ids"]), len(off["ids"]))
+
+
+if __name__ == "__main__":
+    unittest.main()