@aiwayds/dsh-topics-memory 0.17.1 → 0.18.1

package/lib/index.js

@@ -2,7 +2,8 @@
  * dsh-topics-memory — OKF topic memory for DeepSeek Harness.
  *
  * Wiring (per ADR 0001–0008):
- *  - `topics` settings namespace (user-tunable via /topics set)
+ *  - settings page = projection of the plugin `Config` schema, namespace =
+ *    profile entry id `dsh-topics-memory` (user-tunable via /topics set)
  *  - static systemPrompt section teaching the topic tools (never volatile
  *    content — the provider cache prefix stays byte-stable)
  *  - same-turn injection: retrieval runs synchronously at inbox-claim time
@@ -34,6 +35,7 @@ import { Consolidator, dropExpiredDeprecated } from "./consolidate.js";
 import { SlowLane } from "./quality.js";
 import { CONFIG_KEYS, TopicsConfig } from "./config.js";
 import { isDelegated } from "./delegation.js";
+import { runLegacySettingsImport } from "./legacy-import.js";
 export const name = 'dsh-topics-memory';
 /**
  * Bounded wait for the process-exit meta commit. The exit path is
@@ -154,68 +156,20 @@ export function resolveClaimedText(input) {
         source: 'projection',
     };
 }
-// dsh-settings 0.1.2-alpha.3 removed the runtime settingsNamespace() helper:
-// register() now brand-checks the namespace at the type level
-// (SettingsNamespaceInput) and validates the same lowercase-hyphenated
-// pattern at runtime via parseSettingsNamespace. A plain literal is the
-// supported spelling (same adaptation as dsh-cron / dsh-model-sync).
-const OWN_NS = 'topics';
-/** Pre-rename settings namespace (dsh-llmwiki-memory ≤ 0.5.x). The plugin
- *  itself never writes to it, but while the migration window is open the
- *  registration shows up in config UIs like any other namespace (ADR 0013). */
-const LEGACY_NS = 'llmwiki';
-/**
- * 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 function migrateLegacySettings(settings, warn) {
-    try {
-        const describe = settings.describe?.bind(settings);
-        if (describe === undefined)
-            return undefined;
-        const findUser = (ns) => {
-            const user = describe().find((entry) => entry.ns === ns)?.user;
-            return user !== undefined && user !== null && typeof user === 'object' ? user : undefined;
-        };
-        // Already migrated / user-configured on the new name — never touch it.
-        if (findUser(OWN_NS) !== undefined)
-            return undefined;
-        // Old-plugin coexistence (ADR 0013): `llmwiki` already registered means
-        // the pre-rename dsh-llmwiki-memory 0.5.x is still loaded in this host.
-        // Our register below would hit the duplicate guard, migration would
-        // silently skip, and both plugins would drift onto separate bundles
-        // (split brain). Warn loudly instead of registering blind.
-        if (describe().some((entry) => entry.ns === LEGACY_NS)) {
-            warn?.('dsh-topics-memory: the legacy dsh-llmwiki-memory (0.5.x) is still running in this host — ' +
-                'settings migration was skipped because the "llmwiki" namespace is already registered. ' +
-                'Remove @aiwayds/dsh-llmwiki-memory from this profile so only dsh-topics-memory loads.');
-            return undefined;
-        }
-        // Registering the legacy namespace is the only API that surfaces its
-        // stored section; a duplicate or schema-invalid section throws — contained.
-        settings.register(LEGACY_NS, TopicsConfig);
-        const legacyUser = findUser(LEGACY_NS);
-        if (legacyUser === undefined)
-            return undefined;
-        const ops = CONFIG_KEYS.filter((k) => k in legacyUser && legacyUser[k] !== DEFAULTS[k]).map((k) => ({ op: 'set', path: [k], value: legacyUser[k] }));
-        if (ops.length === 0)
-            return undefined;
-        return settings.mutate?.call(settings, OWN_NS, ops)?.catch(() => undefined);
-    }
-    catch {
-        return undefined;
-    }
+// dsh 0.1.7 settings: the runtime namespace registry (register/describe per
+// plugin) is gone. A plugin's settings page is the projection of its `Config`
+// schema below, and the settings namespace is the profile entry id
+// (`dsh-topics-memory`, cordis.patch.yml) — the same spelling /topics set
+// passes to ctx.settings.mutate(). A legacy top-level `topics:` section in
+// settings.yaml is NOT auto-imported under this id — the host imports the
+// old settings.yaml once, then renames it to settings.yaml.imported.
+export const Config = TopicsConfig;
+/** Settings namespace this plugin reads and writes: the profile entry id. */
+const ENTRY_ID = 'dsh-topics-memory';
+/** Snapshot one config slot: live ref → current value, plain value → itself. */
+function readConfigValue(slot) {
+    const ref = slot;
+    return typeof ref?.get === 'function' ? ref.get() : slot;
 }
 // --- Bundled skill -----------------------------------------------------------
 /** Provider name under `ctx.skills`; doubles as the skill name. */
@@ -229,7 +183,7 @@ const SKILL_RESOURCE_BASE = {
 };
 const SKILL_INVOCATION = { modelInvocable: true, userInvocable: true };
 /** Routing description; must stay identical to the SKILL.md frontmatter (asserted in tests). */
-const SKILL_DESCRIPTION = 'dsh 记忆插件（@aiwayds/dsh-topics-memory）使用与配置指南。凡涉及 dsh 记忆/话题库/GitHub 同步/蒸馏/整理，或要配置 topics 段时先读本指南：settings.yaml 顶层 `topics:` 段全部键（repo/autoInject/topK/注入预算/蒸馏/整理/观察/图游走等）、/topics 命令族（onboard/status/distill/consolidate/stats/list/show/history/graph/sync/config/set）、首次配置 ask_user_question 向导（local-only 或绑 GitHub 仓、蒸馏模型路由、注入档位、自动观察）、注入形态 pointer/digest、legacy llmwiki 段自动迁移。触发词：topics、记忆、topic、蒸馏、distill、整理、consolidate、合并重复、deprecatedTtl、usageBoost、使用加成、autoInject、记忆库、llmwiki、include-subagents。';
+const SKILL_DESCRIPTION = 'dsh 记忆插件（@aiwayds/dsh-topics-memory）使用与配置指南。凡涉及 dsh 记忆/话题库/GitHub 同步/蒸馏/整理，或要配置 topics 时先读本指南：设置页 `dsh-topics-memory` 条目全部键（repo/autoInject/topK/注入预算/蒸馏/整理/观察/图游走等）、/topics 命令族（onboard/status/distill/consolidate/stats/list/show/history/graph/sync/config/set）、首次配置 ask_user_question 向导（local-only 或绑 GitHub 仓、蒸馏模型路由、注入档位、自动观察）、注入形态 pointer/digest。触发词：topics、记忆、topic、蒸馏、distill、整理、consolidate、合并重复、deprecatedTtl、usageBoost、使用加成、autoInject、记忆库、include-subagents。';
 const SKILL_CANDIDATE = {
     name: SKILL_PROVIDER_NAME,
     description: SKILL_DESCRIPTION,
@@ -282,19 +236,16 @@ export function stripFrontmatter(raw) {
     }
     return raw;
 }
-export function apply(ctx) {
+export async function apply(ctx, config = {}) {
     // `inject = ['skills']` guarantees the service exists on every real host;
     // register unconditionally so a missing service fails loud instead of
     // silently dropping the bundled skill.
     ctx.skills.registerProvider(() => skillProvider);
-    // dsh-settings is part of every real host closure but is a runtime-optional
-    // peer so bare test harnesses can still load this module.
-    const settingsNs = ctx.settings;
-    if (settingsNs === undefined)
-        return;
-    const scope = settingsNs.register(OWN_NS, TopicsConfig);
+    // 0.1.7 hosts validate the profile patch against `Config` above and hand
+    // apply() live volatile references; bare harnesses pass plain values (or
+    // nothing) — readConfigValue treats both shapes the same.
     // Host logger access is best-effort: cordis always provides one, but bare
-    // test harnesses may not — the migration stays silent rather than throwing.
+    // test harnesses may not — the logging stays silent rather than throwing.
     const warn = (message) => {
         try {
             const logger = ctx.logger;
@@ -305,10 +256,6 @@ export function apply(ctx) {
             // contained — a missing/broken logger must not break startup
         }
     };
-    // Carry user-tuned values over from the pre-rename namespace (one-time,
-    // fail-open, idempotent — see migrateLegacySettings). Fire-and-forget: the
-    // write settles on its own; a rejection only skips the migration.
-    void migrateLegacySettings(settingsNs, warn);
     // Low-noise observability for the fast lane's early exits. The 2026-09-21
     // silent-death incident (0.1.5-rc.2 claim order) died precisely because
     // every exit path was silent: the injected log stayed empty for weeks
@@ -326,7 +273,14 @@ export function apply(ctx) {
         }
     };
     const cfgNow = () => {
-        const v = scope.get();
+        const v = {};
+        for (const k of CONFIG_KEYS) {
+            const slot = config[k];
+            // Skip absent keys so the DEFAULTS fold below keeps them (an explicit
+            // undefined spread would wipe the default).
+            if (slot !== undefined)
+                v[k] = readConfigValue(slot);
+        }
         // Schema defaults may not be applied by bare test harnesses; fill them in.
         return { ...DEFAULTS, ...v };
     };
@@ -616,6 +570,11 @@ export function apply(ctx) {
             let logEvents;
             if (typeof seq === 'number') {
                 try {
+                    // Soft-deprecated surface, deliberately kept (dsh 0.17 migration):
+                    // `snapshotEvents` still ships in dsh-session 0.1.7-rc.1 and this is
+                    // the replay's data source, reachable only behind event.seq with a
+                    // full projection-read fallback below. Migrating to registered
+                    // SessionMessageProjections is a dedicated project, not a drive-by.
                     const snapshot = session.snapshotEvents;
                     if (typeof snapshot === 'function')
                         logEvents = snapshot.call(session, 0, seq);
@@ -668,10 +627,6 @@ export function apply(ctx) {
         if (event.type === 'turn/end')
             dispatchSlowLane(sessionId);
     }));
-    // Session-start boot chain dedup: rc.2's creation transaction emits BOTH
-    // `agent/session-start` and `agent/created`, so the pair collapses to one
-    // chain run per session; teardown clears the entry.
-    const bootedSessions = new Set();
     // ---- Session teardown: real cordis events, not session/event types ----
     // dsh-session 0.1.2-alpha.4's SessionEventMap has no `agent/disposed` or
     // `session/disposed` event type — the old `event.type === 'agent/disposed'`
@@ -696,7 +651,6 @@ export function apply(ctx) {
             observer.onSessionEvent(sessionId, name, undefined);
             injectedBySession.delete(sessionId);
             slowLane.clear(sessionId);
-            bootedSessions.delete(sessionId);
             // A teardown-triggered run (session-end distill) reads the payload
             // capture lazily: drop the entry here only when no run can still read
             // it. The slow lane's in-flight pipeline reads it too (shared caller);
@@ -704,91 +658,128 @@ export function apply(ctx) {
             releaseSessionLlm(sessionId);
         }));
     }
-    // ---- Sync lifecycle: pull on session start, local commit on dispose ----
+    // ---- Boot chain: pull on session start, replay-distill, consolidate, TTL ----
     // Session start is an agent-bus event, never a session/event firehose type:
-    // the firehose only carries Session.append types. Tarball-verified emission
-    // sites: `agent/session-start` (sync, payload { agent, source }) is emitted
-    // by dsh-agent-loop up to 0.1.5; 0.1.6-alpha.1 merges the startup
-    // notification into the serial `agent/created` announcement (payload
-    // { agent, source, signal? }) and drops the old name. So one registration
-    // per name — a host that never emits a name simply never calls that
-    // listener. Only { agent } is structural; the rest is defensive.
+    // the firehose only carries Session.append types. dsh 0.1.7 announces ONE
+    // serial `agent/created` event (payload { agent, source, signal? }, source
+    // ∈ 'startup' | 'resume' | 'clear' | 'compact') and `agent/session-start`
+    // is gone with no shim — 0.16.1's dual-name registration collapses to a
+    // single listener, and with it the per-session dedup Set: the registry
+    // guarantees exactly one announce per agent entry (a second announce
+    // throws), so a 'clear'/'compact' re-creation legitimately re-runs the
+    // chain on its fresh entry and teardown has nothing to re-arm. Only
+    // { agent } is structural; the rest is defensive.
+    //
+    // BOOT GUARANTEE (dsh 0.1.7): the serial dispatch awaits every
+    // `agent/created` listener and a throw or rejection ROLLS THE ENTIRE AGENT
+    // CREATION BACK. This listener is therefore total and synchronous — it
+    // never throws, never returns a promise — and the chain is deferred off
+    // the creation transaction entirely (setImmediate, unref'd): the pull /
+    // replay-distill / consolidation slow work starts only after the serial
+    // dispatch has moved on. Plugin initialization must never block, delay,
+    // or abort session startup; a chain failure at most warns.
     const runBootChain = (sessionId) => {
-        void sync
-            .pull()
-            .catch(() => undefined)
-            .finally(() => store.ensure().catch(() => undefined))
-            .then(() => {
-            // Boot replay: the observations JSONL is the durable distill queue.
-            // Whatever the previous exit skipped (local-only exit since the
-            // no-network exit commit) or a killed run left unmarked is still
-            // undistilled here. Empty pool and no-model are cheap no-ops inside
-            // the distiller; the per-session dedup guards double runs.
-            void store
-                .undistilledObservations(1)
-                .then((pending) => {
-                if (pending.length === 0)
-                    return;
-                // Same trigger-time capture the observer callback does: the
-                // replay run's caller resolves candidates lazily and a fresh
-                // session has no prior capture to lean on.
+        // Contained at the top too: a synchronous prologue throw (config read,
+        // sync bookkeeping) must degrade to a warn, not leak toward the host.
+        try {
+            void sync
+                .pull()
+                .catch((error) => {
+                // The pull failing must stay non-fatal for the chain (replay and
+                // TTL still run on the local pool), but no longer silent — a dead
+                // sync route should leave a host-log trace.
+                warn(`dsh-topics-memory 启动同步 pull 失败（继续本地启动链）：${error instanceof Error ? error.message : String(error)}`);
+            })
+                .finally(() => store.ensure().catch(() => undefined))
+                .then(() => {
+                // Boot replay: the observations JSONL is the durable distill queue.
+                // Whatever the previous exit skipped (local-only exit since the
+                // no-network exit commit) or a killed run left unmarked is still
+                // undistilled here. Empty pool and no-model are cheap no-ops inside
+                // the distiller; the per-session dedup guards double runs.
+                void store
+                    .undistilledObservations(1)
+                    .then((pending) => {
+                    if (pending.length === 0)
+                        return;
+                    // Same trigger-time capture the observer callback does: the
+                    // replay run's caller resolves candidates lazily and a fresh
+                    // session has no prior capture to lean on.
+                    try {
+                        captureFromAgent(agents()?.get(sessionId));
+                    }
+                    catch {
+                        // contained — the run below fails with the readable
+                        // no-adapter detail instead
+                    }
+                    const run = distiller.request(sessionId, 'boot-replay');
+                    if (run !== undefined)
+                        void run.catch(() => undefined);
+                })
+                    .catch(() => undefined);
+                // Consolidation cadence check — after the pull (freshest pool),
+                // fully fire-and-forget: cadence/single-flight gates live inside
+                // maybeRun, and a no-model boot just skips (no stamp advanced).
+                // Failures are NOT silent at the host log: the 2026-09-09 real-host
+                // test showed a dead distill route would otherwise hide here with
+                // zero observable trace (the state file only advances on success).
                 try {
                     captureFromAgent(agents()?.get(sessionId));
                 }
                 catch {
-                    // contained — the run below fails with the readable
-                    // no-adapter detail instead
-                }
-                const run = distiller.request(sessionId, 'boot-replay');
-                if (run !== undefined)
-                    void run.catch(() => undefined);
-            })
-                .catch(() => undefined);
-            // Consolidation cadence check — after the pull (freshest pool),
-            // fully fire-and-forget: cadence/single-flight gates live inside
-            // maybeRun, and a no-model boot just skips (no stamp advanced).
-            // Failures are NOT silent at the host log: the 2026-09-09 real-host
-            // test showed a dead distill route would otherwise hide here with
-            // zero observable trace (the state file only advances on success).
-            try {
-                captureFromAgent(agents()?.get(sessionId));
-            }
-            catch {
-                // contained — the run below fails with a readable no-model detail
-            }
-            void consolidator
-                .maybeRun({ sessionId })
-                .then((r) => {
-                if (r !== undefined && !r.ok && r.reason !== 'no-clusters') {
-                    warn(`dsh-topics-memory 整理 lane 未执行：${r.reason ?? 'unknown'}${r.detail !== undefined ? `（${r.detail}）` : ''}`);
+                    // contained — the run below fails with a readable no-model detail
                 }
-            })
-                .catch(() => undefined);
-            // Deprecated-TTL sweep — pure local rule, no model, runs even when
-            // the distill route is unconfigured. Drops are logged: deletion is
-            // the one housekeeping action the user should always see happened.
-            const ttl = cfgNow().deprecatedTtlDays;
-            if (ttl > 0) {
-                void dropExpiredDeprecated(service, ttl)
-                    .then((dropped) => {
-                    if (dropped.length > 0) {
-                        warn(`dsh-topics-memory：按 ${ttl} 天 TTL 删除了 ${dropped.length} 条 deprecated topic（${dropped.map((s) => `topics/${s}`).join('、')}）；git 历史可找回`);
+                void consolidator
+                    .maybeRun({ sessionId })
+                    .then((r) => {
+                    if (r !== undefined && !r.ok && r.reason !== 'no-clusters') {
+                        warn(`dsh-topics-memory 整理 lane 未执行：${r.reason ?? 'unknown'}${r.detail !== undefined ? `（${r.detail}）` : ''}`);
                     }
                 })
                     .catch(() => undefined);
-            }
-        })
-            .catch(() => undefined);
+                // Deprecated-TTL sweep — pure local rule, no model, runs even when
+                // the distill route is unconfigured. Drops are logged: deletion is
+                // the one housekeeping action the user should always see happened.
+                const ttl = cfgNow().deprecatedTtlDays;
+                if (ttl > 0) {
+                    void dropExpiredDeprecated(service, ttl)
+                        .then((dropped) => {
+                        if (dropped.length > 0) {
+                            warn(`dsh-topics-memory：按 ${ttl} 天 TTL 删除了 ${dropped.length} 条 deprecated topic（${dropped.map((s) => `topics/${s}`).join('、')}）；git 历史可找回`);
+                        }
+                    })
+                        .catch(() => undefined);
+                }
+            })
+                .catch((error) => {
+                warn(`dsh-topics-memory 启动链失败（不影响会话启动）：${error instanceof Error ? error.message : String(error)}`);
+            });
+        }
+        catch (error) {
+            warn(`dsh-topics-memory 启动链无法启动（不影响会话启动）：${error instanceof Error ? error.message : String(error)}`);
+        }
     };
-    for (const name of ['agent/session-start', 'agent/created']) {
-        ctx.on(name, ((payload) => {
+    ctx.on('agent/created', ((payload) => {
+        // The boot-fallback contract lives HERE, not inside runBootChain: dsh
+        // 0.1.7 rolls agent creation back when this listener throws, so even a
+        // hostile/malformed payload (a throwing getter, a proxy trap) degrades to
+        // a warn. Returning undefined (never a thenable) keeps the serial
+        // dispatch from awaiting anything.
+        try {
             const sessionId = String(payload?.agent?.id ?? '');
-            if (sessionId === '' || bootedSessions.has(sessionId))
+            if (sessionId === '')
                 return;
-            bootedSessions.add(sessionId);
-            runBootChain(sessionId);
-        }));
-    }
+            // Off the creation transaction: the unref'd immediate fires after the
+            // current serial dispatch slice, so the chain's synchronous prologue
+            // (config read, sync state) never delays the remaining listeners nor
+            // the loop start, and the timer cannot hold a dying process open.
+            const deferred = setImmediate(() => runBootChain(sessionId));
+            deferred.unref?.();
+        }
+        catch (error) {
+            warn(`dsh-topics-memory boot 链触发失败（不影响会话启动）：${error instanceof Error ? error.message : String(error)}`);
+        }
+    }));
     ctx.effect(() => {
         void store.ensure().catch(() => undefined);
         // Async disposer: cordis awaits it during unload (Disposable may be
@@ -821,7 +812,9 @@ export function apply(ctx) {
         const mutate = async (ops) => {
             if (settingsMutator?.mutate === undefined)
                 throw new Error('settings 服务不可用，无法写入配置');
-            await settingsMutator.mutate(OWN_NS, ops);
+            // 0.1.7: the settings namespace is the profile entry id, not the old
+            // `topics` namespace name.
+            await settingsMutator.mutate(ENTRY_ID, ops);
         };
         // Resolved lazily at invocation time: whichever UI registered the ask-user
         // provider (TUI panel / web composer / feishu card, ask-router optional)
@@ -901,6 +894,27 @@ export function apply(ctx) {
         };
         cmdCtx.effect(() => commands.register(buildTopicsCommand(service, mutate, resolveAsk, resolveLlm, manualDistill, manualConsolidate)), 'topics: /topics');
     });
+    // ---- One-time legacy settings import (0.1.5 → 0.1.7 upgrade path) ----
+    // The 0.1.7 host imports the old settings.yaml ONCE by "section name =
+    // entry id" and renames it settings.yaml.imported — this plugin's legacy
+    // section was named `topics`, so the host's import silently dropped it.
+    // Recover it here (see legacy-import.ts). Awaited as apply()'s LAST step:
+    // every registration above stays synchronous (fake-ctx tests dispatch
+    // immediately), while a real boot — whose loader awaits the fiber setup —
+    // also settles the import before activation completes. Fully contained:
+    // any failure only warns and leaves the audit marker unwritten, so the
+    // next boot retries; activation never depends on this.
+    try {
+        await runLegacySettingsImport({
+            home: paths.resolveDshHome(),
+            settings: ctx.settings,
+            logger: ctx.logger,
+            getCurrent: (key) => cfgNow()[key],
+        });
+    }
+    catch (error) {
+        warn(`dsh-topics-memory 旧 settings 迁移失败（不影响启动，下次启动重试）：${error instanceof Error ? error.message : String(error)}`);
+    }
 }
 /** Config defaults for harnesses that skip schemastery's default application. */
 const DEFAULTS = {

package/lib/legacy-import.d.ts

@@ -0,0 +1,94 @@
+/**
+ * One-time legacy settings import for the 0.1.5 → 0.1.7 upgrade: the dsh
+ * 0.1.7 host renames the old `~/.dsh/settings.yaml` to
+ * `settings.yaml.imported` and imports its sections as profile patches keyed
+ * by "section name = entry id". This plugin's old section was named `topics`,
+ * NOT `dsh-topics-memory` — the host's one-shot import silently drops it.
+ * This module recovers it once:
+ *
+ *   1. read `<home>/settings.yaml.imported` (preferred) →
+ *      `<home>/settings.yaml` (fallback);
+ *   2. flat-parse the `topics:` section (scalars only, conservative);
+ *   3. keep keys whose legacy value differs from the current effective value;
+ *   4. `settings.update('dsh-topics-memory', patch)` → on success write the
+ *      audit marker `<home>/storages/dsh-topics-memory/legacy-import.json`;
+ *      on failure warn and write nothing (the next boot retries);
+ *   5. marker present → the whole migration is skipped (idempotent — a
+ *      later manual edit of the imported file must not resurrect old values).
+ *
+ * A marker is written for EVERY settled outcome (imported / no-op /
+ * no-legacy / no-section) so this runs at most once per home. Never throws
+ * into the caller beyond what the apply()-side catch contains: plugin
+ * activation must not depend on this.
+ *
+ * @module legacy-import
+ */
+/** Profile entry id the recovered values are written to. */
+export declare const ENTRY_ID = "dsh-topics-memory";
+/** Legacy top-level section name in the old settings.yaml. */
+export declare const LEGACY_SECTION = "topics";
+/** Storage dir name for the audit marker (repo dir name, host convention). */
+export declare const STORAGE_DIR_NAME = "dsh-topics-memory";
+/** Legacy keys worth recovering, mapped 1:1 onto Config keys of the same name. */
+export declare const LEGACY_KEYS: readonly ["repo", "distillProvider", "distillModel", "topK", "totalBudget", "autoObserve"];
+export type LegacyKey = (typeof LEGACY_KEYS)[number];
+/** The settings seam the import writes through (`ctx.settings.update`). */
+export interface SettingsUpdateSeam {
+    update(ns: string, patch: object): Promise<void>;
+}
+/** Minimal logger surface (both sinks optional — bare harnesses have none). */
+export interface LegacyImportLogger {
+    info?(message: string): void;
+    warn?(message: string): void;
+}
+export interface LegacyImportInput {
+    /** Resolved dsh home (`paths.resolveDshHome()` at the call site). */
+    home: string;
+    /** `ctx.settings` — absent/unusable seams skip the import without a marker. */
+    settings?: SettingsUpdateSeam | undefined;
+    /** Host logger (optional). */
+    logger?: LegacyImportLogger | undefined;
+    /** Current effective value for one legacy key (Volatile ref `.get()` at the call site). */
+    getCurrent(key: LegacyKey): unknown;
+}
+export type LegacyImportOutcome = 'imported' | 'no-op' | 'no-legacy' | 'no-section' | 'marker-exists' | 'no-settings' | 'update-failed';
+export interface LegacyImportResult {
+    outcome: LegacyImportOutcome;
+    /** Keys written through settings.update (also in the marker). */
+    imported: Record<string, unknown>;
+    /** Keys not imported, with the reason (audit trail). */
+    skipped: Record<string, string>;
+}
+/** Candidates in priority order: the host's renamed document first. */
+export declare function legacySettingsCandidates(home: string): string[];
+/** Audit marker path: `<home>/storages/<dir>/legacy-import.json`. */
+export declare function legacyMarkerPath(home: string): string;
+/**
+ * Scalar inference for one flat `key: value` value. Quoted values are
+ * unquoted (mirroring src/yaml.ts); a single-line quoted flow-JSON value
+ * (`'["a","b"]'`) is JSON-parsed after unquoting — a malformed one stays a
+ * string. Unquoted flow collections are kept as strings (conservative:
+ * this is not a full YAML parser). Empty never reaches here (the line
+ * parser skips value-less keys — they open a nested block).
+ */
+export declare function inferScalar(raw: string): unknown;
+/**
+ * Flat section parser: locate the top-level `section:` line and collect its
+ * DIRECT children (`key: value` at one common indent) until the next
+ * top-level key. Deliberately conservative — NOT a YAML parser:
+ * - `key:` with an empty value (opens a nested map/sequence) is skipped, and
+ *   the deeper lines under it never match the child indent, so folded values
+ *   are skipped whole;
+ * - lines at any other indent are ignored;
+ * - an inline value on the header line itself (`section: x`) is not a flat
+ *   map → `{}`.
+ * Pure function — tests run it against literal strings.
+ */
+export declare function parseFlatSection(raw: string, section: string): Record<string, unknown>;
+/**
+ * Run the one-time import. Resolves with the outcome; only throws on truly
+ * unexpected I/O errors (the apply()-side catch contains those). The marker
+ * is written for every settled outcome EXCEPT the retry-worthy failures
+ * (`no-settings`, `update-failed`) — those must re-run at the next boot.
+ */
+export declare function runLegacySettingsImport(input: LegacyImportInput): Promise<LegacyImportResult>;