dsh-trivium 0.4.21 → 0.5.0

package/lib/index.js

@@ -12,7 +12,6 @@ import {
   setActiveCwd,
   embedQueryVector,
 } from "./store.js";
-import { clipToTokenBudget } from "./tokens.js";
 import { clip } from "./schema.js";
 import {
   clearPending,
@@ -25,7 +24,29 @@ import { readUiSettings, registerMemoryApi } from "./server.js";
 import { applyRecallMode, chipsEnabledOf, recallModeOf, sessionLayerEnabledOf } from "./settings.js";
 import { configureEmbedding } from "./embed.js";
 import { recordCheckpoint, ensureTail, syncForkLineage } from "./episode.js";
-import { buildPinInject } from "./pins.js";
+import { pinCandidates } from "./pins.js";
+import { startTrace } from "./recall-trace.js";
+import { makeRevisionResolver } from "./revisions.js";
+import { noteObservedSession } from "./provenance.js";
+import {
+  MAP_TOKEN_BUDGET,
+  renderContextRecords,
+  selectContextRecords,
+  TURN_ADDITIONAL_BUDGET,
+  turnKeyOf,
+} from "./context-budget.js";
+import {
+  beginTurn,
+  clearAfterCompaction,
+  clearSession,
+  commit,
+  deliveredOf,
+  mapTextOf,
+  pendingCorrections,
+  remainingOf,
+  reserve,
+  rollback,
+} from "./turn-ledger.js";
 import { syncSidecarOnOpen } from "./sidecar.js";
 
 export const name = "dsh-trivium";
@@ -74,10 +95,22 @@ const DEFAULTS = {
 const buffers = new Map();
 const idleTimers = new Map();
 const mapInjected = new Set();
+/**
+ * The map text stays in the host context until compaction replaces it, so keep
+ * it per session and use it for cross-stage de-duplication in later turns.
+ */
+const mapTextBySession = new Map();
 const status = {
   lastInjectTokens: 0,
   lastInjectAt: null,
   lastExtract: null,
+  lastContextPlan: null,
+  /*
+   * Invocation probe for the pre-step hook: it separates "the host never called
+   * us" from "we threw before planning", which is otherwise invisible — the
+   * per-step warning only reaches the host log.
+   */
+  preStep: { count: 0, at: null, stage: "", error: "" },
 };
 
 function liveOptions(config) {
@@ -201,6 +234,9 @@ async function runExtract(ctx, { cwd, turns, sessionId, session, agent, log, opt
 
 function onSessionEvent(session, event) {
   const buf = bufOf(session);
+  // Provenance can only report a session as live if this process actually saw
+  // it; nothing here is inferred from the stored text.
+  noteObservedSession(sessionKey(session) || buf.sessionId);
   switch (event.type) {
     case "user/message": {
       const msg = event.data;
@@ -297,13 +333,100 @@ async function ensureShortMap(agent, options) {
     const cwd = cwdOf(agent);
     setActiveCwd(cwd);
     const db = await openWorkspaceDb(cwd);
-    return { db, cwd, map: injectShortMap(agent, db, options.mapTokenBudget || 400) };
+    const map = injectShortMap(agent, db, options.mapTokenBudget || MAP_TOKEN_BUDGET);
+    mapTextBySession.set(id, map.text);
+    return { db, cwd, map };
   } catch (err) {
     mapInjected.delete(id);
     throw err;
   }
 }
 
+function proposedQuery(decision, messages) {
+  const proposed = [...(decision?.messages || []), ...(messages || [])];
+  const lastUser = [...proposed].reverse().find((m) => m?.source?.kind === "user");
+  return lastUser ? textFromContent(lastUser.content).trim() : "";
+}
+
+/** Search hits carry a rendered row; selection wants fields. */
+function structuredHit(db, hit) {
+  const row = formatHit(db, hit);
+  return {
+    id: row.id,
+    type: row.type,
+    l0: row.l0,
+    until: row.until,
+    stale: row.stale,
+    path: row.path,
+  };
+}
+
+async function recallCandidates(db, mode, query, onStage) {
+  if (!query) return { hits: [], semantic: "not_run" };
+  if (mode === "anchor") {
+    return {
+      hits: namedRecallHits(db, query, { topK: 8, onStage })
+        .slice(0, 8)
+        .map((hit) => structuredHit(db, hit)),
+      // Anchor mode never consults the semantic channel.
+      semantic: "not_run",
+    };
+  }
+  const queryVector = await embedQueryVector(query);
+  const hits = searchNodes(db, query, {
+    topK: 3,
+    expandDepth: 1,
+    includeStale: false,
+    queryVector: queryVector || undefined,
+    onStage,
+  })
+    .slice(0, 3)
+    .map((hit) => structuredHit(db, hit));
+  return { hits, semantic: queryVector ? "ran" : "not_run" };
+}
+
+/** Trace-friendly node summaries for a list of ids. */
+function stageNodes(db, ids) {
+  return (ids || []).map((raw) => {
+    const id = Number(raw);
+    const payload = db.get(id)?.payload || {};
+    return { id, type: payload.type || "unknown", l0: String(payload.text || payload.name || "").slice(0, 80) };
+  });
+}
+
+/** Map a selection drop reason onto a trace filter reason. */
+const FILTER_BY_DROP = {
+  "over-budget": "budget",
+  "duplicate-node": "duplicate",
+  "duplicate-in-turn": "duplicate",
+  "already-in-map": "duplicate",
+  stale: "stale",
+  archived: "archived",
+  dirty: "hygiene",
+  "no-current": "revision",
+  empty: "hygiene",
+};
+
+function planSummary(plan) {
+  return {
+    budget: plan.budget,
+    tokens: plan.tokens,
+    estimatedTokens: plan.estimatedTokens,
+    at: plan.at,
+    records: plan.records.map((r) => ({
+      id: r.id,
+      channel: r.channel,
+      channels: r.channels,
+      type: r.type,
+      tokens: r.tokens || 0,
+      historical: r.historical === true,
+      matchedHistory: r.matchedHistory || null,
+    })),
+    dropped: plan.dropped,
+    deferred: plan.deferred,
+  };
+}
+
 export function apply(ctx, config = {}) {
   const log = ctx.logger?.("dsh-trivium") ?? console;
   const optionsOf = () => liveOptions(config);
@@ -384,6 +507,17 @@ export function apply(ctx, config = {}) {
       if (event.type === "compaction/end" && !event.data?.error) {
         clearIdle(sessionKey(session));
         const buf = bufOf(session);
+        /*
+         * The host replaced the old messages with a summary, so the map and the
+         * per-turn ledger describe content that is no longer there. Clear both
+         * and let the next pre-step rebuild what is still needed.
+         */
+        const compactedId = sessionKey(session) || buf.sessionId;
+        if (compactedId) {
+          clearAfterCompaction(compactedId);
+          mapInjected.delete(compactedId);
+          mapTextBySession.delete(compactedId);
+        }
         runExtract(runtime, {
           cwd: buf.cwd || session.header?.cwd,
           turns: buf.turns,
@@ -472,77 +606,112 @@ export function apply(ctx, config = {}) {
 
   ctx.on("agent/pre-step", async ({ agent, messages }, next) => {
     const decision = await next();
+    status.preStep.count += 1;
+    status.preStep.at = new Date().toISOString();
+    status.preStep.stage = "decision";
+    status.preStep.error = "";
     try {
-      if (!decision || decision.kind !== "enter") return decision;
+      if (!decision || decision.kind !== "enter") {
+        status.preStep.stage = "not-enter";
+        return decision;
+      }
+      const options = optionsOf();
       try {
-        await ensureShortMap(agent, optionsOf());
+        await ensureShortMap(agent, options);
       } catch (err) {
         log.warn?.(`[dsh-trivium] pre-step map skipped: ${err.message}`);
       }
-      const extra = [];
-      const db = await openWorkspaceDb(cwdOf(agent));
+      const chipsOn = chipsEnabledOf(options);
+      const mode = recallModeOf(options);
+      // Default stays quiet: both channels off means no pin/recall planning at all.
+      if (!chipsOn && mode === "off") {
+        status.preStep.stage = "channels-off";
+        return decision;
+      }
+
       const sessionId = sessionKey(agent.session);
-      const options = optionsOf();
-      if (chipsEnabledOf(options)) {
-        try {
-          const pin = buildPinInject(db, sessionId, 300);
-          if (pin.text) {
-            extra.push(
-              createUserMessage({
-                content: [{ type: "text", text: pin.text }],
-                // No `form`: "pins" was never in DSH's ContextForm union, so the
-                // client already rendered it as undeclared (opaque) context.
-                // Omitting the field is the documented default for that.
-                source: producerSource(),
-              }),
-            );
-          }
-        } catch (err) {
-          log.warn?.(`[dsh-trivium] pre-step pins skipped: ${err.message}`);
+      const turnKey = turnKeyOf([...(decision.messages || []), ...(messages || [])]);
+      beginTurn(sessionId, turnKey);
+      // 300 is the cumulative allowance for one user turn, not per pre-step:
+      // a tool loop that re-enters must not start a fresh 300 each time.
+      const remaining = remainingOf(sessionId, turnKey, TURN_ADDITIONAL_BUDGET);
+      if (remaining <= 0) return decision;
+
+      const db = await openWorkspaceDb(cwdOf(agent));
+      const cwd = cwdOf(agent);
+      const pins = chipsOn ? pinCandidates(db, sessionId, { resolveRevision: makeRevisionResolver(db) }) : [];
+      const query = mode === "off" ? "" : proposedQuery(decision, messages);
+      const trace =
+        mode === "off"
+          ? null
+          : startTrace({ cwd, sessionId, query, mode, semantic: "not_run", source: "pre-step" });
+      const recall = mode === "off" ? { hits: [], semantic: "not_run" } : await recallCandidates(db, mode, query, (stage, ids) => trace?.stage(stage, stageNodes(db, ids)));
+      const form = mode === "anchor" ? "anchorRecall" : "autoRecall";
+      const plan = selectContextRecords({
+        pins,
+        recall: recall.hits,
+        corrections: pendingCorrections(sessionId),
+        budget: remaining,
+        form,
+        delivered: deliveredOf(sessionId, turnKey),
+        mapText: mapTextOf(sessionId, turnKey) || mapTextBySession.get(sessionId) || "",
+        resolveCurrent: makeRevisionResolver(db),
+      });
+      if (trace) {
+        // Only nodes that were actually candidates get a filter reason; a node
+        // that never entered the pipeline is not "filtered by a rule".
+        for (const [dropReason, filterReason] of Object.entries(FILTER_BY_DROP)) {
+          const ids = plan.dropped.filter((d) => d.reason === dropReason).map((d) => d.id);
+          if (ids.length) trace.filter(filterReason, stageNodes(db, ids));
         }
+        trace.selected({
+          ids: plan.records.map((r) => r.id),
+          budget: plan.budget,
+          tokens: plan.tokens,
+          deferred: plan.deferred,
+        });
+        status.lastTrace = trace.finish({ semantic: recall.semantic });
       }
-      const mode = recallModeOf(options);
-      if (mode !== "off") {
-        const proposed = [...(decision.messages || []), ...(messages || [])];
-        const lastUser = [...proposed].reverse().find((m) => m?.source?.kind === "user");
-        const query = lastUser ? textFromContent(lastUser.content).trim() : "";
-        if (query) {
-          let hits;
-          if (mode === "anchor") {
-            hits = namedRecallHits(db, query, { topK: 8 }).slice(0, 8);
-          } else {
-            const queryVector = await embedQueryVector(query);
-            hits = searchNodes(db, query, {
-              topK: 3,
-              expandDepth: 1,
-              queryVector: queryVector || undefined,
-            }).slice(0, 3);
-          }
-          if (hits.length) {
-            const lines = hits.map((hit) => {
-              const row = formatHit(db, hit);
-              return `- [${row.type}#${row.id}] ${row.l0} (${row.path.join(" | ") || "no path"})`;
-            });
-            const form = mode === "anchor" ? "anchorRecall" : "autoRecall";
-            const text = clipToTokenBudget(
-              `dsh-trivium ${form} (L0 only; use ctx_read for full text):\n${lines.join("\n")}`,
-              300,
-            );
-            extra.push(
-              createUserMessage({
-                content: [{ type: "text", text }],
-                source: producerSource({ form: "recall" }),
-              }),
-            );
-          }
+      status.lastContextPlan = planSummary(plan);
+      status.preStep.stage = "planned";
+      if (!plan.records.length) return decision;
+
+      const rendered = renderContextRecords(plan, { form });
+      // Reserve first, assemble second, commit last: anything that throws while
+      // building the messages rolls the reservation back, so the next pre-step
+      // retries the same content instead of believing it was delivered.
+      const reservation = reserve(sessionId, turnKey, plan.records);
+      try {
+        const extra = [];
+        if (rendered.pins.text) {
+          extra.push(
+            createUserMessage({
+              content: [{ type: "text", text: rendered.pins.text }],
+              // No `form`: "pins" was never in DSH's ContextForm union, so the
+              // client already rendered it as undeclared (opaque) context.
+              // Omitting the field is the documented default for that.
+              source: producerSource(),
+            }),
+          );
+        }
+        if (rendered.recall.text) {
+          extra.push(
+            createUserMessage({
+              content: [{ type: "text", text: rendered.recall.text }],
+              source: producerSource({ form: "recall" }),
+            }),
+          );
         }
+        const nextDecision = { kind: "enter", messages: [...extra, ...decision.messages] };
+        commit(reservation);
+        return nextDecision;
+      } catch (err) {
+        rollback(reservation);
+        throw err;
       }
-      if (!extra.length) return decision;
-      return {
-        kind: "enter",
-        messages: [...extra, ...decision.messages],
-      };
     } catch (err) {
+      status.preStep.stage = "error";
+      status.preStep.error = String(err?.message || err);
       log.warn?.(`[dsh-trivium] pre-step recall skipped: ${err.message}`);
       return decision;
     }
@@ -557,6 +726,10 @@ export function apply(ctx, config = {}) {
       }
       buffers.delete(sessionKey(session));
       mapInjected.delete(sessionKey(session));
+      mapTextBySession.delete(sessionKey(session));
+      // A fork is a different session id, so it starts with an empty ledger and
+      // no inherited pins — nothing from the parent can leak through here.
+      clearSession(sessionKey(session));
     } catch (err) {
       log.warn?.(`[dsh-trivium] dispose skipped: ${err.message}`);
     }

package/lib/markdown.js

@@ -19,7 +19,6 @@ import {
   applyCandidates,
   firstEntityName,
 } from "./extract.js";
-import { parseUntilFromText } from "./until.js";
 import { listOutgoingBusiness } from "./store.js";
 
 export const EXPORT_MARKER = "dsh-trivium-export";
@@ -192,7 +191,6 @@ function classifyBullet(text, sectionEntity) {
           type: "decision",
           name,
           text: fact,
-          until: parseUntilFromText(body),
           linkName: name,
           linkLabel: "decided",
           quote: clip(body, 120),

package/lib/pins.js

@@ -1,15 +1,15 @@
 /** Per-session memory chips. Pins inject into the next turn of the current session. */
 
 import { listEpisodeRecords } from "./episode.js";
-import { clipToTokenBudget, estimateTokens } from "./tokens.js";
+import { renderContextRecords, selectContextRecords, TURN_ADDITIONAL_BUDGET } from "./context-budget.js";
 import { pinsOf, writePins } from "./settings.js";
 import { archiveNode, deleteNode, suggestedNeighborIds } from "./store.js";
 import { applyCandidates, DECISION_CUES, EXPLICIT_LINE_CHARS, firstEntityName } from "./extract.js";
 import { clip } from "./schema.js";
 import { payloadLooksDirty, sanitizeForWrite, writeGateMessage } from "./hygiene.js";
-import { parseUntilFromText } from "./until.js";
+import { isStalePayload } from "./until.js";
 
-export const PIN_TOKEN_BUDGET = 300;
+export const PIN_TOKEN_BUDGET = TURN_ADDITIONAL_BUDGET;
 export const CHIP_TYPES = Object.freeze(["preference", "decision", "entity"]);
 
 const CHIP_SET = new Set(CHIP_TYPES);
@@ -109,25 +109,56 @@ export function prunePins(db, sessionId) {
   return kept;
 }
 
-export function buildPinInject(db, sessionId, budget = PIN_TOKEN_BUDGET) {
+/**
+ * Structured pin candidates, in user order.
+ *
+ * Selection owns filtering, de-duplication and rendering; handing over fields
+ * instead of a pre-clipped string is what lets chips and recall share one
+ * budget without the same node appearing twice.
+ *
+ * A pinned node that has since been superseded is kept as the user pinned it —
+ * it is marked historical, never silently rewritten to its successor.
+ */
+export function pinCandidates(db, sessionId, { resolveRevision = null, now } = {}) {
   const ids = prunePins(db, sessionId);
-  if (!ids.length) return { text: "", tokens: 0, clipped: false, ids: [] };
-  const lines = ["dsh-trivium pins (L0 only; use ctx_read for full text):"];
-  const used = [];
+  const out = [];
   for (const id of ids) {
     const payload = db.get(Number(id))?.payload;
-    if (!payload || payloadLooksDirty(payload)) continue;
-    lines.push(`- [${payload.type}#${id}] ${l0Of(payload)}`);
-    used.push(Number(id));
+    if (!payload) continue;
+    const row = {
+      id: Number(id),
+      type: payload.type,
+      l0: l0Of(payload),
+      until: payload.until || payload.untilAt || "",
+      stale: isStalePayload(payload, now instanceof Date ? now : undefined),
+      archived: payload.status === "archived",
+      dirty: payloadLooksDirty(payload),
+      historical: false,
+      supersededBy: null,
+    };
+    if (typeof resolveRevision === "function") {
+      const revision = resolveRevision(Number(id));
+      const currentId = Number(revision?.currentId);
+      if (Number.isFinite(currentId) && currentId !== Number(id)) {
+        row.historical = true;
+        row.supersededBy = currentId;
+      }
+    }
+    out.push(row);
   }
-  const full = lines.join("\n");
-  const cap = Math.max(1, Number(budget) || PIN_TOKEN_BUDGET);
-  const text = clipToTokenBudget(full, cap);
+  return out;
+}
+
+export function buildPinInject(db, sessionId, budget = PIN_TOKEN_BUDGET, { resolveRevision = null } = {}) {
+  const candidates = pinCandidates(db, sessionId, { resolveRevision });
+  if (!candidates.length) return { text: "", tokens: 0, clipped: false, ids: [] };
+  const plan = selectContextRecords({ pins: candidates, budget });
+  const rendered = renderContextRecords(plan).pins;
   return {
-    text,
-    tokens: estimateTokens(text),
-    clipped: estimateTokens(full) > cap,
-    ids: used,
+    text: rendered.text,
+    tokens: rendered.tokens,
+    clipped: plan.dropped.some((d) => d.reason === "over-budget"),
+    ids: plan.records.map((record) => record.id),
   };
 }
 
@@ -200,7 +231,6 @@ function candidateFromChipLine(body) {
           type: "decision",
           name,
           text: clip(text, EXPLICIT_LINE_CHARS),
-          until: parseUntilFromText(text),
           linkName: name,
           linkLabel: "decided",
           quote: clip(text, 120),
@@ -258,10 +288,25 @@ export function batchChipAction(db, { action, ids, sessionId = "" } = {}) {
   const verb = action === "delete" ? "delete" : "archive";
   const list = [...new Set((ids || []).map(Number).filter((id) => Number.isFinite(id)))];
   let count = 0;
+  const blocked = [];
   for (const id of list) {
-    const ok = verb === "delete" ? deleteNode(db, id) : archiveNode(db, id);
-    if (ok) count += 1;
+    try {
+      const ok = verb === "delete" ? deleteNode(db, id) : archiveNode(db, id);
+      if (ok) count += 1;
+    } catch (err) {
+      // Deleting a node inside a revision chain would leave a dangling
+      // history; report it per id instead of failing the whole batch.
+      if (err?.code === "REVISION_LINKED") blocked.push(id);
+      else throw err;
+    }
   }
   if (sessionId) prunePins(db, sessionId);
-  return { ok: count > 0 || list.length === 0, action: verb, count, ids: list };
+  return {
+    ok: count > 0 || list.length === 0,
+    action: verb,
+    count,
+    ids: list,
+    blocked,
+    code: blocked.length ? "REVISION_LINKED" : "",
+  };
 }

package/lib/provenance.js

@@ -0,0 +1,147 @@
+/**
+ * Provenance: where a memory came from.
+ *
+ * The plugin only ever has the fields it actually recorded. There is no host
+ * API that can turn a node id back into a message, so this module never
+ * reconstructs a session, an author or a quote — a record without `source`
+ * reports "not recorded" instead of guessing.
+ *
+ * Everything here is a projection for the management UI; none of it is injected
+ * into model context and none of it leaves the current workspace.
+ */
+
+import { listEpisodeRecords } from "./episode.js";
+
+/** Short preview cap for a stored quote, in code points. */
+export const QUOTE_PREVIEW_MAX = 240;
+
+export const SOURCE_KINDS = Object.freeze(["manual", "extract", "chip", "import", "tool"]);
+
+/** Existing writes carried `via`; map them onto the newer `kind`. */
+const KIND_BY_VIA = Object.freeze({
+  "chip-add": "chip",
+  "workbuddy-import": "import",
+  "external-import": "import",
+  extract: "extract",
+  tool: "tool",
+  manual: "manual",
+});
+
+const SESSION_SEEN = new Set();
+
+/** Called on every session we observe, so a recent one can be reported as live. */
+export function noteObservedSession(sessionId) {
+  const id = String(sessionId || "").trim();
+  if (id) SESSION_SEEN.add(id);
+  if (SESSION_SEEN.size > 200) {
+    const first = SESSION_SEEN.values().next().value;
+    SESSION_SEEN.delete(first);
+  }
+}
+
+export function resetObservedSessions() {
+  SESSION_SEEN.clear();
+}
+
+/**
+ * Plain text for display: control characters and bidi overrides removed.
+ *
+ * HTML/script markup is deliberately NOT stripped here — the client renders
+ * this as a text node, so it cannot execute, and losing it would hide what the
+ * user actually stored. Write-time hygiene still applies before anything is
+ * saved.
+ */
+export function plainText(value, max = QUOTE_PREVIEW_MAX) {
+  const raw = String(value ?? "").replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, " ");
+  const flat = raw.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, Math.max(0, max - 1))}…` : flat;
+}
+
+function str(value, max = 200) {
+  const raw = plainText(value, max);
+  return raw;
+}
+
+/**
+ * Project a stored `source`. Optional fields may be missing; nothing is inferred.
+ *
+ * @returns `{ recorded: false }` when the payload carries no locatable source.
+ */
+export function normalizeSource(source) {
+  if (!source || typeof source !== "object") return { recorded: false };
+  const via = str(source.via, 40);
+  const rawKind = str(source.kind, 24).toLowerCase();
+  const kind = SOURCE_KINDS.includes(rawKind) ? rawKind : KIND_BY_VIA[via] || "";
+  const sessionId = str(source.sessionId, 120);
+  const messageId = str(source.messageId ?? source.eventSeq ?? "", 120);
+  const quote = plainText(source.quote);
+  const capturedAt = str(source.capturedAt, 40);
+  const importPath = str(source.importPath, 400);
+  const recorded = Boolean(kind || sessionId || messageId || quote || capturedAt || importPath || via);
+  if (!recorded) return { recorded: false };
+  return {
+    recorded: true,
+    kind,
+    via,
+    sessionId,
+    messageId,
+    quote,
+    capturedAt,
+    importPath,
+  };
+}
+
+/**
+ * Is this session still reachable from this workspace?
+ *
+ * The plugin has two honest signals: an episode node recorded for that session
+ * in this workspace, or having observed the session in this process. Anything
+ * else is reported as unverifiable rather than assumed alive.
+ */
+export function sessionStateOf(db, sessionId) {
+  const sid = String(sessionId || "");
+  if (!sid) return "unknown";
+  try {
+    if (listEpisodeRecords(db, sid).length) return "seen";
+  } catch {
+    // an unreadable episode index must not turn into a false positive
+  }
+  return SESSION_SEEN.has(sid) ? "seen" : "unknown";
+}
+
+/**
+ * `status`: `missing` (nothing recorded), `recorded` (locatable), or
+ * `unavailable` (fields exist but the session cannot be confirmed).
+ */
+export function provenanceOf(db, id) {
+  const node = db.get(Number(id));
+  if (!node) return null;
+  const source = normalizeSource(node.payload?.source);
+  if (!source.recorded) {
+    return {
+      ok: true,
+      id: Number(id),
+      status: "missing",
+      message: "此条目没有可定位的来源。",
+      jump: false,
+      jumpReason: "",
+      source: null,
+    };
+  }
+  const state = source.sessionId ? sessionStateOf(db, source.sessionId) : "unknown";
+  const unavailable = Boolean(source.sessionId) && state !== "seen";
+  return {
+    ok: true,
+    id: Number(id),
+    status: unavailable ? "unavailable" : "recorded",
+    message: unavailable
+      ? "会话已不可用，保留现有摘录。"
+      : "宿主没有提供可用的会话定位接口，已保留摘录。",
+    sessionState: state,
+    // No deep link is invented: the host exposes no session locator here.
+    jump: false,
+    jumpReason: "host has no session locator API",
+    quotePreviewMax: QUOTE_PREVIEW_MAX,
+    source,
+  };
+}