@theseus-whale/dsh-continuity 0.0.0-stage → 4.12.2

package/src/memory/planner.mjs

@@ -0,0 +1,249 @@
+/**
+ * Retrieval planner: route a query to the most appropriate layer, with
+ * explicit coverage/score gates instead of always fusing every layer.
+ */
+import { buildFacetIndex, queryFacets } from '../facets/index.mjs';
+import { DEFAULT_ALIASES, aliasFacets } from '../facets/schema.mjs';
+import { BM25Index } from './bm25.mjs';
+
+export function reciprocalRankFusion(lists, { k = 60, weights = {} } = {}) {
+  const scores = new Map();
+  for (const [layer, hits] of Object.entries(lists)) {
+    const weight = weights[layer] ?? 1;
+    hits.forEach((hit, index) => {
+      const key = hit.turn;
+      const add = weight / (k + index + 1);
+      const current = scores.get(key) ?? { turn: key, sources: {}, score: 0, hit };
+      current.score += add;
+      current.sources[layer] = (current.sources[layer] ?? 0) + add;
+      scores.set(key, current);
+    });
+  }
+  return [...scores.values()].sort((a, b) => b.score - a.score);
+}
+
+function isLastIntent(query) {
+  return /上次|最近|刚才|上一次/.test(query);
+}
+
+function asOfFilter(hits, asOf) {
+  if (!Number.isInteger(asOf)) return hits;
+  return hits.filter((hit) => hit.turn <= asOf);
+}
+
+function orderHits(hits, last) {
+  return last ? [...hits].sort((a, b) => b.turn - a.turn) : hits;
+}
+
+export function buildPlanner({ records, bm25, vectorIndex, summaryBm25 }) {
+  const facetIndex = buildFacetIndex(records);
+  return {
+    query(query, { queryVector = null, topK = 20, asOf = null } = {}) {
+      const last = isLastIntent(query);
+      const cleanQuery = String(query).replace(/^(上次的?|最近的?|刚才的?|上一次的?)\s*/u, '').trim() || String(query);
+      const routeSuffix = last ? '-last' : '';
+      const facetAliasKey = Object.keys(DEFAULT_ALIASES).find((key) => cleanQuery.includes(key));
+      const facetAlias = facetAliasKey === undefined ? {} : aliasFacets(facetAliasKey);
+      if (Object.keys(facetAlias).length > 0) {
+        const matches = asOfFilter(queryFacets(facetIndex, facetAliasKey, { topK: records.length }).matches, asOf);
+        return {
+          query,
+          route: `facet${routeSuffix}`,
+          layers: ['facet'],
+          facet: facetAlias,
+          fused: orderHits(matches, last).slice(0, topK).map((hit) => ({
+            turn: hit.turn,
+            seqStart: hit.seqStart,
+            seqEnd: hit.seqEnd,
+            score: hit.score,
+            sources: { facet: hit.score },
+          })),
+        };
+      }
+
+      const visible = Number.isInteger(asOf) ? records.filter((record) => record.turn <= asOf) : records;
+      const lastQuery = cleanQuery.replace(/(是什么|怎么样了|怎么样|呢|吗|是哪轮|是哪一轮)$/u, '').trim();
+      if (last) {
+        const literalTerms = [...new Set(lastQuery.toLowerCase().match(/[a-z0-9_.-]+|[\u4e00-\u9fff]+/g) ?? [])];
+        if (literalTerms.length >= 2) {
+          const literalHits = visible.filter((record) => {
+            const text = record.text.toLowerCase();
+            return literalTerms.every((term) => text.includes(term));
+          });
+          if (literalHits.length > 0) {
+            return {
+              query,
+              route: `literal${routeSuffix}`,
+              layers: ['literal'],
+              facet: {},
+              fused: orderHits(literalHits, true).slice(0, topK).map((record) => ({
+                turn: record.turn,
+                seqStart: record.seqStart,
+                seqEnd: record.seqEnd,
+                score: 1,
+                sources: { literal: 1 },
+              })),
+            };
+          }
+        }
+      }
+      if (last && /^[\u4e00-\u9fff]{4,}$/u.test(lastQuery)) {
+        const mid = Math.ceil(lastQuery.length / 2);
+        const left = lastQuery.slice(0, mid);
+        const right = lastQuery.slice(mid);
+        const concept = visible.filter((record) => {
+          const text = record.text;
+          return text.includes(left) && text.includes(right);
+        });
+        if (concept.length > 0) {
+          return {
+            query,
+            route: `concept${routeSuffix}`,
+            layers: ['concept'],
+            facet: {},
+            fused: orderHits(concept, true).slice(0, topK).map((record) => ({
+              turn: record.turn,
+              seqStart: record.seqStart,
+              seqEnd: record.seqEnd,
+              score: 1,
+              sources: { concept: 1 },
+            })),
+          };
+        }
+      }
+      if (last && lastQuery.length >= 2) {
+        const textHits = visible.filter((record) => record.text.toLowerCase().includes(lastQuery.toLowerCase()));
+        if (textHits.length > 0) {
+          return {
+            query,
+            route: `phrase${routeSuffix}`,
+            layers: ['phrase'],
+            facet: {},
+            fused: orderHits(textHits, true).slice(0, topK).map((record) => ({
+              turn: record.turn,
+              seqStart: record.seqStart,
+              seqEnd: record.seqEnd,
+              score: 1,
+              sources: { phrase: 1 },
+            })),
+          };
+        }
+      }
+      const normalized = cleanQuery.toLowerCase();
+      const exact = /\.[a-z0-9]{2,5}\b/i.test(cleanQuery)
+        ? visible.filter((record) => record.text.toLowerCase().includes(normalized))
+        : [];
+      if (exact.length > 0 && exact.length <= 50) {
+        return {
+          query,
+          route: `phrase${routeSuffix}`,
+          layers: ['phrase'],
+          facet: {},
+          fused: orderHits(exact, last).slice(0, topK).map((record) => ({
+            turn: record.turn,
+            seqStart: record.seqStart,
+            seqEnd: record.seqEnd,
+            score: 1,
+            sources: { phrase: 1 },
+          })),
+        };
+      }
+
+      const terms = cleanQuery.split(/\s+/).map((term) => term.trim().toLowerCase()).filter(Boolean);
+      if (terms.length >= 2) {
+        const both = visible.filter((record) => {
+          const text = record.text.toLowerCase();
+          return terms.every((term) => text.includes(term));
+        });
+        if (both.length > 0 && both.length <= 50) {
+          return {
+            query,
+            route: `and${routeSuffix}`,
+            layers: ['and'],
+            facet: {},
+            fused: orderHits(both, last).slice(0, topK).map((record) => ({
+              turn: record.turn,
+              seqStart: record.seqStart,
+              seqEnd: record.seqEnd,
+              score: 1,
+              sources: { and: 1 },
+            })),
+          };
+        }
+      }
+
+      const keyword = asOfFilter(bm25.search(lastQuery || cleanQuery, {
+        topK: last ? visible.length : topK * 5,
+        minCoverage: last ? 0.8 : 0.6,
+      }), asOf);
+      if (keyword.length > 0 && keyword[0].score >= 2) {
+        return {
+          query,
+          route: `bm25${routeSuffix}`,
+          layers: ['bm25'],
+          facet: {},
+          fused: orderHits(keyword, last).slice(0, topK).map((hit) => ({
+            turn: hit.turn,
+            seqStart: hit.seqStart,
+            seqEnd: hit.seqEnd,
+            score: hit.score,
+            sources: { bm25: hit.score, coverage: hit.coverage },
+          })),
+        };
+      }
+
+      if (queryVector !== null) {
+        const semantic = asOfFilter(vectorIndex.search(queryVector, { topK: topK * 5 }), asOf);
+        if (semantic.length > 0 && semantic[0].score >= (last ? 0.65 : 0.55)) {
+          return {
+            query,
+            route: `vector${routeSuffix}`,
+            layers: ['vector'],
+            facet: {},
+            fused: orderHits(semantic, last).slice(0, topK).map((hit) => ({
+              turn: hit.turn,
+              seqStart: hit.seqStart,
+              seqEnd: hit.seqEnd,
+              score: hit.score,
+              sources: { vector: hit.score },
+            })),
+          };
+        }
+      }
+
+      if (/后来|经过|总结|发生了什么|时间线/.test(cleanQuery)) {
+        const summary = asOfFilter(summaryBm25.search(cleanQuery, { topK: topK * 3, minCoverage: 0.5 }), asOf);
+        if (summary.length > 0) {
+          return {
+            query,
+            route: `summary${routeSuffix}`,
+            layers: ['summary'],
+            facet: {},
+            fused: orderHits(summary, last).slice(0, topK).map((hit) => ({
+              turn: hit.turn,
+              seqStart: hit.seqStart,
+              seqEnd: hit.seqEnd,
+              score: hit.score,
+              sources: { summary: hit.score },
+            })),
+          };
+        }
+      }
+
+      return { query, route: 'empty', layers: [], facet: {}, fused: [] };
+    },
+  };
+}
+
+export function summaryIndex(tree) {
+  return new BM25Index().build(tree.nodes
+    .filter((node) => node.level !== 'turn')
+    .map((node) => ({
+      turn: node.firstTurn,
+      firstTurn: node.firstTurn,
+      lastTurn: node.lastTurn,
+      seqStart: node.seqStart,
+      seqEnd: node.seqEnd,
+      text: node.summary,
+    })));
+}

package/src/memory/pre-turn.mjs

@@ -0,0 +1,80 @@
+/**
+ * Pre-turn integration: one incoming user/Coo message -> facet/event/gate/load.
+ * Pure system layer. No live session writes.
+ */
+import { MemoryLoadState, latestCandidate, candidateSegment } from './load-gate.mjs';
+import { EventModelState } from './event-model.mjs';
+import { attachStructuredExtraction } from './extraction-adapter.mjs';
+
+export class PreTurnController {
+  constructor({ records = [], gate = null, eventModel = null } = {}) {
+    this.records = records;
+    this.gate = gate ?? new MemoryLoadState();
+    this.eventModel = eventModel ?? new EventModelState({ slots: this.gate.loadedFacets });
+  }
+
+  async stepAsync({ extractionProvider = null, ...args } = {}) {
+    if (!extractionProvider) return this.step(args);
+    const extraction = await extractionProvider.extract({ text: args.text });
+    if (!extraction.ok) {
+      return {
+        ok: false,
+        extraction,
+        gate: this.step({ ...args, eventSlots: args.eventSlots ?? null }),
+      };
+    }
+    const data = extraction.data ?? {};
+    const result = attachStructuredExtraction(this, {
+      ...args,
+      slots: data.slots ?? null,
+      srl: data.srl ?? null,
+      corefClusters: data.corefClusters ?? [],
+      entityLinks: data.entityLinks ?? [],
+    });
+    return { ok: result.ok, extraction, ...result };
+  }
+
+  step({ text, role = 'user', facets = {}, confidence = 1, eventSlots = null, nowTurn = 0 } = {}) {
+    if (role === 'assistant') {
+      return { action: 'none', reason: 'assistant-text', telemetry: { role } };
+    }
+    const observed = this.eventModel.observe({ slots: eventSlots ?? facets });
+    const candidate = latestCandidate(this.records, 'activity', facets.activity);
+    const segment = candidateSegment(this.records, candidate);
+    const decision = this.gate.decide({
+      text,
+      currentFacets: facets,
+      confidence,
+      nowTurn,
+      hasCandidate: candidate !== null,
+      candidate,
+      role,
+      boundaryScore: observed.score,
+    });
+    if (decision.action === 'load') {
+      this.gate.recordLoad({
+        facets,
+        seq: segment?.seqStart ?? null,
+        nowTurn,
+        reason: decision.reason,
+      });
+    }
+    return {
+      ...decision,
+      boundaryScore: observed.score,
+      eventId: observed.eventId,
+      eventError: observed.error ?? null,
+      candidateTurn: candidate?.turn ?? null,
+      segment: decision.action === 'none' ? null : segment,
+      telemetry: {
+        role,
+        activity: facets.activity ?? null,
+        topic: facets.topic ?? null,
+        confidence,
+        eventSlots: observed.slots,
+        eventChanged: observed.changed,
+        gateReason: decision.reason,
+      },
+    };
+  }
+}

package/src/memory/query-aliases.mjs

@@ -0,0 +1,39 @@
+/**
+ * Query-side aliases for the literal layer.
+ *
+ * Format (one term per line):
+ *   通知 => notification / post_notifications
+ *   ...
+ *
+ * This file affects only the literal query path; it does not change the index,
+ * B descriptors, or C/K data.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export function defaultAliasesPath(home = process.env.USERPROFILE ?? process.env.HOME ?? os.homedir()) {
+  return path.join(home, '.dsh', 'continuity', 'aliases.md');
+}
+
+export function parseAliases(text) {
+  const aliases = new Map();
+  for (const raw of String(text ?? '').split(/\r?\n/)) {
+    const line = raw.replace(/#.*$/, '').trim();
+    if (!line) continue;
+    const match = line.match(/^(.+?)\s*(?:=>|->|→)\s*(.+)$/);
+    if (!match) continue;
+    const term = match[1].trim();
+    const values = match[2].split(/[\/,，、]/).map((word) => word.trim()).filter(Boolean);
+    if (term && values.length > 0) aliases.set(term, values);
+  }
+  return aliases;
+}
+
+export function loadQueryAliases(file = defaultAliasesPath()) {
+  try {
+    return parseAliases(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return new Map();
+  }
+}

package/src/memory/recall-cue.mjs

@@ -0,0 +1,43 @@
+/**
+ * High-precision explicit recall cues.
+ * Deliberately does not fire on bare "之前", "那个", or "继续".
+ */
+const CUES = [
+  /上次/,
+  /上回/,
+  /上一次/,
+  /前一回/,
+  /之前我们/,
+  /之前那次/,
+  /之前那个/,
+  /之前我(?:说|提|讲)过?/,
+  /以前我们/,
+  /以前那次/,
+  /还记得/,
+  /记得上次/,
+  /记得之前/,
+  /回到(?:刚才|之前|那个|上次)/,
+  /接着(?:上次|之前)/,
+  /那个(?:事|项目|话题|东西|办法|决定|问题)/,
+];
+
+export function detectRecallCue(text) {
+  // Quoted cue words are usually meta-discussion ("if I say '上次' ..."),
+  // not an actual request to recall.
+  const source = String(text ?? '')
+    .replace(/`[^`]*`/g, ' ')
+    .replace(/“[^”]*”/g, ' ')
+    .replace(/「[^」]*」/g, ' ')
+    .replace(/"[^"]*"/g, ' ');
+  for (const pattern of CUES) {
+    const match = source.match(pattern);
+    if (match) return { hit: true, cue: match[0], index: match.index ?? 0, pattern: pattern.source };
+  }
+  return { hit: false, cue: null, index: -1, pattern: null };
+}
+
+export function shouldTriggerRecall(text) {
+  return detectRecallCue(text).hit;
+}
+
+export const RECALL_CUE_PATTERNS = CUES.map((pattern) => pattern.source);

package/src/memory/recall.mjs

@@ -0,0 +1,65 @@
+/**
+ * Lexical recall over the immutable session event log.
+ *
+ * This is deliberately small: it only answers "which previous turn/seq
+ * contains text close to this query". It does not call the LLM and it does
+ * not write anything.
+ */
+import { eventText } from '../session-log.mjs';
+import { BM25Index } from './bm25.mjs';
+import { tokenize } from './tokenize.mjs';
+
+const INJECTED_PREFIXES = ['[continuity:', '[抽取]', '[工作线]', '[标签]', '[规矩]', '[习惯]', '[技能]', '[归位', '[候选', '[存?]', '[闸', '[gate', '[peer', '[回正]', '[学习', '[话题?]'];
+
+function isInjected(text) {
+  return INJECTED_PREFIXES.some((prefix) => text.startsWith(prefix));
+}
+
+export function collectRecallRecords(events = [], { beforeTurn = Infinity } = {}) {
+  const records = [];
+  for (const event of events) {
+    if (event?.type !== 'user/message') continue;
+    const text = eventText(event).trim();
+    if (text.length === 0 || isInjected(text)) continue;
+    const turn = Number(event?.data?.turn ?? event?.turn);
+    if (Number.isFinite(turn) && turn >= beforeTurn) continue;
+    const seq = Number(event?.seq);
+    if (!Number.isInteger(seq)) continue;
+    records.push({
+      turn: Number.isFinite(turn) ? turn : null,
+      seqStart: seq,
+      seqEnd: seq,
+      text,
+    });
+  }
+  return records;
+}
+
+export function buildRecallIndex(events, options = {}) {
+  const records = collectRecallRecords(events, options);
+  return { records, index: new BM25Index().build(records) };
+}
+
+export function findRecall(recall, query, { topK = 3, minCoverage = 0.3 } = {}) {
+  if (!recall || !Array.isArray(recall.records) || recall.records.length === 0) return [];
+  const hits = recall.index.search(String(query ?? ''), { topK, minCoverage });
+  return hits.map((hit) => ({
+    turn: hit.turn,
+    seqStart: hit.seqStart,
+    seqEnd: hit.seqEnd,
+    score: hit.score,
+    coverage: hit.coverage,
+    text: recall.records.find((record) => record.seqStart === hit.seqStart)?.text ?? '',
+  }));
+}
+
+export function renderRecall(hit, query = '') {
+  const where = hit.turn === null ? `seq ${hit.seqStart}` : `turn ${hit.turn} / seq ${hit.seqStart}`;
+  const lower = String(hit.text ?? '').toLowerCase();
+  const terms = [...new Set(tokenize(query))]
+    .filter((term) => term.length >= 2 && lower.includes(term.toLowerCase()))
+    .slice(0, 4);
+  const label = terms.length > 0 ? terms.join(' / ') : '旧记录';
+  const snippet = String(hit.text ?? '').replace(/\s+/g, ' ').slice(0, 80);
+  return `[追忆] ${label} -> ${where}\n${snippet}`;
+}

package/src/memory/referent-candidates.mjs

@@ -0,0 +1,55 @@
+/**
+ * Referent candidate generation.
+ * Deterministic evidence: known aliases, exact term occurrences, retrieval hits.
+ * A candidate is not a promotion; it is input to the referent ledger.
+ */
+import { DEFAULT_ALIASES } from '../facets/schema.mjs';
+
+export function candidateReferents({
+  term,
+  records = [],
+  keywordHits = [],
+  semanticHits = [],
+  max = 5,
+} = {}) {
+  const clean = String(term ?? '').trim();
+  const candidates = new Map();
+  const add = (referent, target, source, score, role = null, turn = null) => {
+    const existing = candidates.get(referent);
+    if (existing === undefined || score > existing.score) {
+      candidates.set(referent, { referent, target, source, score, role, turn });
+    }
+  };
+
+  if (DEFAULT_ALIASES[clean] !== undefined) {
+    const alias = DEFAULT_ALIASES[clean];
+    add(`facet:${alias.activity ?? alias.topic}`, alias.activity ?? alias.topic, 'alias', 1, 'alias');
+  }
+
+  for (const record of records) {
+    if (!String(record.text ?? '').includes(clean)) continue;
+    add(`turn:${record.turn}`, record.facets?.activity ?? null, 'event-log', 0.8, 'mention', record.turn);
+  }
+
+  const hitRank = new Map();
+  [...keywordHits, ...semanticHits].forEach((hit, index) => {
+    const previous = hitRank.get(hit.turn);
+    if (previous === undefined) hitRank.set(hit.turn, index);
+    else hitRank.set(hit.turn, Math.min(previous, index));
+  });
+  for (const [turn, rank] of hitRank) {
+    const record = records.find((item) => item.turn === turn);
+    if (record === undefined) continue;
+    add(`turn:${turn}`, record.facets?.activity ?? null, 'retrieval', 0.5 / (rank + 1), 'retrieval', turn);
+  }
+
+  return [...candidates.values()]
+    .sort((a, b) => b.score - a.score)
+    .slice(0, max);
+}
+
+export function bindReferent(candidates, { threshold = 0.5 } = {}) {
+  const top = candidates[0] ?? null;
+  if (top === null || top.score < threshold) return { referent: 'NIL', candidate: top, reason: 'below-threshold' };
+  return { referent: top.referent, candidate: top, reason: 'bound' };
+}

package/src/memory/referent-ledger.mjs

@@ -0,0 +1,86 @@
+/**
+ * Term-to-referent ledger.
+ *
+ * An alias is a relation between a term and a stable referent, not merely a
+ * repeated word. Same term with two referents is a new sense, not an alias.
+ */
+import { DEFAULT_ALIASES } from '../facets/schema.mjs';
+
+const NIL_REFERENTS = new Set(['NIL', 'nil', 'unknown', '未知', '未知实体', 'null']);
+
+function dominant(counts) {
+  const entries = Object.entries(counts).sort((a, b) => b[1] - a[1]);
+  if (entries.length === 0) return null;
+  const total = entries.reduce((sum, [, count]) => sum + count, 0);
+  return { value: entries[0][0], count: entries[0][1], total, ratio: entries[0][1] / total };
+}
+
+export class ReferentLedger {
+  constructor({ minUser = 2, minEvents = 2, terms = new Map(), requireConfirmation = false } = {}) {
+    this.minUser = minUser;
+    this.minEvents = minEvents;
+    this.terms = terms;
+    this.requireConfirmation = requireConfirmation;
+  }
+
+  observe({ term, source = 'user', eventId, referent = null, role = null, target = null, nowTurn = 0, kind = 'mention', confirmed = false }) {
+    const clean = String(term ?? '').trim();
+    if (clean.length === 0) return { action: 'none', reason: 'no-term' };
+    if (DEFAULT_ALIASES[clean] !== undefined) return { action: 'none', reason: 'known-alias' };
+
+    const record = this.terms.get(clean) ?? {
+      term: clean,
+      user: 0,
+      assistant: 0,
+      events: new Set(),
+      referents: {},
+      roles: {},
+      targets: {},
+      firstSeen: nowTurn,
+      lastSeen: nowTurn,
+      strong: false,
+      proposed: false,
+      nilCount: 0,
+      confirmed: false,
+    };
+    if (source === 'user' || (source === 'coo' || source === 'peer')) record.user += 1;
+    else record.assistant += 1;
+    record.events.add(eventId);
+    if (confirmed) record.confirmed = true;
+    if (referent !== null && NIL_REFERENTS.has(String(referent))) record.nilCount += 1;
+    if (referent !== null && !NIL_REFERENTS.has(String(referent))) record.referents[referent] = (record.referents[referent] ?? 0) + 1;
+    if (role !== null) record.roles[role] = (record.roles[role] ?? 0) + 1;
+    if (target !== null) record.targets[target] = (record.targets[target] ?? 0) + 1;
+    if (kind === 'definition' || kind === 'quoted') record.strong = true;
+    record.lastSeen = nowTurn;
+    this.terms.set(clean, record);
+
+    if (record.proposed) return { action: 'none', reason: 'already-proposed', record };
+    if (record.user < this.minUser) return { action: 'none', reason: 'need-user-repeat', record };
+    if (record.events.size < this.minEvents) return { action: 'none', reason: 'need-event-repeat', record };
+    if (Object.keys(record.referents).length === 0 && record.nilCount > 0) {
+      return { action: 'none', reason: 'nil-referent', record };
+    }
+
+    const dominantRole = dominant(record.roles);
+    if (dominantRole !== null && dominantRole.ratio < 0.8) return { action: 'none', reason: 'role-unstable', record };
+    const dominantReferent = dominant(record.referents);
+    if (dominantReferent === null) return { action: 'none', reason: 'no-referent', record };
+    if (dominantReferent.ratio < 0.8) return { action: 'none', reason: 'referent-unstable', record };
+    const dominantTarget = dominant(record.targets);
+    if (dominantTarget === null) return { action: 'none', reason: 'no-target-facet', record };
+    if (this.requireConfirmation && !record.confirmed) return { action: 'none', reason: 'unconfirmed', record };
+
+    record.proposed = true;
+    return {
+      action: 'propose',
+      reason: 'cross-event-referent',
+      term: clean,
+      referent: dominantReferent.value,
+      role: dominantRole?.value ?? null,
+      target: dominantTarget.value,
+      text: `[新别名?] ${clean} → ${dominantTarget.value}（referent ${dominantReferent.value}）`,
+      record,
+    };
+  }
+}