@aiwayds/dsh-topics-memory 0.6.0 → 0.7.0

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[];

package/lib/service.js

@@ -9,8 +9,8 @@ import { readFile, stat } from 'node:fs/promises';
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import * as okf from "./okf.js";
-import { searchTopics, tokenize } from "./retrieval.js";
-import { assembleInjection } from "./digest.js";
+import { searchTopics, scoreTopic, passesGate, tokenize } from "./retrieval.js";
+import { assembleInjection, assemblePointer, POINTER_PER_TOPIC, POINTER_TOTAL } from "./digest.js";
 import { aggregateStats, querySample } from "./ilog.js";
 import { fileHistory, fileAtRev } from "./git.js";
 export class TopicsService {
@@ -70,6 +70,7 @@ export class TopicsService {
                 description: doc.fm.description,
                 status: doc.fm.status,
                 tags: doc.fm.tags,
+                triggers: doc.fm.triggers,
                 depends: doc.fm.depends,
                 links: okf.bodyLinkSlugs(doc.body),
                 generatedAt: doc.fm.generated.at,
@@ -116,10 +117,12 @@ export class TopicsService {
             if (doc !== undefined)
                 entries.push({ slug: hit.slug, doc, hit });
         }
-        const injection = assembleInjection(entries, {
-            perTopicBudget: cfg.perTopicBudget,
-            totalBudget: cfg.totalBudget,
-        });
+        const injection = cfg.injectMode !== 'digest'
+            ? assemblePointer(entries, { perTopicBudget: POINTER_PER_TOPIC, totalBudget: Math.min(cfg.totalBudget, POINTER_TOTAL) })
+            : assembleInjection(entries, {
+                perTopicBudget: cfg.perTopicBudget,
+                totalBudget: cfg.totalBudget,
+            });
         const record = {
             at: new Date().toISOString(),
             queryTokenCount: tokenize(query).length,
@@ -146,18 +149,52 @@ export 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, sessionId, dedup) {
+    retrieveSync(query, sessionId, dedup, slow, slowExpired) {
         const cfg = this.cfg;
         const roster = this.rosterSync();
         const empty = { hits: [], nearMisses: [], rosterSize: roster.length };
         if (!cfg.autoInject || query.trim() === '' || roster.length === 0) {
-            return { text: '', outcome: empty, deduped: [], included: [] };
+            // A consumed/expired pending must always leave an ilog trace (ADR 0014:
+            // 过期/消费都写 ilog) — even when the fast path early-returns here
+            // because the roster vanished between production and consumption.
+            if (cfg.autoInject && query.trim() !== '' && (slow !== undefined || slowExpired !== undefined)) {
+                const trace = {
+                    at: new Date().toISOString(),
+                    queryTokenCount: tokenize(query).length,
+                    querySample: querySample(query),
+                    rosterSize: roster.length,
+                    hits: [],
+                    nearMisses: [],
+                    injected: false,
+                    why: slowExpired !== undefined ? `slow-expired-${slowExpired}` : 'slow-no-roster',
+                    lane: 'slow',
+                };
+                if (sessionId !== undefined)
+                    trace.sessionId = sessionId;
+                if (slowExpired !== undefined)
+                    trace.slowExpired = slowExpired;
+                if (slow !== undefined) {
+                    trace.computedAt = slow.computedAt;
+                    trace.queryBuild = slow.queryBuild;
+                    trace.slowModel = slow.model;
+                    trace.slowMs = slow.ms;
+                    trace.slow = [];
+                }
+                void this.store.appendInjectionRecord(trace).catch(() => undefined);
+            }
+            return { text: '', outcome: empty, deduped: [], included: [], slowIncluded: [] };
         }
         const conflicts = this.store.getConflictsSync();
         const outcome = searchTopics(query, roster, {
@@ -170,25 +207,81 @@ export class TopicsService {
         });
         const exclude = dedup?.exclude;
         const deduped = exclude === undefined ? [] : outcome.hits.filter((h) => exclude.has(h.slug)).map((h) => h.slug);
+        const bySlug = new Map(roster.map((r) => [r.slug, r]));
         const entries = [];
+        const unreadable = [];
         for (const hit of outcome.hits) {
             if (exclude?.has(hit.slug))
                 continue;
             const doc = this.readDocSync(hit.slug);
-            if (doc !== undefined)
-                entries.push({ slug: hit.slug, doc, hit });
+            if (doc === undefined) {
+                // The hit has no readable doc — without this accounting it used to
+                // vanish from `included` AND `dropped` (v4 design §2 疑点).
+                unreadable.push(hit.slug);
+                continue;
+            }
+            entries.push({ slug: hit.slug, doc, hit });
+        }
+        // ---- Slow-lane merge (log-only shadow gate; consumption bookkeeping) ----
+        const slowPointers = [];
+        const slowDelivered = [];
+        const shadow = [];
+        let slowIncluded = [];
+        const consumedAt = new Date().toISOString();
+        if (slow !== undefined) {
+            const queryTokens = new Set(tokenize(query));
+            for (const item of slow.items) {
+                if (exclude?.has(item.slug)) {
+                    if (!deduped.includes(item.slug))
+                        deduped.push(item.slug);
+                    continue;
+                }
+                const meta = bySlug.get(item.slug);
+                if (meta === undefined)
+                    continue; // vanished between production and consumption
+                const verdict = scoreTopic(queryTokens, meta, {
+                    threshold: cfg.matchThreshold,
+                    topK: cfg.topK,
+                    tagBoost: cfg.tagBoost,
+                    graphDepth: cfg.graphDepth,
+                    recencyWindowDays: cfg.recencyWindowDays,
+                    conflicts,
+                    structuralGate: true,
+                });
+                shadow.push({
+                    slug: item.slug,
+                    pass: passesGate(verdict),
+                    why: verdict.strong ? `strong:${verdict.reasons[0] ?? 'field'}` : `body-hits:${verdict.bodyHits}`,
+                });
+                slowPointers.push({
+                    slug: item.slug,
+                    title: meta.title,
+                    status: meta.status,
+                    description: meta.description,
+                    why: item.why,
+                });
+            }
+        }
+        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);
+        slowIncluded = injection.slowIncluded ?? [];
+        for (const pointer of slowPointers) {
+            if (slowIncluded.includes(pointer.slug))
+                slowDelivered.push({ slug: pointer.slug, why: pointer.why });
         }
-        const injection = assembleInjection(entries, {
-            perTopicBudget: cfg.perTopicBudget,
-            totalBudget: cfg.totalBudget,
-        });
         const record = {
             at: new Date().toISOString(),
             queryTokenCount: tokenize(query).length,
             querySample: querySample(query),
             rosterSize: outcome.rosterSize,
-            hits: outcome.hits.map((h) => ({ slug: h.slug, score: h.score, reasons: h.reasons, viaGraph: h.viaGraph })),
-            nearMisses: outcome.nearMisses.map((h) => ({ slug: h.slug, score: h.score })),
+            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
+            // the P3 threshold decision needs (ADR 0014).
+            nearMisses: outcome.nearMisses.map((h) => ({ slug: h.slug, score: h.score, reasons: h.reasons })),
             injected: injection.text !== '',
             usedTokens: injection.usedTokens,
         };
@@ -196,14 +289,73 @@ export class TopicsService {
             record.sessionId = sessionId;
         if (deduped.length > 0)
             record.deduped = deduped;
-        if (injection.text === '' && outcome.hits.length > 0) {
+        if (unreadable.length > 0) {
+            record.dropped = [...(record.dropped ?? []), ...unreadable.map((slug) => ({ slug, reason: 'doc-unreadable' }))];
+        }
+        if (slow !== undefined) {
+            // 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
+            // round beside fast pointers stays 'fast'; everything else 'slow').
+            record.lane = slowDelivered.length > 0 ? (injection.included.length > 0 ? 'mixed' : 'slow') : injection.included.length > 0 ? 'fast' : 'slow';
+            record.computedAt = slow.computedAt;
+            record.consumedAt = consumedAt;
+            if (shadow.length > 0)
+                record.shadowVerdict = shadow;
+            record.queryBuild = slow.queryBuild;
+            record.slowModel = slow.model;
+            record.slowMs = slow.ms;
+            record.slow = slowDelivered;
+        }
+        if (slowExpired !== undefined) {
+            // Expiry is recorded INDEPENDENT of whether the fast lane injected —
+            // the 赶上率 denominator must not lose rounds to a coincidental hit.
+            record.slowExpired = slowExpired;
+            if (record.lane === undefined)
+                record.lane = injection.text !== '' ? 'fast' : 'slow';
+        }
+        if (injection.text === '' && (outcome.hits.length > 0 || slowPointers.length > 0)) {
             // All hits deduped is a different story than a budget squeeze — say so.
-            record.why = deduped.length === outcome.hits.length ? 'dedup' : 'below-budget-or-dropped';
+            record.why = deduped.length === outcome.hits.length && outcome.hits.length > 0 ? 'dedup' : 'below-budget-or-dropped';
+        }
+        else if (injection.text === '' && slowExpired !== undefined) {
+            // The pending died at its hard bounds (TTL / turn-lag) without ever
+            // being delivered — the denominator the 赶上率 needs (v4 B4).
+            record.why = `slow-expired-${slowExpired}`;
         }
+        if (slowExpired !== undefined && injection.text === '')
+            record.lane = 'slow';
         if (injection.dropped.length > 0)
-            record.dropped = injection.dropped;
+            record.dropped = [...(record.dropped ?? []), ...injection.dropped];
         void this.store.appendInjectionRecord(record).catch(() => undefined);
-        return { text: injection.text, outcome, deduped, included: injection.included };
+        return { text: injection.text, outcome, deduped, included: injection.included, slowIncluded };
+    }
+    /**
+     * 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.
+     */
+    async openTopic(slug, sessionId) {
+        const doc = 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.
+        await this.store
+            .appendOpenRecord({ slug, at: new Date().toISOString(), ...(sessionId !== undefined ? { sessionId } : {}) })
+            .catch(() => undefined);
+        return {
+            found: true,
+            slug,
+            title: doc.fm.title,
+            status: doc.fm.status,
+            updatedAt: doc.fm.generated.at,
+            description: doc.fm.description,
+            conclusion: okf.sectionOf(doc.body, okf.CONCLUSION_HEADING) ?? '',
+            openQuestions: doc.fm.open_questions,
+            recommendations: okf.sectionOf(doc.body, okf.RECOMMENDATIONS_HEADING) ?? '',
+        };
     }
     /** Sync roster read (same mtime cache as roster()). */
     rosterSync() {
@@ -248,6 +400,7 @@ export class TopicsService {
                 description: doc.fm.description,
                 status: doc.fm.status,
                 tags: doc.fm.tags,
+                triggers: doc.fm.triggers,
                 depends: doc.fm.depends,
                 links: okf.bodyLinkSlugs(doc.body),
                 generatedAt: doc.fm.generated.at,
@@ -301,6 +454,11 @@ export class TopicsService {
         };
         if (input.description !== undefined && input.description !== '')
             fm.description = input.description;
+        // Triggers pass through on create; on update the caller's value wins, else
+        // the stored list survives (same preserve-on-update semantics as tags).
+        const triggers = sanitizeTriggers(input.triggers ?? existing?.fm.triggers ?? []);
+        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 } }, { message: existing === undefined ? `topics(topic): create ${slug}` : `topics(topic): update ${slug}`, created: existing === undefined });
@@ -319,6 +477,9 @@ export class TopicsService {
             tagBoost: cfg.tagBoost,
             graphDepth: cfg.graphDepth,
             recencyWindowDays: cfg.recencyWindowDays,
+            // Explicit tool: the model asked for recall, so the injection-only
+            // structural gate must not hide results.
+            structuralGate: false,
             conflicts: await this.store.getConflicts(),
         });
     }
@@ -373,3 +534,15 @@ function dedupeLower(tags) {
     }
     return out;
 }
+function sanitizeTriggers(triggers) {
+    const out = [];
+    for (const t of triggers) {
+        if (typeof t !== 'string')
+            continue;
+        const key = t.trim();
+        if (key === '')
+            continue;
+        out.push(key);
+    }
+    return out;
+}

package/lib/store.d.ts

@@ -135,6 +135,19 @@ export declare class BundleStore {
     appendInjectionRecord(record: unknown): Promise<void>;
     private compactInjectionsIfNeeded;
     readInjectionRecords(limit?: number): Promise<InjectionRecord[]>;
+    private opensPath;
+    appendOpenRecord(record: {
+        slug: string;
+        at: string;
+        sessionId?: string;
+    }): Promise<void>;
+    private compactOpensIfNeeded;
+    /** Opens in the recent window; tolerant of a torn tail like the other JSONLs. */
+    readOpenRecords(limit?: number): Promise<{
+        slug: string;
+        at: string;
+        sessionId?: string;
+    }[]>;
     getConflicts(): Promise<Set<string>>;
     /** Sync variant for the injection hot path. */
     getConflictsSync(): Set<string>;

package/lib/store.js

@@ -425,6 +425,60 @@ export class BundleStore {
         return out.slice(-limit);
     }
     // ------------------------------------------------------------------
+    // Pointer-open log (v4 §4.3) — one line per topic_open call; feeds the
+    // 「指针打开率」 stat. Features only (slug/time), never conversation text.
+    // ------------------------------------------------------------------
+    opensPath() {
+        return join(this.metaDir(), 'opens.jsonl');
+    }
+    async appendOpenRecord(record) {
+        await mkdir(this.metaDir(), { recursive: true });
+        await appendFile(this.opensPath(), `${JSON.stringify(record)}\n`, 'utf8');
+        await this.compactOpensIfNeeded();
+    }
+    async compactOpensIfNeeded() {
+        const file = this.opensPath();
+        let size = 0;
+        try {
+            size = (await readFile(file, 'utf8')).length;
+        }
+        catch {
+            return;
+        }
+        if (size <= 512 * 1024)
+            return;
+        const lines = (await readFile(file, 'utf8')).split('\n').filter((l) => l.trim() !== '');
+        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) {
+        let raw;
+        try {
+            raw = await readFile(this.opensPath(), 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const line of raw.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                if (typeof parsed.slug === 'string' && typeof parsed.at === 'string') {
+                    const rec = { slug: parsed.slug, at: parsed.at };
+                    if (typeof parsed.sessionId === 'string')
+                        rec.sessionId = parsed.sessionId;
+                    out.push(rec);
+                }
+            }
+            catch {
+                // Torn tail line tolerated.
+            }
+        }
+        return out.slice(-limit);
+    }
+    // ------------------------------------------------------------------
     // Conflicted topics (ADR 0003) — retrieval demotes these
     // ------------------------------------------------------------------
     async getConflicts() {