dsh-memory-dba 0.1.4 → 0.3.0

package/src/index.mjs

@@ -6,17 +6,26 @@
  *   stream.md    a timeline, retrieved only
  *   ws/*.md      detail notes, retrieved only
  *
- * The plugin owns injection and turn recording; retrieval is BM25 over all three
- * layers, so the package has no runtime outside Node itself.
+ * Placement decides whether the prompt cache survives. `core.md` goes in as a
+ * system-prompt section, which is the stable head every request shares. Retrieval
+ * hits change on every user turn, so they are contributed as runtime context
+ * instead: the harness materializes that as a trailing user snapshot, leaving every
+ * earlier message byte-identical. The same text returned from a system-prompt
+ * section would land near the head and invalidate the whole conversation after it.
+ *
+ * The plugin owns injection and turn recording; retrieval is BM25 over the
+ * stream and workspace names, so the package has no runtime outside Node itself.
  *
  * Failure policy: memory is an enhancement. A broken layer, a missing directory,
  * or a corrupt index degrades to an empty section and never fails the turn.
  */
 
+import { join } from 'node:path'
 import { buildCore, buildHits } from './assemble.mjs'
 import { fitHits, loadCorpus, search } from './search.mjs'
 import { bytes, ensureLayout, fingerprint, resolveHome } from './store.mjs'
-import { appendTurn } from './stream.mjs'
+import { publishEvent } from './stream.mjs'
+import { completeEvent, createPendingEvent, interruptEvent, listOutbox, readEvent, updateEventAssistant } from './events.mjs'
 import { queryTerms, tokenize } from './tokenize.mjs'
 import { embed } from './embed.mjs'
 import { docKey, semanticRecall } from './vector.mjs'
@@ -37,9 +46,39 @@ export const defaults = {
   writeStream: true,
   tag: '',
   exclude: [],
+  /**
+   * Full text of the level-1 workspace hint. Empty means derive the command from
+   * `home` (`<home>/../scripts/nb_search.py`); set it for non-Windows installs or
+   * a different Python launcher.
+   */
+  detailHint: '',
+  /**
+   * Text contributed when level-1 recall has no hits. Empty derives a sentence
+   * naming the Python index; `'off'` (or an explicit `false`) disables it.
+   */
+  coldHint: '',
+  /**
+   * `session` snapshots core.md on first assembly per session (the stable head
+   * must not change mid-session); `always` re-reads every assembly for edits
+   * that must apply immediately.
+   */
+  coreRefresh: 'session',
   coreOrder: -50,
-  hitsOrder: 200,
-  vector: { enabled: true, url: 'http://127.0.0.1:11434', model: 'bge-m3', timeoutMs: 1500, minScore: 0.45, keepAlive: '30m' },
+  /**
+   * Order of the retrieval-hits runtime context. Above the harness's own contexts
+   * (repository 100–200, web surface 210) so memory stays the last thing the model
+   * reads in the snapshot.
+   */
+  hitsOrder: 300,
+  /**
+   * Semantic recall is off by default. Level 1 is already narrow: core is
+   * injected in full, workspace documents are names only, and stream entries
+   * are short lines. The synchronous 1500 ms worker/GPU cost bought a measured
+   * 0/143 non-core coverage (core 67/74, stream 0/124, workspace 0/19), while
+   * core no longer belongs in the recall corpus. Use the Python CLI for semantic
+   * search over full text; enable this only on a machine with a warm bge-m3.
+   */
+  vector: { enabled: false, url: 'http://127.0.0.1:11434', model: 'bge-m3', timeoutMs: 1500, minScore: 0.45, keepAlive: '30m' },
 }
 
 /** Text of one message's content blocks, ignoring tool calls and images. */
@@ -85,8 +124,13 @@ export function normalizeConfig(config = {}) {
     writeStream: cfg.writeStream !== false,
     tag: typeof cfg.tag === 'string' ? cfg.tag : '',
     exclude: Array.isArray(cfg.exclude) ? cfg.exclude.filter(name => typeof name === 'string') : [],
+    detailHint: typeof cfg.detailHint === 'string' ? cfg.detailHint : '',
+    coldHint: typeof cfg.coldHint === 'string' ? cfg.coldHint : '',
+    coreRefresh: cfg.coreRefresh === 'always' ? 'always' : 'session',
     vector: {
-      enabled: vector.enabled !== false,
+      // Explicit opt-in only: the default is false so a missing/partial vector
+      // config cannot silently re-enable the synchronous worker path.
+      enabled: vector.enabled === true,
       url,
       model: typeof vector.model === 'string' && vector.model.trim() ? vector.model : defaults.vector.model,
       timeoutMs: Number.isFinite(timeoutMs) && timeoutMs >= 1 ? Math.floor(timeoutMs) : defaults.vector.timeoutMs,
@@ -114,10 +158,36 @@ export function recall(docs, query, options = {}) {
 /**
  * @param {import('@deepseek-ai/cordis').Context} ctx
  * @param {Partial<typeof defaults>} config
+ * @param {{
+ *   buildCore?: typeof buildCore,
+ *   vector?: { embed?: typeof embed, semanticRecall?: typeof semanticRecall },
+ * }} [runtime] Test seam; production callers omit it. Lets tests prove that the
+ *   default config never calls the vector runtime and that core reads are
+ *   per-session.
  */
-export function apply(ctx, config = {}) {
+export function apply(ctx, config = {}, runtime = {}) {
   const cfg = normalizeConfig(config)
   const home = resolveHome(cfg.home)
+  const coreBuilder = runtime.buildCore || buildCore
+  const vectorRuntime = { embed, semanticRecall, ...(runtime.vector || {}) }
+  // Derived once per mount: the hint names the Python DBA script that performs
+  // the level-2 read. `home` is the memory directory, so the script lives in its
+  // sibling `scripts/`; an explicit `detailHint` replaces the whole line for
+  // installs that use another launcher or a different tree layout.
+  const scriptPath = join(home, '..', 'scripts', 'nb_search.py')
+  const detailHint = cfg.detailHint || `工作区册只给文件名；详情用：py -3.14 ${scriptPath} "查询" --file <区名>`
+  // Cold hint follows detailHint's convention (empty derives, a string wins),
+  // but an explicitly supplied empty value turns it off. `Object.hasOwn` is what
+  // distinguishes "not configured" from "configured empty" — normalizeConfig
+  // cannot, because its default is also ''.
+  const defaultColdHint = `本地召回本轮无命中；全量历史（含更早的 stream 记录）用 py -3.14 ${scriptPath} "查询" 查（工作区册正文用 --file <区名>）。`
+  const coldHint = (() => {
+    if (!Object.hasOwn(config || {}, 'coldHint')) return defaultColdHint
+    const raw = config.coldHint
+    if (raw === '' || raw === false || raw === null) return ''
+    if (typeof raw === 'string' && raw.trim().toLowerCase() === 'off') return ''
+    return typeof raw === 'string' && raw.trim() ? raw : defaultColdHint
+  })()
 
   try {
     ensureLayout(home)
@@ -127,20 +197,37 @@ export function apply(ctx, config = {}) {
   }
 
   // A cold Ollama takes longer than the synchronous recall budget, so warm it in the
-  // background; the first turn would otherwise lose semantic recall.
+  // background; the first turn would otherwise lose semantic recall. With the
+  // default `vector.enabled: false` this branch never runs, so no fetch/worker.
   if (cfg.vector.enabled) {
-    embed('warmup', { url: cfg.vector.url, model: cfg.vector.model, timeoutMs: 8000, keepAlive: cfg.vector.keepAlive })
+    vectorRuntime.embed('warmup', { url: cfg.vector.url, model: cfg.vector.model, timeoutMs: 8000, keepAlive: cfg.vector.keepAlive })
       .catch(() => {})
   }
 
   let corpus = null
   let corpusKey = ''
-  // The assembly context carries only a scope key, not a session id, so recall text
-  // is single-slot: the most recent user turn wins. Concurrent sessions (subagents)
-  // therefore render the last query, not their own.
+  /** One slot for contexts without a session id (diagnostics/tests/subagents). */
   let latestHits = ''
+  /** Per-session recall text; a shared slot would leak one session's hits into another. */
+  const hitsBySession = new Map()
+  /**
+   * Core snapshots keyed by session id. `{text, bytes, clipped}` is already the
+   * clipped section, so the model sees the same head for the whole session.
+   * Snapshots live for the session lifetime and are released on session/disposed;
+   * retaining every active session is required to keep its prompt head stable.
+   */
+  const coreSnapshots = new Map()
+  /** Last read for the no-session-id fallback; never used to skip a read. */
+  let fallbackCore = null
   const pending = new Map()
 
+  // Repair complete archives whose stream publication was interrupted. Scanning
+  // event files here is recovery only; recall indexing remains stream-only.
+  if (cfg.writeStream) {
+    try { for (const id of listOutbox(home)) { try { const event = readEvent(home, id); if (event?.status === 'complete') publishEvent(home, id) } catch (error) { console.error(`[memory-dba] event recovery skipped ${id}: ${error.message}`) } } }
+    catch (error) { console.error(`[memory-dba] event recovery failed: ${error.message}`) }
+  }
+
   const docs = () => {
     const key = fingerprint(home)
     if (corpus && key === corpusKey) return corpus
@@ -153,7 +240,7 @@ export function apply(ctx, config = {}) {
     if (!query) return { hits: [], applied: false, clipped: false }
     const corpus = docs()
     const semantic = cfg.vector.enabled
-      ? semanticRecall(home, query, corpus.map(doc => docKey(doc.text)), { ...cfg.vector, topK: cfg.topK })
+      ? vectorRuntime.semanticRecall(home, query, corpus.map(doc => docKey(doc.text)), { ...cfg.vector, topK: cfg.topK })
       : null
     const result = recall(corpus, query, {
       topK: cfg.topK,
@@ -176,11 +263,60 @@ export function apply(ctx, config = {}) {
 
   const renderHits = query => {
     const result = recallQuery(query)
-    return buildHits(result.hits, { budgetKB: cfg.hitBudgetKB })
+    return buildHits(result.hits, { budgetKB: cfg.hitBudgetKB, detailHint, coldHint })
+  }
+
+  /** Read + clip core now, and record the bytes/clipped flags with the snapshot. */
+  const readCore = () => {
+    const snapshot = coreBuilder(home, { coreLimitKB: cfg.coreLimitKB })
+    const text = snapshot?.text ?? ''
+    return { text, bytes: bytes(text), clipped: Boolean(snapshot?.clipped) }
+  }
+
+  /**
+   * Core section text, resolved per assembly.
+   *
+   * The system prompt must stay byte-identical for a session or prefix caching
+   * loses the whole head; therefore the default `coreRefresh: 'session'` reads
+   * core.md once per session id and replays that snapshot. A new session gets a
+   * new id and reads the latest file. `coreRefresh: 'always'` opts out for
+   * edits that must be visible immediately.
+   *
+   * Without `context.agent.id` (diagnostics, tests, non-agent assembly) there is
+   * no safe cache key: a single global snapshot would leak one session's core
+   * into another. That path reads on every assembly and keeps only the last
+   * read in `fallbackCore` for the section contract.
+   */
+  const coreText = context => {
+    try {
+      if (cfg.coreRefresh === 'always') {
+        fallbackCore = readCore()
+        return fallbackCore.text
+      }
+      const id = context?.agent?.id
+      if (!id) {
+        fallbackCore = readCore()
+        return fallbackCore.text
+      }
+      const cached = coreSnapshots.get(id)
+      if (cached) return cached.text
+      const snapshot = readCore()
+      coreSnapshots.set(id, snapshot)
+      return snapshot.text
+    } catch {
+      // A broken core must not fail assembly; the next assembly retries.
+      return ''
+    }
   }
 
   ctx.on('session/disposed', session => {
-    pending.delete(session?.id)
+    const sessionId = session?.id
+    if (!sessionId) return
+    pending.delete(sessionId)
+    // Session-scoped prompt text must not outlive the session: otherwise a
+    // later id reuse (or a long process's map) serves stale hits/core.
+    hitsBySession.delete(sessionId)
+    coreSnapshots.delete(sessionId)
   })
 
   ctx.on('session/event', (session, event) => {
@@ -189,11 +325,27 @@ export function apply(ctx, config = {}) {
       if (!sessionId) return
       if (event?.type === 'user/message') {
         if (event.data?.source?.kind !== 'user') return
+        const previous = pending.get(sessionId)
+        if (previous?.eventId) {
+          try { interruptEvent(home, previous.eventId) }
+          catch (error) { console.error(`[memory-dba] cannot interrupt prior archive: ${error.message}`) }
+        }
         pending.delete(sessionId)
         const user = textOf(event.data?.content)
         if (!user) return
-        pending.set(sessionId, { user, assistant: '', at: new Date() })
-        latestHits = renderHits(user).text
+        const at = new Date()
+        let archive = null
+        if (cfg.writeStream) {
+          try { archive = createPendingEvent(home, { session_id: sessionId, user, at, tag: cfg.tag }) }
+          catch (error) { console.error(`[memory-dba] cannot archive pending event: ${error.message}`) }
+        }
+        pending.set(sessionId, { user, assistant: '', at, eventId: archive?.id })
+        let text = ''
+        try { text = renderHits(user).text }
+        catch (error) { console.error(`[memory-dba] recall failed: ${error.message}`) }
+        hitsBySession.set(sessionId, text)
+        // Keep the no-session-id fallback in sync with the latest turn.
+        latestHits = text
         return
       }
       if (event?.type === 'assistant/message') {
@@ -202,6 +354,10 @@ export function apply(ctx, config = {}) {
         const text = textOf(event.data?.message?.content)
         if (!text) return
         turn.assistant = turn.assistant ? `${turn.assistant}\n${text}` : text
+        if (turn.eventId) {
+          try { updateEventAssistant(home, turn.eventId, text) }
+          catch (error) { console.error(`[memory-dba] cannot update event archive: ${error.message}`) }
+        }
         return
       }
       if (event?.type === 'turn/end') {
@@ -209,7 +365,13 @@ export function apply(ctx, config = {}) {
         if (!turn) return
         pending.delete(sessionId)
         if (!cfg.writeStream) return
-        const outcome = appendTurn(home, { ...turn, tag: cfg.tag })
+        if (!turn.eventId) return
+        if (!turn.assistant.trim()) {
+          interruptEvent(home, turn.eventId)
+          return
+        }
+        completeEvent(home, turn.eventId, turn)
+        const outcome = publishEvent(home, turn.eventId, { tag: cfg.tag })
         if (outcome.written) corpus = null
       }
     } catch (error) {
@@ -220,21 +382,23 @@ export function apply(ctx, config = {}) {
   ctx.systemPrompt.section({
     name: 'memory-dba:core',
     order: cfg.coreOrder,
-    text: () => {
-      try {
-        return buildCore(home, { coreLimitKB: cfg.coreLimitKB }).text
-      } catch {
-        return ''
-      }
-    },
+    text: coreText,
   })
 
-  ctx.systemPrompt.section({
+  // Retrieval hits change per turn, so they must not touch the cacheable head:
+  // runtime context is materialized after the conversation history, where a change
+  // costs only the tokens that follow it. Resolve by the assembly's agent id;
+  // contexts without one fall back to the latest single slot.
+  ctx.systemPrompt.context({
     name: 'memory-dba:hits',
     order: cfg.hitsOrder,
-    text: () => latestHits,
+    text: context => {
+      const id = context?.agent?.id
+      if (id) return hitsBySession.get(id) ?? ''
+      return latestHits
+    },
   })
 }
 
 /** Exposed for tests: the retrieval path without a harness context. */
-export { buildCore, buildHits, fitHits, loadCorpus, search }
+export { buildCore, buildHits, fitHits, loadCorpus, search, readEvent }

package/src/search.mjs

@@ -9,11 +9,12 @@
  * that already matched.
  */
 
-import { readdirSync, statSync } from 'node:fs'
+import { lstatSync, readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { bytes, readLayer } from './store.mjs'
 import { queryTerms, tokenize } from './tokenize.mjs'
 import { docKey } from './vector.mjs'
+import { readCatalog, effectiveFacts } from './catalog.mjs'
 
 const K1 = 1.5
 const B = 0.75
@@ -27,7 +28,12 @@ const DATE_RE = /(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2}))?/
 
 /**
  * Split one layer into retrievable units. Core and stream split per non-empty
- * line; a workspace file splits per `##` heading so a long note is one hit.
+ * line; a workspace source still splits per `##` heading for callers that pass
+ * one explicitly.
+ *
+ * Retrieval does NOT use this for workspace files: level-1 workspace documents
+ * are name-only (see `wsDoc`), because a section of workspace text in the
+ * corpus is exactly what the two-level design keeps out of the prompt.
  *
  * @param {string} text Layer contents.
  * @param {string} source Layer label used in results.
@@ -59,6 +65,41 @@ export function splitDocs(text, source) {
   return docs
 }
 
+/**
+ * First-line title of a workspace file, or `''` when the first line is not a
+ * level-1 heading (`# ...`).
+ *
+ * Only the first physical line counts. Workspace bodies contain `#` lines in
+ * quotes and code blocks; scanning the whole file for something that looks
+ * like a title would put body text back into the level-1 document.
+ *
+ * @param {string} text Workspace file contents.
+ * @returns {string} Title line, or empty string.
+ */
+export function wsTitle(text) {
+  const first = String(text || '').replace(/^\uFEFF/, '').split(/\r?\n/, 1)[0].trim()
+  return first.startsWith('# ') && !first.startsWith('## ') ? first : ''
+}
+
+/**
+ * Level-1 workspace document: file name plus first-line title, never the body.
+ *
+ * Rationale: at level 1 retrieval may answer "which workspace note might be
+ * relevant", not "what does it say". Indexing the body means any unrelated
+ * query can pull a whole workspace section into the prompt. Reading the body
+ * is an explicit second step (`nb_search.py --file <area>`), which is also why
+ * `date` is null here: without a body there is no section date to weight.
+ *
+ * @param {string} name Workspace file name, e.g. `记忆系统.md`.
+ * @param {string} text Workspace file contents.
+ * @returns {MemoryDoc} Name-only document.
+ */
+export function wsDoc(name, text) {
+  const source = `ws/${name}`
+  const title = wsTitle(text)
+  return { source, line: 1, text: title ? `${source}\n${title}` : source, date: null }
+}
+
 /** First `YYYY-MM-DD[ HH:MM]` in the text, normalized to an ISO date string. */
 export function dateOf(text) {
   const m = DATE_RE.exec(text || '')
@@ -85,16 +126,22 @@ function streamDocs(text) {
   return docs.reverse()
 }
 
-/** Unavailable or invalid layers are skipped unless strict diagnostics are requested. */
-export function loadCorpus(home, { exclude = [], strict = false } = {}) {
+/**
+ * Unavailable or invalid layers are skipped unless strict diagnostics are requested.
+ *
+ * `core.md` is deliberately **not** part of the retrieval corpus. It is injected
+ * in full every turn by `buildCore`, so indexing it here would let the same text
+ * consume the prompt budget twice — the exact rule the Python side follows
+ * (`nb_search.py` excludes `scope === "core"` by default). A broken `core.md`
+ * is still reported by the core-budget check and by `buildCore` throwing, not by
+ * pretending it was a retrievable document.
+ */
+export function loadCorpus(home, { exclude = [], strict = false, includeHistory = false } = {}) {
   const docs = []
-  for (const [file, label] of [['core.md', 'core'], ['stream.md', 'stream']]) {
-    try {
-      const text = readLayer(home, file)
-      docs.push(...(label === 'stream' ? streamDocs(text) : splitDocs(text, label)))
-    } catch (error) {
-      if (strict && error?.name !== 'MissingLayer') throw error
-    }
+  try {
+    docs.push(...streamDocs(readLayer(home, 'stream.md')))
+  } catch (error) {
+    if (strict && error?.name !== 'MissingLayer') throw error
   }
   const wsDir = join(home, 'ws')
   let names = []
@@ -107,11 +154,40 @@ export function loadCorpus(home, { exclude = [], strict = false } = {}) {
   for (const name of names) {
     if (skip.has(name)) continue
     try {
-      docs.push(...splitDocs(readLayer(home, `ws/${name}`), `ws/${name}`))
+      const fileStat = lstatSync(join(wsDir, name))
+      if (fileStat.isSymbolicLink() || !fileStat.isFile()) {
+        if (strict) throw new Error(`workspace entry must be a regular file: ${name}`)
+        continue
+      }
+      // One name-only document per file. `exclude` stays as an extra guardrail;
+      // the real gate is that no workspace body ever enters this corpus.
+      const doc = wsDoc(name, readLayer(home, `ws/${name}`))
+      docs.push(doc)
     } catch (error) {
       if (strict && error?.name !== 'MissingLayer') throw error
     }
   }
+  let catalog
+  try { catalog = readCatalog(home, { strict }) }
+  catch (error) { console.error(`[memory-dba] ${error.message}`); if (strict) throw error }
+  if (catalog) {
+    const cards = new Map(catalog.cards.map(card => [card.file, card]))
+    for (const doc of docs) {
+      const card = cards.get(doc.source)
+      if (!card || exclude.includes(doc.source) || exclude.includes(doc.source.slice(3))) continue
+      const labels = [['topics','topics'],['aliases','aliases'],['entities','entities'],['questions','questions']]
+        .filter(([key]) => card[key].length).map(([key,label]) => `${label}: ${card[key].join(', ')}`)
+      if (labels.length) doc.text += `\n${labels.join('\n')}`
+    }
+    const superseded = new Set(catalog.facts.flatMap(f => f.supersedes))
+    const eff = effectiveFacts(catalog, { history: includeHistory })
+    for (const fact of eff) {
+      if (!includeHistory && fact.effective_status !== 'active' && fact.effective_status !== 'conflict') continue
+      const evidence = fact.source.role === 'user' ? 'user_reported' : 'assistant_reported'
+      const text = `key: ${fact.key}\nclaim: ${fact.claim}\nkind: ${fact.kind}\nsource: ${evidence}\nevent: ${fact.source.event_id}\nstatus: ${fact.effective_status}`
+      docs.push({ source: `fact/${fact.id}`, line: 1, text, date: fact.observed_at, evidence: { ...fact.source }, source_label: evidence, factStatus: fact.effective_status, effective_status: fact.effective_status, conflict: fact.effective_status === 'conflict', key: fact.key, claim: fact.claim, kind: fact.kind, factKey: fact.key, superseded: superseded.has(fact.id) })
+    }
+  }
   return docs
 }
 

package/src/store.mjs

@@ -14,6 +14,7 @@
 import { closeSync, existsSync, fstatSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, renameSync, statSync, writeFileSync } from 'node:fs'
 import { homedir, platform } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
+import { createHash } from 'node:crypto'
 
 export const CORE_FILE = 'core.md'
 export const STREAM_FILE = 'stream.md'
@@ -158,14 +159,28 @@ export function fingerprint(home) {
   let names = []
   try {
     names = readdirSync(join(home, WS_DIR)).filter(name => name.endsWith('.md')).sort()
-  } catch { /* An unavailable workspace has no cacheable entries. */ }
+  } catch (error) { parts.push(`ws-dir:${error?.code || 'unreadable'}`) }
   for (const name of [CORE_FILE, STREAM_FILE, ...names.map(name => `${WS_DIR}/${name}`)]) {
     try {
       const st = statSync(join(home, name))
       parts.push(JSON.stringify([name, st.size, st.mtimeMs]))
-    } catch {
-      parts.push(`${name}:-`)
+    } catch (error) {
+      parts.push(`${name}:${error?.code || 'unreadable'}`)
     }
   }
+  // Catalog edits and changes to referenced evidence invalidate retrieved facts.
+  const catalogPath = join(home, 'catalog.json')
+  try {
+    const st = statSync(catalogPath)
+    const digest = createHash('sha256').update(readFileSync(catalogPath)).digest('hex')
+    parts.push(JSON.stringify(['catalog.json', st.size, st.mtimeMs, digest]))
+    try {
+      const catalog = JSON.parse(readFileSync(catalogPath, 'utf8'))
+      for (const id of [...new Set((catalog.facts || []).map(f => f?.source?.event_id).filter(x => typeof x === 'string' && /^[A-Za-z0-9_-]{1,128}$/.test(x)))].sort()) {
+        try { const path=join(home, 'events-v1', `${id}.json`); const ev = statSync(path); const evHash=createHash('sha256').update(readFileSync(path)).digest('hex'); parts.push(JSON.stringify([`events-v1/${id}.json`, ev.size, ev.mtimeMs, evHash])) }
+        catch { parts.push(`events-v1/${id}.json:-`) }
+      }
+    } catch { parts.push('catalog.json:invalid') }
+  } catch (error) { parts.push(`catalog.json:${error?.code || 'unreadable'}`) }
   return parts.join('|')
 }

package/src/stream.mjs

@@ -7,20 +7,10 @@
  */
 
 import { appendLayer, readLayer } from './store.mjs'
-
-const SECRET_PATTERNS = [
-  /sk-[A-Za-z0-9_-]{16,}/g,
-  /\bBearer\s+[A-Za-z0-9._-]{16,}/gi,
-  /\b[A-Fa-f0-9]{32,}\b/g,
-  /\b\d{13,19}\b/g,
-]
+import { completeEvent, createPendingEvent, eventId, markEventPublished, readEvent, sanitizeEventText, saveEvent } from './events.mjs'
 
 /** Remove credential-looking runs before text reaches a committable file. */
-export function sanitize(text) {
-  let out = String(text || '')
-  for (const pattern of SECRET_PATTERNS) out = out.replace(pattern, '[redacted]')
-  return out
-}
+export const sanitize = sanitizeEventText
 
 /** Collapse whitespace so one turn stays one line. */
 export function oneLine(text, maxChars = 600) {
@@ -43,12 +33,42 @@ export function stamp(date = new Date()) {
  * @param {{user?: string, assistant?: string, tag?: string, at?: Date}} turn
  * @returns {string|null} Line, or null when the turn is not worth remembering.
  */
-export function formatTurn({ user, assistant, tag, at }) {
+export function formatTurn({ user, assistant, tag, at, eventId: id }) {
   const u = oneLine(sanitize(user), 300)
   const a = oneLine(sanitize(assistant), 600)
   if (!u || !a) return null
   const label = tag ? ` | tag=${oneLine(sanitize(tag), 100)}` : ''
-  return `- ${stamp(at)}${label} | 用户：${u} | 助手：${a}`
+  return `- ${stamp(at)}${label} | 用户：${u} | 助手：${a}${id ? ` [event=${id}]` : ''}`
+}
+
+/** Compact navigation excerpt balanced across both ends of each message. */
+export function summarizeForStream(text, maxChars) {
+  const flat = oneLine(sanitize(text), Number.MAX_SAFE_INTEGER)
+  if (flat.length <= maxChars) return flat
+  let head = Math.floor((maxChars - 1) * 0.58)
+  const tail = maxChars - 1 - head
+  if (head > 0 && /[\uD800-\uDBFF]/.test(flat[head - 1]) && /[\uDC00-\uDFFF]/.test(flat[head])) head -= 1
+  let tailStart = flat.length - tail
+  if (tailStart > 0 && /[\uD800-\uDBFF]/.test(flat[tailStart - 1]) && /[\uDC00-\uDFFF]/.test(flat[tailStart])) tailStart += 1
+  return `${flat.slice(0, head)}…${flat.slice(tailStart)}`
+}
+
+/** Publish one completed archive; the reference makes append recovery idempotent. */
+export function publishEvent(home, id, options = {}) {
+  const event = readEvent(home, id)
+  if (!event || event.status !== 'complete') return { written: false, reason: 'not-complete' }
+  let stream = ''
+  try { stream = readLayer(home, 'stream.md') } catch (error) { if (error?.name !== 'MissingLayer') throw error }
+  if (stream.includes(`[event=${id}]`)) {
+    markEventPublished(home, id)
+    return { written: false, reason: 'already-published' }
+  }
+  const tag = options.tag ?? event.tag ?? ''
+  const line = formatTurn({ user: summarizeForStream(event.user, 300), assistant: summarizeForStream(event.assistant, 600), tag, at: new Date(event.started_at), eventId: id })
+  if (!line) return { written: false, reason: 'empty-turn' }
+  appendLayer(home, 'stream.md', line)
+  markEventPublished(home, id)
+  return { written: true, line }
 }
 
 /**
@@ -59,16 +79,37 @@ export function formatTurn({ user, assistant, tag, at }) {
  * @returns {{written: boolean, reason?: string, line?: string}}
  */
 export function appendTurn(home, turn) {
-  const line = formatTurn(turn)
-  if (!line) return { written: false, reason: 'empty-turn' }
-  let last = ''
-  try {
-    const stream = readLayer(home, 'stream.md').trimEnd()
-    last = stream.slice(stream.lastIndexOf('\n') + 1)
-  } catch (error) {
-    if (error?.name !== 'MissingLayer') throw error
+  if (!turn?.user || !turn?.assistant) return { written: false, reason: 'empty-turn' }
+  const at = turn.at ? new Date(turn.at) : new Date()
+  const digest = String(turn.eventId || eventId())
+  if (!turn.eventId) {
+    const wanted = formatTurn({ ...turn, at, user: summarizeForStream(turn.user, 300), assistant: summarizeForStream(turn.assistant, 600) }).replace(/\s+$/, '')
+    try {
+      const stream = readLayer(home, 'stream.md').trimEnd()
+      const lastLine = stream.slice(stream.lastIndexOf('\n') + 1)
+      const priorId = / \[event=([A-Za-z0-9_-]+)\]$/.exec(lastLine)?.[1]
+      const last = lastLine.replace(/ \[event=[A-Za-z0-9_-]+\]$/, '')
+      if (last === wanted) {
+        const prior = priorId ? readEvent(home, priorId) : null
+        const sameArchive = prior && prior.user === sanitize(turn.user) && prior.assistant === sanitize(turn.assistant)
+        const legacyShort = !priorId && String(turn.user).length <= 300 && String(turn.assistant).length <= 600
+        if (sameArchive || legacyShort) return { written: false, reason: 'duplicate' }
+      }
+    } catch (error) { if (error?.name !== 'MissingLayer') throw error }
   }
-  if (last === line) return { written: false, reason: 'duplicate' }
-  appendLayer(home, 'stream.md', line)
-  return { written: true, line }
+  let event = readEvent(home, digest)
+  if (!event) {
+    event = createPendingEvent(home, { id: digest, session_id: turn.session_id || 'cli', user: turn.user, at, tag: turn.tag })
+    event.assistant = sanitize(turn.assistant)
+    event.updated_at = new Date().toISOString()
+    saveEvent(home, event)
+    completeEvent(home, event.id)
+  } else if (event.status !== 'complete') {
+    event.assistant = sanitize(turn.assistant)
+    event.updated_at = new Date().toISOString()
+    saveEvent(home, event)
+    completeEvent(home, event.id)
+  }
+  const result = publishEvent(home, event.id, { tag: turn.tag })
+  return result.reason === 'already-published' ? { ...result, reason: 'duplicate' } : result
 }