@aiwayds/dsh-topics-memory 0.6.0 → 0.7.0

package/lib/observer.d.ts

@@ -16,6 +16,19 @@
  * @module observer
  */
 import type { TopicsService } from './service.ts';
+/** 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 declare const RING_CAPACITY = 3;
 export interface UserMessageLike {
     source?: {
         kind?: string;
@@ -34,6 +47,10 @@ export declare class Observer {
     private readonly onRequestDistill;
     constructor(service: TopicsService, onRequestDistill: (sessionId: string, reason: 'every-n' | 'session-end') => void);
     private stateFor;
+    /** Completed-turn snapshot for the slow lane (deep copy — callers may hold it). */
+    recentTurns(sessionId: string): RingEntry[];
+    /** Current turn count for the session (0 before the first turn ends). */
+    turnCountOf(sessionId: string): number;
     /** Entry point wired to ctx.on('session/event', …). */
     onSessionEvent(sessionId: string, eventType: string, data: unknown): void;
     private handleAsync;

package/lib/observer.js

@@ -15,6 +15,13 @@
  *
  * @module observer
  */
+/**
+ * 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 function textOf(message) {
     // Deliberately text-only and explicit: since dsh 0.1.2-alpha.3 sub-agent
     // follow-up messages may carry image (and other non-text) content blocks —
@@ -38,11 +45,19 @@ export class Observer {
     stateFor(sessionId) {
         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) {
+        return (this.sessions.get(sessionId)?.ring ?? []).map((e) => ({ ...e }));
+    }
+    /** Current turn count for the session (0 before the first turn ends). */
+    turnCountOf(sessionId) {
+        return this.sessions.get(sessionId)?.turnCount ?? 0;
+    }
     /** Entry point wired to ctx.on('session/event', …). */
     onSessionEvent(sessionId, eventType, data) {
         try {
@@ -72,8 +87,23 @@ 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',
@@ -87,9 +117,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/lib/okf.d.ts

@@ -30,6 +30,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[];

package/lib/okf.js

@@ -85,6 +85,15 @@ export function parseTopicDoc(raw) {
     };
     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) => 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 !== '')
@@ -98,7 +107,7 @@ export function parseTopicDoc(raw) {
         });
     }
     // 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;
@@ -115,6 +124,8 @@ export function serializeTopicDoc(doc) {
     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/lib/quality.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 type { RingEntry } from './observer.ts';
+import type { QueryBuildShape } from './ilog.ts';
+export declare const PENDING_TTL_MS: number;
+/** Hard drift bound: a pending older than this many turn-ends expires. */
+export declare const TURN_LAG_LIMIT = 2;
+export declare const CALL_TIMEOUT_MS = 20000;
+export declare const PIPELINE_TIMEOUT_MS = 45000;
+/** qualityLane 'sampled' runs on every Nth turn (design default 1/3). */
+export declare const SAMPLED_EVERY = 3;
+export declare const QUERY_BUILD_PROMPT: string;
+export declare const RERANK_PROMPT: string;
+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;
+}
+/** Extract the first balanced JSON object from model output (tolerates fences). */
+export declare function parseJsonObject(raw: string): Record<string, unknown>;
+export declare class SlowLane {
+    private pending;
+    private inFlight;
+    private readonly service;
+    private readonly caller;
+    /**
+     * 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;
+    constructor(service: TopicsService, caller: ModelCaller | undefined, onSettle?: (sessionId: string) => void);
+    /** True while the session has a pending slot awaiting the next spliced. */
+    hasPending(sessionId: string): boolean;
+    /** True while the session's produce pipeline is still running (llm-capture guard). */
+    hasInFlight(sessionId: string): boolean;
+    /** Drop the pending slot (session teardown, restore boundary). */
+    clear(sessionId: string): void;
+    /**
+     * 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;
+    private produce;
+    /**
+     * 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;
+}

package/lib/quality.js

@@ -0,0 +1,315 @@
+/**
+ * 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 { searchTopics } from "./retrieval.js";
+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');
+/** Race `p` against a timeout; `onTimeout` fires so callers can abort upstream work. */
+function withTimeout(p, ms, onTimeout) {
+    return new Promise((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) {
+    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 = JSON.parse(text.slice(start, i + 1));
+                if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+                    throw new Error('not an object');
+                return parsed;
+            }
+        }
+    }
+    throw new Error('unbalanced JSON in output');
+}
+export class SlowLane {
+    pending = new Map();
+    inFlight = new Map();
+    service;
+    caller;
+    /**
+     * 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).
+     */
+    onSettle;
+    constructor(service, caller, onSettle = () => undefined) {
+        this.service = service;
+        this.caller = caller;
+        this.onSettle = onSettle;
+    }
+    /** True while the session has a pending slot awaiting the next spliced. */
+    hasPending(sessionId) {
+        return this.pending.has(sessionId);
+    }
+    /** True while the session's produce pipeline is still running (llm-capture guard). */
+    hasInFlight(sessionId) {
+        return this.inFlight.has(sessionId);
+    }
+    /** Drop the pending slot (session teardown, restore boundary). */
+    clear(sessionId) {
+        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, input) {
+        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
+        }
+    }
+    async produce(sessionId, input) {
+        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;
+            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) => typeof s === 'string' && s.trim() !== '').slice(0, 5)
+                : [];
+            const queryBuild = { 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;
+            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 = [];
+            const picked = new Set();
+            for (const pick of rawPicks) {
+                if (pick === null || typeof pick !== 'object')
+                    continue;
+                const slug = pick.slug;
+                const why = pick.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, turnId) {
+        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/lib/retrieval.d.ts

@@ -17,6 +17,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 {
     threshold: number;
@@ -27,13 +29,27 @@ 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 declare const DEFAULT_RETRIEVAL: RetrievalConfig;
+/** Trigger hits outrank every other lexical field (pi-llm-wiki: highest weight). */
+export declare 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 {
     hits: SearchHit[];
@@ -50,12 +66,28 @@ 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. */
 export declare function scoreTopic(queryTokens: ReadonlySet<string>, topic: RetrievableTopic, cfg: RetrievalConfig): ScoredTopic;
+/** Structural gate v0 verdict: strong-field hit, or ≥2 distinct body terms. */
+export declare function passesGate(s: {
+    strong: boolean;
+    bodyHits: number;
+}): boolean;
 /**
- * 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 declare function searchTopics(query: string, roster: readonly RetrievableTopic[], cfg?: Partial<RetrievalConfig>): SearchOutcome;