@modusensus/dsh-mneme 0.10.0 → 0.11.0

package/test/quality-backfill.test.js

@@ -0,0 +1,290 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { DatabaseSync } from "node:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createStore } from "../src/store.js";
+import { REPETITION_THRESHOLD, repetitionRatio } from "../src/quality-filter.js";
+
+// 一次性迁移：撤回旧重复度度量留下的 repetitive 误判（#560 的收尾）。
+//
+// 这批用例锁的不是「迁移会改标签」，而是它的四条边界——每一条单独失守，都会让这次回填
+// 变成比它要修的问题更大的问题：
+//   1. 只动**新度量下不重复**的行。真重复（trigram > 0.7）的标签是对的，重算它就是把
+//      「撤销误判」偷偷换成「重新判一遍」。
+//   2. 分数只升不降（max(存量, 重建)）。存量分不是纯标签函数，直接用重建值会把历史上
+//      被别的路径改过分的行往下压。
+//   3. 归档位、updated_at、content_hash 一个都不许碰——归档是另一个决定；刷 updated_at
+//      会让整库镜像重排并拆掉人工编辑的版本令牌；重算 content_hash 会把一次标签修订
+//      变成一次内容修订。
+//   4. 登记后不再跑。它不是「条件恒等幂等」，而是「一次性」：登记行就是判据，否则每次
+//      打开都要全表扫一遍（本机 12,827 行实测 36.7ms，而 createStore 稳态 3.3ms）。
+
+const LONG_NOTE = [
+  "公共政策执行的偏差并不是单一原因造成的。从组织理论看，执行机构的层级结构会稀释政策意图，",
+  "每一层都会按本层的信息与激励重新解释一次指令，到了末梢，任务的原始目标常常只剩下一个名称。",
+  "从激励结构看，考核指标一旦被简化，执行者就会把可测量的部分当作全部，把不可测量的部分留空。",
+  "从资源依赖看，政策落地需要财政、人事、信息三条线的配合，任何一条线短缺，执行都会退回到",
+  "最容易完成的那部分动作，于是出现「有动作、无效果」。因此讨论执行偏差时，与其寻找一个总原因，",
+  "不如分别问：目标在传递过程中被改写了什么，考核把哪些行为变成了理性选择，资源缺口让哪个环节",
+  "先断掉。这三问分别对应组织、激励与资源三个解释层次，也对应三类不同的纠偏手段：前者靠信息回流",
+  "与目标澄清，中者靠指标设计与问责边界，后者靠预算与能力建设。把它们混在一起谈，得到的往往",
+  "是「重视不够」这类无法落地的结论。"
+].join("").repeat(2);
+const REPETITIVE = "好".repeat(40);
+
+test("迁移：长中文散文的 repetitive 误判被撤回，分数与 low_quality 跟着修", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-qbackfill-"));
+  const dbPath = join(dir, "legacy.db");
+  try {
+    // 前置自检：这一行必须是「旧度量判重复、新度量不判重复」的那一类，否则用例测不到东西。
+    assert.ok(
+      repetitionRatio(LONG_NOTE.trim()) < REPETITION_THRESHOLD,
+      "sample must read as non-repetitive under the new metric"
+    );
+    assert.ok(repetitionRatio(REPETITIVE) > REPETITION_THRESHOLD, "control sample must read as repetitive");
+
+    const legacy = new DatabaseSync(dbPath);
+    // quality_score 与 content_hash 都先建好：这条迁移的判据依赖前者，而后者用它当
+    // 「不许被碰」的哨兵值（若迁移顺手重算内容哈希，哨兵就变了）。
+    legacy.exec(
+      "CREATE TABLE memories (" +
+        "id TEXT PRIMARY KEY, type TEXT NOT NULL, title TEXT NOT NULL, content TEXT NOT NULL," +
+        "tags TEXT NOT NULL DEFAULT '[]', importance INTEGER NOT NULL DEFAULT 3," +
+        "forgotten INTEGER NOT NULL DEFAULT 0, archived INTEGER NOT NULL DEFAULT 0," +
+        "source TEXT, quality_score REAL, content_hash TEXT," +
+        "created_at TEXT NOT NULL, updated_at TEXT NOT NULL)"
+    );
+    const insert = legacy.prepare(
+      "INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, quality_score, content_hash, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, 0, ?, NULL, ?, ?, ?, ?)"
+    );
+    const add = (id, content, tags, score, archivedFlag, updatedAt) =>
+      insert.run(id, "project", "样本 " + id, content, tags, 3, archivedFlag ? 1 : 0, score, "sentinel-" + id,
+        "2026-01-01T00:00:00.000Z", updatedAt);
+
+    // 被长文本误判：100 − 50 = 50。
+    add("misjudged", LONG_NOTE, '["repetitive","low_quality"]', 50, false, "2026-01-01T00:00:00.000Z");
+    // 真重复：新度量下依旧 > 0.7，标签有效，一个字段都不该动。
+    add("really-repetitive", REPETITIVE, '["repetitive","low_quality"]', 50, false, "2026-01-02T00:00:00.000Z");
+    // 归档行：分数与标签照修，归档位不许动（撤销归档是另一个决定）。
+    add("archived-misjudged", LONG_NOTE, '["repetitive","low_quality"]', 50, true, "2026-01-03T00:00:00.000Z");
+    // 只升不降：重建值 100 − 45 − 15 = 40 < 存量 55。
+    add("keep-higher", LONG_NOTE, '["meta","self_referential","repetitive"]', 55, false, "2026-01-04T00:00:00.000Z");
+    // 解析不了 / 不是数组：打开库时抛异常等于插件整树起不来，一律原样放过。
+    add("broken-tags", LONG_NOTE, '["repetitive"', 50, false, "2026-01-05T00:00:00.000Z");
+    add("not-array", LONG_NOTE, '{"repetitive":true}', 50, false, "2026-01-06T00:00:00.000Z");
+    // 子串但非标签：LIKE 只做候选裁剪，真正的判据是下一段的 tags.includes("repetitive")。
+    // 带引号形态的意义只是少解析几条坏 JSON，误伤由 includes 兜住。
+    add("substring", LONG_NOTE, '["low_quality_repetitive"]', 50, false, "2026-01-07T00:00:00.000Z");
+    // 撤掉 repetitive 后仍 < 30（100 − 80 = 20）→ low_quality 必须留着：它是分数的派生态。
+    add("still-low", LONG_NOTE, '["duplicate","repetitive","low_quality"]', 20, false, "2026-01-08T00:00:00.000Z");
+    legacy.close();
+
+    const store = createStore(dbPath);
+    const got = (id) => store.getById(id);
+    const raw = (id) => store.db.prepare("SELECT * FROM memories WHERE id = ?").get(id);
+
+    assert.deepEqual(got("misjudged").tags, [], "repetitive 与 low_quality 都该撤掉");
+    assert.equal(got("misjudged").quality_score, 100);
+    assert.equal(got("misjudged").archived, false);
+
+    assert.deepEqual(got("really-repetitive").tags, ["repetitive", "low_quality"], "真重复的标签是对的");
+    assert.equal(got("really-repetitive").quality_score, 50, "真重复的 50 分也是它应得的");
+
+    assert.deepEqual(got("archived-misjudged").tags, []);
+    assert.equal(got("archived-misjudged").quality_score, 100);
+    assert.equal(got("archived-misjudged").archived, true, "修分数不等于撤销归档");
+
+    assert.deepEqual(got("keep-higher").tags, ["meta", "self_referential"]);
+    assert.equal(got("keep-higher").quality_score, 55, "重建值低于存量时保留存量，绝不往下压");
+
+    assert.equal(raw("broken-tags").tags, '["repetitive"');
+    assert.equal(raw("not-array").tags, '{"repetitive":true}');
+    assert.deepEqual(got("substring").tags, ["low_quality_repetitive"]);
+
+    assert.deepEqual(got("still-low").tags, ["duplicate", "low_quality"]);
+    assert.equal(got("still-low").quality_score, 20);
+
+    // 三项「不许被碰」的证据：updated_at 原值、content_hash 哨兵值、generation 不涨。
+    assert.equal(raw("misjudged").updated_at, "2026-01-01T00:00:00.000Z",
+      "回填不许刷 updated_at：镜像按它排序，人工编辑也拿它当版本令牌");
+    assert.equal(raw("misjudged").content_hash, "sentinel-misjudged", "回填不是内容修订，不许重算内容哈希");
+    // mirror_state 行由 incrementGeneration 懒建（INSERT OR IGNORE）：没有行就等于 0。
+    const gen = store.db.prepare("SELECT generation FROM mirror_state WHERE id = 'main'").get();
+    assert.equal(gen?.generation ?? 0, 0, "回填不是业务写，不许记镜像债（那会触发全量重渲染）");
+
+    const record = store.db
+      .prepare("SELECT applied_at FROM applied_migrations WHERE id = ?")
+      .get("2026-11-quality-repetitive-backfill");
+    assert.ok(record, "迁移必须登记，否则每次打开都要全表扫一遍");
+    assert.match(record.applied_at, /^\d{4}-\d{2}-\d{2}T/);
+    store.close();
+
+    // 再开一次：登记行在，整块跳过。故意把一条已经修好的行重新打回误判状态，它必须
+    // **留着**——这条迁移是一次性的，不是「条件恒等幂等」（后者每次打开都要扫全表）。
+    const re = new DatabaseSync(dbPath);
+    re.prepare("UPDATE memories SET tags = '[\"repetitive\"]', quality_score = 50 WHERE id = 'misjudged'").run();
+    re.close();
+    const again = createStore(dbPath);
+    assert.deepEqual(again.getById("misjudged").tags, ["repetitive"], "登记后不再跑：重开不得二次改写");
+    assert.equal(again.getById("misjudged").quality_score, 50);
+    again.close();
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// 第二批边界：分批、原文判据、原型链查表。三条都不是「好看一点」，各自对应一种会静默
+// 写坏数据或漏修的形态——
+//   * 分批：候选行带全文，一次 .all() 把行数 × 正文长度全攒在内存，且一次超大 WAL 提交；
+//   * 原文判据：已降级的行 content 只是前 120 字摘要，拿摘要判重复正好会放过「前缀干净、
+//     后段大量重复」——旧度量误判最多的那一类；
+//   * 原型链查表：SIGNAL_DEDUCTIONS 是对象字面量，查 constructor 拿到的是原型上的函数，
+//     `?? 0` 兜不住，分数会算成 NaN 再写进 REAL 列。
+test("迁移：分批翻页、按原文判重复、只减自有扣分键", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-qbackfill2-"));
+  const dbPath = join(dir, "legacy.db");
+  try {
+    assert.ok(repetitionRatio(LONG_NOTE.trim()) < REPETITION_THRESHOLD, "fixture: 长文必须不重复");
+    assert.ok(repetitionRatio(REPETITIVE) > REPETITION_THRESHOLD, "fixture: 填充分必须重复");
+
+    const legacy = new DatabaseSync(dbPath);
+    legacy.exec(
+      "CREATE TABLE memories (" +
+        "id TEXT PRIMARY KEY, type TEXT NOT NULL, title TEXT NOT NULL, content TEXT NOT NULL," +
+        "tags TEXT NOT NULL DEFAULT '[]', importance INTEGER NOT NULL DEFAULT 3," +
+        "forgotten INTEGER NOT NULL DEFAULT 0, archived INTEGER NOT NULL DEFAULT 0," +
+        "source TEXT, quality_score REAL, content_hash TEXT, _full_content TEXT," +
+        "created_at TEXT NOT NULL, updated_at TEXT NOT NULL)"
+    );
+    const insert = legacy.prepare(
+      "INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, quality_score, content_hash, _full_content, created_at, updated_at) VALUES (?, 'project', ?, ?, ?, 3, 0, 0, NULL, ?, NULL, ?, '2026-01-01T00:00:00.000Z', '2026-01-01T00:00:00.000Z')"
+    );
+    // 260 条跨过 BATCH=200，逼第二轮翻页真的发生（只有一轮的话分批逻辑等于没测）。
+    for (let i = 0; i < 260; i++) {
+      insert.run("bulk-" + String(i).padStart(3, "0"), "批量 " + i, LONG_NOTE, '["repetitive","low_quality"]', 50, null);
+    }
+    // 已降级：content 是前 120 字摘要（这里刻意给一段不重复的摘要），原文在 _full_content
+    // 且它才是真重复的那一类。按原文判 → 标签保留；按摘要判 → 会被误撤。
+    const summary = "这段摘要本身很短，字符分布也正常，按它判重复永远不会命中。" + "公共政策执行的偏差并不是单一原因造成的。".repeat(2);
+    insert.run("demoted", "降级行", summary, '["repetitive","low_quality"]', 50, REPETITIVE);
+    // 原型链标签：constructor 不在自有键里，一分都不该扣（扣了就是 NaN）。
+    insert.run("proto-tag", "原型链标签", LONG_NOTE, '["repetitive","constructor"]', 50, null);
+    // 非字符串元素：Object.hasOwn 会对它做属性键转换并抛 TypeError。这里没有任何 catch，
+    // 异常会直接让 createStore 中止——插件整树起不来，且登记行永远写不上、每次打开都重撞。
+    insert.run("obj-tag", "对象标签", LONG_NOTE, '["repetitive",{"toString":1}]', 50, null);
+    legacy.close();
+
+    const store = createStore(dbPath);
+    try {
+      const raw = (id) => store.db.prepare("SELECT * FROM memories WHERE id = ?").get(id);
+      // 260 条全修完，且不含任何 null 分（NaN 会被写成 NULL）。
+      const bulk = store.db
+        .prepare("SELECT COUNT(*) AS c FROM memories WHERE id LIKE 'bulk-%' AND tags = '[]' AND quality_score = 100")
+        .get().c;
+      assert.equal(bulk, 260, "跨批次的行必须逐批全部修完");
+      const nulls = store.db
+        .prepare("SELECT COUNT(*) AS c FROM memories WHERE quality_score IS NULL")
+        .get().c;
+      assert.equal(nulls, 0, "分数算成 NaN 会落成 NULL，这里必须是 0");
+
+      const demoted = raw("demoted");
+      assert.deepEqual(JSON.parse(demoted.tags), ["repetitive", "low_quality"], "按摘要判会把这条原文重复的行误撤");
+      assert.equal(demoted.quality_score, 50, "原文仍重复 → 分数与标签一起保持原样");
+      assert.equal(demoted._full_content, REPETITIVE, "判据读原文不等于改原文");
+      assert.ok(demoted.content.startsWith("这段摘要"), "content 仍是摘要，迁移不许顺手恢复原文");
+
+      // 整条原样放过（与坏 tags 同一策略）：本迁移不该顺手重写一个自己解析不了的值。
+      assert.equal(raw("obj-tag").tags, '["repetitive",{"toString":1}]', "非字符串标签不许碰，更不许让它把打开库搞崩");
+      assert.equal(raw("obj-tag").quality_score, 50);
+
+      const proto = raw("proto-tag");
+      assert.deepEqual(JSON.parse(proto.tags), ["constructor"], "repetitive 撤掉，其余标签原样保留");
+      // constructor 不是自有扣分键 → 一分不扣，重建值 100；存量 50 是旧误判压出来的，
+      // 取 max 抬回 100。若误按原型链扣分，这里会是 NaN → 写入 NULL，下面的断言就抓它。
+      assert.equal(proto.quality_score, 100, "constructor 不得扣分：重建值应为满分");
+    } finally {
+      store.close();
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// 第三条边界：CAS 落空的行这一趟没修到，那就不许登记「已完成」——登记行是「这条迁移
+// 跑完了」的唯一证据，写早了，那条行会带着旧分与旧标签一直留在库里，再没人回头看它。
+// 这里用 AFTER UPDATE 触发器造**确定性**的 CAS 落空（不用定时器）：cur-a 的 rowid 在前，
+// 它一被改写就分别去改 cur-b 的 tags 与 cur-c 的正文，于是这两行的 UPDATE 因 WHERE 不匹配
+// 而 changes = 0。两条分开测，是因为它们各自对应 CAS 的一个条件：cur-b 验 tags，
+// cur-c 验正文——只校验 tags/quality_score 时，cur-c 那种「正文被换成重复文本、另两列没动」
+// 的情况会原地通过，把本该保留的 repetitive 撤掉。
+test("迁移：CAS 落空时不写登记行，下次打开整条重跑", () => {
+  const dir = mkdtempSync(join(tmpdir(), "dsh-mneme-qbackfill3-"));
+  const dbPath = join(dir, "legacy.db");
+  try {
+    assert.ok(repetitionRatio(LONG_NOTE.trim()) < REPETITION_THRESHOLD, "fixture: 长文必须不重复");
+
+    const legacy = new DatabaseSync(dbPath);
+    legacy.exec(
+      "CREATE TABLE memories (" +
+        "id TEXT PRIMARY KEY, type TEXT NOT NULL, title TEXT NOT NULL, content TEXT NOT NULL," +
+        "tags TEXT NOT NULL DEFAULT '[]', importance INTEGER NOT NULL DEFAULT 3," +
+        "forgotten INTEGER NOT NULL DEFAULT 0, archived INTEGER NOT NULL DEFAULT 0," +
+        "source TEXT, quality_score REAL, content_hash TEXT," +
+        "created_at TEXT NOT NULL, updated_at TEXT NOT NULL)"
+    );
+    // content_hash 给非空哨兵：这一列的存量回填跑在本条迁移之前，也会 UPDATE memories，
+    // 若留 NULL 就会提前触发下面的触发器、把 cas 冲突挪到错误的位置。
+    const insert = legacy.prepare(
+      "INSERT INTO memories (id, type, title, content, tags, importance, forgotten, archived, source, quality_score, content_hash, created_at, updated_at) VALUES (?, 'project', ?, ?, ?, 3, 0, 0, NULL, 50, ?, '2026-01-01T00:00:00.000Z', '2026-01-01T00:00:00.000Z')"
+    );
+    insert.run("cur-a", "样本 A", LONG_NOTE, '["repetitive","low_quality"]', "sentinel-a");
+    insert.run("cur-b", "样本 B", LONG_NOTE, '["repetitive","low_quality"]', "sentinel-b");
+    insert.run("cur-c", "样本 C", LONG_NOTE, '["repetitive","low_quality"]', "sentinel-c");
+    // 只认 cur-a：别的 UPDATE 不该引发冲突，否则测到的就不是本条迁移的 CAS 了。
+    const replaced = '["repetitive","meta"]';
+    legacy.exec(
+      "CREATE TRIGGER cas_conflict AFTER UPDATE ON memories WHEN NEW.id = 'cur-a' " +
+        "BEGIN " +
+        "UPDATE memories SET tags = '" + replaced + "' WHERE id = 'cur-b'; " +
+        "UPDATE memories SET content = '" + REPETITIVE + "' WHERE id = 'cur-c'; " +
+        "END;"
+    );
+    legacy.close();
+
+    const store = createStore(dbPath);
+    try {
+      // cur-a 修好了（它就是触发源），cur-b 的 CAS 落空、原样留着。
+      assert.deepEqual(store.getById("cur-a").tags, [], "触发源那一行本身照常修好");
+      assert.deepEqual(store.getById("cur-b").tags, ["repetitive", "meta"], "tags 变了：CAS 落空的行这一趟不许被覆盖");
+      assert.deepEqual(store.getById("cur-c").tags, ["repetitive", "low_quality"],
+        "只有正文变了也得挡下：判据读的是正文，不校验它就会把该保留的 repetitive 撤掉");
+      assert.equal(store.getById("cur-c").content, REPETITIVE, "迁移不许顺手把正文改回去");
+      const mark = store.db
+        .prepare("SELECT 1 FROM applied_migrations WHERE id = ?")
+        .get("2026-11-quality-repetitive-backfill");
+      assert.equal(mark, undefined, "还有行没修到时不许登记：登记行一写，它就再也不会被处理");
+    } finally {
+      store.close();
+    }
+
+    // 再开一次：cur-a 已不是候选（repetitive 已撤），触发器不再开火，cur-b 这次能修好、
+    // 登记行也才写上——「重跑」而不是「放弃」，这是不重试、只推迟登记的完整语义。
+    const again = createStore(dbPath);
+    try {
+      assert.deepEqual(again.getById("cur-b").tags, ["meta"], "重跑时补上落空的那一行");
+      // cur-c 的正文已被换成真重复文本：重跑时判据看到它是真重复，标签就该留着——
+      // 这条顺带证明「重跑」不是「无条件撤销」，判据每次都重新读当次正文。
+      assert.deepEqual(again.getById("cur-c").tags, ["repetitive", "low_quality"], "重跑按当次正文重新判");
+      const mark = again.db
+        .prepare("SELECT 1 FROM applied_migrations WHERE id = ?")
+        .get("2026-11-quality-repetitive-backfill");
+      assert.ok(mark, "没有落空之后才登记");
+    } finally {
+      again.close();
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/test/quality-filter.test.js

@@ -6,7 +6,8 @@ import {
   evaluateMemoryQuality,
   META_MEMORY_RE,
   textSimilarity,
-  dedupRatio
+  REPETITION_THRESHOLD,
+  repetitionRatio
 } from "../src/quality-filter.js";
 
 // Bug7: rule-based memory quality filter. Gated on
@@ -107,14 +108,122 @@ test("injectCandidates: degraded memory ranks below a healthy preference", () =>
     "degraded memory is demoted below the healthy one");
 });
 
-test("exported helpers behave (meta regex, similarity, dedup ratio)", () => {
+test("exported helpers behave (meta regex, similarity, repetition ratio)", () => {
   assert.ok(META_MEMORY_RE.test("总结一下刚才的对话"));
   assert.ok(META_MEMORY_RE.test("作为AI助手，我需要记住"));
   assert.ok(!META_MEMORY_RE.test("用户喜欢喝咖啡"));
   assert.equal(textSimilarity("猫咪喜欢晒太阳", "猫咪喜欢晒太阳"), 1);
   assert.ok(textSimilarity("猫咪喜欢晒太阳", "完全不同的内容") < 0.3);
-  assert.ok(dedupRatio("哈哈哈哈哈哈") < 0.3, "repetitive filler has low dedup ratio");
-  assert.ok(dedupRatio("一句信息量足够的话") > 0.3);
+  assert.ok(repetitionRatio("哈哈哈哈哈哈") > REPETITION_THRESHOLD, "repetitive filler is flagged");
+  assert.ok(repetitionRatio("一句信息量足够的话") < REPETITION_THRESHOLD, "normal prose is not");
+});
+
+// --- repetition is measured by trigrams, not by unique-chars/total ---
+//
+// The v0.7.12 measure (uniqueChars / length) was a function of LENGTH: Chinese
+// prose draws from a few hundred common characters, so the ratio decays toward 0
+// as text grows. On a real 12,827-row library it fell under the old 0.3 gate for
+// 94% of 800-2000 char memories and 100% of those over 2000 chars — long notes
+// were tagged "repetitive" for being long. These locks keep that from coming
+// back; the fixture below is a genuine regression sample (old ratio 0.291 < 0.3,
+// trigram ratio 0.060), not a synthetic one.
+
+const LONG_NOTE = [
+  "韦伯的科层制理论把理想型官僚组织拆成几个可检验的特征：职务分工固定、权责由成文规则界定、层级节制形成命令链条、任职者以技术资格选拔、薪酬按职级而非个人关系发放、公文与档案构成组织运行的书面基础。这套设计的目的不是效率本身，而是把统治的随意性关进规则的笼子，让命令的执行可以预期、可以追责。因此科层制的优点与缺点来自同一个源头：规则化带来稳定性，也带来僵化；非人格化带来公平，也带来冷漠。默顿对这一点的处理很典型，他提出目标置换的概念，说规则本来是达成目标的手段，运行久了就变成组织成员直接追求的目的，于是遵守程序本身成了绩效，组织对外部变化的反应速度下降。尼斯坎南则从经济人假设出发，把官僚视为预算最大化的理性行动者，用双边垄断模型解释为什么机构规模倾向于扩张而不是收缩，这与公共选择学派把政治过程还原为交换过程的做法一致。新制度主义的三条支流各有侧重：历史制度主义关心关键节点与路径依赖，强调早期制度选择如何锁定后续的可能性集合；社会学制度主义关心合法性机制，认为组织采纳某种结构往往是为了显得正当，而不是因为它在技术上更有效，于是出现制度同构的三种压力，即强制、模仿与规范；理性选择制度主义关心规则如何改变行动者的激励结构，把制度看成博弈的约束条件而非博弈的结果。奥斯特罗姆的公共池塘资源研究提供了另一条路径，她通过大量案例归纳出自主治理的八项设计原则，包括边界清晰、规则与本地条件相适应、集体选择安排的参与性、监督、渐进惩罚、冲突解决机制、对组织权的最低限度承认以及嵌套式单位的衔接，用来说明国家与市场之外还存在第三条可能的治理路径。",
+  "公共政策的过程模型把政策生命周期切分成议程设定、方案形成、决策、执行、评估与终结几个阶段，好处是便于把一个连续的过程切开来观察，代价是它暗示阶段之间存在清晰的边界，而现实里议程往往在方案已经形成之后才被重新打开。金登的多源流框架对此做了修正，他用问题流、政策流与政治流三股彼此独立的溪流来解释议程的突然开启，当三股溪流在某个政策窗口处耦合，机会便出现，此时政策企业家的工作是把早已在政策共同体里流通的备选方案迅速挂到窗口上，因此所谓偶然的决策其实有长期的准备在前。间断平衡理论从另一个角度解释同一批现象，它注意到政策在很长时间里只有渐进调整，偶尔出现剧烈的方向改变，原因在于政策子系统被少数关注同一议题的行动者所垄断，一旦外部注意力被聚焦事件拉进来，子系统被打开，宏观政治的力量就会直接作用到原先封闭的领域。执行研究则提醒我们，政策文本与政策结果之间存在一个由基层官僚填充的空间，李普斯基观察到街头官僚在工作中必须处理个案，而个案的具体性迫使他们行使裁量，裁量的累积效果在某种意义上就是政策本身，这与自上而下的执行观形成对照，后者假设目标由上层确定、下级只负责忠实实现。",
+  "把这三条支流放在一起看，它们的差别不在是否承认制度重要，而在制度以什么方式起作用。历史制度主义把制度看成时间中的结构，关注的是某个早期选择如何通过正反馈机制把自己固化下来，因此它最擅长解释为什么两个起点相似的体系会走向不同的终点，也最容易被批评为事后叙事，因为路径依赖往往只能在结果已经出现之后才被指认出来。社会学制度主义把制度看成意义的载体，组织的结构被采纳不一定因为它提高了效率，而因为它在一个组织场域里被认作正当，于是同构的压力从三个方向来：上级的强制、同行的模仿、专业共同体的规范。这一支最有解释力的是那些效率解释失效的现象，比如为什么不同国家的政府部门会长得越来越像，哪怕它们面对的公共问题并不相同。理性选择制度主义把制度看成激励的约束，行动者的偏好被视为给定，制度的作用是改变行动的收益矩阵，这一支的优点是模型清晰、可推演，缺点是把偏好的形成过程留在模型之外，而偏好的形成往往正是政治最要紧的部分。三种解释不是互斥的，处理同一个案例时它们常常各自说对一部分，问题在于研究者愿意为哪一种解释放弃信息量。"
+].join("");
+
+test("repetitionRatio: a long Chinese note is not repetitive (length no longer reads as repetition)", () => {
+  // Guard the sample itself: it must still be long enough and character-diverse
+  // enough that the OLD measure failed it — otherwise this proves nothing.
+  const legacyRatio = new Set(LONG_NOTE).size / LONG_NOTE.length;
+  assert.ok(LONG_NOTE.length > 1500, "fixture should be long, got " + LONG_NOTE.length);
+  assert.ok(legacyRatio < 0.3,
+    "fixture must still trip the old gate, got " + legacyRatio.toFixed(3) + "; if it no longer does, replace the sample");
+
+  const ratio = repetitionRatio(LONG_NOTE);
+  assert.ok(ratio < REPETITION_THRESHOLD, "long prose is not repetitive, got " + ratio.toFixed(3));
+
+  const { score, tags } = evaluateMemoryQuality({ type: "project", title: "公共管理理论笔记", content: LONG_NOTE });
+  assert.equal(score, 100, "a clean long note scores full marks");
+  assert.ok(!tags.includes("repetitive"), "no repetitive tag");
+});
+
+test("repetitionRatio: stays well below the gate at every prefix length", () => {
+  // The old measure went DOWN as text grew (it divided by length), so a long
+  // note could never clear 0.3 no matter how original it was. Trigram ratio
+  // drifts up only mildly with length (finite trigram space): on the real
+  // library, stitching distinct memories up to 30,000 chars reached just 0.428.
+  // So growing this genuine 1,611-char note must never approach the gate.
+  for (const len of [200, 400, 800, 1200, LONG_NOTE.length]) {
+    const ratio = repetitionRatio(LONG_NOTE.slice(0, len));
+    assert.ok(ratio < 0.2,
+      len + "-char prefix must stay far below the gate, got " + ratio.toFixed(3));
+  }
+});
+
+// A path-dense technical note repeats the same install/invocation pattern on
+// every line — the most "repetitive-looking" thing a real memory legitimately
+// contains. On the real library the highest such note measured 0.591, so the
+// threshold must sit above it; garbage fillers start at 0.75. Pinning both
+// ends keeps a future "just lower it a bit" change from re-creating the false
+// positives this issue is about.
+test("repetitionRatio: a path-dense technical note is not filler", () => {
+  const pathNote = [
+    "各 agent 的 skill 安装目录与调用方式：",
+    "Claude Code 的 skill 放在 ~/.claude/skills/<name>/SKILL.md，调用方式是在会话里输入 /<name>；",
+    "Codex CLI 的 skill 放在 ~/.codex/skills/<name>/SKILL.md，调用方式是输入 $<name>；",
+    "Cursor 的 skill 放在 .cursor/rules/<name>.mdc，随仓库提交，调用方式是自动 attach；",
+    "Windsurf 的 skill 放在 .windsurf/rules/<name>.md，调用方式同样是自动 attach；",
+    "Cline 的 skill 放在 .clinerules/<name>.md，调用方式是按目录层级继承；",
+    "Gemini CLI 的 skill 放在 ~/.gemini/skills/<name>/SKILL.md，调用方式是 /<name>；",
+    "Aider 的 skill 放在 .aider.conf.yml 的 read 列表里，调用方式是每次启动都读；",
+    "每个 skill 目录里的 SKILL.md 都要有 frontmatter，写 name 与 description，",
+    "description 决定它什么时候被调用，所以要写清触发条件而不是写功能概述。",
+    "目录结构统一为 skills/<name>/SKILL.md，附带 references/ 与 scripts/ 子目录。",
+    "同步方式：把 skills/<name>/SKILL.md 软链到各家的 skills/<name>/SKILL.md，",
+    "这样只维护一份，各家读到的都是 ~/.claude/skills/<name>/SKILL.md 同一份内容。"
+  ].join("");
+  const ratio = repetitionRatio(pathNote);
+  assert.ok(ratio > 0.3,
+    "sanity: this note does repeat pattern-wise (" + ratio.toFixed(3) + "), so a low gate would flag it");
+  assert.ok(ratio < REPETITION_THRESHOLD,
+    "yet it is real content and must clear the gate, got " + ratio.toFixed(3));
+
+  const { score, tags } = evaluateMemoryQuality({ type: "project", title: "各家 skill 安装目录", content: pathNote });
+  assert.equal(score, 100, "path-dense note keeps full quality");
+  assert.ok(!tags.includes("repetitive"), "not tagged repetitive");
+});
+
+test("repetitionRatio: duplicated content crosses the gate", () => {
+  // Appending the same paragraph repeatedly is the failure mode this signal
+  // exists for; x4 is where the paragraph dominates the text.
+  const para = LONG_NOTE.slice(0, 339);
+  assert.ok(repetitionRatio(para) < 0.1, "a single copy is clean");
+  assert.ok(repetitionRatio(para.repeat(4)) > REPETITION_THRESHOLD, "four copies are caught");
+});
+
+test("repetitionRatio: degenerate filler is caught, short text is exempt", () => {
+  assert.ok(repetitionRatio("好".repeat(20)) > REPETITION_THRESHOLD);
+  assert.ok(repetitionRatio("a".repeat(1000)) > REPETITION_THRESHOLD);
+  assert.ok(repetitionRatio("今天天气不错我们去跑步吧".repeat(5)) > REPETITION_THRESHOLD);
+  assert.equal(repetitionRatio("好"), 0, "short text cannot be repetitive");
+  assert.equal(repetitionRatio(""), 0);
+});
+
+test("saveWithDedupe: a long Chinese note keeps full quality (no repetitive demotion)", () => {
+  const { store, service } = setup();
+  const { memory } = service.saveWithDedupe({
+    type: "project",
+    title: "公共管理理论笔记",
+    content: LONG_NOTE,
+    importance: 3
+  });
+  const got = store.getById(memory.id);
+  assert.equal(got.quality_score, 100, "long prose is not demoted");
+  assert.ok(!got.tags.includes("repetitive"), "no repetitive tag persisted");
+  assert.equal(got.archived, false);
 });
 
 // --- Issue #135 附属发现 1：importance ≥ exemptImportance 只降权，不静默归档 ----

package/test/service.test.js

@@ -305,7 +305,7 @@ test("Bug7: near-duplicate content is archived and tagged low_quality", () => {
   assert.ok(row.quality_score < 30, `score below archive threshold: ${row.quality_score}`);
 });
 
-test("Bug7: repetitive (dedup<0.3) content is scored into the degraded band", () => {
+test("Bug7: repetitive (trigram > 0.7) content is scored into the degraded band", () => {
   const { store, service } = qualitySetup();
   const result = service.saveWithDedupe({ type: "history", title: "唠叨", content: "好好好好好好好好好好好好好好好好好好" });
   const row = store.getById(result.memory.id);

package/test/wiki-api.test.js

@@ -0,0 +1,153 @@
+// chorography 四条读路由的回归锁（M1）。锁四层闸的语义分叉（#497 口径）：
+// choro queries 缺装配 → 503 unavailable（环境缺件）；chorographyEnabled 关 →
+// 409 disabled（用户没开）；repo 解析失败 → 404 / 歧义 → 400 带可选清单；
+// 快乐路径四条全通。数据用真实 T0 fixture 建（同 wiki-queries 的对账纪律）。
+import test from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { createStore } from "../src/store.js";
+import { createService } from "../src/service.js";
+import { createApi } from "../src/api.js";
+import { createSettings } from "../src/settings.js";
+import { createChoroQueries } from "../src/wiki/queries.js";
+import { runChoroT0 } from "../src/wiki/t0.js";
+
+class FakeRes extends EventEmitter {
+  constructor() { super(); this.statusCode = 200; this.body = ""; }
+  writeHead(code, headers) { this.statusCode = code; this.headers = headers; return this; }
+  end(text) { this.body = text ?? ""; this.emit("end"); return this; }
+}
+
+function req(path, method = "GET") {
+  const r = new EventEmitter();
+  r.url = path;
+  r.method = method;
+  r.headers = {};
+  return r;
+}
+
+function setup({ config = null, choro = null } = {}) {
+  const store = createStore(":memory:");
+  const service = createService({ store, mirror: null, config: {} });
+  const settings = createSettings(store.db);
+  const routes = [];
+  const ctx = { webServer: { register(route) { routes.push(route); return () => {}; } } };
+  createApi(ctx, service, settings, { add: () => {}, remove: () => false, list: () => [] }, null, undefined, "", config, null, null, choro);
+  return { routes };
+}
+
+function handler(routes, path) {
+  return routes.find((r) => r.path === path);
+}
+
+async function invoke(route, path) {
+  const res = new FakeRes();
+  await route.handler(req(path), res);
+  return { status: res.statusCode, body: JSON.parse(res.body || "{}") };
+}
+
+function makeRepo(store) {
+  const root = mkdtempSync(join(tmpdir(), "choro-api-"));
+  writeFileSync(join(root, "package.json"), JSON.stringify({ name: "apifix", scripts: { test: "node --test" } }, null, 2) + "\n", "utf8");
+  mkdirSync(join(root, "src"), { recursive: true });
+  writeFileSync(join(root, "src", "a.js"), 'import { b } from "./b.js";\nexport const a = () => b();\n', "utf8");
+  writeFileSync(join(root, "src", "b.js"), "export const b = () => 1;\n", "utf8");
+  execFileSync("git", ["init", "-b", "main"], { cwd: root, stdio: "pipe" });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "add", "-A"], { cwd: root, stdio: "pipe" });
+  execFileSync("git", ["-c", "user.email=t@t", "-c", "user.name=t", "commit", "-m", "init", "--no-gpg-sign"], { cwd: root, stdio: "pipe" });
+  runChoroT0({ repoRoot: root, store, apply: true, now: () => "T" });
+  return root;
+}
+
+function rmTempBestEffort(dir) {
+  try {
+    rmSync(dir, { recursive: true, force: true });
+  } catch {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200);
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* 留给系统清理 */ }
+  }
+}
+
+test("四条 choro 路由都在册且 policy 全 open", () => {
+  const { routes } = setup({});
+  for (const p of ["/api/dsh-mneme/choro/repos", "/api/dsh-mneme/choro/modules", "/api/dsh-mneme/choro/page", "/api/dsh-mneme/choro/search"]) {
+    const route = handler(routes, p);
+    assert.ok(route, `${p} 在册`);
+    assert.equal(route.policy, "open");
+  }
+});
+
+test("queries 缺装配 → 503；开关关 → 409 disabled（语义分叉）", async () => {
+  const missing = setup({});
+  const reposRoute = handler(missing.routes, "/api/dsh-mneme/choro/repos");
+  const a = await invoke(reposRoute, "/api/dsh-mneme/choro/repos");
+  assert.equal(a.status, 503);
+  assert.equal(a.body.error, "unavailable");
+
+  const off = setup({ config: { chorographyEnabled: false }, choro: createChoroQueries({ store: createStore(":memory:") }) });
+  const b = await invoke(handler(off.routes, "/api/dsh-mneme/choro/repos"), "/api/dsh-mneme/choro/repos");
+  assert.equal(b.status, 409);
+  assert.equal(b.body.error, "disabled");
+});
+
+test("快乐路径：repos / modules / page / search 全通", async () => {
+  const store = createStore(":memory:");
+  const root = makeRepo(store);
+  try {
+    const { routes } = setup({ config: { chorographyEnabled: true }, choro: createChoroQueries({ store }) });
+    const repos = await invoke(handler(routes, "/api/dsh-mneme/choro/repos"), "/api/dsh-mneme/choro/repos");
+    assert.equal(repos.status, 200);
+    assert.equal(repos.body.repos.length, 1);
+    const repoId = repos.body.repos[0].id;
+
+    const modules = await invoke(handler(routes, "/api/dsh-mneme/choro/modules"), `/api/dsh-mneme/choro/modules?repo=${repoId}`);
+    assert.equal(modules.status, 200);
+    assert.ok(modules.body.modules.length >= 2);
+    assert.ok(Array.isArray(modules.body.edges));
+
+    const page = await invoke(handler(routes, "/api/dsh-mneme/choro/page"), `/api/dsh-mneme/choro/page?repo=${repoId}&slug=src`);
+    assert.equal(page.status, 200);
+    assert.ok(page.body.page.content.includes("## 文件清单"));
+
+    const search = await invoke(handler(routes, "/api/dsh-mneme/choro/search"), `/api/dsh-mneme/choro/search?repo=${repoId}&q=b.js`);
+    assert.equal(search.status, 200);
+    assert.ok(search.body.hits.length >= 1);
+  } finally {
+    rmTempBestEffort(root);
+  }
+});
+
+test("repo 解析失败各归各位：未知 → 404；歧义 → 400 带清单；slug 缺 → 400", async () => {
+  const store = createStore(":memory:");
+  const root = makeRepo(store);
+  try {
+    const { routes } = setup({ config: { chorographyEnabled: true }, choro: createChoroQueries({ store }) });
+    const notFound = await invoke(handler(routes, "/api/dsh-mneme/choro/modules"), "/api/dsh-mneme/choro/modules?repo=nope");
+    assert.equal(notFound.status, 404);
+    assert.equal(notFound.body.error, "repo-not-found");
+
+    const root2 = makeRepo(store);
+    try {
+      const ambiguous = await invoke(handler(routes, "/api/dsh-mneme/choro/modules"), "/api/dsh-mneme/choro/modules");
+      assert.equal(ambiguous.status, 400);
+      assert.equal(ambiguous.body.error, "repo-ambiguous");
+      assert.equal(ambiguous.body.repos.length, 2);
+    } finally {
+      rmTempBestEffort(root2);
+    }
+
+    const repoId = 1;
+    const noSlug = await invoke(handler(routes, "/api/dsh-mneme/choro/page"), `/api/dsh-mneme/choro/page?repo=${repoId}`);
+    assert.equal(noSlug.status, 400);
+    assert.equal(noSlug.body.error, "slug-required");
+
+    const badSlug = await invoke(handler(routes, "/api/dsh-mneme/choro/page"), `/api/dsh-mneme/choro/page?repo=${repoId}&slug=../etc/passwd`);
+    assert.equal(badSlug.status, 404, "路径穿越形态的 slug 走未知页 404（slug 只从 DB 白名单解析）");
+  } finally {
+    rmTempBestEffort(root);
+  }
+});