@aiwayds/dsh-topics-memory 0.17.1 → 0.18.1

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.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.**
+> **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.**
 
 ## Demo
 
@@ -90,14 +90,14 @@ The host reconciles the profile automatically: the `dsh.profile.bundles` entry i
 What stays on disk (kept on purpose — this is your memory):
 
 - `~/.dsh/topics/` — the whole topic bundle: topic markdown, `meta/`, and the embedded `.git` repo (the full history; it may carry an `origin` remote — GitHub sync stops with the plugin). To archive the bundle elsewhere, copy or clone this directory as-is.
-- `~/.dsh/settings.yaml` `topics:` section — user overrides. Reinstalling silently reactivates sync including any configured `repo`; delete the section first if you want a clean start.
-- The legacy `llmwiki:` settings section left by the 0.5.x → 0.6.x migration is never auto-deleted; remove it by hand once nothing needs it.
+- The settings-page `dsh-topics-memory` entry (profile patch) — user overrides. Reinstalling silently reactivates sync including any configured `repo`; clear the entry first if you want a clean start.
+- A legacy `llmwiki:` section left inside the old `settings.yaml` (renamed `settings.yaml.imported` after the host's one-shot 0.1.7 import) is never touched again; mine it by hand if something still needs it.
 
 Purge everything: back up `~/.dsh/topics` first, then `rm -rf ~/.dsh/topics`.
 
 ## Configuration
 
-First-time setup belongs to `/topics onboard`; day-to-day tuning is `/topics set <key> <value>` (writes the `topics` namespace in `settings.yaml`, effective from the next session). All keys and defaults:
+First-time setup belongs to `/topics onboard`; day-to-day tuning is `/topics set <key> <value>` — on dsh 0.1.7+ it writes the settings-page `dsh-topics-memory` entry (the profile patch) and every key is volatile: edits take effect immediately, no restart. Upgrading from a pre-0.1.7 install: a legacy top-level `topics:` section in the old `settings.yaml` is imported once into the new entry automatically at the next plugin boot (the audit record lands in `~/.dsh/storages/dsh-topics-memory/legacy-import.json`). All keys and defaults:
 
 | Key | Default | Meaning |
 |---|---|---|
@@ -142,7 +142,7 @@ This project's shape is directly inspired and supported by:
 - **Subagents are out of memory by default — one switch to opt in**: by default (`include-subagents` off since 0.7.0) delegated sessions are skipped entirely — no injection, no observation, no distill triggers; `/topics set include-subagents on` applies injection and observation to them too. The topic tools stay on the global layer, so an explicit `topic_save` from a child still lands. Out-of-process subagents (claude-code/codex providers) never load this plugin anyway.
 - **Exit is local-only (0.10.0)**: the plugin's disposer makes one local git commit of the meta sidecars (observations / injections / distill state) and never waits on the network — no pull, no push, no model call, so host exit no longer pays a git round-trip or a bounded distill wait (the old 90s cap is gone; only a 10s guard against a pathological git stall remains). The exit distill trigger is fired fire-and-forget and is skipped entirely while a session-end run is still in flight (the same pool head would otherwise be fed to the model twice). Nothing is lost by skipping: observations are write-through on disk, the deferred push is replayed by the next boot's pull, and the skipped distill is replayed there too (boot-replay). `meta/distill-state.json` records each lane's outcome, checkable via `/topics status`.
 - **Observation GC (three strikes)**: an observation the model actually evaluated (parseable answer, however useless) but no op consumed accrues one failed attempt; the third failed attempt physically deletes it — explicitly authorized cleanup of raw data the lane demonstrably cannot process. Runs that never evaluated the batch never count: infrastructure failures (network errors, unconfigured distill route → readable `no-model` short-circuit) and unparseable output (`invalid-output`) are exempt, and a batch still mid-shrink on output-limit retries is only counted once a verdict is reached (success, floor stop, stall, or an explicit skip). Deletions are committed immediately (data destruction stays git-traceable); pure attempt counters follow the usual flush cadence.
-- **Config read timing**: `/topics set` and `settings.yaml` edits take effect most reliably from the next session start.
+- **Config read timing**: `/topics set` and profile-patch edits take effect most reliably from the next session start (dsh 0.1.7: the settings document is the profile patch; the old `settings.yaml` is imported once and renamed).
 - **Picking a distill model**: `/topics onboard` splits the distill decision into two dependent questions (provider first, then that provider's model catalog), pre-validated with `resolveModelInfo` — a provider with no live route blocks and re-asks, an off-catalog model (a non-NO_ADAPTER failure: outside the advisory catalog, possibly still usable) warns but is allowed; hosts without an ask UI or a usable model route fall back to typed input. The same validation backs the `/topics set` picker panels.
 
 ## Design docs

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.5-rc.2** — 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。**不再支持 alpha 线。**
+> **要求 dsh >= 0.1.7-rc.1** — 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。**不再支持 alpha 线。**
 
 ## 演示
 
@@ -90,14 +90,14 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 以下内容有意保留在磁盘上（这是你的记忆本体）：
 
 - `~/.dsh/topics/` —— 整个话题包：话题 markdown、`meta/`、以及内嵌的 `.git` 仓库（完整历史；可能带有 `origin` 远端 —— GitHub 同步随插件停止）。要异地归档就原样拷贝/克隆这个目录。
-- `~/.dsh/settings.yaml` 的 `topics:` 段 —— 用户覆盖项。注意：重装会静默恢复同步（包括已配置的 `repo`）；想干净重来就先删这一段。
+- 设置页 `dsh-topics-memory` 条目（profile patch）—— 用户覆盖项。注意：重装会静默恢复同步（包括已配置的 `repo`）；想干净重来就先清空该条目。
 - 0.5.x → 0.6.x 迁移留下的 `llmwiki:` 旧设置段不会被自动删除；确认无用后手动移除。
 
 彻底清除：先备份 `~/.dsh/topics`，再 `rm -rf ~/.dsh/topics`。
 
 ## 配置
 
-首次配置交给 `/topics onboard`；日常微调用 `/topics set <key> <value>`（写 `settings.yaml` 的 `topics` namespace，下次会话启动生效）。全部键与默认值：
+首次配置交给 `/topics onboard`；日常微调用 `/topics set <key> <value>`——0.1.7+ 宿主上写设置页 `dsh-topics-memory` 条目（profile patch），全部键 volatile 免重启即时生效。从 0.1.7 之前升级：旧 `settings.yaml` 里的 `topics:` 段会在下次插件 boot 时一次性自动迁入新条目（审计档在 `~/.dsh/storages/dsh-topics-memory/legacy-import.json`）。全部键与默认值：
 
 | 键 | 默认 | 说明 |
 |---|---|---|
@@ -142,7 +142,7 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 - **子代理默认不参与记忆，可整体打开**：默认（`include-subagents` off，0.7.0 起）delegation depth > 0 的子代理会话被整体跳过——不注入、不观察、不触发蒸馏；`/topics set include-subagents on` 后注入与观察同样作用于子代理会话。topic 工具始终在全局层（子代理显式 `topic_save` 不受开关影响）。跨进程子代理（claude-code/codex 等 provider）本就不加载本插件。
 - **退出路径本地化（0.10.0）**：插件 disposer 只做一步本地 git commit（meta 侧车文件：observations / injections / distill state），不再等待任何网络——没有 pull、没有 push、没有模型调用，宿主退出不再支付 git 双程与有界蒸馏等待（旧的 90s 上限移除，仅保留 10s 兜底以防病理性 git 卡死）。退出蒸馏触发改为 fire-and-forget；已有 session-end run 在跑时整体跳过（否则同一全局队头批次会被双份喂给模型）。跳过不丢活：observations 本就 write-through 落盘，推迟的 push 由下次启动的 pull 补推，被跳过的蒸馏同样由下次启动回放（boot-replay）。`meta/distill-state.json` 记录每次 lane 的结局，`/topics status` 可查。
 - **观察 GC（三振删除）**：被模型实际评估（返回了可解析应答，无论内容有无价值）却未被任何 op 消费的观察记一次 failed attempt，连续 3 次即物理删除（用户已明确授权删除 lane 确实无法处理的原始观察）。模型从未评估过的批次永不计数：基础设施失败（网络错误、蒸馏路由未配置 → 可读 `no-model` 短路）与输出不可解析（`invalid-output`）豁免；输出上限减半重试中的批次只有到达裁决（成功 / 触底 / stalled / 明确跳过）才计一次。删除立即 commit（数据销毁 git 可追溯），纯计数沿用 flush 节奏。
-- **配置读取时机**：`/topics set` 与 settings.yaml 修改在下次会话启动后生效最稳。
+- **配置读取时机**：`/topics set` 与 profile patch 修改在下次会话启动后生效最稳（dsh 0.1.7 起 settings 文档即 profile patch；旧 settings.yaml 导入一次后改名）。
 - **蒸馏选模型**：`/topics onboard` 的蒸馏一步拆成两问（先 provider 后 model，模型列表取自该 provider 的目录），选完经 `resolveModelInfo` 预校验——provider 无活路由会阻断重选，模型目录校验非 NO_ADAPTER 失败（目录外，可能仍可用）则警告但放行；无 ask UI 或无可用模型路由的环境自动退回文本输入。`/topics set` 的选择面板走同一套校验。
 
 ## 设计文档

package/icon.svg

@@ -0,0 +1,6 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg">
+  <circle cx="6.5" cy="6" r="2.2"/>
+  <circle cx="17.5" cy="7.5" r="2.2"/>
+  <circle cx="12" cy="17.5" r="2.2"/>
+  <path d="M8.7 6.5 15.3 7M16.3 9.6 13.5 15.6M9.5 8.1l1.7 7.3"/>
+</svg>

package/lib/config.d.ts

@@ -5,141 +5,141 @@
  * @module config
  */
 import z from '@deepseek-ai/schemastery';
-export declare const TopicsConfig: z<Schemastery.ObjectS<{
+export declare const TopicsConfig: z<Schemastery.ObjectS<NoInfer<{
     /** GitHub repo `owner/name`; empty = local-only mode (ADR 0008). */
-    repo: z<string, string>;
+    repo: z<string, string, "volatile-defined">;
     /** Master switch for per-turn injection. */
-    autoInject: z<boolean, boolean>;
+    autoInject: z<boolean, boolean, "volatile-defined">;
     /** Skip re-injecting topics already injected earlier in the same session. */
-    injectDedup: z<boolean, boolean>;
+    injectDedup: z<boolean, boolean, "volatile-defined">;
     /** Skip re-injecting topics distilled from the CURRENT session's own turns
      *  (蒸馏回声): the conversation already carries that knowledge, so a
      *  pointer is a stale echo at best (2026-09 audit: 3 of 6 useless rounds).
      *  Provenance rides the observations log (sessionId → distilledInto). */
-    suppressEcho: z<boolean, boolean>;
+    suppressEcho: z<boolean, boolean, "volatile-defined">;
     /** Max topics injected per round (ADR 0006: ≤4). */
-    topK: z<number, number>;
+    topK: z<number, number, "volatile-defined">;
     /** Per-topic digest budget in tokens. */
-    perTopicBudget: z<number, number>;
+    perTopicBudget: z<number, number, "volatile-defined">;
     /** Total injection budget in tokens. */
-    totalBudget: z<number, number>;
+    totalBudget: z<number, number, "volatile-defined">;
     /** Retrieval score threshold — tune via /topics stats near-miss evidence. */
-    matchThreshold: z<number, number>;
+    matchThreshold: z<number, number, "volatile-defined">;
     /** Additive boost per tag hit (v4: total cap = this value, was ×3). */
-    tagBoost: z<number, number>;
+    tagBoost: z<number, number, "volatile-defined">;
     /** Injection shape: pointer (default, ≤600 tok) keeps the legacy digest view. */
-    injectMode: z<string, string>;
+    injectMode: z<string, string, "volatile-defined">;
     /** Slow quality lane (v4 §4.2): off | sampled (1/3 of turns) | always. */
-    qualityLane: z<string, string>;
+    qualityLane: z<string, string, "volatile-defined">;
     /** depends-graph expansion depth (0 disables). */
-    graphDepth: z<number, number>;
+    graphDepth: z<number, number, "volatile-defined">;
     /** Days within which a topic counts as recent (+0.2). */
-    recencyWindowDays: z<number, number>;
+    recencyWindowDays: z<number, number, "volatile-defined">;
     /** Capture each turn's user/assistant text as raw observations (M2). */
-    autoObserve: z<boolean, boolean>;
+    autoObserve: z<boolean, boolean, "volatile-defined">;
     /** Whether injection and observation also engage delegated subagent sessions (ADR 0011).
      *  v4 default flipped to false: one-shot subagent turns diluted the pool.
      *  The slow quality lane never runs for subagents either way (hard guard). */
-    includeSubagents: z<boolean, boolean>;
+    includeSubagents: z<boolean, boolean, "volatile-defined">;
     /** Max auto-captured chars per side (user/assistant) per turn. */
-    observationMaxChars: z<number, number>;
+    observationMaxChars: z<number, number, "volatile-defined">;
     /** Background distill cadence: every N turns of a long session. */
-    distillEveryTurns: z<number, number>;
+    distillEveryTurns: z<number, number, "volatile-defined">;
     /** Distill once when a session ends. */
-    distillOnSessionEnd: z<boolean, boolean>;
+    distillOnSessionEnd: z<boolean, boolean, "volatile-defined">;
     /** Distill lane model route; both must be set, else distill stays idle. */
-    distillProvider: z<string, string>;
-    distillModel: z<string, string>;
+    distillProvider: z<string, string, "volatile-defined">;
+    distillModel: z<string, string, "volatile-defined">;
     /** Observations per distill model call; auto-halves on output-limit failures (floor 5). */
-    distillBatchSize: z<number, number>;
+    distillBatchSize: z<number, number, "volatile-defined">;
     /** Max model calls per distill run — successful batches keep their marks (partial progress).
      *  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>;
+    distillMaxModelCalls: z<number, number, "volatile-defined">;
     /** 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>;
+    consolidateCadence: z<string, string, "volatile-defined">;
     /** 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>;
+    deprecatedTtlDays: z<number, number, "volatile-defined">;
     /** 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>;
+    usageBoost: z<number, number, "volatile-defined">;
     /** Debounced push delay in GitHub mode. */
-    pushDebounceSeconds: z<number, number>;
-}>, Schemastery.ObjectT<{
+    pushDebounceSeconds: z<number, number, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
     /** GitHub repo `owner/name`; empty = local-only mode (ADR 0008). */
-    repo: z<string, string>;
+    repo: z<string, string, "volatile-defined">;
     /** Master switch for per-turn injection. */
-    autoInject: z<boolean, boolean>;
+    autoInject: z<boolean, boolean, "volatile-defined">;
     /** Skip re-injecting topics already injected earlier in the same session. */
-    injectDedup: z<boolean, boolean>;
+    injectDedup: z<boolean, boolean, "volatile-defined">;
     /** Skip re-injecting topics distilled from the CURRENT session's own turns
      *  (蒸馏回声): the conversation already carries that knowledge, so a
      *  pointer is a stale echo at best (2026-09 audit: 3 of 6 useless rounds).
      *  Provenance rides the observations log (sessionId → distilledInto). */
-    suppressEcho: z<boolean, boolean>;
+    suppressEcho: z<boolean, boolean, "volatile-defined">;
     /** Max topics injected per round (ADR 0006: ≤4). */
-    topK: z<number, number>;
+    topK: z<number, number, "volatile-defined">;
     /** Per-topic digest budget in tokens. */
-    perTopicBudget: z<number, number>;
+    perTopicBudget: z<number, number, "volatile-defined">;
     /** Total injection budget in tokens. */
-    totalBudget: z<number, number>;
+    totalBudget: z<number, number, "volatile-defined">;
     /** Retrieval score threshold — tune via /topics stats near-miss evidence. */
-    matchThreshold: z<number, number>;
+    matchThreshold: z<number, number, "volatile-defined">;
     /** Additive boost per tag hit (v4: total cap = this value, was ×3). */
-    tagBoost: z<number, number>;
+    tagBoost: z<number, number, "volatile-defined">;
     /** Injection shape: pointer (default, ≤600 tok) keeps the legacy digest view. */
-    injectMode: z<string, string>;
+    injectMode: z<string, string, "volatile-defined">;
     /** Slow quality lane (v4 §4.2): off | sampled (1/3 of turns) | always. */
-    qualityLane: z<string, string>;
+    qualityLane: z<string, string, "volatile-defined">;
     /** depends-graph expansion depth (0 disables). */
-    graphDepth: z<number, number>;
+    graphDepth: z<number, number, "volatile-defined">;
     /** Days within which a topic counts as recent (+0.2). */
-    recencyWindowDays: z<number, number>;
+    recencyWindowDays: z<number, number, "volatile-defined">;
     /** Capture each turn's user/assistant text as raw observations (M2). */
-    autoObserve: z<boolean, boolean>;
+    autoObserve: z<boolean, boolean, "volatile-defined">;
     /** Whether injection and observation also engage delegated subagent sessions (ADR 0011).
      *  v4 default flipped to false: one-shot subagent turns diluted the pool.
      *  The slow quality lane never runs for subagents either way (hard guard). */
-    includeSubagents: z<boolean, boolean>;
+    includeSubagents: z<boolean, boolean, "volatile-defined">;
     /** Max auto-captured chars per side (user/assistant) per turn. */
-    observationMaxChars: z<number, number>;
+    observationMaxChars: z<number, number, "volatile-defined">;
     /** Background distill cadence: every N turns of a long session. */
-    distillEveryTurns: z<number, number>;
+    distillEveryTurns: z<number, number, "volatile-defined">;
     /** Distill once when a session ends. */
-    distillOnSessionEnd: z<boolean, boolean>;
+    distillOnSessionEnd: z<boolean, boolean, "volatile-defined">;
     /** Distill lane model route; both must be set, else distill stays idle. */
-    distillProvider: z<string, string>;
-    distillModel: z<string, string>;
+    distillProvider: z<string, string, "volatile-defined">;
+    distillModel: z<string, string, "volatile-defined">;
     /** Observations per distill model call; auto-halves on output-limit failures (floor 5). */
-    distillBatchSize: z<number, number>;
+    distillBatchSize: z<number, number, "volatile-defined">;
     /** Max model calls per distill run — successful batches keep their marks (partial progress).
      *  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>;
+    distillMaxModelCalls: z<number, number, "volatile-defined">;
     /** 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>;
+    consolidateCadence: z<string, string, "volatile-defined">;
     /** 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>;
+    deprecatedTtlDays: z<number, number, "volatile-defined">;
     /** 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>;
+    usageBoost: z<number, number, "volatile-defined">;
     /** Debounced push delay in GitHub mode. */
-    pushDebounceSeconds: z<number, number>;
-}>>;
+    pushDebounceSeconds: z<number, number, "volatile-defined">;
+}>>, "plain">;
 export type TopicsConfigValue = {
     repo: string;
     autoInject: boolean;

package/lib/config.js

@@ -7,71 +7,71 @@
 import z from '@deepseek-ai/schemastery';
 export const TopicsConfig = z.object({
     /** GitHub repo `owner/name`; empty = local-only mode (ADR 0008). */
-    repo: z.string().default(''),
+    repo: z.string().default('').volatile(),
     /** Master switch for per-turn injection. */
-    autoInject: z.boolean().default(true),
+    autoInject: z.boolean().default(true).volatile(),
     /** Skip re-injecting topics already injected earlier in the same session. */
-    injectDedup: z.boolean().default(true),
+    injectDedup: z.boolean().default(true).volatile(),
     /** Skip re-injecting topics distilled from the CURRENT session's own turns
      *  (蒸馏回声): the conversation already carries that knowledge, so a
      *  pointer is a stale echo at best (2026-09 audit: 3 of 6 useless rounds).
      *  Provenance rides the observations log (sessionId → distilledInto). */
-    suppressEcho: z.boolean().default(true),
+    suppressEcho: z.boolean().default(true).volatile(),
     /** Max topics injected per round (ADR 0006: ≤4). */
-    topK: z.number().default(4),
+    topK: z.number().default(4).volatile(),
     /** Per-topic digest budget in tokens. */
-    perTopicBudget: z.number().default(300),
+    perTopicBudget: z.number().default(300).volatile(),
     /** Total injection budget in tokens. */
-    totalBudget: z.number().default(1500),
+    totalBudget: z.number().default(1500).volatile(),
     /** Retrieval score threshold — tune via /topics stats near-miss evidence. */
-    matchThreshold: z.number().default(0.3),
+    matchThreshold: z.number().default(0.3).volatile(),
     /** Additive boost per tag hit (v4: total cap = this value, was ×3). */
-    tagBoost: z.number().default(0.15),
+    tagBoost: z.number().default(0.15).volatile(),
     /** Injection shape: pointer (default, ≤600 tok) keeps the legacy digest view. */
-    injectMode: z.string().default('pointer'),
+    injectMode: z.string().default('pointer').volatile(),
     /** Slow quality lane (v4 §4.2): off | sampled (1/3 of turns) | always. */
-    qualityLane: z.string().default('sampled'),
+    qualityLane: z.string().default('sampled').volatile(),
     /** depends-graph expansion depth (0 disables). */
-    graphDepth: z.number().default(2),
+    graphDepth: z.number().default(2).volatile(),
     /** Days within which a topic counts as recent (+0.2). */
-    recencyWindowDays: z.number().default(7),
+    recencyWindowDays: z.number().default(7).volatile(),
     /** Capture each turn's user/assistant text as raw observations (M2). */
-    autoObserve: z.boolean().default(true),
+    autoObserve: z.boolean().default(true).volatile(),
     /** Whether injection and observation also engage delegated subagent sessions (ADR 0011).
      *  v4 default flipped to false: one-shot subagent turns diluted the pool.
      *  The slow quality lane never runs for subagents either way (hard guard). */
-    includeSubagents: z.boolean().default(false),
+    includeSubagents: z.boolean().default(false).volatile(),
     /** Max auto-captured chars per side (user/assistant) per turn. */
-    observationMaxChars: z.number().default(2000),
+    observationMaxChars: z.number().default(2000).volatile(),
     /** Background distill cadence: every N turns of a long session. */
-    distillEveryTurns: z.number().default(5),
+    distillEveryTurns: z.number().default(5).volatile(),
     /** Distill once when a session ends. */
-    distillOnSessionEnd: z.boolean().default(true),
+    distillOnSessionEnd: z.boolean().default(true).volatile(),
     /** Distill lane model route; both must be set, else distill stays idle. */
-    distillProvider: z.string().default(''),
-    distillModel: z.string().default(''),
+    distillProvider: z.string().default('').volatile(),
+    distillModel: z.string().default('').volatile(),
     /** Observations per distill model call; auto-halves on output-limit failures (floor 5). */
-    distillBatchSize: z.number().default(40),
+    distillBatchSize: z.number().default(40).volatile(),
     /** Max model calls per distill run — successful batches keep their marks (partial progress).
      *  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),
+    distillMaxModelCalls: z.number().default(8).volatile(),
     /** 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'),
+    consolidateCadence: z.string().default('daily').volatile(),
     /** 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),
+    deprecatedTtlDays: z.number().default(15).volatile(),
     /** 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),
+    usageBoost: z.number().default(0.15).volatile(),
     /** Debounced push delay in GitHub mode. */
-    pushDebounceSeconds: z.number().default(45),
+    pushDebounceSeconds: z.number().default(45).volatile(),
 });
 export const CONFIG_KEYS = [
     'repo',

package/lib/distill.d.ts

@@ -10,6 +10,14 @@
  * @module distill
  */
 import type { TopicsService } from './service.ts';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** Producer context contributed by the dsh-topics-memory plugin. */
+        'topics-memory': {
+            kind: 'topics-memory';
+        };
+    }
+}
 export interface ModelRequest {
     system: string;
     user: string;

package/lib/distill.js

@@ -710,7 +710,7 @@ export function defaultModelCaller(getCandidates, getRoute) {
         const messages = [
             createUserMessage({
                 content: [{ type: 'text', text: req.user }],
-                source: { kind: 'plugin', plugin: 'dsh-topics-memory' },
+                source: { kind: 'topics-memory' },
             }),
         ];
         const options = deepFreeze({

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 import type { Context } from '@deepseek-ai/cordis';
+import { type TopicsConfigValue } from './config.ts';
 export declare const name = "dsh-topics-memory";
 /**
  * Bounded wait for the process-exit meta commit. The exit path is
@@ -85,42 +86,72 @@ export declare function resolveClaimedText(input: {
     start: number;
     removedCount: number;
 }): ClaimedTextResolution;
-/**
- * Settings-provider surface the legacy-namespace migration needs. Structurally
- * typed like every other host seam in this file, so bare test harnesses
- * without dsh-settings still load the module: a host lacking `describe` or
- * `mutate` simply skips the migration.
- */
-interface SettingsNsLike {
-    register(n: unknown, s: unknown): {
-        get(): unknown;
-    };
-    describe?(): {
-        ns: unknown;
-        user?: unknown;
-    }[];
-    mutate?(ns: unknown, ops: readonly {
-        op: 'set';
-        path: string[];
-        value?: unknown;
-    }[]): Promise<void>;
+export declare const Config: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<NoInfer<{
+    repo: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    autoInject: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    injectDedup: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    suppressEcho: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    topK: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    perTopicBudget: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    totalBudget: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    matchThreshold: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    tagBoost: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    injectMode: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    qualityLane: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    graphDepth: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    recencyWindowDays: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    autoObserve: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    includeSubagents: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    observationMaxChars: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    distillEveryTurns: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    distillOnSessionEnd: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    distillProvider: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    distillModel: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    distillBatchSize: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    distillMaxModelCalls: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    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">;
+    pushDebounceSeconds: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    repo: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    autoInject: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    injectDedup: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    suppressEcho: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    topK: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    perTopicBudget: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    totalBudget: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    matchThreshold: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    tagBoost: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    injectMode: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    qualityLane: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    graphDepth: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    recencyWindowDays: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    autoObserve: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    includeSubagents: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    observationMaxChars: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    distillEveryTurns: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    distillOnSessionEnd: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    distillProvider: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    distillModel: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    distillBatchSize: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    distillMaxModelCalls: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    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">;
+    pushDebounceSeconds: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+}>>, "plain">;
+/** Live config reference as a 0.1.7 host passes it (cron / mcp-adapter
+ * spelling): `.get()` snapshots the current value — the host swaps the
+ * reference in-place when a volatile field is edited on the settings page. */
+interface VolatileRef<T> {
+    get(): T;
 }
-/**
- * One-time carry-over of user-tuned values from the pre-rename `llmwiki`
- * settings namespace into `topics` (ADR 0013). Constraints:
- * - one-time: only fires while the new namespace holds NO raw user overrides —
- *   describe().user is the only way to tell user keys from schema defaults,
- *   because scope.get() folds the defaults in;
- * - idempotent: after the copy (or any config written on the new name) the
- *   override check short-circuits every later boot;
- * - fail-open: registering the legacy namespace can throw (duplicate or
- *   schema-invalid stored section) and the write can reject — both contained,
- *   so plugin startup never depends on the migration.
- * Keys whose stored value equals the schema default are not copied (nothing
- * user-tuned to preserve). Returns the in-flight write for tests; apply()
- * fire-and-forgets it.
- */
-export declare function migrateLegacySettings(settings: SettingsNsLike, warn?: (message: string) => void): Promise<void> | undefined;
+/** apply()-time config: live VolatileRef fields on real hosts, plain values
+ * on bare test harnesses — {@link readConfigValue} accepts both. */
+export type TopicsRuntimeConfig = Partial<{
+    [K in keyof TopicsConfigValue]: VolatileRef<TopicsConfigValue[K]> | TopicsConfigValue[K];
+}>;
 /**
  * Strip a leading YAML frontmatter block (`---` / body / `---`) from a skill
  * markdown file. `SkillDefinition.content` must be the instruction body after
@@ -132,5 +163,5 @@ export declare function migrateLegacySettings(settings: SettingsNsLike, warn?: (
  * delimiter semantics of the upstream skill-filesystem provider.
  */
 export declare function stripFrontmatter(raw: string): string;
-export declare function apply(ctx: Context): void;
+export declare function apply(ctx: Context, config?: TopicsRuntimeConfig): Promise<void>;
 export {};