@aiwayds/dsh-topics-memory 0.21.0 → 0.23.0

package/src/service.ts

@@ -7,14 +7,16 @@
  */
 
 import { readFile, stat } from 'node:fs/promises'
-import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import * as okf from './okf.ts'
-import { searchTopics, scoreTopic, passesGate, tokenize, type RetrievableTopic, type SearchOutcome } from './retrieval.ts'
-import { assembleInjection, assemblePointer, POINTER_PER_TOPIC, POINTER_TOTAL, type AssembleResult, type DigestInput, type SlowPointerInput } from './digest.ts'
+import { searchTopics, scoreTopic, passesGate, tokenize, sanitizeQuery, loadEmbeddingIndex, rerankNearFloor, ensureIndexFresh, saveEmbeddingIndex, type EmbeddingIndex, type RetrievableTopic, type RetrievalConfig, type SearchOutcome } from './retrieval.ts'
+import { assembleInjection, assemblePointer, assemblePackage, POINTER_PER_TOPIC, POINTER_TOTAL, type AssembleResult, type DigestInput, type PackageCandidate, type PackageInput, type PackageResult, type SlowPointerInput } from './digest.ts'
+import { embedTexts, embedQuerySync, embedderWith, resolveEmbedModel } from './embedding.ts'
+import { resolveBundleRoot } from './paths.ts'
 import type { BundleStore, Observation, SaveResult } from './store.ts'
 import type { TopicsConfigValue } from './config.ts'
-import { aggregateStats, querySample, aggregateUsage, USAGE_WINDOW_DAYS, type AggregateStats, type InjectionRecord, type QueryBuildShape, type ShadowVerdict, type SlowItem, type UsageSignal } from './ilog.ts'
+import { aggregateStats, querySample, aggregateUsage, aggregateZeroOpen, ZERO_OPEN_TAIL, USAGE_WINDOW_DAYS, attributeOpen, OPEN_ATTRIBUTION_TAIL, type AggregateStats, type InjectionRecord, type OpenRecord, type QueryBuildShape, type ShadowVerdict, type SlowItem, type SlowOutcome, type UsageSignal } from './ilog.ts'
 import { fileHistory, fileAtRev } from './git.ts'
 import type { Sync } from './sync.ts'
 
@@ -25,6 +27,37 @@ interface CacheEntry {
   slug: string
 }
 
+/** Tolerant JSONL line read: undefined = unreadable file. Unlike an empty
+ *  array, undefined tells the caller to fail open AND skip caching — a
+ *  successful stat paired with a failed read must not freeze an empty
+ *  snapshot into the cache until the next append. */
+function readLogLinesSync(file: string): string[] | undefined {
+  try {
+    return readFileSync(file, 'utf8').split('\n')
+  } catch {
+    return undefined
+  }
+}
+
+/** Parse already-split lines back-to-front, keeping the last `tail` parsed
+ *  records in order: blanks and torn JSON lines are skipped (and never
+ *  consume tail budget), so a torn tail line cannot crowd out a good one.
+ *  Shared by the usage/zero-open cache — one tail parse feeds both. */
+function parseJsonlLinesSync<T>(lines: readonly string[], tail = Number.POSITIVE_INFINITY): T[] {
+  const out: T[] = []
+  for (let i = lines.length - 1; i >= 0 && out.length < tail; i -= 1) {
+    const line = lines[i]
+    if (line.trim() === '') continue
+    try {
+      out.push(JSON.parse(line) as T)
+    } catch {
+      continue // torn tail line
+    }
+  }
+  out.reverse()
+  return out
+}
+
 export interface RetrieveOutcome {
   outcome: SearchOutcome
   injection: AssembleResult
@@ -44,19 +77,30 @@ export interface SlowDelivery {
   queryBuild: QueryBuildShape
   model: string
   ms: number
+  /** Producing run's disposition (A4 全留痕) — copied into ilog.slowOutcome. */
+  outcome?: SlowOutcome
 }
 
 export class TopicsService {
   private cache = new Map<string, CacheEntry>()
   /** mtime-keyed parse of the observations log, grouped by session. */
   private echoCache: { mtimeMs: number; size: number; bySession: Map<string, Set<string>> } | undefined
-  private usageCache: {
-    injMs: number
-    injSize: number
-    opensMs: number
-    opensSize: number
-    signals: Map<string, UsageSignal>
-  } | undefined
+  /** Single shared cache over the two feedback JSONL logs (S2): the key is
+   *  the (mtime,size) quartet of injections.jsonl + opens.jsonl, one read
+   *  and one tail parse feed BOTH aggregates — usageSignalsSync and
+   *  zeroOpenSlugsSync used to each keep a full-parse cache of their own.
+   *  Invalidation stays append-driven: the store only ever appends, so any
+   *  write moves mtime+size. Never populated when a read failed (N1). */
+  private logSignalsCache:
+    | {
+        injMs: number
+        injSize: number
+        opensMs: number
+        opensSize: number
+        signals: Map<string, UsageSignal>
+        zeroOpenSlugs: ReadonlySet<string>
+      }
+    | undefined
   readonly store: BundleStore
   private readonly getConfig: () => TopicsConfigValue
   readonly sync?: Sync
@@ -131,7 +175,7 @@ export class TopicsService {
   invalidate(): void {
     this.cache.clear()
     this.echoCache = undefined
-    this.usageCache = undefined
+    this.logSignalsCache = undefined
   }
 
   /**
@@ -186,10 +230,36 @@ export class TopicsService {
    * Usage signals (ADR 0015): mtime-cached aggregate over the injection log
    * and the opens log, rolling USAGE_WINDOW_DAYS. Synchronous like
    * echoSlugsSync — the retrieval hot path is sync — and cheap when warm:
-   * a fresh cache costs two stat() calls. Unreadable logs fail open to an
+   * a fresh cache costs two stat() calls, one read of each log, and feeds
+   * the zero-open set from the same parse. Unreadable logs fail open to an
    * empty map (no boost), never an error.
    */
   usageSignalsSync(): Map<string, UsageSignal> {
+    return this.logSignalsSync().signals
+  }
+
+  /**
+   * Zero-open slug set for the decay (v5): the shared aggregateZeroOpen
+   * rule over the injection tail and the whole opens log (compacted, so a
+   * full read stays small). Shares one cache and one parse with
+   * usageSignalsSync; unreadable logs fail open to an empty set (no
+   * decay), never an error. Only called when zeroOpenDecay is on.
+   */
+  zeroOpenSlugsSync(): ReadonlySet<string> {
+    return this.logSignalsSync().zeroOpenSlugs
+  }
+
+  /**
+   * The one shared feedback-log read behind both signals: stat both files
+   * (mtime+size quartet key), parse the injections TAIL only
+   * (ZERO_OPEN_TAIL rounds comfortably cover both 30-day windows) and the
+   * opens log whole (the zero-open rule is whole-history), then feed the
+   * two pure aggregates from that single parse. A failed read still fails
+   * open to empty inputs but NEVER populates the cache (N1) — otherwise a
+   * stat-success/read-failure race would freeze an empty snapshot until
+   * the next append.
+   */
+  private logSignalsSync(): { signals: Map<string, UsageSignal>; zeroOpenSlugs: ReadonlySet<string> } {
     const injFile = join(this.store.metaDir(), 'injections.jsonl')
     const opensFile = join(this.store.metaDir(), 'opens.jsonl')
     const statOf = (file: string): { mtimeMs: number; size: number } => {
@@ -202,7 +272,7 @@ export class TopicsService {
     }
     const injSt = statOf(injFile)
     const opensSt = statOf(opensFile)
-    const cached = this.usageCache
+    const cached = this.logSignalsCache
     if (
       cached !== undefined &&
       cached.injMs === injSt.mtimeMs &&
@@ -210,38 +280,102 @@ export class TopicsService {
       cached.opensMs === opensSt.mtimeMs &&
       cached.opensSize === opensSt.size
     ) {
-      return cached.signals
+      return cached
     }
-    const parseLines = <T>(file: string): T[] => {
-      const out: T[] = []
-      try {
-        for (const line of readFileSync(file, 'utf8').split('\n')) {
-          if (line.trim() === '') continue
-          try {
-            out.push(JSON.parse(line) as T)
-          } catch {
-            continue // torn tail line
-          }
-        }
-      } catch {
-        // unreadable log: contribute nothing
+    const injLines = readLogLinesSync(injFile)
+    const opensLines = readLogLinesSync(opensFile)
+    const injections = parseJsonlLinesSync<InjectionRecord>(injLines ?? [], ZERO_OPEN_TAIL)
+    const opens = parseJsonlLinesSync<OpenRecord>(opensLines ?? [])
+    const now = Date.now()
+    const signals = aggregateUsage(injections, opens, USAGE_WINDOW_DAYS, now)
+    const zeroOpenSlugs: ReadonlySet<string> = new Set(aggregateZeroOpen(injections, opens, now).keys())
+    if (injLines !== undefined && opensLines !== undefined) {
+      this.logSignalsCache = {
+        injMs: injSt.mtimeMs,
+        injSize: injSt.size,
+        opensMs: opensSt.mtimeMs,
+        opensSize: opensSt.size,
+        signals,
+        zeroOpenSlugs,
       }
-      return out
     }
-    const signals = aggregateUsage(
-      parseLines(injFile),
-      parseLines(opensFile),
-      USAGE_WINDOW_DAYS,
-      Date.now(),
-    )
-    this.usageCache = {
-      injMs: injSt.mtimeMs,
-      injSize: injSt.size,
-      opensMs: opensSt.mtimeMs,
-      opensSize: opensSt.size,
-      signals,
+    return { signals, zeroOpenSlugs }
+  }
+
+  /**
+   * zeroOpenDecay fields for scoring calls: empty when the gate is off —
+   * no file reads, zero behavior change — and the shared mtime-cached set
+   * when on. Spread into every searchTopics/scoreTopic cfg that already
+   * carries the usage signals (injection paths + explicit topic_search;
+   * the slow lane's recall band stays untouched, mirroring usageBoost).
+   */
+  private zeroOpenCfg(): Pick<RetrievalConfig, 'zeroOpenDecay' | 'zeroOpenSlugs'> {
+    if (this.cfg.zeroOpenDecay !== true) return {}
+    return { zeroOpenDecay: true, zeroOpenSlugs: this.zeroOpenSlugsSync() }
+  }
+
+  /** mtime-cached view of meta/embeddings.json (sync read — hot-lane caller).
+   *  Missing/corrupt index = {} → the reranker degrades to lexical order. */
+  private embedIndexCache: { mtimeMs: number; size: number; index: EmbeddingIndex } | undefined
+
+  private embeddingIndexCacheGet(): EmbeddingIndex {
+    const root = resolveBundleRoot()
+    const file = join(root, 'meta', 'embeddings.json')
+    try {
+      const st = statSync(file)
+      if (this.embedIndexCache !== undefined && this.embedIndexCache.mtimeMs === st.mtimeMs && this.embedIndexCache.size === st.size) {
+        return this.embedIndexCache.index
+      }
+      const index = loadEmbeddingIndex(root)
+      this.embedIndexCache = { mtimeMs: st.mtimeMs, size: st.size, index }
+      return index
+    } catch {
+      return this.embedIndexCache?.index ?? {}
     }
-    return signals
+  }
+
+  /** Shadow bypass ledger (spec §8.3): one line per shadow round — feature
+   *  fields only, never query text (jev-log discipline). Silent on failure;
+   *  512KB truncation keeps the newest three quarters. */
+  private appendPackageShadowLedger(entry: Record<string, unknown>): void {
+    try {
+      const file = join(resolveBundleRoot(), 'meta', 'package-shadow.jsonl')
+      let lines: string[] = []
+      try {
+        const st = statSync(file)
+        if (st.size > 512 * 1024) {
+          const all = readFileSync(file, 'utf8').split('\n').filter((l) => l !== '')
+          lines = all.slice(Math.floor(all.length / 4))
+        }
+      } catch { /* first write */ }
+      lines.push(JSON.stringify(entry))
+      writeFileSync(file, lines.join('\n') + '\n')
+    } catch { /* ledger must never break the lane */ }
+  }
+
+  /** Boot-time embedding index maintenance (spec §3: boot 校验+增量重建).
+   *  Provider '' or packageMode off → no-op (default-off byte-for-byte).
+   *  Full-roster embed on rebuild (A1 §5: ~9.5s for 137 topics). */
+  async refreshEmbeddingIndex(): Promise<void> {
+    const provider = (this.cfg.embeddingProvider ?? '').trim()
+    if (provider === '' || this.cfg.packageMode === undefined || this.cfg.packageMode === 'off') return
+    const embedder = embedderWith({ provider, model: this.cfg.embeddingModel })
+    const topics = await this.roster()
+    const root = resolveBundleRoot()
+    const index = loadEmbeddingIndex(root)
+    const stale = ensureIndexFresh(index, topics, embedder)
+    if (stale.length === 0) return
+    const docs = await Promise.all(stale.map(async (slug) => (await this.readDoc(slug)) ?? ''))
+    const texts = stale.map((slug, i) => `${slug}\n${docs[i] ?? ''}`)
+    const r = await embedTexts(texts, { provider, model: this.cfg.embeddingModel })
+    if (!r.ok) return
+    const next: EmbeddingIndex = { ...index }
+    stale.forEach((slug, i) => {
+      const vec = r.vectors[i]
+      if (vec !== undefined) next[slug] = { model: r.model, dim: vec.length, vec }
+    })
+    saveEmbeddingIndex(root, next)
+    this.embedIndexCache = undefined
   }
 
   /**
@@ -269,6 +403,7 @@ export class TopicsService {
       conflicts,
       usageBoost: cfg.usageBoost,
       usage: this.usageSignalsSync(),
+      ...this.zeroOpenCfg(),
     })
     const bySlug = new Map(roster.map((r) => [r.slug, r]))
     const entries: DigestInput[] = []
@@ -358,8 +493,13 @@ export class TopicsService {
       }
       return { text: '', outcome: empty, deduped: [], echoed: [], included: [], slowIncluded: [] }
     }
+    // A-line gate (A3/A4): query cleaning + package + semantic rerank ride
+    // behind packageMode (default off = byte-for-byte legacy path).
+    const pkgMode: 'shadow' | 'on' | undefined =
+      cfg.packageMode === 'shadow' || cfg.packageMode === 'on' ? cfg.packageMode : undefined
+    const effectiveQuery = pkgMode !== undefined ? sanitizeQuery(query) : query
     const conflicts = this.store.getConflictsSync()
-    const outcome = searchTopics(query, roster, {
+    const outcome = searchTopics(effectiveQuery, roster, {
       threshold: cfg.matchThreshold,
       topK: cfg.topK,
       tagBoost: cfg.tagBoost,
@@ -368,7 +508,37 @@ export class TopicsService {
       conflicts,
       usageBoost: cfg.usageBoost,
       usage: this.usageSignalsSync(),
+      ...this.zeroOpenCfg(),
     })
+    // ---- A-line semantic rerank (A4 决议 2, spec §3.1) ----
+    // Reorder ONLY the 0.20–0.30 nearFloor band (the 93% near-miss mass);
+    // thresholds/gateScore/hits untouched. Any failure degrades to the
+    // original order — the fast lane never blocks on the semantic layer.
+    let nearFloorRerank: { reranked: boolean; passthroughReason?: string; orderBefore: string[]; orderAfter: string[] } | undefined
+    if (pkgMode !== undefined) {
+      const bandLo = 0.2
+      const band = outcome.nearMisses.filter((h) => h.score >= bandLo && h.score < cfg.matchThreshold)
+      const orderBefore = band.map((h) => h.slug)
+      if (band.length > 1) {
+        const index = this.embeddingIndexCacheGet()
+        const models = new Set(Object.values(index).map((e) => e.model))
+        const embedModel = resolveEmbedModel(cfg.embeddingModel)
+        if (models.size <= 1 && (models.size === 0 || models.has(embedModel))) {
+          const qv = embedQuerySync(effectiveQuery, { provider: cfg.embeddingProvider, model: cfg.embeddingModel })
+          const rr = rerankNearFloor(effectiveQuery, qv.ok ? qv.vector : null, band, index)
+          if (rr.reranked) {
+            const inBand = (h: { score: number }) => h.score >= bandLo && h.score < cfg.matchThreshold
+            const rrSlugs = new Set(rr.hits.map((h) => h.slug))
+            const merged = [...rr.hits, ...band.filter((h) => !rrSlugs.has(h.slug))]
+            let mi = 0
+            outcome.nearMisses = outcome.nearMisses.map((h) => (inBand(h) ? merged[mi++]! : h))
+            nearFloorRerank = { reranked: true, orderBefore, orderAfter: merged.map((h) => h.slug) }
+          } else {
+            nearFloorRerank = { reranked: false, passthroughReason: rr.passthroughReason, orderBefore, orderAfter: orderBefore }
+          }
+        }
+      }
+    }
     const exclude = dedup?.exclude
     const echo = dedup?.echo
     const deduped = exclude === undefined ? [] : outcome.hits.filter((h) => exclude.has(h.slug)).map((h) => h.slug)
@@ -398,7 +568,7 @@ export class TopicsService {
     let slowIncluded: string[] = []
     const consumedAt = new Date().toISOString()
     if (slow !== undefined) {
-      const queryTokens = new Set(tokenize(query))
+      const queryTokens = new Set(tokenize(effectiveQuery))
       for (const item of slow.items) {
         if (exclude?.has(item.slug)) {
           if (!deduped.includes(item.slug)) deduped.push(item.slug)
@@ -427,6 +597,7 @@ export class TopicsService {
           structuralGate: true,
           usageBoost: cfg.usageBoost,
           usage: this.usageSignalsSync(),
+          ...this.zeroOpenCfg(),
         })
         shadow.push({
           slug: item.slug,
@@ -445,17 +616,74 @@ export class TopicsService {
     const pointerMode = cfg.injectMode !== 'digest'
     // Pointer budget: per-entry fixed at the design's 80, total clamped to the
     // fast-lane upper bound of 600 (I4) — totalBudget stays tunable downward.
-    const injection = pointerMode
-      ? assemblePointer(entries, { perTopicBudget: POINTER_PER_TOPIC, totalBudget: Math.min(cfg.totalBudget, POINTER_TOTAL) }, slowPointers)
-      : assembleInjection(entries, { perTopicBudget: cfg.perTopicBudget, totalBudget: cfg.totalBudget }, slowPointers)
+    let packageSkipped = false
+    let packageShadow: PackageResult | null | undefined
+    let injection: AssembleResult
+    if (!pointerMode) {
+      injection = assembleInjection(entries, { perTopicBudget: cfg.perTopicBudget, totalBudget: cfg.totalBudget }, slowPointers)
+    } else if (pkgMode === undefined) {
+      injection = assemblePointer(entries, { perTopicBudget: POINTER_PER_TOPIC, totalBudget: Math.min(cfg.totalBudget, POINTER_TOTAL) }, slowPointers)
+    } else {
+      // A-line relevance package (A3, spec §2): direct = lexical hits,
+      // neighborhood = graph hits + slow picks, weak = reranked band head.
+      const budget = { perTopicBudget: POINTER_PER_TOPIC, totalBudget: Math.min(cfg.totalBudget, POINTER_TOTAL) }
+      const legacy = assemblePointer(entries, budget, slowPointers)
+      const direct: PackageCandidate[] = []
+      const neighborhood: PackageCandidate[] = []
+      for (const e of entries) {
+        const meta = bySlug.get(e.slug)
+        const cand: PackageCandidate = {
+          slug: e.slug,
+          title: meta?.title ?? e.slug,
+          status: meta?.status ?? 'draft',
+          description: meta?.description,
+          conclusion: firstContentLine(e.doc.body),
+          score: e.hit.score,
+          reasons: e.hit.reasons,
+          via: e.hit.viaGraph ? 'graph' : undefined,
+        }
+        ;(e.hit.viaGraph ? neighborhood : direct).push(cand)
+      }
+      for (const sp of slowPointers) {
+        neighborhood.push({ slug: sp.slug, title: sp.title, status: sp.status, description: sp.description, score: 0, reasons: [], via: 'slow-pick' })
+      }
+      const weak = outcome.nearMisses
+        .filter((h) => h.score >= 0.2 && h.score < cfg.matchThreshold)
+        .slice(0, 2)
+        .map((h) => {
+          const meta = bySlug.get(h.slug)
+          return { slug: h.slug, title: meta?.title ?? h.slug, status: meta?.status ?? 'draft', score: h.score, reasons: h.reasons, via: 'weak' }
+        })
+      const usage = this.usageSignalsSync()
+      const usageBySlug = new Map<string, number>([...usage].map(([slug, sig]) => [slug, sig.opens * 3 + sig.hits]))
+      const pkgInput: PackageInput = { query: effectiveQuery, queryTokens: tokenize(effectiveQuery), direct, neighborhood, weak, usageBySlug }
+      const pkg = assemblePackage(pkgInput)
+      if (pkgMode === 'shadow') {
+        packageShadow = pkg
+        injection = legacy
+      } else if (pkg === null) {
+        // Trivial-query downgrade (A3 决议 5): emit nothing, log the why.
+        packageSkipped = true
+        injection = { text: '', usedTokens: 0, included: [], dropped: [] }
+      } else {
+        const slowSet = new Set(slowPointers.map((sp) => sp.slug))
+        injection = {
+          text: pkg.text,
+          usedTokens: pkg.usedTokens,
+          included: pkg.included,
+          dropped: pkg.dropped,
+          slowIncluded: pkg.included.filter((slug) => slowSet.has(slug)),
+        }
+      }
+    }
     slowIncluded = injection.slowIncluded ?? []
     for (const pointer of slowPointers) {
       if (slowIncluded.includes(pointer.slug)) slowDelivered.push({ slug: pointer.slug, why: pointer.why })
     }
     const record: InjectionRecord = {
       at: new Date().toISOString(),
-      queryTokenCount: tokenize(query).length,
-      querySample: querySample(query),
+      queryTokenCount: tokenize(effectiveQuery).length,
+      querySample: querySample(effectiveQuery),
       rosterSize: outcome.rosterSize,
       hits: outcome.hits.map((h) => ({ slug: h.slug, score: h.score, reasons: h.reasons, viaGraph: h.viaGraph, strong: h.strong, bodyHits: h.bodyHits })),
       // Reasons ride along: the gate-blocked marker is the replay evidence
@@ -467,10 +695,27 @@ export class TopicsService {
     if (sessionId !== undefined) record.sessionId = sessionId
     if (deduped.length > 0) record.deduped = deduped
     if (echoed.length > 0) record.echoed = echoed
+    if (packageSkipped) record.why = 'package-skipped-trivial'
     if (unreadable.length > 0) {
       record.dropped = [...(record.dropped ?? []), ...unreadable.map((slug) => ({ slug, reason: 'doc-unreadable' }))]
     }
+    if (pkgMode === 'shadow' && pointerMode) {
+      this.appendPackageShadowLedger({
+        at: record.at,
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        queryTokenCount: record.queryTokenCount,
+        emitted: { tokens: injection.usedTokens, included: injection.included },
+        package:
+          packageShadow === undefined
+            ? null
+            : packageShadow === null
+              ? { skipped: 'trivial-or-empty' }
+              : { tokens: packageShadow.usedTokens, included: packageShadow.included, layers: packageShadow.layers },
+        nearFloorRerank: nearFloorRerank ?? null,
+      })
+    }
     if (slow !== undefined) {
+      if (slow.outcome !== undefined) record.slowOutcome = slow.outcome
       // Any round whose pending was consumed is a slow-participating round —
       // lane never stays undefined when the lane family is present (a
       // delivered pick with fast pointers is 'mixed'; a consumed-but-empty
@@ -532,9 +777,14 @@ export class TopicsService {
     const doc = slug === '' ? undefined : await this.store.readTopic(slug).catch(() => undefined)
     if (doc === undefined) return { found: false, slug }
     // Awaited (tool path, not hot): a settled write makes the pointer-open
-    // stat reliable; a failed log write must not fail the tool.
+    // stat reliable; a failed log write must not fail the tool. Source
+    // attribution rides the same write: a cheap injections-tail scan decides
+    // pointer vs search and, for pointers, carries the hit score and the
+    // open→injection lag (ilog.attributeOpen).
+    const at = new Date().toISOString()
+    const attribution = await this.attributeOpen(slug, sessionId, Date.parse(at))
     await this.store
-      .appendOpenRecord({ slug, at: new Date().toISOString(), ...(sessionId !== undefined ? { sessionId } : {}) })
+      .appendOpenRecord({ slug, at, ...(sessionId !== undefined ? { sessionId } : {}), ...attribution })
       .catch(() => undefined)
     // Optional fields are OMITTED, never present-as-undefined: the host's
     // tool-output validation rejects any object carrying an undefined-valued
@@ -564,6 +814,18 @@ export class TopicsService {
     return found
   }
 
+  /**
+   * Resolve the open's source attribution: the injections tail (bounded by
+   * OPEN_ATTRIBUTION_TAIL) scanned for a same-session hit within the
+   * attribution window. Read failures degrade to 'search' — attribution is
+   * telemetry, never a blocker.
+   */
+  private async attributeOpen(slug: string, sessionId: string | undefined, nowMs: number): Promise<{ source: 'pointer' | 'search'; score?: number; sinceInjectionMs?: number }> {
+    if (sessionId === undefined) return { source: 'search' }
+    const tail = await this.store.readInjectionRecords(OPEN_ATTRIBUTION_TAIL).catch(() => [])
+    return attributeOpen(tail, slug, sessionId, nowMs)
+  }
+
   /** Sync roster read (same mtime cache as roster()). */
   rosterSync(): RetrievableTopic[] {
     let files: string[]
@@ -639,6 +901,8 @@ export class TopicsService {
     depends?: string[]
     openQuestions?: string[]
     impact?: string[]
+    /** A2 semantic-link targets; store.saveTopic lands them as body wikilinks. */
+    links?: string[]
     status?: okf.TopicStatus
     conclusion?: string
     recommendations?: string
@@ -680,7 +944,7 @@ export class TopicsService {
     if (triggers.length > 0) fm.triggers = triggers
     if (existing !== undefined && existing.fm.verified !== undefined) fm.verified = existing.fm.verified
     const result = await this.store.saveTopic(
-      { slug, doc: { fm, body } },
+      { slug, doc: { fm, body }, links: input.links },
       { message: existing === undefined ? `topics(topic): create ${slug}` : `topics(topic): update ${slug}`, created: existing === undefined },
     )
     this.invalidate()
@@ -706,6 +970,7 @@ export class TopicsService {
       conflicts: await this.store.getConflicts(),
       usageBoost: cfg.usageBoost,
       usage: this.usageSignalsSync(),
+      ...this.zeroOpenCfg(),
     })
   }
 
@@ -773,6 +1038,15 @@ function dedupePaths(paths: string[]): string[] {
   return out
 }
 
+function firstContentLine(doc: string): string {
+  for (const line of doc.split('\n')) {
+    const t = line.trim()
+    if (t === '' || t.startsWith('#')) continue
+    return t.slice(0, 200)
+  }
+  return ''
+}
+
 function sanitizeTriggers(triggers: readonly string[]): string[] {
   const out: string[] = []
   for (const t of triggers) {

package/src/store.ts

@@ -26,7 +26,7 @@ import { randomUUID } from 'node:crypto'
 import * as okf from './okf.ts'
 import * as gitmod from './git.ts'
 import { actorFor } from './paths.ts'
-import type { InjectionRecord } from './ilog.ts'
+import type { InjectionRecord, OpenRecord } from './ilog.ts'
 
 export interface TopicMeta {
   slug: string
@@ -93,6 +93,15 @@ function sameStrings(a: readonly string[], b: readonly string[]): boolean {
   return a.length === b.length && a.every((v, i) => v === b[i])
 }
 
+/**
+ * Body heading for caller-supplied semantic links (A2). Links are rendered as
+ * `[[wikilinks]]` under this section so the EXISTING link-edge machinery
+ * (okf.bodyLinkSlugs → computeBacklinks → retrieval graph walk) indexes them
+ * as `via: 'link'` edges — the edge representation gains no new type; the
+ * body landing spot is what makes them first-class links for free.
+ */
+const LINKS_HEADING = 'Links'
+
 export interface BundleStoreOptions {
   /** Override the stamped actor (tests). Defaults to `agent:dsh-topics-memory@<host>`. */
   actor?: string
@@ -348,9 +357,17 @@ export class BundleStore {
    * Write a topic (atomic), regenerate the index, and commit both — one
    * commit per conclusion change (ADR 0003). `slug` in the doc's depends is
    * NOT normalized here; callers pass bundle-relative paths.
+   *
+   * `links` (A2, optional): whitelist-surviving semantic targets from the
+   * distill lane. Applied INSIDE this one write transaction — the topic and
+   * its edges land together (先落 topic 再建边); the Links section lands as
+   * body wikilinks and the index/backlinks regeneration below (same
+   * transaction) recomputes the edge index over them. Normalized and
+   * self/dedup-guarded here too, so any caller benefits from the same guard
+   * the distill lane already ran.
    */
   async saveTopic(
-    input: { slug: string; doc: okf.TopicDoc },
+    input: { slug: string; doc: okf.TopicDoc; links?: readonly string[] },
     opts: { message: string; actor?: string; created?: boolean },
   ): Promise<SaveResult> {
     return this.enqueue(async () => {
@@ -358,9 +375,22 @@ export class BundleStore {
       const file = this.topicPath(slug)
       const created = opts.created ?? !(await existsSync(file))
       const now = new Date().toISOString()
+      let body = input.doc.body
+      if (input.links !== undefined && input.links.length > 0) {
+        const targets: string[] = []
+        for (const raw of input.links) {
+          if (typeof raw !== 'string') continue
+          const target = okf.normalizeLinkTarget(raw)
+          if (target === undefined || target === slug || targets.includes(target)) continue
+          targets.push(target)
+        }
+        if (targets.length > 0) {
+          body = okf.setSection(body, LINKS_HEADING, targets.map((t) => `- [[${t}]]`).join('\n'))
+        }
+      }
       const doc: okf.TopicDoc = {
         fm: { ...input.doc.fm, generated: { by: opts.actor ?? this.actor, at: now } },
-        body: input.doc.body,
+        body,
       }
       const raw = okf.serializeTopicDoc(doc)
       await atomicWrite(file, raw)
@@ -612,14 +642,15 @@ export class BundleStore {
 
   // ------------------------------------------------------------------
   // Pointer-open log (v4 §4.3) — one line per topic_open call; feeds the
-  // 「指针打开率」 stat. Features only (slug/time), never conversation text.
+  // 「指针打开率」 stat. Features only (slug/time + attribution), never
+  // conversation text.
   // ------------------------------------------------------------------
 
   private opensPath(): string {
     return join(this.metaDir(), 'opens.jsonl')
   }
 
-  async appendOpenRecord(record: { slug: string; at: string; sessionId?: string }): Promise<void> {
+  async appendOpenRecord(record: OpenRecord): Promise<void> {
     await mkdir(this.metaDir(), { recursive: true })
     await appendFile(this.opensPath(), `${JSON.stringify(record)}\n`, 'utf8')
     await this.compactOpensIfNeeded()
@@ -638,22 +669,27 @@ export class BundleStore {
     await atomicWrite(file, lines.slice(-Math.max(1, Math.floor(lines.length / 4))).map((l) => `${l}\n`).join(''))
   }
 
-  /** Opens in the recent window; tolerant of a torn tail like the other JSONLs. */
-  async readOpenRecords(limit = 2000): Promise<{ slug: string; at: string; sessionId?: string }[]> {
+  /** Opens in the recent window; tolerant of a torn tail like the other JSONLs.
+   *  Enrichment fields (sessionId/source/score/sinceInjectionMs) are optional:
+   *  pre-enrichment lines carry only slug/at and read back without them. */
+  async readOpenRecords(limit = 2000): Promise<OpenRecord[]> {
     let raw: string
     try {
       raw = await readFile(this.opensPath(), 'utf8')
     } catch {
       return []
     }
-    const out: { slug: string; at: string; sessionId?: string }[] = []
+    const out: OpenRecord[] = []
     for (const line of raw.split('\n')) {
       if (line.trim() === '') continue
       try {
-        const parsed = JSON.parse(line) as { slug?: unknown; at?: unknown; sessionId?: unknown }
+        const parsed = JSON.parse(line) as { slug?: unknown; at?: unknown; sessionId?: unknown; source?: unknown; score?: unknown; sinceInjectionMs?: unknown }
         if (typeof parsed.slug === 'string' && typeof parsed.at === 'string') {
-          const rec: { slug: string; at: string; sessionId?: string } = { slug: parsed.slug, at: parsed.at }
+          const rec: OpenRecord = { slug: parsed.slug, at: parsed.at }
           if (typeof parsed.sessionId === 'string') rec.sessionId = parsed.sessionId
+          if (parsed.source === 'pointer' || parsed.source === 'search') rec.source = parsed.source
+          if (typeof parsed.score === 'number') rec.score = parsed.score
+          if (typeof parsed.sinceInjectionMs === 'number') rec.sinceInjectionMs = parsed.sinceInjectionMs
           out.push(rec)
         }
       } catch {