@aiwayds/dsh-topics-memory 0.6.0 → 0.7.0

package/src/observer.ts

@@ -24,8 +24,25 @@ interface SessionState {
   userText: string
   assistantText: string
   capturing: boolean
+  /** Last-K completed turns (v4 slow-lane data source, K≈3). */
+  ring: RingEntry[]
 }
 
+/** One completed turn in the ring buffer — the slow lane's only context source. */
+export interface RingEntry {
+  user: string
+  assistant: string
+  at: string
+}
+
+/**
+ * Ring capacity (v4 §4.2 B1): the slow lane sees at most the last 3 completed
+ * turns. Deliberately small — query building wants the current intent, not a
+ * transcript; larger windows re-introduce the verbatim-priming surface the
+ * lane exists to remove.
+ */
+export const RING_CAPACITY = 3
+
 export interface UserMessageLike {
   source?: { kind?: string }
   content: readonly { type: string; text?: string }[]
@@ -58,12 +75,22 @@ export class Observer {
   private stateFor(sessionId: string): SessionState {
     let s = this.sessions.get(sessionId)
     if (s === undefined) {
-      s = { turnCount: 0, userText: '', assistantText: '', capturing: false }
+      s = { turnCount: 0, userText: '', assistantText: '', capturing: false, ring: [] }
       this.sessions.set(sessionId, s)
     }
     return s
   }
 
+  /** Completed-turn snapshot for the slow lane (deep copy — callers may hold it). */
+  recentTurns(sessionId: string): RingEntry[] {
+    return (this.sessions.get(sessionId)?.ring ?? []).map((e) => ({ ...e }))
+  }
+
+  /** Current turn count for the session (0 before the first turn ends). */
+  turnCountOf(sessionId: string): number {
+    return this.sessions.get(sessionId)?.turnCount ?? 0
+  }
+
   /** Entry point wired to ctx.on('session/event', …). */
   onSessionEvent(sessionId: string, eventType: string, data: unknown): void {
     try {
@@ -91,8 +118,22 @@ export class Observer {
       }
       case 'turn/end': {
         state.turnCount += 1
+        // Cadence trigger FIRST and synchronously: index.ts dispatches the
+        // slow quality lane the moment onSessionEvent returns — which happens
+        // at the first await below (the observation write). The lane's
+        // distill-yield guard reads distiller.hasPending, so the every-N slot
+        // must be claimed before that first await or the %15 collision would
+        // never yield. The trigger's run fetches observations lazily; this
+        // turn's capture below still lands in the pool for a later run.
+        if (cfg.distillEveryTurns > 0 && state.turnCount % cfg.distillEveryTurns === 0) {
+          this.onRequestDistill(sessionId, 'every-n')
+        }
         const user = state.userText.trim()
         const assistant = state.assistantText.trim()
+        if (user !== '' || assistant !== '') {
+          state.ring.push({ user, assistant, at: new Date().toISOString() })
+          if (state.ring.length > RING_CAPACITY) state.ring.splice(0, state.ring.length - RING_CAPACITY)
+        }
         if (cfg.autoObserve && user !== '' && assistant !== '') {
           await this.service.store.appendObservation({
             kind: 'turn',
@@ -106,9 +147,6 @@ export class Observer {
         }
         state.userText = ''
         state.assistantText = ''
-        if (cfg.distillEveryTurns > 0 && state.turnCount % cfg.distillEveryTurns === 0) {
-          this.onRequestDistill(sessionId, 'every-n')
-        }
         return
       }
       // Real session teardown: both cordis events fire at teardown (agent

package/src/okf.ts

@@ -36,6 +36,13 @@ export interface TopicFrontmatter {
   title: string
   description?: string
   tags: string[]
+  /**
+   * Self-declared recall triggers (v4 dual-channel design §4.1): short
+   * phrases that should recall this topic when they appear in a query.
+   * Optional; bundles written before the field simply have no trigger
+   * matching (degraded, never an error). Highest-weight strong field.
+   */
+  triggers?: string[]
   /** Bundle-relative paths: `topics/<slug>.md`. */
   depends: string[]
   open_questions: string[]
@@ -123,6 +130,14 @@ export function parseTopicDoc(raw: string): TopicDoc {
     generated,
   }
   if (typeof fmRaw.description === 'string' && fmRaw.description !== '') fm.description = fmRaw.description
+  // Triggers are producer-optional and must never invalidate an otherwise
+  // sound doc: non-string entries are filtered, not thrown (degrade, per the
+  // v4 design's "旧 bundle 无此字段降级不命中").
+  if (fmRaw.triggers !== undefined && fmRaw.triggers !== null) {
+    const raw = Array.isArray(fmRaw.triggers) ? fmRaw.triggers : [fmRaw.triggers]
+    const triggers = raw.filter((t): t is string => typeof t === 'string' && t.trim() !== '').map((t) => t.trim())
+    if (triggers.length > 0) fm.triggers = triggers
+  }
   if ('verified' in fmRaw && fmRaw.verified !== null && fmRaw.verified !== undefined) fm.verified = asTrust(fmRaw.verified, 'verified')
   if (typeof fmRaw.stale_after === 'string' && fmRaw.stale_after !== '') fm.stale_after = fmRaw.stale_after
   if (Array.isArray(fmRaw.sources)) {
@@ -134,7 +149,7 @@ export function parseTopicDoc(raw: string): TopicDoc {
     })
   }
   // Preserve unknown producer-defined keys verbatim (OKF §4.1 extensions).
-  const known = new Set(['type', 'title', 'description', 'tags', 'depends', 'open_questions', 'impact', 'status', 'generated', 'verified', 'stale_after', 'sources'])
+  const known = new Set(['type', 'title', 'description', 'tags', 'triggers', 'depends', 'open_questions', 'impact', 'status', 'generated', 'verified', 'stale_after', 'sources'])
   for (const [k, v] of Object.entries(fmRaw)) {
     if (!known.has(k)) fm[k] = v
   }
@@ -150,6 +165,7 @@ export function serializeTopicDoc(doc: TopicDoc): string {
   }
   if (fm.description !== undefined) out.description = fm.description
   out.tags = fm.tags
+  if (fm.triggers !== undefined && fm.triggers.length > 0) out.triggers = fm.triggers
   out.depends = fm.depends
   out.open_questions = fm.open_questions
   out.impact = fm.impact

package/src/quality.ts

@@ -0,0 +1,335 @@
+/**
+ * Slow quality lane (v4 dual-channel design §4.2) — asynchronous, turn-end
+ * triggered, LLM-gated injection. Two serial aux calls per run:
+ *
+ *   1. intent-query build over the observer's last-K ring buffer — kills
+ *      verbatim priming at the root (the query is what the model needs, not
+ *      what the user typed);
+ *   2. lexical candidate band (hits + near-misses, recall-oriented) then an
+ *      LLM rerank that releases 0-2 picks, each with a one-line why.
+ *
+ * Picks rest in a per-session pending slot and inject at the NEXT spliced
+ * (steer message), then the slot is gone (消费即清). Hard bounds: per-call
+ * 20s, pipeline 45s, pending TTL 10min, turn-lag ≤2. Every failure is
+ * contained and silent — I3 (可丢弃性): async products may be missing, never
+ * blocking. The lexical re-gate at consumption is SHADOW-ONLY (v4 B3): it
+ * records verdicts into ilog and never blocks a pick.
+ *
+ * @module quality
+ */
+
+import type { TopicsService } from './service.ts'
+import type { ModelCaller } from './distill.ts'
+import { searchTopics } from './retrieval.ts'
+import type { RingEntry } from './observer.ts'
+import type { QueryBuildShape } from './ilog.ts'
+
+export const PENDING_TTL_MS = 10 * 60_000
+/** Hard drift bound: a pending older than this many turn-ends expires. */
+export const TURN_LAG_LIMIT = 2
+export const CALL_TIMEOUT_MS = 20_000
+export const PIPELINE_TIMEOUT_MS = 45_000
+/** qualityLane 'sampled' runs on every Nth turn (design default 1/3). */
+export const SAMPLED_EVERY = 3
+
+/** Max ring-buffer chars fed to the query build (features budget, not a transcript). */
+const RING_CHARS = 6000
+/** Candidate band size fed to the rerank. */
+const CANDIDATE_LIMIT = 6
+
+export const QUERY_BUILD_PROMPT = [
+  '你是检索查询构建器。输入是最近几轮对话。任务：判断「模型此刻需要什么背景知识」，输出一个用于关键词检索的 query。',
+  '只输出一个 JSON 对象，不要任何其他文字：{"needs": true, "query": "3-8 个检索词加一句意图", "ignore": ["被你忽略的内容类型"]}',
+  '规则：',
+  '- query 给词法检索用：写具体的名词、术语、项目名，不要照抄对话原句。',
+  '- 对话里粘贴的日志、代码块、URL、命令输出等大段内容必须忽略，并把类型写进 ignore 数组（如 "粘贴的命令输出"）。',
+  '- 没有需要补充背景知识的迹象时输出 {"needs": false}。',
+].join('\n')
+
+export const RERANK_PROMPT = [
+  '你是注入门禁。输入一个检索 query 和候选 topic 列表。逐个判断候选是否「真的与当前工作相关」。',
+  '只输出一个 JSON 对象，不要任何其他文字：{"picks": [{"slug": "候选里的 slug", "why": "一句话说明为什么现在需要它"}]}',
+  '规则：',
+  '- 最多 2 条，宁缺勿滥；没有真相关的就输出 {"picks": []}。',
+  '- why 面向模型自己读：说清这条记忆能帮上当前哪一步。',
+  '- slug 必须逐字取自候选列表，禁止编造。',
+].join('\n')
+
+export interface PendingInjection {
+  items: { slug: string; why: string }[]
+  computedAt: string
+  /** Observer turnCount when the pending was produced (turn-lag clock). */
+  turnId: number
+  queryBuild: QueryBuildShape
+  model: string
+  ms: number
+}
+
+export type ConsumeResult = { pending: PendingInjection } | { expired: 'ttl' | 'turn-lag' } | undefined
+
+export interface DispatchInput {
+  ring: readonly RingEntry[]
+  turnId: number
+}
+
+/** Race `p` against a timeout; `onTimeout` fires so callers can abort upstream work. */
+function withTimeout<T>(p: Promise<T>, ms: number, onTimeout: () => void): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      onTimeout()
+      reject(new Error(`slow-lane call timeout (${ms}ms)`))
+    }, ms)
+    timer.unref?.()
+    p.then(
+      (v) => {
+        clearTimeout(timer)
+        resolve(v)
+      },
+      (e) => {
+        clearTimeout(timer)
+        reject(e)
+      },
+    )
+  })
+}
+
+/** Extract the first balanced JSON object from model output (tolerates fences). */
+export function parseJsonObject(raw: string): Record<string, unknown> {
+  let text = raw.trim()
+  const fence = /```(?:json)?\s*([\s\S]*?)```/.exec(text)
+  if (fence !== null) text = fence[1].trim()
+  const start = text.indexOf('{')
+  if (start < 0) throw new Error('no JSON object in output')
+  let depth = 0
+  let inString = false
+  let escaped = false
+  for (let i = start; i < text.length; i += 1) {
+    const ch = text[i]
+    if (escaped) {
+      escaped = false
+      continue
+    }
+    if (ch === '\\') {
+      escaped = true
+      continue
+    }
+    if (ch === '"') inString = !inString
+    if (inString) continue
+    if (ch === '{') depth += 1
+    if (ch === '}') {
+      depth -= 1
+      if (depth === 0) {
+        const parsed: unknown = JSON.parse(text.slice(start, i + 1))
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not an object')
+        return parsed as Record<string, unknown>
+      }
+    }
+  }
+  throw new Error('unbalanced JSON in output')
+}
+
+export class SlowLane {
+  private pending = new Map<string, PendingInjection>()
+  private inFlight = new Map<string, Promise<void>>()
+  private readonly service: TopicsService
+  private readonly caller: ModelCaller | undefined
+  /**
+   * Settle hook: fires when a session's pipeline leaves the in-flight map.
+   * The host uses it to re-check the sessionLlm release guards — a disposal
+   * that landed mid-pipeline held the entry open for THIS pipeline, and this
+   * callback is the only chance to release it afterwards (the distill lane
+   * has the same shape via its run.finally).
+   */
+  private readonly onSettle: (sessionId: string) => void
+
+  constructor(service: TopicsService, caller: ModelCaller | undefined, onSettle: (sessionId: string) => void = () => undefined) {
+    this.service = service
+    this.caller = caller
+    this.onSettle = onSettle
+  }
+
+  /** True while the session has a pending slot awaiting the next spliced. */
+  hasPending(sessionId: string): boolean {
+    return this.pending.has(sessionId)
+  }
+
+  /** True while the session's produce pipeline is still running (llm-capture guard). */
+  hasInFlight(sessionId: string): boolean {
+    return this.inFlight.has(sessionId)
+  }
+
+  /** Drop the pending slot (session teardown, restore boundary). */
+  clear(sessionId: string): void {
+    this.pending.delete(sessionId)
+  }
+
+  /**
+   * Produce a pending slot for the session's next steer message. Fire-and-
+   * forget; every guard failure is silent. Policy gates live here (config,
+   * sampling, in-flight); host gates (delegation, distill yield) live with
+   * the caller, which owns those services.
+   */
+  dispatch(sessionId: string, input: DispatchInput): void {
+    try {
+      const cfg = this.service.cfg
+      if (cfg.qualityLane !== 'sampled' && cfg.qualityLane !== 'always') return
+      if (cfg.qualityLane === 'sampled' && input.turnId % SAMPLED_EVERY !== 0) return
+      if (this.caller === undefined || this.inFlight.has(sessionId)) return
+      if (input.ring.length === 0) return
+      const run = this.produce(sessionId, input).finally(() => {
+        this.inFlight.delete(sessionId)
+        this.onSettle(sessionId)
+      })
+      this.inFlight.set(sessionId, run)
+      void run.catch(() => undefined)
+    } catch {
+      // contained — the lane must never break the event handler
+    }
+  }
+
+  private async produce(sessionId: string, input: DispatchInput): Promise<void> {
+    const caller = this.caller
+    if (caller === undefined) return
+    const started = Date.now()
+    const controller = new AbortController()
+    const deadline = setTimeout(() => controller.abort(), PIPELINE_TIMEOUT_MS)
+    deadline.unref?.()
+    try {
+      const cfg = this.service.cfg
+      const ringText = input.ring
+        .map((e, i) => {
+          const turn = `【轮 ${i + 1}】\n用户: ${e.user}\n助手: ${e.assistant}`
+          return turn.length > RING_CHARS / input.ring.length ? turn.slice(0, Math.floor(RING_CHARS / input.ring.length)) : turn
+        })
+        .join('\n\n')
+      const buildRaw = await withTimeout(
+        caller({
+          system: QUERY_BUILD_PROMPT,
+          user: ringText,
+          purpose: 'topics-quality',
+          sessionId,
+          maxTokens: 300,
+          signal: controller.signal,
+        }),
+        CALL_TIMEOUT_MS,
+        () => controller.abort(),
+      )
+      let built: Record<string, unknown>
+      try {
+        built = parseJsonObject(buildRaw)
+      } catch {
+        return // unparseable build → no pending, nothing logged, next turn retries
+      }
+      if (built.needs !== true || typeof built.query !== 'string' || built.query.trim() === '') return
+      const query = built.query.trim()
+      const stripped = Array.isArray(built.ignore)
+        ? built.ignore.filter((s): s is string => typeof s === 'string' && s.trim() !== '').slice(0, 5)
+        : []
+      const queryBuild: QueryBuildShape = { rawChars: ringText.length, keptChars: query.length, stripped }
+
+      const roster = await this.service.roster().catch(() => [])
+      if (roster.length === 0) return
+      // Recall-oriented band: gate OFF (the rerank IS this lane's gate);
+      // candidates = threshold passers + the near-miss band beneath them.
+      const band = searchTopics(query, roster, {
+        threshold: this.service.cfg.matchThreshold,
+        topK: CANDIDATE_LIMIT,
+        tagBoost: this.service.cfg.tagBoost,
+        graphDepth: 0,
+        recencyWindowDays: this.service.cfg.recencyWindowDays,
+        structuralGate: false,
+      })
+      const candidates = [...band.hits, ...band.nearMisses].slice(0, CANDIDATE_LIMIT)
+      if (candidates.length === 0) return
+      const bySlug = new Map(roster.map((r) => [r.slug, r]))
+      const payload = candidates.flatMap((c) => {
+        const meta = bySlug.get(c.slug)
+        if (meta === undefined) return []
+        const conclusionFirst = meta.conclusion.split('\n').find((l) => l.trim() !== '') ?? ''
+        return [
+          {
+            slug: c.slug,
+            title: meta.title,
+            status: meta.status,
+            description: meta.description ?? '',
+            conclusion: conclusionFirst.slice(0, 160),
+          },
+        ]
+      })
+      if (payload.length === 0) return
+      const rerankRaw = await withTimeout(
+        caller({
+          system: RERANK_PROMPT,
+          user: [
+            `检索 query：${query}`,
+            '',
+            `候选 topic（${payload.length} 个）：`,
+            JSON.stringify(payload),
+          ].join('\n'),
+          purpose: 'topics-quality',
+          sessionId,
+          maxTokens: 400,
+          signal: controller.signal,
+        }),
+        CALL_TIMEOUT_MS,
+        () => controller.abort(),
+      )
+      let reranked: Record<string, unknown>
+      try {
+        reranked = parseJsonObject(rerankRaw)
+      } catch {
+        return
+      }
+      const legal = new Set(payload.map((p) => p.slug))
+      const rawPicks = Array.isArray(reranked.picks) ? reranked.picks : []
+      const items: { slug: string; why: string }[] = []
+      const picked = new Set<string>()
+      for (const pick of rawPicks) {
+        if (pick === null || typeof pick !== 'object') continue
+        const slug = (pick as { slug?: unknown }).slug
+        const why = (pick as { why?: unknown }).why
+        if (typeof slug !== 'string' || !legal.has(slug)) continue
+        if (typeof why !== 'string' || why.trim() === '') continue
+        if (picked.has(slug)) continue
+        picked.add(slug)
+        items.push({ slug, why: why.trim().slice(0, 200) })
+        if (items.length >= 2) break
+      }
+      if (items.length === 0) return
+      const route = this.service.cfg
+      this.pending.set(sessionId, {
+        items,
+        computedAt: new Date().toISOString(),
+        turnId: input.turnId,
+        queryBuild,
+        model: `${route.distillProvider}/${route.distillModel}`,
+        ms: Date.now() - started,
+      })
+    } catch {
+      // timeouts, aborts, model errors — I3: the async product is simply absent
+    } finally {
+      clearTimeout(deadline)
+    }
+  }
+
+  /**
+   * Consumption point (the next spliced). Returns the pending exactly once
+   * (消费即清) or an expiry reason; `turnId` is the CURRENT observer turn
+   * count so the drift bound can judge. Undefined when nothing is pending.
+   */
+  consume(sessionId: string, turnId: number): ConsumeResult {
+    const pending = this.pending.get(sessionId)
+    if (pending === undefined) return undefined
+    const produced = Date.parse(pending.computedAt)
+    if (!Number.isNaN(produced) && Date.now() - produced > PENDING_TTL_MS) {
+      this.pending.delete(sessionId)
+      return { expired: 'ttl' }
+    }
+    if (turnId - pending.turnId > TURN_LAG_LIMIT) {
+      this.pending.delete(sessionId)
+      return { expired: 'turn-lag' }
+    }
+    this.pending.delete(sessionId)
+    return { pending }
+  }
+}

package/src/retrieval.ts

@@ -20,6 +20,8 @@ export interface RetrievableTopic extends TopicMeta {
   conclusion: string
   /** Body-referenced topic slugs ([[wikilinks]] + markdown links) — graph edges. */
   links?: string[]
+  /** Self-declared recall triggers (v4 structural gate strong field). */
+  triggers?: string[]
 }
 
 export interface RetrievalConfig {
@@ -31,6 +33,13 @@ export interface RetrievalConfig {
   now?: Date
   /** Slugs currently conflicted — demoted, not dropped. */
   conflicts?: ReadonlySet<string>
+  /**
+   * v4 structural gate v0 (design §4.1): a threshold-passing candidate only
+   * injects when it ALSO hits a strong field (triggers/title/slug) or ≥2
+   * distinct body terms — tags alone and single body terms can no longer
+   * self-cross. Off for the explicit topic_search tool (the model asked).
+   */
+  structuralGate: boolean
 }
 
 export const DEFAULT_RETRIEVAL: RetrievalConfig = {
@@ -39,13 +48,22 @@ export const DEFAULT_RETRIEVAL: RetrievalConfig = {
   tagBoost: 0.15,
   graphDepth: 2,
   recencyWindowDays: 7,
+  structuralGate: true,
 }
 
+/** Trigger hits outrank every other lexical field (pi-llm-wiki: highest weight). */
+export const TRIGGER_WEIGHT = 5
+
 export interface SearchHit {
   slug: string
   score: number
   reasons: string[]
   viaGraph: boolean
+  /** Structural gate v0 evidence (absent on graph-expanded entries). */
+  strong?: boolean
+  bodyHits?: number
+  /** Recency-free score; graph decay starts from it (settle ties with the gate). */
+  gateScore?: number
 }
 
 export interface SearchOutcome {
@@ -93,6 +111,12 @@ export interface ScoredTopic {
   slug: string
   score: number
   reasons: string[]
+  /** Strong-field hit (triggers/title/slug) — gate v0 pass condition A. */
+  strong: boolean
+  /** Distinct query terms found in description ∪ conclusion — pass condition B is ≥2. */
+  bodyHits: number
+  /** Score with the recency tiebreaker removed — the only score the gate looks at. */
+  gateScore: number
 }
 
 /** Score one topic against the query tokens. */
@@ -103,21 +127,35 @@ export function scoreTopic(
 ): ScoredTopic {
   const title = new Set(tokenize(topic.title))
   const slug = new Set(tokenize(topic.slug))
+  const triggers = new Set((topic.triggers ?? []).flatMap((t) => tokenize(t)))
   const tags = new Set(topic.tags.flatMap((t) => tokenize(t)))
   const description = new Set(tokenize(topic.description ?? ''))
   const conclusion = new Set(tokenize(topic.conclusion))
   const reasons: string[] = []
   let score = 0
 
+  const cTriggers = containment(queryTokens, triggers)
+  if (cTriggers > 0) {
+    score += TRIGGER_WEIGHT * cTriggers
+    reasons.push(`triggers:${cTriggers.toFixed(2)}`)
+  }
   const cTitle = containment(queryTokens, title)
   if (cTitle > 0) {
     score += 3 * cTitle
     reasons.push(`title:${cTitle.toFixed(2)}`)
   }
-  const cTag = containment(queryTokens, new Set([...tags, ...slug]))
-  if (cTag > 0) {
-    score += 2 * cTag
-    reasons.push(`tags:${cTag.toFixed(2)}`)
+  // Slug and tags are scored separately since the structural gate (v4): the
+  // slug is a strong field, tags are not. Weights unchanged (2) so historical
+  // score distributions stay comparable.
+  const cSlug = containment(queryTokens, slug)
+  if (cSlug > 0) {
+    score += 2 * cSlug
+    reasons.push(`slug:${cSlug.toFixed(2)}`)
+  }
+  const cTags = containment(queryTokens, tags)
+  if (cTags > 0) {
+    score += 2 * cTags
+    reasons.push(`tags:${cTags.toFixed(2)}`)
   }
   const cDesc = containment(queryTokens, description)
   if (cDesc > 0) {
@@ -129,25 +167,28 @@ export function scoreTopic(
     score += 0.8 * cConc
     reasons.push(`conclusion:${cConc.toFixed(2)}`)
   }
-  // Exact tag hit boost, additive and capped (pi-topic-memory lesson: add,
-  // never fold into the token set — dilution breaks the guard).
+  // Exact tag hit boost, additive and capped at ONE boost's worth (v4 design:
+  // the old ×3 cap let shared tags mint a 0.45 floor — the priming main
+  // culprit). Never folded into the token set (dilution breaks the guard).
   let tagHits = 0
   for (const t of tags) {
     if (overlap(queryTokens, new Set([...tokenize(t)]))) tagHits += 1
   }
   if (tagHits > 0) {
-    const boost = Math.min(cfg.tagBoost * tagHits, cfg.tagBoost * 3)
+    const boost = Math.min(cfg.tagBoost * tagHits, cfg.tagBoost)
     score += boost
     reasons.push(`tag-boost:+${boost.toFixed(2)}`)
   }
-  // Recency is a tiebreaker among relevant topics, never a free pass: only
-  // fires when the query already matched some content above.
+  // Recency is a RANKING tiebreaker only (v4): it pads `score` but is kept
+  // out of `gateScore`, so it can never carry a candidate across the numeric
+  // threshold. Conflict demotion applies to the pre-tiebreaker score.
+  let recencyBonus = 0
   if (score > 0 && cfg.recencyWindowDays > 0) {
     const generated = Date.parse(topic.generatedAt)
     if (!Number.isNaN(generated)) {
       const ageDays = ((cfg.now?.getTime() ?? Date.now()) - generated) / 86_400_000
       if (ageDays >= 0 && ageDays <= cfg.recencyWindowDays) {
-        score += 0.2
+        recencyBonus = 0.2
         reasons.push('recency')
       }
     }
@@ -156,13 +197,36 @@ export function scoreTopic(
     score *= 0.3
     reasons.push('conflicted-demoted')
   }
-  return { slug: topic.slug, score: Math.round(score * 1000) / 1000, reasons }
+  const gateScore = score
+  score += recencyBonus
+  const bodySet = new Set([...description, ...conclusion])
+  let bodyHits = 0
+  for (const t of queryTokens) if (bodySet.has(t)) bodyHits += 1
+  const strong = cTriggers > 0 || cTitle > 0 || cSlug > 0
+  return {
+    slug: topic.slug,
+    score: Math.round(score * 1000) / 1000,
+    reasons,
+    strong,
+    bodyHits,
+    gateScore: Math.round(gateScore * 1000) / 1000,
+  }
+}
+
+/** Structural gate v0 verdict: strong-field hit, or ≥2 distinct body terms. */
+export function passesGate(s: { strong: boolean; bodyHits: number }): boolean {
+  return s.strong || s.bodyHits >= 2
 }
 
 /**
- * Search the roster: score every topic, split hits from near-misses, then
- * expand seeds through the `depends` graph (both directions, geometric decay,
- * depth ≤ cfg.graphDepth). Expanded entries enter at the back of the hits.
+ * Search the roster: score every topic, apply the numeric threshold to the
+ * gate score (recency excluded), split by the structural gate, then expand
+ * gate-passed seeds through the `depends` graph (both directions, geometric
+ * decay, depth ≤ cfg.graphDepth). Expanded entries enter at the back of the
+ * hits and are exempt from the structural gate — they carry no lexical
+ * evidence by design, only graph adjacency. Threshold-passing candidates the
+ * gate rejects lead the near-misses (reason `gate-blocked`) so the replay
+ * evidence shows what the gate is costing.
  */
 export function searchTopics(query: string, roster: readonly RetrievableTopic[], cfg: Partial<RetrievalConfig> = {}): SearchOutcome {
   const c: RetrievalConfig = { ...DEFAULT_RETRIEVAL, ...cfg }
@@ -171,10 +235,18 @@ export function searchTopics(query: string, roster: readonly RetrievableTopic[],
     return { hits: [], nearMisses: [], rosterSize: roster.length }
   }
   const scored = roster.map((t) => scoreTopic(queryTokens, t, c)).sort((a, b) => b.score - a.score)
-  const direct = scored.filter((s) => s.score >= c.threshold).slice(0, c.topK)
-  const near = scored.filter((s) => s.score < c.threshold && s.score >= c.threshold * 0.5).slice(0, 8)
+  const passing = scored.filter((s) => s.gateScore >= c.threshold)
+  const directHits = passing.filter((s) => !c.structuralGate || passesGate(s)).slice(0, c.topK)
+  const gateBlocked = c.structuralGate
+    ? passing.filter((s) => !passesGate(s)).slice(0, c.topK)
+    : []
+  const nearFloor = scored.filter((s) => s.gateScore < c.threshold && s.gateScore >= c.threshold * 0.5).slice(0, 8)
 
-  const hits: SearchHit[] = direct.map((s) => ({ ...s, viaGraph: false }))
+  const hits: SearchHit[] = directHits.map((s) => ({ ...s, viaGraph: false }))
+  const nearMisses: SearchHit[] = [
+    ...gateBlocked.map((s) => ({ ...s, reasons: [...s.reasons, 'gate-blocked'], viaGraph: false })),
+    ...nearFloor.map((s) => ({ ...s, viaGraph: false })),
+  ].slice(0, 8)
   // Graph expansion (ADR 0005 graph-shaped bundle): walk depends + body
   // links, both directions, from the seeds; include up to topK+2 slots at
   // decaying score.
@@ -196,7 +268,9 @@ export function searchTopics(query: string, roster: readonly RetrievableTopic[],
       }
     }
     const seen = new Set(hits.map((h) => h.slug))
-    let frontier = hits.map((h) => ({ slug: h.slug, score: h.score }))
+    // Decay starts from the gateScore: recency must not re-enter through the
+    // graph channel after being banned from the direct gate.
+    let frontier = hits.map((h) => ({ slug: h.slug, score: h.gateScore ?? h.score }))
     for (let depth = 1; depth <= c.graphDepth && frontier.length > 0; depth += 1) {
       const next: { slug: string; score: number }[] = []
       for (const node of frontier) {
@@ -215,5 +289,5 @@ export function searchTopics(query: string, roster: readonly RetrievableTopic[],
       frontier = next
     }
   }
-  return { hits, nearMisses: near.map((s) => ({ ...s, viaGraph: false })), rosterSize: roster.length }
+  return { hits, nearMisses, rosterSize: roster.length }
 }