dsh-trivium 0.4.21 → 0.5.0

package/lib/store.js

@@ -10,9 +10,21 @@ import {
   syncSidecarOnOpen,
   writeSidecarNow,
 } from "./sidecar.js";
-import { DIM, EDGE_LABELS, BUSINESS_EDGES, NODE_TYPES, indexTextFor, nowIso, weightOf, zeroVector } from "./schema.js";
+import {
+  DIM,
+  EDGE_LABELS,
+  BUSINESS_EDGES,
+  NODE_TYPES,
+  REVISION_EDGES,
+  REVISION_WALK_LIMIT,
+  indexTextFor,
+  nowIso,
+  weightOf,
+  zeroVector,
+} from "./schema.js";
+import { validateRevisionStructure } from "./revision-graph.js";
 import { clipToTokenBudget, estimateTokens } from "./tokens.js";
-import { isStalePayload, parseUntilFromText, queryMentionsUntil, resolveUntilAt } from "./until.js";
+import { isStalePayload, queryMentionsUntil, resolveUntilAt } from "./until.js";
 import { embedText, embeddingEnabled } from "./embed.js";
 import { payloadLooksDirty, sanitizeForWrite } from "./hygiene.js";
 
@@ -65,6 +77,17 @@ function persist(db) {
   if (cwd) scheduleSidecarWrite(cwd, db);
 }
 
+/**
+ * Post-write hook for the revision path.
+ *
+ * The graph write is authoritative and already committed; this flushes it and
+ * lets the JSONL sidecar catch up on its own timer. Cross-file atomicity is not
+ * claimed, and a sidecar failure is reported through sidecarHealth().
+ */
+export function persistAfterRevision(db) {
+  persist(db);
+}
+
 export function dbPathFor(cwd) {
   return join(resolve(cwd), ".dsh", "trivium.tdb");
 }
@@ -270,13 +293,16 @@ function rebuildTextIndex(db) {
   }
 }
 
-export function findMergeTarget(db, candidate) {
+export function findMergeTarget(db, candidate, { allowRevisionLinked = false } = {}) {
   const type = candidate?.type;
   if (!type || type === "episode") return null;
   const name = String(candidate.name || "").trim().toLowerCase();
   const text = String(candidate.text || "").trim().toLowerCase();
   for (const n of findByType(db, type)) {
     const payload = n.payload || {};
+    // A node inside a revision chain is confirmed history: auto-extraction must
+    // create a new decision instead of quietly folding new text into it.
+    if (!allowRevisionLinked && isRevisionLinked(db, n.id)) continue;
     const nName = String(payload.name || "").trim().toLowerCase();
     const nText = String(payload.text || "").trim().toLowerCase();
     const aliases = (payload.aliases || []).map((a) => String(a).trim().toLowerCase());
@@ -310,12 +336,28 @@ export function mergeInto(db, id, incoming) {
   const node = db.get(Number(id));
   if (!node) return insertNode(db, incoming);
   const old = node.payload || {};
+  /*
+   * A node in a revision chain holds confirmed history: new text becomes a new
+   * decision that then supersedes it. Non-factual fields (aliases, deadlines,
+   * source notes) may still be filled in.
+   */
+  if (isRevisionLinked(db, Number(id))) {
+    const nextBody = pickMergedText(old.text, incoming.text);
+    if (String(nextBody || "").trim() !== String(old.text || "").trim()) {
+      const err = new Error("REVISION_PROTECTED");
+      err.code = "REVISION_PROTECTED";
+      err.status = 409;
+      err.nodeId = Number(id);
+      throw err;
+    }
+  }
   const aliases = uniqueStrings([
     ...(old.aliases || []),
     ...(incoming.aliases || []),
     incoming.name,
     old.name,
   ]).filter((a) => a !== (incoming.name || old.name));
+  const deadlineChanged = incoming.until !== undefined && String(incoming.until || "").trim() !== String(old.until || "").trim();
   const next = decorateUntil({
     ...old,
     ...incoming,
@@ -326,7 +368,11 @@ export function mergeInto(db, id, incoming) {
     updatedAt: nowIso(),
     status: old.status || "active",
     source: incoming.source || old.source,
-  });
+    // An omitted expiry must not erase an existing one or leave an orphaned
+    // untilAt. A changed label must not inherit the previous absolute instant.
+    until: incoming.until === undefined ? old.until : incoming.until,
+    untilAt: incoming.untilAt || (deadlineChanged ? undefined : old.untilAt),
+  }, deadlineChanged ? nowIso() : old.createdAt);
   db.updatePayload(Number(id), next);
   indexNode(db, Number(id), next);
   persist(db);
@@ -336,7 +382,17 @@ export function mergeInto(db, id, incoming) {
 
 export function listNodes(
   db,
-  { type, q, includeArchived = false, includeStale = false, aboutId, includeEpisodes = false } = {},
+  {
+    type,
+    q,
+    includeArchived = false,
+    includeStale = false,
+    // Superseded versions are hidden by default and revealed by their own
+    // switch: "show expired" and "show replaced" are different questions.
+    includeSuperseded = false,
+    aboutId,
+    includeEpisodes = false,
+  } = {},
 ) {
   const rows = [];
   const needle = String(q || "").trim().toLowerCase();
@@ -353,6 +409,8 @@ export function listNodes(
     if (payload.type === "episode" && !includeEpisodes && type !== "episode") continue;
     if (type && payload.type !== type) continue;
     if (around && !around.has(Number(id))) continue;
+    const successor = successorOf(db, id);
+    if (!includeSuperseded && successor != null) continue;
     const stale = isStalePayload(payload);
     if (
       !includeStale &&
@@ -381,6 +439,13 @@ export function listNodes(
       aliases: payload.aliases || [],
       until: payload.until || "",
       stale,
+      // Independent axes, reported independently.
+      revision: successor != null ? "superseded" : "current",
+      currentId: successor != null ? currentHeadOf(db, id).id ?? null : Number(id),
+      // The two relation endpoints, so the panel can offer "view current" and
+      // "undo the replacement" without a second request.
+      supersededBy: successor != null ? Number(successor) : null,
+      replacesId: predecessorOf(db, id),
       dirty: payloadLooksDirty(payload),
       status: payload.status || "active",
       edges: (node.edges || []).length,
@@ -409,9 +474,90 @@ export function archiveNode(db, id) {
   return true;
 }
 
+/** Expiry is one axis; revision history is another. Kept apart on purpose. */
+const SUPERSEDES = EDGE_LABELS.supersedes;
+
+export { REVISION_WALK_LIMIT };
+
+/** Outgoing supersedes edges with their metadata. */
+export function supersedesOut(db, id) {
+  const node = db.get(Number(id));
+  return (node?.edges || [])
+    .filter((e) => String(e.label) === SUPERSEDES)
+    .map((e) => ({ to: edgeTarget(e), metadata: e.metadata ?? null }));
+}
+
+/** Incoming supersedes edges: who claims to replace this node. */
+export function supersedesIn(db, id) {
+  const node = db.get(Number(id));
+  const rows = incomingLabeled(db, id, [SUPERSEDES]);
+  return rows.map((row) => {
+    const from = db.get(Number(row.from));
+    const edge = (from?.edges || []).find(
+      (e) => String(e.label) === SUPERSEDES && edgeTarget(e) === Number(id),
+    );
+    return { from: Number(row.from), metadata: edge?.metadata ?? null };
+  });
+}
+
+/** The node that replaces this one (newer), or null. */
+export function successorOf(db, id) {
+  const rows = supersedesIn(db, id);
+  return rows.length ? Number(rows[0].from) : null;
+}
+
+/** The node this one replaces (older), or null. */
+export function predecessorOf(db, id) {
+  const rows = supersedesOut(db, id);
+  return rows.length ? Number(rows[0].to) : null;
+}
+
+/** The supersedes edge this node is the target of, metadata included. */
+export function revisionEdgeOf(db, id) {
+  const rows = supersedesIn(db, id);
+  return rows.length ? rows[0] : null;
+}
+
+/** Any relation at all, in either direction. */
+export function isRevisionLinked(db, id) {
+  return successorOf(db, id) != null || predecessorOf(db, id) != null;
+}
+
+/** Walk forward to the head of the chain, or report why we cannot. */
+export function currentHeadOf(db, id, limit = REVISION_WALK_LIMIT) {
+  let current = Number(id);
+  const seen = new Set();
+  for (let hops = 0; hops < limit; hops += 1) {
+    if (seen.has(current)) return { ok: false, reason: "cycle", id: null, hops };
+    seen.add(current);
+    const next = successorOf(db, current);
+    if (next == null) return { ok: true, id: current, hops };
+    current = next;
+  }
+  return { ok: false, reason: "too-long", id: null, hops: limit };
+}
+
+/** Error the HTTP layer turns into 409 REVISION_LINKED / REVISION_PROTECTED. */
+function revisionGuardError(code, id, action) {
+  const err = new Error(`#${id} is part of a decision revision chain; ${action} would break the recorded history.`);
+  err.code = code;
+  err.status = 409;
+  err.nodeId = Number(id);
+  return err;
+}
+
+/**
+ * Chain bodies are confirmed history: a new fact is a new decision that then
+ * supersedes the old one, never an in-place rewrite.
+ */
+export function assertBodyEditable(db, id) {
+  if (isRevisionLinked(db, id)) throw revisionGuardError("REVISION_PROTECTED", id, "rewriting its body");
+}
+
 export function deleteNode(db, id) {
   const n = Number(id);
   if (!db.contains?.(n) && !db.get(n)) return false;
+  if (isRevisionLinked(db, n)) throw revisionGuardError("REVISION_LINKED", n, "deleting it");
   db.delete(n);
   rebuildTextIndex(db);
   persist(db);
@@ -426,18 +572,22 @@ export function updateNode(db, id, patch = {}) {
   if (old.type === "workspace") return null;
   const next = { ...old };
   if (patch.name !== undefined) next.name = String(patch.name || "").trim();
-  if (patch.text !== undefined) next.text = String(patch.text || "").trim();
+  if (patch.text !== undefined) {
+    const body = String(patch.text || "").trim();
+    // Only the body is protected: a renamed alias, a corrected deadline or an
+    // extra source note does not change the fact being remembered.
+    if (body !== String(old.text || "").trim()) assertBodyEditable(db, nid);
+    next.text = body;
+  }
   if (Array.isArray(patch.aliases)) {
     next.aliases = uniqueStrings(patch.aliases).filter((a) => a !== next.name);
   }
+  let deadlineChanged = false;
   if (patch.until !== undefined) {
     const until = String(patch.until || "").trim();
-    if (until) {
-      next.until = until;
-      const untilAt = resolveUntilAt(until, next.createdAt);
-      if (untilAt) next.untilAt = untilAt;
-    } else {
-      delete next.until;
+    deadlineChanged = until !== String(old.until || "").trim();
+    next.until = until;
+    if (deadlineChanged || !until) {
       delete next.untilAt;
     }
   }
@@ -447,7 +597,7 @@ export function updateNode(db, id, patch = {}) {
     createdAt: old.createdAt,
     status: old.status || "active",
     updatedAt: nowIso(),
-  });
+  }, deadlineChanged ? nowIso() : old.createdAt);
   const gate = sanitizeForWrite([body.name, body.text, body.fail, body.fix].filter(Boolean).join("\n"));
   if (!gate.ok && gate.reason !== "empty") {
     const err = new Error(gate.reason);
@@ -480,6 +630,16 @@ export function mergeNodes(db, keepId, dropId) {
   if (pa.status === "archived" || pb.status === "archived") {
     return { ok: false, message: "archived" };
   }
+  // Merging either end of a revision chain would leave a dangling history or a
+  // wrong "current version". The user has to undo the relation first.
+  if (isRevisionLinked(db, keep) || isRevisionLinked(db, drop)) {
+    return {
+      ok: false,
+      status: 409,
+      code: "REVISION_LINKED",
+      message: "节点在决策替代链上，请先处理替代关系再合并。",
+    };
+  }
   const inbound = nativeIncoming(db, drop);
   if (inbound) {
     for (const e of inbound) {
@@ -506,7 +666,7 @@ export function mergeNodes(db, keepId, dropId) {
     text: pa.text,
     aliases: [...(pa.aliases || []), ...(pb.aliases || []), pb.name],
     until: pa.until || pb.until,
-    untilAt: pa.untilAt || pb.untilAt,
+    untilAt: pa.until ? pa.untilAt : pb.untilAt,
     source: pa.source || pb.source,
   });
   ensureLink(db, drop, keep, EDGE_LABELS.sameAs);
@@ -514,6 +674,15 @@ export function mergeNodes(db, keepId, dropId) {
   return { ok: true, keep, drop, type: pa.type };
 }
 
+export const GRAPH_FORMAT = "dsh-trivium-graph";
+
+/**
+ * v2 keeps the v1 node/edge shape and adds edge metadata, which is where a
+ * revision relation stores its reason and confirmation time. A v1 reader that
+ * ignores `metadata` still imports the graph; it just loses the reason text.
+ */
+export const GRAPH_VERSION = 2;
+
 export function exportGraph(db, cwd = "") {
   const nodes = [];
   const edges = [];
@@ -522,17 +691,21 @@ export function exportGraph(db, cwd = "") {
     if (!node) continue;
     nodes.push({ id: Number(id), payload: node.payload || {} });
     for (const e of node.edges || []) {
-      edges.push({
+      const row = {
         from: Number(id),
         to: edgeTarget(e),
         label: e.label || "",
         weight: e.weight ?? null,
-      });
+      };
+      // Edge metadata is only written when present, so a graph without revision
+      // relations stays byte-comparable with a v1 export.
+      if (e.metadata && typeof e.metadata === "object") row.metadata = e.metadata;
+      edges.push(row);
     }
   }
   return {
-    format: "dsh-trivium-graph",
-    version: 1,
+    format: GRAPH_FORMAT,
+    version: GRAPH_VERSION,
     exportedAt: nowIso(),
     cwd: cwd || "",
     dim: DIM,
@@ -551,12 +724,91 @@ export function findByUri(db, uri) {
   return null;
 }
 
-/** Merge an exported graph into the open workspace. Remaps ids; skips extra workspace roots. */
+/**
+ * Merge an exported graph into the open workspace. Remaps ids; skips extra
+ * workspace roots.
+ *
+ * Revision edges are validated as a whole before anything is written, and
+ * conflicts with the live chain are reported instead of applied: an import must
+ * never resurrect an old version or half-build a chain.
+ */
 export function importGraph(db, graph) {
   const body = graph?.graph && Array.isArray(graph.graph.nodes) ? graph.graph : graph;
   const nodes = Array.isArray(body?.nodes) ? body.nodes : null;
   if (!nodes) return { ok: false, message: "不是本插件导出的 JSON" };
   const edges = Array.isArray(body.edges) ? body.edges : [];
+  const version = Number(body.version) || 1;
+
+  const payloadByOldId = new Map();
+  for (const row of nodes) {
+    const oldId = Number(row?.id);
+    if (!Number.isFinite(oldId)) continue;
+    payloadByOldId.set(oldId, row?.payload && typeof row.payload === "object" ? row.payload : null);
+  }
+  const revisionEdges = edges
+    .filter((e) => REVISION_EDGES.includes(String(e.label || "")))
+    .map((e) => ({ from: Number(e.from), to: Number(e.to), metadata: e.metadata || null }));
+
+  if (revisionEdges.length) {
+    // Pure structural pass over the imported graph, before any write.
+    const structure = validateRevisionStructure({
+      edges: revisionEdges,
+      payloadOf: (id) => payloadByOldId.get(Number(id)) || null,
+    });
+    if (!structure.ok) {
+      return {
+        ok: false,
+        status: 409,
+        code: "REVISION_LINKED",
+        message: "导入的版本关系未通过校验，未写入任何内容。",
+        conflicts: structure.conflicts,
+      };
+    }
+    const conflicts = [];
+    /*
+     * Resolve exactly like the apply pass does: stable URI first, then the text
+     * heuristic for legacy nodes that never got a URI. Anything else would let
+     * the pre-check miss a conflict the apply pass would then write into.
+     */
+    const resolveLocal = (payload) => {
+      const uri = String(payload?.uri || "").trim();
+      if (uri) {
+        const byUri = findByUri(db, uri);
+        if (byUri != null) return byUri;
+      }
+      return findMergeTarget(db, payload, { allowRevisionLinked: true });
+    };
+    const localOf = (oldId) => resolveLocal(payloadByOldId.get(Number(oldId)));
+    for (const edge of revisionEdges) {
+      const oldLocal = localOf(edge.to);
+      if (oldLocal == null) continue;
+      const existing = successorOf(db, oldLocal);
+      if (existing == null) continue;
+      const successorLocal = localOf(edge.from);
+      if (successorLocal == null || Number(existing) !== Number(successorLocal)) {
+        conflicts.push({ code: "already-superseded", id: oldLocal });
+      }
+    }
+    for (const row of nodes) {
+      const payload = row?.payload;
+      if (!payload) continue;
+      const dest = resolveLocal(payload);
+      if (dest == null) continue;
+      const live = db.get(dest)?.payload || {};
+      if (String(payload.text || "").trim() === String(live.text || "").trim()) continue;
+      if (isRevisionLinked(db, dest)) conflicts.push({ code: "chain-body", id: dest });
+    }
+    if (conflicts.length) {
+      return {
+        ok: false,
+        status: 409,
+        code: "REVISION_LINKED",
+        message: "导入内容与现有的决策替代链冲突，未写入。",
+        conflicts,
+      };
+    }
+  }
+
   const idMap = new Map();
   const root = workspaceId(db);
   let created = 0;
@@ -572,9 +824,10 @@ export function importGraph(db, graph) {
     }
     if (!NODE_TYPES.includes(payload.type)) continue;
     let dest = findByUri(db, payload.uri);
-    if (dest == null) dest = findMergeTarget(db, payload);
+    if (dest == null) dest = findMergeTarget(db, payload, { allowRevisionLinked: true });
     if (dest != null) {
-      mergeInto(db, dest, payload);
+      // An exported snapshot is authoritative, including a cleared deadline.
+      mergeInto(db, dest, { ...payload, until: payload.until ?? "" });
       idMap.set(oldId, dest);
       merged += 1;
     } else {
@@ -584,13 +837,62 @@ export function importGraph(db, graph) {
     }
   }
   for (const e of edges) {
+    const label = e.label || EDGE_LABELS.about;
+    if (REVISION_EDGES.includes(String(label))) continue;
     const from = idMap.get(Number(e.from));
     const to = idMap.get(Number(e.to));
-    const label = e.label || EDGE_LABELS.about;
     if (from == null || to == null || from === to) continue;
     if (ensureLink(db, from, to, label)) linked += 1;
   }
-  return { ok: true, created, merged, linked, nodes: idMap.size };
+
+  // Revision edges go in one native transaction after the nodes exist: the
+  // chain is either complete or absent, never half built.
+  let revisionLinked = 0;
+  const revisionConflicts = [];
+  if (revisionEdges.length) {
+    const ops = [];
+    const seenPairs = new Set();
+    for (const edge of revisionEdges) {
+      const from = idMap.get(Number(edge.from));
+      const to = idMap.get(Number(edge.to));
+      if (from == null || to == null) {
+        revisionConflicts.push({ code: "unmapped", id: Number(edge.from) });
+        continue;
+      }
+      const pair = `${from}\u0000${to}`;
+      if (seenPairs.has(pair)) continue;
+      seenPairs.add(pair);
+      if (hasEdge(db, from, to, EDGE_LABELS.supersedes)) continue;
+      ops.push({
+        type: "upsertEdge",
+        src: from,
+        dst: to,
+        label: EDGE_LABELS.supersedes,
+        weight: weightOf(EDGE_LABELS.supersedes),
+        metadata: edge.metadata || { at: nowIso() },
+      });
+    }
+    if (ops.length) {
+      try {
+        db.commitTransaction(ops);
+        revisionLinked = ops.length;
+        persistAfterRevision(db);
+      } catch (err) {
+        revisionConflicts.push({ code: "transaction-failed", message: String(err.message || err) });
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    version,
+    created,
+    merged,
+    linked,
+    revisionLinked,
+    revisionConflicts,
+    nodes: idMap.size,
+  };
 }
 
 export function hasEdge(db, from, to, label) {
@@ -637,14 +939,18 @@ function pickMergedText(oldText, incomingText) {
   return b.length >= a.length ? b : a;
 }
 
-function decorateUntil(payload) {
+function decorateUntil(payload, from = payload.createdAt) {
   const body = { ...payload };
-  if (body.type === "decision" && !body.until) {
-    const until = parseUntilFromText(body.text);
-    if (until) body.until = until;
+  const until = String(body.until || "").trim();
+  if (!until) {
+    delete body.until;
+    delete body.untilAt;
+    return body;
   }
-  if (body.until && !body.untilAt) {
-    const untilAt = resolveUntilAt(body.until, body.createdAt);
+  body.until = until;
+  if (!body.untilAt || !Number.isFinite(Date.parse(body.untilAt))) {
+    delete body.untilAt;
+    const untilAt = resolveUntilAt(until, from);
     if (untilAt) body.untilAt = untilAt;
   }
   return body;
@@ -718,15 +1024,35 @@ export async function backfillEmbeddings(db, { log } = {}) {
   return { ok: true, embedded, failed };
 }
 
-export function searchNodes(db, query, { topK = 8, expandDepth = 1, now, queryVector } = {}) {
+/**
+ * @param onStage - optional observer `(stageName, ids)` called once per pipeline
+ *   branch that actually produced candidates. Used by the recall trace, which
+ *   must not claim a branch ran when it did not.
+ */
+export function searchNodes(db, query, { topK = 8, expandDepth = 1, now, queryVector, includeStale = true, onStage } = {}) {
   const text = String(query || "").trim();
   if (!text) return [];
   const at = now instanceof Date ? now : new Date();
   const primary = new Map();
-  const consider = (id) => {
+  const terms = queryTerms(text);
+  const hasQueryVector = Array.isArray(queryVector) && queryVector.length === DIM &&
+    queryVector.every(Number.isFinite) && queryVector.some((value) => value !== 0);
+  const identifierQuery = /^[a-z0-9_]+(?:[-./:][a-z0-9_]+)+$/i.test(text);
+  const consider = (id, nativeScore = 0) => {
     const rec = hitRecord(db, id);
     if (!rec) return;
-    const score = primaryScore(rec.payload, text, at);
+    // A native BM25/vector hit is already a retrieval candidate. Lexical
+    // evidence may boost it, but must never veto it with an exact-phrase gate.
+    const lexical = primaryScore(rec.payload, text, at, terms);
+    // Explicit keywords are additive in 0.8.x. A renamed node may still have
+    // an old native keyword: require some current token evidence for text-only
+    // hits, never the whole query phrase. Vector-only hits need no such overlap.
+    const currentText = indexTextFor(rec.payload).toLowerCase();
+    if (!hasQueryVector && lexical <= 0 && !terms.some((term) => currentText.includes(term))) return;
+    // Keep code identifiers atomic: a sparse hit for just "X" must not turn
+    // an exact X-Request-Id lookup into a hit on an unrelated header X fact.
+    if (identifierQuery && !hasQueryVector && lexical <= 0) return;
+    const score = Math.max(lexical, Number.isFinite(nativeScore) ? nativeScore : 0);
     if (score <= 0) return;
     rec.score = score;
     rec.query = text;
@@ -734,20 +1060,38 @@ export function searchNodes(db, query, { topK = 8, expandDepth = 1, now, queryVe
     const prev = primary.get(rec.id);
     if (!prev || rec.score > prev.score) primary.set(rec.id, rec);
   };
+  const report = (stage, ids) => {
+    if (typeof onStage !== "function") return;
+    try {
+      onStage(stage, ids);
+    } catch {
+      // a broken observer must not break retrieval
+    }
+  };
   try {
     const vec =
-      Array.isArray(queryVector) && queryVector.length === DIM ? queryVector : zeroVector();
-    const hits = db.searchHybrid(vec, text, Math.max(topK, 16), 0, 0.01, 0.2);
-    for (const hit of hits || []) consider(hit.id);
+      hasQueryVector ? queryVector : zeroVector();
+    const hits = db.searchHybrid(vec, text, Math.max(topK, 16), 0, 0.01, 0.2, {
+      type: { $in: ["entity", "decision", "preference", "experience"] },
+      status: { $ne: "archived" },
+    });
+    report("native-hybrid", (hits || []).map((hit) => hit.id));
+    for (const hit of hits || []) consider(hit.id, Number(hit.score));
   } catch {
     // fall through to keyword scan
   }
-  for (const hit of keywordFallback(db, text, 64)) consider(hit.id);
-  for (const id of entityAnchorIds(db, text)) consider(id);
+  const fallback = keywordFallback(db, text, 64, terms);
+  report("keyword-fallback", fallback.map((hit) => hit.id));
+  for (const hit of fallback) consider(hit.id);
+  const anchors = entityAnchorIds(db, text);
+  report("entity-anchor", anchors);
+  for (const id of anchors) consider(id);
   if (queryMentionsUntil(text)) {
     for (const id of db.allNodeIds?.() || []) consider(id);
+    report("deadline-scan", [...primary.keys()]);
   }
 
+  const normalized = [];
   for (const hit of [...primary.values()]) {
     const dest = sameAsTarget(db, hit.id);
     if (dest == null || dest === hit.id || primary.has(dest)) continue;
@@ -758,10 +1102,13 @@ export function searchNodes(db, query, { topK = 8, expandDepth = 1, now, queryVe
     rec.query = text;
     rec.now = at;
     primary.set(dest, rec);
+    normalized.push(dest);
   }
+  report("same-as-normalize", normalized);
 
   const out = new Map(primary);
   if (expandDepth > 0) {
+    const expanded = [];
     for (const hit of primary.values()) {
       for (const nid of businessNeighborIds(db, hit.id)) {
         if (out.has(nid)) continue;
@@ -772,30 +1119,43 @@ export function searchNodes(db, query, { topK = 8, expandDepth = 1, now, queryVe
           rec.query = text;
           rec.now = at;
           out.set(nid, rec);
+          expanded.push(nid);
         }
       }
     }
+    report("business-expand", expanded);
   }
   const typeRank = { entity: 0, decision: 1, preference: 2, experience: 3 };
   return [...out.values()]
-    .filter((hit) => !shouldHideStale(hit, text, at))
+    .filter((hit) => includeStale || !isStalePayload(hit.payload, at))
+    .map((hit) => ({ ...hit, includeStale }))
     .sort((a, b) => {
       const rb = rankBoost(db, b, text, at) - rankBoost(db, a, text, at);
       if (rb) return rb;
-      const td = (typeRank[a.payload?.type] ?? 9) - (typeRank[b.payload?.type] ?? 9);
-      if (td) return td;
-      return (b.score || 0) - (a.score || 0);
+      const score = (b.score || 0) - (a.score || 0);
+      if (score) return score;
+      return (typeRank[a.payload?.type] ?? 9) - (typeRank[b.payload?.type] ?? 9);
     })
     .slice(0, topK);
 }
 
 /** Entity-name hit → that entity plus unexpired business-edge neighbors. Empty if query names none. */
-export function namedRecallHits(db, query, { topK = 8, now } = {}) {
+export function namedRecallHits(db, query, { topK = 8, now, onStage } = {}) {
   const text = String(query || "").trim();
   const ids = entityAnchorIds(db, text);
   if (!ids.length) return [];
   const at = now instanceof Date ? now : new Date();
   const out = new Map();
+  const report = (stage, list) => {
+    if (typeof onStage !== "function") return;
+    try {
+      onStage(stage, list);
+    } catch {
+      // ignore a broken observer
+    }
+  };
+  report("entity-anchor", ids);
+  const expanded = [];
   for (const id of ids) {
     const rec = hitRecord(db, id);
     if (rec) {
@@ -814,10 +1174,12 @@ export function namedRecallHits(db, query, { topK = 8, now } = {}) {
       nrec.query = text;
       nrec.now = at;
       out.set(nid, nrec);
+      expanded.push(nid);
     }
   }
+  report("business-expand", expanded);
   return [...out.values()]
-    .filter((hit) => !shouldHideStale(hit, text, at))
+    .filter((hit) => !isStalePayload(hit.payload, at))
     .slice(0, topK);
 }
 
@@ -827,12 +1189,6 @@ function hasBusinessEdge(db, hit) {
   return incomingBusinessEdges(db, hit.id).length > 0;
 }
 
-function shouldHideStale(hit, query, now) {
-  if (hit.payload?.type !== "decision") return false;
-  if (!isStalePayload(hit.payload, now)) return false;
-  return !queryMentionsUntil(query, hit.payload);
-}
-
 function rankBoost(db, hit, query, now) {
   let n = 0;
   if (hasBusinessEdge(db, hit)) n += 4;
@@ -864,14 +1220,18 @@ function hitRecord(db, id) {
 
 const MIN_ENTITY_ANCHOR = 3;
 
+function longEnoughAnchor(label) {
+  return label.length >= MIN_ENTITY_ANCHOR || /^[\p{Script=Han}]{2}$/u.test(label);
+}
+
 function entityAnchorLabels(payload) {
   return uniqueStrings([payload?.name, ...(payload?.aliases || [])]).filter(
-    (s) => s.length >= MIN_ENTITY_ANCHOR,
+    longEnoughAnchor,
   );
 }
 
 function queryMentionsEntityName(queryLower, nameLower) {
-  if (!queryLower || !nameLower || nameLower.length < MIN_ENTITY_ANCHOR) return false;
+  if (!queryLower || !nameLower || !longEnoughAnchor(nameLower)) return false;
   if (queryLower === nameLower) return true;
   if (/^[\x00-\x7f]+$/.test(nameLower)) {
     const escaped = nameLower.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -902,7 +1262,31 @@ function entityAnchorIds(db, query) {
   return ids;
 }
 
-function primaryScore(payload, query, now) {
+const wordSegmenter = new Intl.Segmenter("zh", { granularity: "word" });
+const QUERY_STOP_WORDS = new Set(["的", "了", "是", "在", "有", "和", "与", "请", "什么", "哪些", "怎么", "如何", "一下", "这个", "我们", "the", "a", "an", "is", "are", "to", "of", "for", "and", "what", "how"]);
+
+function queryTerms(query) {
+  const chunks = query.toLowerCase().match(/[\p{L}\p{N}_]+(?:[-./:][\p{L}\p{N}_]+)*/gu) || [];
+  return [...new Set(chunks.flatMap((chunk) => /\p{Script=Han}/u.test(chunk)
+    ? [...wordSegmenter.segment(chunk)].filter((part) => part.isWordLike).map((part) => part.segment)
+    : [chunk])
+    .filter((term) => !QUERY_STOP_WORDS.has(term) && (!/\p{Script=Han}/u.test(term) || term.length >= 2)))];
+}
+
+function lexicalScore(payload, query, terms = queryTerms(query)) {
+  const hay = indexTextFor(payload).toLowerCase();
+  if (hay.includes(query)) return 2;
+  if (!terms.length) return 0;
+  const matched = terms.filter((term) => {
+    if (/\p{Script=Han}/u.test(term)) return hay.includes(term);
+    const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:^|[^a-z0-9_])${escaped}(?:$|[^a-z0-9_])`, "i").test(hay);
+  }).length;
+  const coverage = matched / terms.length;
+  return coverage >= 0.5 ? coverage : 0;
+}
+
+function primaryScore(payload, query, now, terms) {
   const q = String(query || "").trim().toLowerCase();
   if (!q) return 0;
   const name = String(payload?.name || "").toLowerCase();
@@ -912,7 +1296,7 @@ function primaryScore(payload, query, now) {
   if (name === q) score = 4;
   else if (name.includes(q)) score = 3;
   else if (text.includes(q) || until.includes(q)) score = 2;
-  else if (indexTextFor(payload || {}).toLowerCase().includes(q)) score = 2;
+  else score = lexicalScore(payload || {}, q, terms);
   if (
     payload?.type === "decision" &&
     isStalePayload(payload, now) &&
@@ -993,7 +1377,7 @@ function tqlBusinessNeighbors(db, id) {
   }
 }
 
-function keywordFallback(db, text, topK) {
+function keywordFallback(db, text, topK, terms) {
   const q = text.toLowerCase();
   const ids = db.allNodeIds?.() || [];
   const hits = [];
@@ -1007,17 +1391,16 @@ function keywordFallback(db, text, topK) {
     ) {
       continue;
     }
-    const hay = indexTextFor(node.payload || {}).toLowerCase();
-    if (!hay.includes(q)) continue;
+    const score = lexicalScore(node.payload || {}, q, terms);
+    if (!score) continue;
     hits.push({
       id,
-      score: 1,
+      score,
       payload: node.payload,
       edges: node.edges || [],
     });
-    if (hits.length >= topK) break;
   }
-  return hits;
+  return hits.sort((a, b) => b.score - a.score).slice(0, topK);
 }
 
 function nodeLabel(db, id) {
@@ -1054,8 +1437,7 @@ function incomingBusinessEdges(db, id, { query = "", now, hideStale = false } =
     if (!srcNode || srcNode.payload?.status === "archived") return;
     if (
       hideStale &&
-      isStalePayload(srcNode.payload, at) &&
-      !queryMentionsUntil(query, srcNode.payload)
+      isStalePayload(srcNode.payload, at)
     ) {
       return;
     }
@@ -1109,6 +1491,7 @@ function edgePath(db, nodeId, edges, { query = "", now, hideStale = true } = {})
   const seenOut = new Set();
   for (const e of edges || []) {
     const targetId = e.targetId ?? e.target_id;
+    if (hideStale && isStalePayload(db.get(Number(targetId))?.payload, now)) continue;
     const key = `${e.label}->${targetId}`;
     if (seenOut.has(key)) continue;
     seenOut.add(key);
@@ -1156,6 +1539,41 @@ export function listIncomingBusiness(db, id, opts = {}) {
   }));
 }
 
+/**
+ * Incoming edges for an arbitrary label set (revision edges are not business
+ * edges, so they cannot go through incomingBusinessEdges).
+ *
+ * Uses the native incoming index when available and otherwise scans outgoing
+ * edges. Only the management UI and the revision resolver call this, never the
+ * hot retrieval path.
+ */
+export function incomingLabeled(db, id, labels) {
+  const want = new Set([...(labels || [])].map(String));
+  const target = Number(id);
+  if (!want.size || !Number.isFinite(target)) return [];
+  const found = [];
+  const push = (from, label) => {
+    if (!Number.isFinite(from) || !want.has(String(label))) return;
+    if (found.some((row) => row.from === from && row.label === label)) return;
+    found.push({ from, label: String(label) });
+  };
+  const native = nativeIncoming(db, target);
+  if (Array.isArray(native)) {
+    for (const e of native) push(edgeSource(e), e.label ?? e.edge_label);
+    return found;
+  }
+  for (const raw of db.allNodeIds?.() || []) {
+    const from = Number(raw);
+    if (!Number.isFinite(from)) continue;
+    const node = db.get(from);
+    for (const e of node?.edges || []) {
+      if (edgeTarget(e) !== target) continue;
+      push(from, e.label);
+    }
+  }
+  return found;
+}
+
 export function formatHit(db, hit, opts = {}) {
   const node = db.get(hit.id) || { payload: hit.payload, edges: [] };
   const payload = node.payload || {};
@@ -1170,7 +1588,7 @@ export function formatHit(db, hit, opts = {}) {
     l0: l0.slice(0, 200),
     until: payload.until || "",
     stale,
-    path: edgePath(db, hit.id, node.edges || [], { query, now }),
+    path: edgePath(db, hit.id, node.edges || [], { query, now, hideStale: hit.includeStale !== true }),
   };
 }