@aiwayds/dsh-topics-memory 0.13.1 → 0.15.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.2-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.1.5-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
 
@@ -58,6 +58,7 @@ This plugin is not trying to be the model's notebook. It is trying to be the mod
 | `/topics onboard` | Interactive setup wizard on dsh-native ask-user panels (mode / repo / distill model / injection tier / auto-observe); typed fallback where no ask-user UI exists |
 | `/topics status` | Bundle health: topic count, observation backlog, conflicts, last distill outcome, sync status |
 | `/topics distill` | Manually trigger one distill run over the current observation pool (same lane, same in-flight guard; summary mirrors the distill-state fields) |
+| `/topics consolidate` | Manually trigger one consolidation run: the LLM gardener merges duplicates, promotes settled drafts, deprecates superseded entries, refreshes metadata — every change is its own git commit, revert to roll back |
 | `/topics stats` | Injection stats: hit rate, top-N, near-miss distribution, tuning advice |
 | `/topics list` / `show` / `history` | Browse topics, backlinks, and change history |
 | `/topics graph` | Generate a relationship-graph web page (force-directed, draggable/zoomable, hover for conclusions) and open it in the browser |
@@ -121,6 +122,9 @@ First-time setup belongs to `/topics onboard`; day-to-day tuning is `/topics set
 | `distillOnSessionEnd` | `true` | Distill once when a session ends |
 | `distillBatchSize` | `40` | Observations per distill model call. On an output-limit (`max-tokens`) failure the batch halves automatically (floor 5) and retries — a failing batch can no longer livelock the backlog; the shrink persists until reload or a config change. Note: `/topics set distillBatchSize` back to the same value does not reset the shrink — set a different value or reload the plugin |
 | `distillMaxModelCalls` | `8` | Max model calls per distill run, including the one corrective retry for ops echoing no valid `observed_ids` (the run stalls when the budget can't fit it). Batches already distilled keep their marks when the budget stops the run (partial progress), recorded as `partial: …` in the distill state |
+| `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 |
 | `pushDebounceSeconds` | `45` | GitHub-mode debounced push interval |
 
 ## Acknowledgements

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.2-rc.1** — 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。**不再支持 alpha 线。**
+> **要求 dsh >= 0.1.5-rc.2** — 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。**不再支持 alpha 线。**
 
 ## 演示
 
@@ -52,6 +52,7 @@ https://github.com/user-attachments/assets/6e9b346d-2ec9-4148-ae62-7087797d3188
 | `/topics onboard` | 交互式配置向导：唤起 dsh 原生 ask-user 面板逐项问答（模式 / 仓库 / 蒸馏 / 注入档位 / 自动观察），末步确认才写入；无 ask-user UI 的环境自动退化为逐条输入 |
 | `/topics status` | bundle 健康：topic 数、观察积压、冲突、最近蒸馏结果、同步状态 |
 | `/topics distill` | 手动触发一次蒸馏 run（复用现有 lane 与 in-flight 守卫；输出摘要与 distill-state 字段一一对应） |
+| `/topics consolidate` | 手动触发一次整理 run：LLM 园丁合并重复/晋升 stable/废弃过时/刷新元数据，逐条 git commit 可回滚 |
 | `/topics stats` | 注入统计：hit rate、top-N、near-miss 分布与调参建议 |
 | `/topics list` / `show` / `history` | 浏览 Topic、反向引用与变更史 |
 | `/topics graph` | 生成关系图网页（力导向、可拖拽缩放、悬停看结论）并自动在浏览器打开 |
@@ -121,6 +122,9 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 | `distillOnSessionEnd` | `true` | session 结束时蒸馏一次 |
 | `distillBatchSize` | `40` | 每次蒸馏模型调用携带的观察条数。遇输出上限（`max-tokens`）失败自动减半重试（下限 5），失败批次不再活锁积压；缩小状态跨 run 保持，直到插件重载或配置变更。注意：`/topics set distillBatchSize` 重设为同值不触发复位，需设为不同值或重载插件 |
 | `distillMaxModelCalls` | `8` | 单次蒸馏 run 的模型调用预算，含 ops 未回显有效 `observed_ids` 时的纠错重试（至多一次，预算放不下即零消费停机）。预算耗尽即停，已成功的批次照常 markDistilled（部分前进优于零前进），distill state 记 `partial: …` |
+| `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` 关闭 |
 | `pushDebounceSeconds` | `45` | GitHub 模式去抖推送间隔 |
 
 ## Acknowledgements

package/lib/commands.d.ts

@@ -8,6 +8,7 @@
 import type { CommandDefinition, CommandInvocation } from '@deepseek-ai/dsh-commands';
 import type { TopicsService } from './service.ts';
 import type { DistillResult } from './distill.ts';
+import type { ConsolidateResult } from './consolidate.ts';
 import { aggregateStats } from './ilog.ts';
 import { type AskServiceResolver, type LlmDirectoryResolver, type MutateFn } from './onboard.ts';
 /**
@@ -16,6 +17,12 @@ import { type AskServiceResolver, type LlmDirectoryResolver, type MutateFn } fro
  * the command's normal error path.
  */
 export type ManualDistill = (invocation: CommandInvocation) => Promise<DistillResult>;
+/**
+ * Manual `/topics consolidate` trigger, wired by the host (index.ts owns the
+ * lane instance). Bypasses the cadence gate; the lane's own in-flight guard
+ * still applies.
+ */
+export type ManualConsolidate = (invocation: CommandInvocation) => Promise<ConsolidateResult>;
 export declare const HELP: string;
-export declare function buildTopicsCommand(service: TopicsService, mutate: MutateFn, resolveAsk?: AskServiceResolver, resolveLlm?: LlmDirectoryResolver, distillNow?: ManualDistill): CommandDefinition;
+export declare function buildTopicsCommand(service: TopicsService, mutate: MutateFn, resolveAsk?: AskServiceResolver, resolveLlm?: LlmDirectoryResolver, distillNow?: ManualDistill, consolidateNow?: ManualConsolidate): CommandDefinition;
 export declare function tuningHint(stats: ReturnType<typeof aggregateStats>, threshold: number): string | undefined;

package/lib/commands.js

@@ -18,6 +18,7 @@ export const HELP = [
     '  /topics onboard             交互式配置向导（ask-user 面板逐项问答；无 UI 环境逐条输入）',
     '  /topics status              bundle 健康：topic 数、观察积压、冲突、同步状态',
     '  /topics distill             手动触发一次蒸馏（观察池 → Topic，输出 marked/created/updated/gc 摘要）',
+    '  /topics consolidate         手动触发一次整理（合并重复/晋升 stable/废弃过时/刷新元数据，无视 cadence 立即跑）',
     '  /topics stats               注入统计：hit rate、top-N、near-miss 分布与调参建议',
     '  /topics list                列出全部 Topic',
     '  /topics show <slug>         查看一个 Topic 全文（含反向引用）',
@@ -30,16 +31,16 @@ export const HELP = [
     '',
     '凭据：$GITHUB_TOKEN 或已登录的 gh CLI；登录不在本插件职责内。',
 ].join('\n');
-export function buildTopicsCommand(service, mutate, resolveAsk = () => undefined, resolveLlm = () => [], distillNow) {
+export function buildTopicsCommand(service, mutate, resolveAsk = () => undefined, resolveLlm = () => [], distillNow, consolidateNow) {
     const onboard = createOnboardHandler(service, mutate, undefined, resolveAsk, resolveLlm);
     return {
         name: 'topics',
-        description: 'OKF topic 记忆：onboard | distill | status | stats | list | show | history | graph | sync | config | set',
-        input: { hint: '[onboard | distill | status | stats | list | show <slug> | history <slug> | graph | sync [pull|push] | config | set <key> <value>]' },
-        handler: (invocation) => handle(invocation, service, mutate, onboard, resolveAsk, resolveLlm, distillNow),
+        description: 'OKF topic 记忆：onboard | distill | consolidate | status | stats | list | show | history | graph | sync | config | set',
+        input: { hint: '[onboard | distill | consolidate | status | stats | list | show <slug> | history <slug> | graph | sync [pull|push] | config | set <key> <value>]' },
+        handler: (invocation) => handle(invocation, service, mutate, onboard, resolveAsk, resolveLlm, distillNow, consolidateNow),
     };
 }
-async function handle(invocation, service, mutate, onboard, resolveAsk, resolveLlm, distillNow) {
+async function handle(invocation, service, mutate, onboard, resolveAsk, resolveLlm, distillNow, consolidateNow) {
     const raw = invocation.rawInput.trim();
     const [action = '', ...rest] = raw.split(/\s+/);
     try {
@@ -52,6 +53,8 @@ async function handle(invocation, service, mutate, onboard, resolveAsk, resolveL
                 return ok(await renderStatus(service));
             case 'distill':
                 return await doDistill(service, invocation, distillNow);
+            case 'consolidate':
+                return await doConsolidate(service, invocation, consolidateNow);
             case 'stats':
                 return ok(await renderStats(service));
             case 'list':
@@ -97,6 +100,7 @@ async function renderStatus(service) {
         ['注入去重', cfg.injectDedup ? '开（同会话已注入的 Topic 不重注）' : '关'],
         ['慢道', cfg.qualityLane === 'off' ? '关' : cfg.qualityLane === 'always' ? `每轮（${cfg.distillProvider}/${cfg.distillModel}）` : `采样 1/3（${cfg.distillProvider}/${cfg.distillModel}）`],
         ['蒸馏', cfg.distillProvider !== '' && cfg.distillModel !== '' ? `${cfg.distillProvider}/${cfg.distillModel}，每 ${cfg.distillEveryTurns} 轮` : '未配置模型（/topics set distill-provider / distill-model）'],
+        ['整理', cadenceLabel(cfg.consolidateCadence) + (cfg.consolidateCadence === 'off' ? '' : `（复用蒸馏模型，/topics consolidate 立即跑）`)],
     ];
     // Last lane outcome (distill-state summary) — what "checkable via
     // /topics status" promises; absent until the first run of this bundle.
@@ -108,6 +112,20 @@ async function renderStatus(service) {
         const gc = typeof lastRun.gcDropped === 'number' && lastRun.gcDropped > 0 ? `，GC 回收 ${lastRun.gcDropped}` : '';
         rows.push(['最近蒸馏', `${outcome}${gc} @ ${cell(String(lastRun.at ?? '').slice(0, 19).replace('T', ' '))}`]);
     }
+    const lastConsolidate = await service.store.readConsolidateState();
+    if (lastConsolidate !== undefined) {
+        const count = (v) => (Array.isArray(v) ? v.length : 0);
+        const counts = [
+            `合并 ${count(lastConsolidate.merged)}`,
+            `晋升 ${count(lastConsolidate.promoted)}`,
+            `废弃 ${count(lastConsolidate.deprecated)}`,
+            `刷新 ${count(lastConsolidate.refreshed)}`,
+        ].join('/');
+        rows.push([
+            '最近整理',
+            `${counts} @ ${cell(String(lastConsolidate.at ?? '').slice(0, 19).replace('T', ' '))}${lastConsolidate.ok === false && lastConsolidate.detail ? `（${String(lastConsolidate.detail).slice(0, 80)}）` : ''}`,
+        ]);
+    }
     if (service.sync !== undefined) {
         rows.push(['上次推送', cell(String(service.sync.lastPushAt ?? '从未'))]);
         if (service.sync.lastError !== '')
@@ -127,6 +145,58 @@ async function renderStatus(service) {
  * summary mirrors the distill state fields (ok / marked / created / updated /
  * gc dropped / reason) so what the user sees is what the state file records.
  */
+/** Human-readable cadence for status/consolidate output. */
+function cadenceLabel(value) {
+    switch (value) {
+        case 'daily':
+            return '每天';
+        case '3d':
+            return '每 3 天';
+        case '7d':
+            return '每 7 天';
+        default:
+            return '关';
+    }
+}
+/**
+ * `/topics consolidate` — one manual run of the consolidation lane (LLM
+ * gardener over the existing pool). Bypasses the cadence gate; the lane's
+ * own in-flight guard dedups a concurrent automatic run. Output mirrors the
+ * lane's actions with per-op reasons so the user can eyeball (and git-revert)
+ * what the model decided.
+ */
+async function doConsolidate(service, invocation, consolidateNow) {
+    if (consolidateNow === undefined)
+        return fail('整理 lane 未接线（宿主未提供手动整理触发器）');
+    const cfg = service.cfg;
+    if (cfg.distillProvider === '' || cfg.distillModel === '') {
+        return fail('整理复用蒸馏模型路由：请先 /topics set distill-provider 与 distill-model。');
+    }
+    const result = await consolidateNow(invocation);
+    if (!result.ok) {
+        const reasonNote = result.reason === 'no-clusters'
+            ? '没有找到可能相近的 topic 候选簇（词面上没有疑似重复/相关对）'
+            : result.reason === 'no-model'
+                ? '蒸馏模型未配置（/topics set distill-provider / distill-model）'
+                : result.reason === 'in-flight'
+                    ? '已有整理在跑，稍后再试'
+                    : (result.reason ?? 'unknown');
+        return fail(`整理未执行：${reasonNote}${result.detail !== undefined ? `\n   ${result.detail}` : ''}`);
+    }
+    const lines = [];
+    const actions = result.actions ?? [];
+    const KIND_LABEL = { merge: '合并', promote: '晋升', deprecate: '废弃', refresh: '刷新' };
+    for (const a of actions) {
+        if (a.kind === 'merge' && a.merged !== undefined) {
+            lines.push(`- 合并 ${a.merged.map((m) => cell(m)).join('、')} → ${cell(a.slug)}${a.reason !== undefined ? `：${a.reason}` : ''}`);
+        }
+        else {
+            lines.push(`- ${KIND_LABEL[a.kind] ?? a.kind} ${cell(a.slug)}${a.reason !== undefined ? `：${a.reason}` : ''}`);
+        }
+    }
+    const header = `✅ 整理完成：合并 ${result.merged.length} 组；晋升 ${result.promoted.length}；废弃 ${result.deprecated.length}；刷新 ${result.refreshed.length}${result.droppedOps ? `（丢弃 ${result.droppedOps} 个无效 op）` : ''}${result.detail !== undefined ? `\n   ${result.detail}` : ''}`;
+    return ok(lines.length === 0 ? header : `${header}\n${lines.join('\n')}\n全部变更已逐条 git commit，可 /topics history <slug> 追溯、git revert 回滚。`);
+}
 async function doDistill(service, invocation, distillNow) {
     if (distillNow === undefined)
         return fail('蒸馏 lane 未接线（宿主未提供手动蒸馏触发器）');

package/lib/config.d.ts

@@ -56,6 +56,20 @@ export declare const TopicsConfig: z<Schemastery.ObjectS<{
      *  Default 8: with the batch loop, one run then drains ~30-40 observations
      *  instead of ~10, which is what makes a real backlog actually shrink. */
     distillMaxModelCalls: z<number, number>;
+    /** Consolidation lane (整理) cadence: how often a session start may run the
+     *  LLM gardener over the EXISTING pool (merge near-duplicates, promote
+     *  settled drafts, deprecate superseded, refresh metadata). Reuses the
+     *  distill model route; off disables the lane entirely. */
+    consolidateCadence: z<string, string>;
+    /** Deprecated topics older than this many days are dropped at session start
+     *  (local TTL sweep, no model; each drop is its own git commit, so history
+     *  stays recoverable on the remote). 0 disables the sweep. */
+    deprecatedTtlDays: z<number, number>;
+    /** UsageBoost (ADR 0015): behavioral bonus for topics injected/opened in
+     *  the last 30 days, folded into the gate score — capped at 0.2 and never
+     *  granted to zero-lexical candidates; the structural gate still applies.
+     *  0 = off. */
+    usageBoost: z<number, number>;
     /** Debounced push delay in GitHub mode. */
     pushDebounceSeconds: z<number, number>;
 }>, Schemastery.ObjectT<{
@@ -109,6 +123,20 @@ export declare const TopicsConfig: z<Schemastery.ObjectS<{
      *  Default 8: with the batch loop, one run then drains ~30-40 observations
      *  instead of ~10, which is what makes a real backlog actually shrink. */
     distillMaxModelCalls: z<number, number>;
+    /** Consolidation lane (整理) cadence: how often a session start may run the
+     *  LLM gardener over the EXISTING pool (merge near-duplicates, promote
+     *  settled drafts, deprecate superseded, refresh metadata). Reuses the
+     *  distill model route; off disables the lane entirely. */
+    consolidateCadence: z<string, string>;
+    /** Deprecated topics older than this many days are dropped at session start
+     *  (local TTL sweep, no model; each drop is its own git commit, so history
+     *  stays recoverable on the remote). 0 disables the sweep. */
+    deprecatedTtlDays: z<number, number>;
+    /** UsageBoost (ADR 0015): behavioral bonus for topics injected/opened in
+     *  the last 30 days, folded into the gate score — capped at 0.2 and never
+     *  granted to zero-lexical candidates; the structural gate still applies.
+     *  0 = off. */
+    usageBoost: z<number, number>;
     /** Debounced push delay in GitHub mode. */
     pushDebounceSeconds: z<number, number>;
 }>>;
@@ -135,9 +163,12 @@ export type TopicsConfigValue = {
     distillModel: string;
     distillBatchSize: number;
     distillMaxModelCalls: number;
+    consolidateCadence: string;
+    deprecatedTtlDays: number;
+    usageBoost: number;
     pushDebounceSeconds: number;
 };
-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", "pushDebounceSeconds"];
+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"];
 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

@@ -56,6 +56,20 @@ export const TopicsConfig = z.object({
      *  Default 8: with the batch loop, one run then drains ~30-40 observations
      *  instead of ~10, which is what makes a real backlog actually shrink. */
     distillMaxModelCalls: z.number().default(8),
+    /** Consolidation lane (整理) cadence: how often a session start may run the
+     *  LLM gardener over the EXISTING pool (merge near-duplicates, promote
+     *  settled drafts, deprecate superseded, refresh metadata). Reuses the
+     *  distill model route; off disables the lane entirely. */
+    consolidateCadence: z.string().default('daily'),
+    /** Deprecated topics older than this many days are dropped at session start
+     *  (local TTL sweep, no model; each drop is its own git commit, so history
+     *  stays recoverable on the remote). 0 disables the sweep. */
+    deprecatedTtlDays: z.number().default(15),
+    /** UsageBoost (ADR 0015): behavioral bonus for topics injected/opened in
+     *  the last 30 days, folded into the gate score — capped at 0.2 and never
+     *  granted to zero-lexical candidates; the structural gate still applies.
+     *  0 = off. */
+    usageBoost: z.number().default(0.15),
     /** Debounced push delay in GitHub mode. */
     pushDebounceSeconds: z.number().default(45),
 });
@@ -82,6 +96,9 @@ export const CONFIG_KEYS = [
     'distillModel',
     'distillBatchSize',
     'distillMaxModelCalls',
+    'consolidateCadence',
+    'deprecatedTtlDays',
+    'usageBoost',
     'pushDebounceSeconds',
 ];
 /** CamelCase → dash-display (topK → top-k) for command output. */
@@ -118,6 +135,7 @@ export function parseConfigValue(key, raw) {
         case 'distillEveryTurns':
         case 'distillBatchSize':
         case 'distillMaxModelCalls':
+        case 'deprecatedTtlDays':
         case 'pushDebounceSeconds': {
             const n = Number(raw);
             if (!Number.isFinite(n) || n < 0 || !Number.isInteger(n))
@@ -129,13 +147,19 @@ export function parseConfigValue(key, raw) {
                 return raw;
             return { error: 'inject-mode 取值 pointer|digest' };
         }
+        case 'consolidateCadence': {
+            if (raw === 'off' || raw === 'daily' || raw === '3d' || raw === '7d')
+                return raw;
+            return { error: 'consolidate-cadence 取值 off|daily|3d|7d' };
+        }
         case 'qualityLane': {
             if (raw === 'off' || raw === 'sampled' || raw === 'always')
                 return raw;
             return { error: 'quality-lane 取值 off|sampled|always' };
         }
         case 'matchThreshold':
-        case 'tagBoost': {
+        case 'tagBoost':
+        case 'usageBoost': {
             const n = Number(raw);
             if (!Number.isFinite(n) || n < 0)
                 return { error: `${key} 需要非负数` };

package/lib/consolidate.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Consolidation lane — periodic LLM gardening over the topic pool itself.
+ *
+ * Where the distill lane turns observations into topics, this lane turns the
+ * EXISTING pool into a better one: merging near-duplicates, promoting drafts
+ * whose conclusions have settled, deprecating superseded entries, refreshing
+ * metadata (title/tags/triggers). Triggered by cadence at session start
+ * (`consolidate-cadence`: off | daily | 3d | 7d) or manually via
+ * `/topics consolidate`. The model route is shared with the distill lane
+ * (distill-provider/distill-model) — one route to configure, one caller
+ * instance injected.
+ *
+ * Safety model:
+ *  - grounded proposals: clusters are built locally (lexical similarity over
+ *    title+tags tokens), so the model only ever judges topics that already
+ *    look alike and every op names its slugs verbatim from the bundle;
+ *  - four op kinds only, and refresh may NOT touch the conclusion body —
+ *    rewriting conclusions is merge's exclusive path, so a metadata refresh
+ *    can never silently lose knowledge; no create: consolidation prunes,
+ *    it never grows;
+ *  - every write rides the normal saveTopic path (one git commit per change),
+ *    so the whole run is one `git revert` away;
+ *  - the cadence stamp (meta/consolidate-state.json) advances only when the
+ *    model actually evaluated at least one cluster — a run that died on the
+ *    first call leaves the stamp alone, and the next session start retries.
+ *
+ * @module consolidate
+ */
+import type { TopicsService } from './service.ts';
+import { type ModelCaller } from './distill.ts';
+/** Clusters are capped — a giant cluster drowns the model in candidates. */
+export declare const MAX_CLUSTER_SIZE = 6;
+export interface ConsolidateOp {
+    op: 'merge' | 'promote' | 'deprecate' | 'refresh';
+    /** promote/deprecate/refresh target. */
+    slug?: string;
+    /** merge: the surviving slug. */
+    survivor?: string;
+    /** merge: slugs absorbed INTO the survivor (≥ 1). */
+    merged?: string[];
+    title?: string;
+    description?: string;
+    tags?: string[];
+    triggers?: string[];
+    /** merge only (refresh may not rewrite conclusions). */
+    conclusion?: string;
+    reason?: string;
+}
+export interface ConsolidateAction {
+    kind: ConsolidateOp['op'];
+    /** merge: survivor; others: the target slug. */
+    slug: string;
+    /** merge: the absorbed slugs. */
+    merged?: string[];
+    reason?: string;
+}
+export interface ConsolidateResult {
+    ok: boolean;
+    reason?: 'no-model' | 'no-clusters' | 'in-flight' | 'model-error' | 'invalid-output';
+    merged: string[];
+    promoted: string[];
+    deprecated: string[];
+    refreshed: string[];
+    /** Ops rejected by sanitization, with the model's raw op count for context. */
+    droppedOps?: number;
+    rawOps?: number;
+    calls?: number;
+    actions?: ConsolidateAction[];
+    detail?: string;
+}
+export declare const CONSOLIDATE_SYSTEM_PROMPT: string;
+/** Latin words + CJK bigrams — the token space title/tags similarity lives in. */
+export declare function topicTokens(text: string): Set<string>;
+export interface ClusterEntry {
+    slug: string;
+    title: string;
+    status: string;
+    tags: readonly string[];
+    description?: string;
+    conclusion: string;
+}
+export interface TopicCluster {
+    entries: ClusterEntry[];
+    /** Peak pairwise similarity inside the cluster — runs process peaks first. */
+    similarity: number;
+}
+/**
+ * Group entries whose title+description+tags tokens clear the pairwise
+ * threshold (union-find over similar pairs). Singletons are dropped — the
+ * model only ever sees topics that already look alike. Clusters larger than
+ * {@link MAX_CLUSTER_SIZE} keep their most-connected members.
+ */
+export declare function clusterTopics(entries: readonly ClusterEntry[], threshold?: number): TopicCluster[];
+/**
+ * Drop `deprecated` topics older than `ttlDays` — pure housekeeping, never
+ * touches the model. `generated.at` is the right clock: every save restamps
+ * it and nothing ever touches a deprecated entry afterwards, so it IS the
+ * "became deprecated at" timestamp. Deletion rides the normal store path
+ * (one commit per drop, index regenerated), so the history stays recoverable
+ * on the remote; an unparsable stamp is skipped, not guessed. Returns the
+ * dropped slugs. `ttlDays <= 0` disables the sweep.
+ */
+export declare function dropExpiredDeprecated(service: TopicsService, ttlDays: number, now?: number): Promise<string[]>;
+export declare class Consolidator {
+    private inFlight;
+    private readonly service;
+    private readonly caller;
+    constructor(service: TopicsService, caller: ModelCaller | undefined);
+    get configured(): boolean;
+    /** Cadence days for a config value; undefined = off (or unrecognized). */
+    static cadenceDays(value: string | undefined): number | undefined;
+    get hasPending(): boolean;
+    /**
+     * Cadence-gated entry (session start): silently skips when off, not due,
+     * or already running. Due = no stamp yet (first run) or the last EVALUATED
+     * run is older than the cadence.
+     */
+    maybeRun(opts?: {
+        sessionId?: string;
+        now?: number;
+    }): Promise<ConsolidateResult | undefined>;
+    /** Manual entry (/topics consolidate): bypasses the cadence, keeps the guard. */
+    run(sessionId?: string): Promise<ConsolidateResult>;
+    private start;
+    private runInner;
+    /** Read the active pool and cluster it lexically. */
+    private buildClusters;
+    /** One model call over one cluster, ops shape-validated but not yet applied. */
+    private runCluster;
+    /**
+     * Validate and apply ops against the live bundle. Slugs are slugify-normalized
+     * and must exist; merge requires a non-empty conclusion and forbids self-merge;
+     * refresh never receives the conclusion field (merge's exclusive path); ops on
+     * slugs already merged away earlier in this run are skipped (the deprecation
+     * already redirects readers to the survivor). One bad op never sinks the rest.
+     */
+    private applyOps;
+}