@aiwayds/dsh-topics-memory 0.6.0 → 0.8.0

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;

package/lib/retrieval.js

@@ -18,7 +18,10 @@ export const DEFAULT_RETRIEVAL = {
     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;
 const CJK_RUN = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]+/gu;
 const WORD_RUN = /[\p{Script=Latin}\p{Script=Greek}\p{Script=Cyrillic}\p{Nd}][\p{Script=Latin}\p{Script=Greek}\p{Script=Cyrillic}\p{Nd}+#.-]*/gu;
 /**
@@ -60,20 +63,34 @@ function overlap(a, b) {
 export function scoreTopic(queryTokens, topic, cfg) {
     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 = [];
     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) {
@@ -85,26 +102,29 @@ export function scoreTopic(queryTokens, topic, cfg) {
         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');
             }
         }
@@ -113,12 +133,36 @@ export function scoreTopic(queryTokens, topic, cfg) {
         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) {
+    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, roster, cfg = {}) {
     const c = { ...DEFAULT_RETRIEVAL, ...cfg };
@@ -127,9 +171,17 @@ export function searchTopics(query, roster, cfg = {}) {
         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 hits = direct.map((s) => ({ ...s, viaGraph: false }));
+    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 = directHits.map((s) => ({ ...s, viaGraph: false }));
+    const nearMisses = [
+        ...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.
@@ -153,7 +205,9 @@ export function searchTopics(query, roster, cfg = {}) {
             }
         }
         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 = [];
             for (const node of frontier) {
@@ -174,5 +228,5 @@ export function searchTopics(query, roster, cfg = {}) {
             frontier = next;
         }
     }
-    return { hits, nearMisses: near.map((s) => ({ ...s, viaGraph: false })), rosterSize: roster.length };
+    return { hits, nearMisses, rosterSize: roster.length };
 }

package/lib/service.d.ts

@@ -10,7 +10,7 @@ import { type RetrievableTopic, type SearchOutcome } from './retrieval.ts';
 import { type AssembleResult } from './digest.ts';
 import type { BundleStore, Observation, SaveResult } from './store.ts';
 import type { TopicsConfigValue } from './config.ts';
-import { type AggregateStats } from './ilog.ts';
+import { type AggregateStats, type QueryBuildShape } from './ilog.ts';
 import type { Sync } from './sync.ts';
 export interface RetrieveOutcome {
     outcome: SearchOutcome;
@@ -18,6 +18,22 @@ export interface RetrieveOutcome {
     /** Roster was empty or injection disabled — no record written for pure no-ops. */
     recorded: boolean;
 }
+/**
+ * Slow-lane payload handed to the hot path at consumption time (v4 §4.2).
+ * `items` are the rerank picks (0-2, why lines included); metadata feeds the
+ * ilog lane field family. The hot path resolves titles, filters dedup,
+ * renders, and takes the log-only shadow verdicts.
+ */
+export interface SlowDelivery {
+    items: readonly {
+        slug: string;
+        why: string;
+    }[];
+    computedAt: string;
+    queryBuild: QueryBuildShape;
+    model: string;
+    ms: number;
+}
 export declare class TopicsService {
     private cache;
     readonly store: BundleStore;
@@ -43,20 +59,44 @@ export declare class TopicsService {
      * would always lose the race and inject nothing. Reads files with sync fs
      * behind the mtime cache; the log record is written fire-and-forget.
      *
-     * `dedup.exclude` (session-level injection dedup) filters hits AFTER
-     * retrieval and BEFORE assembly: excluded slugs are reported back as
-     * `deduped` (and logged as `record.deduped`), never packed. `included`
-     * mirrors what actually entered the context — only these may be marked
-     * as injected by the caller; budget-dropped slugs stay injectable later.
+     * `dedup.exclude` (session-level injection dedup) filters hits AND slow
+     * picks before assembly; excluded slugs are reported back as `deduped`
+     * (and logged as `record.deduped`), never packed. `included` mirrors the
+     * fast pointers that entered the context and `slowIncluded` the slow ones
+     * — only these may be marked as injected by the caller; budget-dropped
+     * slugs stay injectable later.
+     *
+     * `slow` (v4 §4.2) carries the consumed pending when one exists: picks are
+     * packed after the fast pointers under the same budget, take log-only
+     * shadow re-gate verdicts against the CURRENT query (B3: record, never
+     * block), and fill the record's lane field family.
      */
     retrieveSync(query: string, sessionId?: string, dedup?: {
         exclude?: ReadonlySet<string>;
-    }): {
+    }, slow?: SlowDelivery, slowExpired?: 'ttl' | 'turn-lag'): {
         text: string;
         outcome: SearchOutcome;
         deduped: string[];
         included: string[];
+        slowIncluded: string[];
     };
+    /**
+     * topic_open tool path (v4 §4.1): full conclusion / open questions /
+     * recommendations plus the staleness notice timestamp (fm.generated.at —
+     * the store stamps it on every write, so it IS the last-updated instant).
+     * Logs an open record for the pointer-open-rate stat.
+     */
+    openTopic(slug: string, sessionId?: string): Promise<{
+        found: boolean;
+        slug: string;
+        title?: string;
+        status?: okf.TopicStatus;
+        updatedAt?: string;
+        description?: string;
+        conclusion?: string;
+        openQuestions?: string[];
+        recommendations?: string;
+    }>;
     /** Sync roster read (same mtime cache as roster()). */
     rosterSync(): RetrievableTopic[];
     private readDocSync;
@@ -66,6 +106,7 @@ export declare class TopicsService {
         title: string;
         description?: string;
         tags?: string[];
+        triggers?: string[];
         depends?: string[];
         openQuestions?: string[];
         impact?: string[];