@aiwayds/dsh-topics-memory 0.20.0 → 0.22.0

package/README.md

@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 A dsh plugin: maintains "working topic memory" as an [OKF (Open Knowledge Format v0.2)](https://github.com/GoogleCloudPlatform/open-knowledge-format) knowledge bundle, persisted in a local git repository (optionally synced to a private GitHub repo), with conclusions traceable through git history, sessions automatically observed and distilled into knowledge, and relevant topics injected to the model before every turn.
 
-> **Requires dsh >= 0.1.7-rc.1** — this plugin targets the dsh RC/stable line only (CI and releases resolve the newest of the `latest`/`next` dist-tags at runtime). **The alpha line is no longer supported.**
+> **Requires dsh >= 0.2.0-rc.2** — this plugin targets the dsh RC/stable line only (CI and releases resolve the newest of the `latest`/`next` dist-tags at runtime). **The alpha line is no longer supported.**
 
 ## Demo
 
@@ -201,6 +201,7 @@ First-time setup belongs to `/topics onboard`; day-to-day tuning is `/topics set
 | `consolidateCadence` | `daily` | Consolidation-lane cadence: `daily`/`3d`/`7d`/`off`. At session start the plugin checks the last consolidation time (`meta/consolidate-state.json`) and, when due, runs the LLM gardener in the background (reusing the distill model route): local lexical clustering only feeds near-look-alike candidate clusters; four op kinds merge/promote/deprecate/refresh, out-of-scope ops are dropped; a failed call never advances the stamp, so the next start retries |
 | `deprecatedTtlDays` | `15` | Deprecated topics older than N days are dropped at session start (local rule, no model; each drop is its own git commit — history stays recoverable); `0` disables the sweep |
 | `usageBoost` | `0.15` | Usage boost (ADR 0015): topics injected/opened in the last 30 days score higher at retrieval (gate-scoped, capped at 0.2, never granted to zero-lexical candidates, structural gate not waived); `0` disables |
+| `zeroOpenDecay` | `false` | Zero-open decay: halve the retrieval score of zero-open high-frequency slugs before the threshold cut (see the section below) |
 | `pushDebounceSeconds` | `45` | GitHub-mode debounced push interval |
 | `jevEnabled` | `false` | System One decision layer master switch (experimental): `false` = zero behavior change — see the Jev decision layer section above |
 | `jevBackend` | `zen` | Decision endpoint: `zen` (free) / `native` / `openrouter` |
@@ -210,6 +211,10 @@ First-time setup belongs to `/topics onboard`; day-to-day tuning is `/topics set
 | `jevLayaFallback` | `false` | Local laya pace-maker: fire a parallel laya call on every jev request; its answer takes over (degraded, relative-ranking only) when the primary fails |
 | `jevLayaUrl` | `http://127.0.0.1:8000/v1/systemone` | laya-serve endpoint for the pace-maker |
 
+### Zero-open decay (default off)
+
+`zeroOpenDecay: true` halves the hit score of slugs the stats panel lists as 零打开高频 — truly rendered ≥5 injections in the rolling 30 days with zero `topic_open` events ever. The decay applies at score finalization, before the match threshold, so a decayed candidate that drops below it lands in nearMisses carrying the `zero-open-decay` reason — the injection log shows why it stopped ranking. Motivation: 24 high-frequency topics held the injection leaderboard with zero opens while score and opens proved only weakly correlated (the 0.3 threshold stays untouched). Default `false` means zero behavior change; unreadable injection/open logs skip the decay (fail-open). Toggle live with `/topics set zero-open-decay on|off`.
+
 ## Acknowledgements
 
 This project's shape is directly inspired and supported by:

package/README.zh.md

@@ -4,7 +4,7 @@
 
 一个 dsh 插件：把「工作 topic 记忆」维护成 [OKF 标准（Open Knowledge Format v0.2）](https://github.com/GoogleCloudPlatform/open-knowledge-format)的知识 bundle，持久化在本地 git 仓库（可选同步到 GitHub 私有仓库），利用 git 历史提供结论可追溯性，自动观察会话沉淀知识，并在每轮对话前向模型注入相关 Topic。
 
-> **要求 dsh >= 0.1.7-rc.1** — 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。**不再支持 alpha 线。**
+> **要求 dsh >= 0.2.0-rc.2** — 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。**不再支持 alpha 线。**
 
 ## 演示
 
@@ -187,6 +187,7 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 | `consolidateCadence` | `daily` | 整理 lane 节拍：`daily`/`3d`/`7d`/`off`。会话启动时检查上次整理时间（`meta/consolidate-state.json`），到期即在后台自动跑 LLM 园丁（复用蒸馏模型路由）：本地词面聚类只送「长得像」的候选簇，四类动作 merge/promote/deprecate/refresh，越权 op 一律丢弃；模型调用失败不推进节拍，下次启动重试 |
 | `deprecatedTtlDays` | `15` | deprecated 条目超过 N 天在会话启动时自动删除（本地规则不依赖模型，逐条 git commit 可回溯找回）；`0` 关闭清扫 |
 | `usageBoost` | `0.15` | 使用加成（ADR 0015）：近 30 天被注入命中/点开过的 Topic 检索加分（计入门槛分、帽 0.2、零词面相关不加、结构门不豁免）；`0` 关闭 |
+| `zeroOpenDecay` | `false` | 零打开衰减：零打开高频 slug 的命中分在阈值裁剪前减半（见下方小节） |
 | `pushDebounceSeconds` | `45` | GitHub 模式去抖推送间隔 |
 | `jevEnabled` | `false` | System One 决策层总开关（实验）：`false` = 零行为变化——见上方「Jev 决策层」一节 |
 | `jevBackend` | `zen` | 决策端点：`zen`（免费）/ `native` / `openrouter` |
@@ -197,6 +198,10 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 | `jevLayaUrl` | `http://127.0.0.1:8000/v1/systemone` | 陪跑用的 laya-serve 端点 |
 | `jevDebug` | 关 | 诊断日志开关（走宿主 logger，默认静默） |
 
+### 零打开衰减（默认关）
+
+`zeroOpenDecay: true` 时，命中分在 matchThreshold 裁剪前乘 0.5：滚动 30 天内被真正注入 ≥5 次、且 opens.jsonl 全期 0 次打开的 slug（即 `/topics stats` 的「零打开高频」清单——stats 面板与打分衰减共用同一条共享规则）不再霸榜；跌破阈值的候选自然落入 nearMisses 并带 `zero-open-decay` 标签，注入日志可见原因。动机：24 个「注入 ≥5 次、0 打开」的高频话题长期霸榜，而 score 与打开仅弱相关（阈值 0.3 不动）。默认 `false` 零行为变化；injections/opens 读取失败跳过衰减（fail-open）；`/topics set zero-open-decay on|off` 运行时切换。
+
 ### laya 本地陪跑（实验，默认关）
 
 `jevLayaFallback: true` 且本地跑着 [laya](https://github.com/NandhaKishorM/laya) serve 时，每次 jev 调用并发一路本地 laya 请求：主路答案驱动决策，laya 答案并排落账——一组永久运行的 laya vs jev 同题对照。laya 是**纯遥测**（真实负载实测批内排序与主路一致率 0/14、绝对分不可用），主路失败照旧回退旧路径；laya 没起 = 毫秒级连接拒绝。

package/lib/commands.js

@@ -12,7 +12,7 @@ import { serializeTopicDoc, slugify, firstParagraph } from "./okf.js";
 import { buildGraph, renderGraphHtml } from "./viz.js";
 import { CONFIG_KEYS, displayKey, parseConfigValue } from "./config.js";
 import { reloadSecrets } from "./jev/gate.js";
-import { aggregateStats } from "./ilog.js";
+import { aggregateStats, aggregateOpenPanel, ZERO_OPEN_MIN_INJECTIONS } from "./ilog.js";
 import { askDistillSingle, createOnboardHandler, llmDirectoryNotice, makePanel, parseDistillInput, pickLlmDirectory, } from "./onboard.js";
 export const HELP = [
     'dsh-topics-memory — OKF topic 记忆（本地 bundle，git 可追溯，可选 GitHub 同步）',
@@ -20,7 +20,7 @@ export const HELP = [
     '  /topics status              bundle 健康：topic 数、观察积压、冲突、同步状态',
     '  /topics distill             手动触发一次蒸馏（观察池 → Topic，输出 marked/created/updated/gc 摘要）',
     '  /topics consolidate         手动触发一次整理（合并重复/晋升 stable/废弃过时/刷新元数据，无视 cadence 立即跑）',
-    '  /topics stats               注入统计：hit rate、top-N、near-miss 分布与调参建议',
+    '  /topics stats               注入统计：hit rate、open rate、注入 vs 打开、near-miss 分布与调参建议',
     '  /topics list                列出全部 Topic',
     '  /topics show <slug>         查看一个 Topic 全文（含反向引用）',
     '  /topics history <slug>      一个 Topic 的结论变更史（git log）',
@@ -277,16 +277,14 @@ async function renderStats(service) {
         }
         lines.push(`| 慢道参与轮 | ${slowRounds}（快 ${records.length - slowRounds} / 慢或混合 ${slowRounds}${medianLag}） |`);
     }
-    // Pointer open rate (v4 §4.3): topic_open calls vs pointer entries injected.
-    // Echoed hits ride the retrieval but never became pointers — excluded here.
+    // Injection-vs-open metrics (v5): the denominator counts only pointers
+    // that truly rendered (deduped/echoed/dropped all excluded, slow pointers
+    // included) and the numerator only counts DISTINCT slugs from that
+    // rendered set opened inside the injection window — search opens and
+    // never-rendered slugs cannot inflate the rate.
     const opens = await service.store.readOpenRecords();
-    if (opens.length > 0 || records.some((r) => r.lane !== undefined)) {
-        const entries = records.reduce((acc, r) => acc +
-            r.hits.filter((h) => !(r.deduped ?? []).includes(h.slug) && !(r.echoed ?? []).includes(h.slug)).length +
-            (r.slow?.length ?? 0), 0);
-        const rate = entries === 0 ? 0 : Math.min(1, opens.length / entries);
-        lines.push(`| 指针打开率 | ${(rate * 100).toFixed(1)}%（${opens.length} 次 topic_open / ${entries} 条注入指针） |`);
-    }
+    const panel = aggregateOpenPanel(records, opens);
+    lines.push(`| open rate | ${(panel.openRate * 100).toFixed(1)}%（${panel.opensInWindow} 个被打开指针 / ${panel.pointerEntries} 条注入指针） |`);
     const echoedCount = records.reduce((acc, r) => acc + (r.echoed?.length ?? 0), 0);
     if (echoedCount > 0) {
         lines.push(`| 回声抑制 | ${echoedCount} 次（本会话蒸馏出的 topic 不回注） |`);
@@ -296,6 +294,24 @@ async function renderStats(service) {
         for (const t of stats.topTopics.slice(0, 5))
             lines.push(`| \`${cell(t.slug)}\` | ${t.count} |`);
     }
+    // ---- 注入 vs 打开 panel ----
+    // Per-topic cut: what the header's windowed rate cannot show — which
+    // topics the model actually bothers to open (wide-scope slug attribution).
+    if (panel.topics.length > 0) {
+        lines.push('', '注入 vs 打开（Top-10，注入=真正渲染的指针；打开按 slug 归因，全窗口）：', '', '| Topic | 注入 | 打开 | 打开率 |', '| --- | --- | --- | --- |', ...panel.topics.map((t) => `| \`${cell(t.slug)}\` | ${t.injections} | ${t.opens} | ${(t.openRate * 100).toFixed(1)}% |`));
+    }
+    if (panel.zeroOpenTotal > 0) {
+        const shown = panel.zeroOpen.map((z) => `\`${cell(z.slug)}\``).join('、');
+        const more = panel.zeroOpenTotal > panel.zeroOpen.length ? `（共 ${panel.zeroOpenTotal} 个）` : '';
+        lines.push('', `零打开高频（注入 ≥${ZERO_OPEN_MIN_INJECTIONS}、打开 0）：${shown}${more}`);
+    }
+    lines.push('', panel.hasSourceData ? `打开来源：pointer ${panel.pointerOpens} / search ${panel.searchOpens}` : '打开来源：暂无来源数据（需新版本 open 记录）');
+    if (panel.pointerEntries > 0) {
+        lines.push('', '| 分桶 | 指针 | 打开率 |', '| --- | --- | --- |');
+        for (const b of panel.bands) {
+            lines.push(`| ${b.label} | ${b.pointers} | ${b.pointers === 0 ? '—' : `${(b.openRate * 100).toFixed(1)}%`} |`);
+        }
+    }
     if (stats.nearMissHistogram.length > 0) {
         lines.push('', `Near-miss 分布（低于阈值 ${service.cfg.matchThreshold.toFixed(2)} 或被结构门挡下，对数刻度）：`, '', '```', ...renderNearMissSparkline(stats.nearMissHistogram), '```');
         const hint = tuningHint(stats, service.cfg.matchThreshold);

package/lib/config.d.ts

@@ -70,6 +70,12 @@ export declare const TopicsConfig: z<Schemastery.ObjectS<NoInfer<{
      *  granted to zero-lexical candidates; the structural gate still applies.
      *  0 = off. */
     usageBoost: z<number, number, "volatile-defined">;
+    /** Zero-open decay (v5, default off): halve the retrieval score of slugs
+     *  injected ≥5 times in the rolling 30 days with zero opens ever — the
+     *  零打开高频 leaderboard stops out-ranking topics the model actually
+     *  reads. false = zero behavior change; the reason tag `zero-open-decay`
+     *  rides the hit/near-miss reasons when on. */
+    zeroOpenDecay: z<boolean, boolean, "volatile-defined">;
     /** Debounced push delay in GitHub mode. */
     pushDebounceSeconds: z<number, number, "volatile-defined">;
     /** System One decision-model integration (design 2026-09-25), default-off
@@ -162,6 +168,12 @@ export declare const TopicsConfig: z<Schemastery.ObjectS<NoInfer<{
      *  granted to zero-lexical candidates; the structural gate still applies.
      *  0 = off. */
     usageBoost: z<number, number, "volatile-defined">;
+    /** Zero-open decay (v5, default off): halve the retrieval score of slugs
+     *  injected ≥5 times in the rolling 30 days with zero opens ever — the
+     *  零打开高频 leaderboard stops out-ranking topics the model actually
+     *  reads. false = zero behavior change; the reason tag `zero-open-decay`
+     *  rides the hit/near-miss reasons when on. */
+    zeroOpenDecay: z<boolean, boolean, "volatile-defined">;
     /** Debounced push delay in GitHub mode. */
     pushDebounceSeconds: z<number, number, "volatile-defined">;
     /** System One decision-model integration (design 2026-09-25), default-off
@@ -216,6 +228,10 @@ export type TopicsConfigValue = {
     consolidateCadence: string;
     deprecatedTtlDays: number;
     usageBoost: number;
+    /** Zero-open decay (v5). Optional in this TS view only (same sentinel
+     *  pattern as the jev keys): bare-harness DEFAULTS predates it —
+     *  consumers must treat undefined as the documented default (false). */
+    zeroOpenDecay?: boolean;
     pushDebounceSeconds: number;
     /** System One integration keys (design 2026-09-25 §4). Optional in this TS
      *  view only: index.ts's bare-harness DEFAULTS literal predates them and
@@ -229,7 +245,7 @@ export type TopicsConfigValue = {
     jevLayaFallback?: boolean;
     jevLayaUrl?: string;
 };
-export declare const CONFIG_KEYS: readonly ["repo", "autoInject", "injectDedup", "suppressEcho", "topK", "perTopicBudget", "totalBudget", "matchThreshold", "tagBoost", "injectMode", "qualityLane", "graphDepth", "recencyWindowDays", "autoObserve", "includeSubagents", "observationMaxChars", "distillEveryTurns", "distillOnSessionEnd", "distillProvider", "distillModel", "distillBatchSize", "distillMaxModelCalls", "consolidateCadence", "deprecatedTtlDays", "usageBoost", "pushDebounceSeconds", "jevEnabled", "jevBackend", "jevModel", "jevTimeoutMs", "jevSecretFile", "jevLayaFallback", "jevLayaUrl"];
+export declare const CONFIG_KEYS: readonly ["repo", "autoInject", "injectDedup", "suppressEcho", "topK", "perTopicBudget", "totalBudget", "matchThreshold", "tagBoost", "injectMode", "qualityLane", "graphDepth", "recencyWindowDays", "autoObserve", "includeSubagents", "observationMaxChars", "distillEveryTurns", "distillOnSessionEnd", "distillProvider", "distillModel", "distillBatchSize", "distillMaxModelCalls", "consolidateCadence", "deprecatedTtlDays", "usageBoost", "zeroOpenDecay", "pushDebounceSeconds", "jevEnabled", "jevBackend", "jevModel", "jevTimeoutMs", "jevSecretFile", "jevLayaFallback", "jevLayaUrl"];
 export type ConfigKey = (typeof CONFIG_KEYS)[number];
 /** CamelCase → dash-display (topK → top-k) for command output. */
 export declare function displayKey(key: string): string;

package/lib/config.js

@@ -70,6 +70,12 @@ export const TopicsConfig = z.object({
      *  granted to zero-lexical candidates; the structural gate still applies.
      *  0 = off. */
     usageBoost: z.number().default(0.15).volatile(),
+    /** Zero-open decay (v5, default off): halve the retrieval score of slugs
+     *  injected ≥5 times in the rolling 30 days with zero opens ever — the
+     *  零打开高频 leaderboard stops out-ranking topics the model actually
+     *  reads. false = zero behavior change; the reason tag `zero-open-decay`
+     *  rides the hit/near-miss reasons when on. */
+    zeroOpenDecay: z.boolean().default(false).volatile(),
     /** Debounced push delay in GitHub mode. */
     pushDebounceSeconds: z.number().default(45).volatile(),
     /** System One decision-model integration (design 2026-09-25), default-off
@@ -124,6 +130,7 @@ export const CONFIG_KEYS = [
     'consolidateCadence',
     'deprecatedTtlDays',
     'usageBoost',
+    'zeroOpenDecay',
     'pushDebounceSeconds',
     'jevEnabled',
     'jevBackend',
@@ -152,7 +159,8 @@ export function parseConfigValue(key, raw) {
         case 'autoObserve':
         case 'distillOnSessionEnd':
         case 'includeSubagents':
-        case 'jevEnabled': {
+        case 'jevEnabled':
+        case 'zeroOpenDecay': {
             if (raw === 'on' || raw === 'true')
                 return true;
             if (raw === 'off' || raw === 'false')

package/lib/ilog.d.ts

@@ -70,6 +70,23 @@ export interface InjectionRecord {
     /** Slow-lane pointers this round, in delivery order. */
     slow?: SlowItem[];
 }
+/**
+ * One topic_open event (pointer-open log, v4 §4.3). Everything beyond
+ * `slug`/`at` is optional and late-added: older lines carry only the
+ * original pair, and every reader must tolerate the rest being absent.
+ */
+export interface OpenRecord {
+    slug: string;
+    at: string;
+    /** Session that issued the topic_open, when the host surface exposed one. */
+    sessionId?: string;
+    /** Attribution: opened off an injected pointer, or off a topic_search hit. */
+    source?: 'pointer' | 'search';
+    /** Retrieval score of the matched injection hit (source='pointer' only). */
+    score?: number;
+    /** open time − the matched injection record's at, in ms (source='pointer' only). */
+    sinceInjectionMs?: number;
+}
 export interface AggregateStats {
     rounds: number;
     injectedRounds: number;
@@ -107,3 +124,115 @@ export declare function aggregateUsage(injections: readonly InjectionRecord[], o
     slug: string;
     at: string;
 }[], windowDays: number, now: number): Map<string, UsageSignal>;
+/** How many tail injection records the cheap open attribution scans. */
+export declare const OPEN_ATTRIBUTION_TAIL = 50;
+/** An injected pointer stays attributable for 48h (a work session's span). */
+export declare const OPEN_ATTRIBUTION_WINDOW_MS: number;
+/**
+ * Cheap source attribution for one open event: scan the injection tail
+ * (newest first) for a same-session record within the attribution window
+ * where the slug was truly delivered to the model's eyes. That is hits
+ * minus echoed/dropped (echo suppression and budget drops never rendered),
+ * PLUS slow-lane deliveries, PLUS deduped hits — dedup only blocks
+ * re-packing THIS round; the pointer rendered earlier in the same session
+ * and the model saw it (deliberately wider than renderedPointers: the panel
+ * denominator asks "did it render this round", attribution asks "did the
+ * model ever see it"). A fast-hit match carries that hit's score; a
+ * slow-only match carries none (slow pointers have no lexical score).
+ * Anything else (no session id, other session, expired, never rendered)
+ * is `search`.
+ */
+export declare function attributeOpen(injections: readonly InjectionRecord[], slug: string, sessionId: string | undefined, nowMs: number): {
+    source: 'pointer' | 'search';
+    score?: number;
+    sinceInjectionMs?: number;
+};
+/** Score bands for the open-rate-by-score cut of the stats panel. */
+export declare const SCORE_BANDS: readonly {
+    label: string;
+    lo: number;
+    hi: number;
+}[];
+/** Zero-open listing threshold: injections at or above this with zero opens. */
+export declare const ZERO_OPEN_MIN_INJECTIONS = 5;
+/** Rolling window of the zero-open rule: only rendered injections inside it count. */
+export declare const ZERO_OPEN_WINDOW_DAYS = 30;
+/** Injection-tail rows the decay read scans — a bound comfortably covering
+ *  the 30-day window at observed round volumes. */
+export declare const ZERO_OPEN_TAIL = 500;
+/**
+ * Slugs that truly rendered in one round, in delivery order: raw hits minus
+ * the round's exclusions (deduped/echoed/dropped were never assembled), plus
+ * delivered slow pointers; a slug the fast lane already delivered counts
+ * once even when the slow lane also reports it delivered ("not packed
+ * twice"). Scores ride along from the fast hit only — slow pointers carry
+ * no lexical score. Shared by the stats panel and the zero-open rule.
+ */
+export declare function renderedPointers(record: InjectionRecord): {
+    slug: string;
+    score?: number;
+}[];
+/**
+ * Zero-open slug set — the single shared 零打开高频 rule (v5): slugs whose
+ * truly-rendered pointer count within the rolling ZERO_OPEN_WINDOW_DAYS
+ * reaches ZERO_OPEN_MIN_INJECTIONS while the WHOLE open log has never
+ * recorded an open (wide scope — an open long after the last injection
+ * still disqualifies). Returns slug → windowed rendered-pointer count for
+ * the qualifying slugs; `/topics stats` (the panel's zero-open list) and
+ * the retrieval decay (`zeroOpenDecay`) both consume this one
+ * implementation. Records with unparsable `at` cannot prove window
+ * membership and are skipped (same tolerance as aggregateUsage).
+ */
+export declare function aggregateZeroOpen(injections: readonly InjectionRecord[], opens: readonly {
+    slug: string;
+}[], nowMs: number): Map<string, number>;
+export interface OpenTopicRow {
+    slug: string;
+    /** Truly rendered pointers for this slug (deduped/echoed/dropped excluded). */
+    injections: number;
+    /** Opens attributed by slug over the whole open log (wide scope, by design). */
+    opens: number;
+    openRate: number;
+}
+export interface OpenBandRow {
+    label: string;
+    /** Rendered fast pointers whose hit score falls in this band. */
+    pointers: number;
+    /** Pointer-sourced opens whose attributed score falls in this band. */
+    opens: number;
+    openRate: number;
+}
+export interface OpenPanelStats {
+    /** Rendered pointer entries across the window: hits − deduped − echoed − dropped, plus slow pointers (same-slug fast+slow pairs counted once). */
+    pointerEntries: number;
+    /** DISTINCT slugs from the window's rendered set with an in-window open
+     *  (search-sourced and never-rendered slugs excluded; one per slug). */
+    opensInWindow: number;
+    openRate: number;
+    topics: OpenTopicRow[];
+    zeroOpen: {
+        slug: string;
+        injections: number;
+    }[];
+    zeroOpenTotal: number;
+    pointerOpens: number;
+    searchOpens: number;
+    /** False when no open record carries a source field (pre-enrichment data). */
+    hasSourceData: boolean;
+    bands: OpenBandRow[];
+}
+/**
+ * Aggregate the injection-vs-open panel from the two JSONL windows. The
+ * per-topic/band denominators count only pointers that truly rendered
+ * (deduped/echoed/dropped excluded — same exclusion family as
+ * aggregateUsage); the header numerator counts only DISTINCT slugs from
+ * that rendered set with an open inside the injection window — a search
+ * open or an open of a never-rendered slug cannot enter, and repeat opens
+ * of the same slug count once, so the rate can no longer be pinned at
+ * 100% by repeated or off-scope opens. Opens per slug stay wide-scope
+ * (the model may open a topic long after its last injection). The
+ * zero-open list shares the decay's rule: rendered injections counted
+ * within the rolling 30-day window (anchored at the newest round), opens
+ * wide-scope.
+ */
+export declare function aggregateOpenPanel(injections: readonly InjectionRecord[], opens: readonly OpenRecord[]): OpenPanelStats;

package/lib/ilog.js

@@ -117,3 +117,239 @@ export function aggregateUsage(injections, opens, windowDays, now) {
     }
     return out;
 }
+// ---------------------------------------------------------------------
+// Injection-vs-open metrics (v5) — open enrichment attribution + the
+// /topics stats panel aggregate. All pure: file I/O stays in store/service.
+// ---------------------------------------------------------------------
+/** How many tail injection records the cheap open attribution scans. */
+export const OPEN_ATTRIBUTION_TAIL = 50;
+/** An injected pointer stays attributable for 48h (a work session's span). */
+export const OPEN_ATTRIBUTION_WINDOW_MS = 48 * 3_600_000;
+/**
+ * Cheap source attribution for one open event: scan the injection tail
+ * (newest first) for a same-session record within the attribution window
+ * where the slug was truly delivered to the model's eyes. That is hits
+ * minus echoed/dropped (echo suppression and budget drops never rendered),
+ * PLUS slow-lane deliveries, PLUS deduped hits — dedup only blocks
+ * re-packing THIS round; the pointer rendered earlier in the same session
+ * and the model saw it (deliberately wider than renderedPointers: the panel
+ * denominator asks "did it render this round", attribution asks "did the
+ * model ever see it"). A fast-hit match carries that hit's score; a
+ * slow-only match carries none (slow pointers have no lexical score).
+ * Anything else (no session id, other session, expired, never rendered)
+ * is `search`.
+ */
+export function attributeOpen(injections, slug, sessionId, nowMs) {
+    if (sessionId === undefined)
+        return { source: 'search' };
+    for (let i = injections.length - 1; i >= 0; i -= 1) {
+        const record = injections[i];
+        if (record.sessionId !== sessionId)
+            continue;
+        const atMs = Date.parse(record.at);
+        if (!Number.isFinite(atMs) || nowMs - atMs > OPEN_ATTRIBUTION_WINDOW_MS)
+            continue;
+        const sinceInjectionMs = Math.max(0, nowMs - atMs);
+        const suppressed = new Set([...(record.echoed ?? []), ...(record.dropped ?? []).map((d) => d.slug)]);
+        const hit = record.hits.find((h) => h.slug === slug && !suppressed.has(h.slug));
+        if (hit !== undefined)
+            return { source: 'pointer', score: hit.score, sinceInjectionMs };
+        if ((record.slow ?? []).some((s) => s.slug === slug))
+            return { source: 'pointer', sinceInjectionMs };
+    }
+    return { source: 'search' };
+}
+/** Score bands for the open-rate-by-score cut of the stats panel. */
+export const SCORE_BANDS = [
+    { label: '[0.3,0.5)', lo: 0.3, hi: 0.5 },
+    { label: '[0.5,1)', lo: 0.5, hi: 1 },
+    { label: '[1,2)', lo: 1, hi: 2 },
+    { label: '[2,5)', lo: 2, hi: 5 },
+    { label: '[5,∞)', lo: 5, hi: Number.POSITIVE_INFINITY },
+];
+/** Zero-open listing threshold: injections at or above this with zero opens. */
+export const ZERO_OPEN_MIN_INJECTIONS = 5;
+/** Rolling window of the zero-open rule: only rendered injections inside it count. */
+export const ZERO_OPEN_WINDOW_DAYS = 30;
+/** Injection-tail rows the decay read scans — a bound comfortably covering
+ *  the 30-day window at observed round volumes. */
+export const ZERO_OPEN_TAIL = 500;
+/**
+ * Slugs that truly rendered in one round, in delivery order: raw hits minus
+ * the round's exclusions (deduped/echoed/dropped were never assembled), plus
+ * delivered slow pointers; a slug the fast lane already delivered counts
+ * once even when the slow lane also reports it delivered ("not packed
+ * twice"). Scores ride along from the fast hit only — slow pointers carry
+ * no lexical score. Shared by the stats panel and the zero-open rule.
+ */
+export function renderedPointers(record) {
+    const excluded = new Set([
+        ...(record.deduped ?? []),
+        ...(record.echoed ?? []),
+        ...(record.dropped ?? []).map((d) => d.slug),
+    ]);
+    const seen = new Set();
+    const out = [];
+    for (const h of record.hits) {
+        if (excluded.has(h.slug) || seen.has(h.slug))
+            continue;
+        seen.add(h.slug);
+        out.push({ slug: h.slug, score: h.score });
+    }
+    for (const s of record.slow ?? []) {
+        if (seen.has(s.slug))
+            continue;
+        seen.add(s.slug);
+        out.push({ slug: s.slug });
+    }
+    return out;
+}
+/**
+ * Zero-open slug set — the single shared 零打开高频 rule (v5): slugs whose
+ * truly-rendered pointer count within the rolling ZERO_OPEN_WINDOW_DAYS
+ * reaches ZERO_OPEN_MIN_INJECTIONS while the WHOLE open log has never
+ * recorded an open (wide scope — an open long after the last injection
+ * still disqualifies). Returns slug → windowed rendered-pointer count for
+ * the qualifying slugs; `/topics stats` (the panel's zero-open list) and
+ * the retrieval decay (`zeroOpenDecay`) both consume this one
+ * implementation. Records with unparsable `at` cannot prove window
+ * membership and are skipped (same tolerance as aggregateUsage).
+ */
+export function aggregateZeroOpen(injections, opens, nowMs) {
+    const cutoff = nowMs - ZERO_OPEN_WINDOW_DAYS * 86_400_000;
+    const counts = new Map();
+    for (const record of injections) {
+        const at = Date.parse(record.at);
+        if (!Number.isFinite(at) || at < cutoff)
+            continue;
+        for (const p of renderedPointers(record)) {
+            counts.set(p.slug, (counts.get(p.slug) ?? 0) + 1);
+        }
+    }
+    const opened = new Set(opens.map((o) => o.slug));
+    const out = new Map();
+    for (const [slug, n] of counts) {
+        if (n >= ZERO_OPEN_MIN_INJECTIONS && !opened.has(slug))
+            out.set(slug, n);
+    }
+    return out;
+}
+/**
+ * Aggregate the injection-vs-open panel from the two JSONL windows. The
+ * per-topic/band denominators count only pointers that truly rendered
+ * (deduped/echoed/dropped excluded — same exclusion family as
+ * aggregateUsage); the header numerator counts only DISTINCT slugs from
+ * that rendered set with an open inside the injection window — a search
+ * open or an open of a never-rendered slug cannot enter, and repeat opens
+ * of the same slug count once, so the rate can no longer be pinned at
+ * 100% by repeated or off-scope opens. Opens per slug stay wide-scope
+ * (the model may open a topic long after its last injection). The
+ * zero-open list shares the decay's rule: rendered injections counted
+ * within the rolling 30-day window (anchored at the newest round), opens
+ * wide-scope.
+ */
+export function aggregateOpenPanel(injections, opens) {
+    // Numerator window: the earliest round represented in the denominator;
+    // the zero-open anchor is the newest round — the panel describes the log
+    // window it was fed, so a stale log still shows the topics that
+    // dominated it. The rendered-slug set below shares that window: only
+    // opens of slugs this window rendered can enter the numerator.
+    let windowStart = Number.POSITIVE_INFINITY;
+    let windowEnd = Number.NEGATIVE_INFINITY;
+    for (const r of injections) {
+        const atMs = Date.parse(r.at);
+        if (!Number.isFinite(atMs))
+            continue;
+        if (atMs < windowStart)
+            windowStart = atMs;
+        if (atMs > windowEnd)
+            windowEnd = atMs;
+    }
+    const topicCounts = new Map();
+    const bandPointers = new Array(SCORE_BANDS.length).fill(0);
+    let pointerEntries = 0;
+    const renderedSlugs = new Set();
+    for (const r of injections) {
+        // renderedPointers keeps the entry/per-topic counts honest: excluded
+        // slugs never counted, a fast+slow pair for the same slug counted once.
+        for (const p of renderedPointers(r)) {
+            pointerEntries += 1;
+            renderedSlugs.add(p.slug);
+            topicCounts.set(p.slug, (topicCounts.get(p.slug) ?? 0) + 1);
+            const score = p.score;
+            if (score === undefined)
+                continue;
+            const bi = SCORE_BANDS.findIndex((b) => score >= b.lo && score < b.hi);
+            if (bi >= 0)
+                bandPointers[bi] += 1;
+        }
+    }
+    const opensBySlug = new Map();
+    const bandOpens = new Array(SCORE_BANDS.length).fill(0);
+    let pointerOpens = 0;
+    let searchOpens = 0;
+    let hasSourceData = false;
+    // Numerator: DISTINCT slugs from the window's rendered set with an
+    // in-window open — search-sourced opens never count (the model found the
+    // topic by asking, not by following a rendered pointer), a never-rendered
+    // slug never counts, and repeat opens of the same slug count once.
+    const openedSlugsInWindow = new Set();
+    for (const o of opens) {
+        opensBySlug.set(o.slug, (opensBySlug.get(o.slug) ?? 0) + 1);
+        if (o.source === 'pointer' || o.source === 'search')
+            hasSourceData = true;
+        if (o.source === 'pointer')
+            pointerOpens += 1;
+        else if (o.source === 'search')
+            searchOpens += 1;
+        if (o.source === 'pointer' && typeof o.score === 'number') {
+            const score = o.score;
+            const bi = SCORE_BANDS.findIndex((b) => score >= b.lo && score < b.hi);
+            if (bi >= 0)
+                bandOpens[bi] += 1;
+        }
+        if (o.source === 'search')
+            continue;
+        const atMs = Date.parse(o.at);
+        // An open joins the windowed numerator unless it is provably older than
+        // the window's earliest round (unparsable stamps cannot prove either
+        // way) — and only when the window actually rendered its slug.
+        if (Number.isFinite(windowStart) && Number.isFinite(atMs) && atMs < windowStart)
+            continue;
+        if (!renderedSlugs.has(o.slug))
+            continue;
+        openedSlugsInWindow.add(o.slug);
+    }
+    const opensInWindow = openedSlugsInWindow.size;
+    const rate = (num, den) => (den === 0 ? 0 : Math.min(1, num / den));
+    const topics = [...topicCounts.entries()]
+        .map(([slug, injections]) => {
+        const opens = opensBySlug.get(slug) ?? 0;
+        return { slug, injections, opens, openRate: rate(opens, injections) };
+    })
+        .sort((a, b) => b.injections - a.injections || a.slug.localeCompare(b.slug));
+    // Zero-open cut: the shared 30-day rule (aggregateZeroOpen), anchored at
+    // the newest round so window semantics match the decay's rolling window
+    // without growing a time-bomb dependency on the wall clock.
+    const zeroOpenCounts = windowEnd === Number.NEGATIVE_INFINITY ? new Map() : aggregateZeroOpen(injections, opens, windowEnd);
+    const zeroOpenAll = [...zeroOpenCounts.entries()]
+        .map(([slug, injections]) => ({ slug, injections }))
+        .sort((a, b) => b.injections - a.injections || a.slug.localeCompare(b.slug));
+    return {
+        pointerEntries,
+        opensInWindow,
+        openRate: rate(opensInWindow, pointerEntries),
+        topics: topics.slice(0, 10),
+        zeroOpen: zeroOpenAll.slice(0, 10).map((t) => ({ slug: t.slug, injections: t.injections })),
+        zeroOpenTotal: zeroOpenAll.length,
+        pointerOpens,
+        searchOpens,
+        hasSourceData,
+        bands: SCORE_BANDS.map((b, i) => ({
+            label: b.label,
+            pointers: bandPointers[i],
+            opens: bandOpens[i],
+            openRate: rate(bandOpens[i], bandPointers[i]),
+        })),
+    };
+}

package/lib/index.d.ts

@@ -112,6 +112,7 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
     consolidateCadence: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
     deprecatedTtlDays: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
     usageBoost: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    zeroOpenDecay: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
     pushDebounceSeconds: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
     jevEnabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
     jevBackend: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
@@ -146,6 +147,7 @@ export declare const Config: import("@deepseek-ai/schemastery").default<Schemast
     consolidateCadence: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
     deprecatedTtlDays: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
     usageBoost: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    zeroOpenDecay: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
     pushDebounceSeconds: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
     jevEnabled: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
     jevBackend: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;

package/lib/retrieval.d.ts

@@ -48,10 +48,23 @@ export interface RetrievalConfig {
         hits: number;
         opens: number;
     }>;
+    /**
+     * Zero-open decay (v5, default off — config `zeroOpenDecay`): halve the
+     * score of slugs on the zero-open list (≥5 rendered injections in the
+     * rolling 30 days, zero opens ever) at score-finalization time, BEFORE
+     * the threshold cut — a decayed candidate that drops below the threshold
+     * lands in nearMisses with the `zero-open-decay` reason, so the log
+     * shows why it stopped injecting. Absent/off = zero behavior change.
+     */
+    zeroOpenDecay?: boolean;
+    /** Zero-open slugs for this round (service-built from the ilog tail). */
+    zeroOpenSlugs?: ReadonlySet<string>;
 }
 /** Hard cap for the usage bonus — below threshold 0.3 so usage can never
  *  carry a candidate across the gate on its own (ADR 0015). */
 export declare const USAGE_BOOST_CAP = 0.2;
+/** Score multiplier for zero-open slugs when zeroOpenDecay is on (v5). */
+export declare const ZERO_OPEN_DECAY_FACTOR = 0.5;
 export declare const DEFAULT_RETRIEVAL: RetrievalConfig;
 /** Trigger hits outrank every other lexical field (pi-llm-wiki: highest weight). */
 export declare const TRIGGER_WEIGHT = 5;

package/lib/retrieval.js

@@ -15,6 +15,8 @@ import { dependsSlugs } from "./okf.js";
 /** Hard cap for the usage bonus — below threshold 0.3 so usage can never
  *  carry a candidate across the gate on its own (ADR 0015). */
 export const USAGE_BOOST_CAP = 0.2;
+/** Score multiplier for zero-open slugs when zeroOpenDecay is on (v5). */
+export const ZERO_OPEN_DECAY_FACTOR = 0.5;
 export const DEFAULT_RETRIEVAL = {
     threshold: 0.3,
     topK: 4,
@@ -149,6 +151,14 @@ export function scoreTopic(queryTokens, topic, cfg) {
         score *= 0.3;
         reasons.push('conflicted-demoted');
     }
+    // Zero-open decay (v5): same demotion family as conflicts — applied to
+    // the content score BEFORE gateScore is taken, so the threshold cut and
+    // the near-miss band both see the halved score; recency still rides
+    // outside it as the ranking tiebreaker.
+    if (cfg.zeroOpenDecay === true && cfg.zeroOpenSlugs?.has(topic.slug) === true) {
+        score *= ZERO_OPEN_DECAY_FACTOR;
+        reasons.push('zero-open-decay');
+    }
     const gateScore = score;
     score += recencyBonus;
     const bodySet = new Set([...description, ...conclusion]);