dsh-plugin-tool-management 0.17.0 → 0.18.0

package/lib/compat/capability-specs.js

@@ -0,0 +1,321 @@
+// 宿主能力表：每一项写明「插件要用宿主的哪个成员、缺了走哪条降级路」。
+//
+// 这张表就是与宿主的契约本体 —— 纯字面量，判定逻辑在 probe.ts 的 inspectCapability，
+// 取数原语在 host-probe.ts。缺一个成员时界面给出的是这一行点名的降级，而不是删除序列
+// 中途抛出的一次异常。
+import { callableWithSentinel, isFn, PROBE_SENTINEL } from './host-probe.js';
+/**
+ * The capability table. This IS the contract with the host: everything the
+ * adapters reach for is listed here with what happens when it is absent, so a
+ * missing member produces a named, visible degradation instead of a throw from
+ * somewhere in the middle of a delete sequence.
+ */
+export const CAPABILITY_SPECS = [
+    // ---- workspace registry: read side -------------------------------------
+    {
+        id: 'workspace.read-state',
+        label: '读取工作区状态',
+        kind: 'read',
+        owner: 'workspace',
+        fallback: 'refuse-operation',
+        methods: ['requireState'],
+        probe: (t) => {
+            try {
+                const state = t.requireState();
+                if (state === null || typeof state !== 'object')
+                    return 'requireState() 未返回对象';
+                const value = state;
+                if (!Array.isArray(value.archivedSessionIds))
+                    return 'requireState().archivedSessionIds 不是数组';
+                if (!Array.isArray(value.workspaceIds))
+                    return 'requireState().workspaceIds 不是数组';
+                return undefined;
+            }
+            catch (error) {
+                return `requireState() 抛错：${String(error?.message ?? error)}`;
+            }
+        },
+    },
+    {
+        id: 'workspace.read-table',
+        label: '读取工作区表',
+        kind: 'read',
+        owner: 'workspace',
+        fallback: 'refuse-operation',
+        methods: ['requireTable'],
+        probe: (t) => {
+            try {
+                const table = t.requireTable();
+                if (table === null || typeof table !== 'object' || !isFn(table.get))
+                    return 'requireTable() 未返回可 get 的表';
+                return undefined;
+            }
+            catch (error) {
+                return `requireTable() 抛错：${String(error?.message ?? error)}`;
+            }
+        },
+    },
+    {
+        id: 'workspace.index-shape',
+        label: '工作区索引结构',
+        kind: 'read',
+        owner: 'workspace',
+        fallback: 'refuse-operation',
+        fields: [
+            { name: 'headers', instanceOf: 'Map' },
+            { name: 'sessionPaths', instanceOf: 'Map' },
+            { name: 'invalidSessionPaths', instanceOf: 'Map' },
+            { name: 'entities', instanceOf: 'Map' },
+        ],
+    },
+    {
+        id: 'workspace.read-header',
+        label: '读取会话头部',
+        kind: 'read',
+        owner: 'workspace',
+        fallback: 'refuse-operation',
+        methods: ['readSessionHeader'],
+    },
+    // ---- workspace registry: write side ------------------------------------
+    {
+        id: 'workspace.enqueue',
+        label: '串行写事务',
+        kind: 'write',
+        owner: 'workspace',
+        fallback: 'disable-destructive',
+        methods: ['enqueueOperation'],
+    },
+    {
+        id: 'workspace.set-state',
+        label: '写工作区状态',
+        kind: 'write',
+        owner: 'workspace',
+        fallback: 'disable-destructive',
+        methods: ['setState'],
+    },
+    {
+        id: 'workspace.index-header',
+        label: '索引会话头部',
+        kind: 'write',
+        owner: 'workspace',
+        fallback: 'disable-destructive',
+        methods: ['indexHeader'],
+    },
+    {
+        id: 'workspace.archive-native',
+        label: '宿主原生归档入口',
+        kind: 'write',
+        owner: 'workspace',
+        fallback: 'native-entry',
+        methods: ['archiveSession'],
+        optional: true,
+        // 分层探针第二层（哨兵真调）：官方实现对未知 id 走读路径校验后受控拒绝
+        //（WorkspaceUnknownSessionError）；同步 TypeError 才是「不该路由信任」的信号。
+        probe: (t) => callableWithSentinel(t, 'archiveSession', PROBE_SENTINEL),
+    },
+    {
+        id: 'workspace.unarchive-native',
+        label: '宿主原生恢复入口',
+        kind: 'write',
+        owner: 'workspace',
+        fallback: 'native-entry',
+        methods: ['unarchiveSession'],
+        optional: true,
+        probe: (t) => callableWithSentinel(t, 'unarchiveSession', PROBE_SENTINEL),
+    },
+    {
+        id: 'workspace.batch-native',
+        label: '宿主原生批量入口',
+        kind: 'write',
+        owner: 'workspace',
+        fallback: 'native-entry',
+        methods: ['archiveWorkspaceSessions'],
+        optional: true,
+        probe: (t) => callableWithSentinel(t, 'archiveWorkspaceSessions', [PROBE_SENTINEL]),
+    },
+    {
+        id: 'workspace.delete-native',
+        label: '宿主原生删除入口',
+        kind: 'delete',
+        owner: 'workspace',
+        // NOT `disable-destructive`: when this slot is empty the plugin performs the
+        // whole delete itself, so nothing is disabled. `native-entry` describes what
+        // actually happens (the adapter takes over).
+        fallback: 'native-entry',
+        methods: ['deleteSession'],
+        optional: true,
+        // 删除路由的 native 判定此前只看方法存在（07 审查五档问题 2）：宿主升级把同名
+        // 方法换成别的签名，路由仍会走 native 裸调。哨兵真调把口径提到「可调用」，
+        // 文本比对收紧（见 inspectCapability 的 delete 类分支）负责「实现漂移」那一层。
+        probe: (t) => callableWithSentinel(t, 'deleteSession', PROBE_SENTINEL),
+    },
+    // ---- sessions runtime (private members, used only on the live branch) ---
+    {
+        id: 'sessions.detach-live',
+        label: '实时会话落盘与分离',
+        kind: 'delete',
+        owner: 'sessions',
+        fallback: 'disable-destructive',
+        methods: ['flush', 'liveEntryFor', 'detachEntered'],
+        // 零副作用真调（按官方源码核对）：liveEntryFor/flush 对哨兵在查表处受控抛错；
+        // detachEntered 传普通对象在未知 id 处早退（entry 形状 {id} 即可）。
+        probe: (t) => callableWithSentinel(t, 'liveEntryFor', PROBE_SENTINEL)
+            ?? callableWithSentinel(t, 'flush', PROBE_SENTINEL)
+            ?? callableWithSentinel(t, 'detachEntered', { id: PROBE_SENTINEL }),
+    },
+    {
+        id: 'sessions.cold-announce',
+        label: '冷会话移除广播',
+        kind: 'delete',
+        owner: 'sessions',
+        fallback: 'disable-destructive',
+        methods: ['enter', 'announce'],
+        // announce 哨兵真调：内部先 liveEntryFor 查表，哨兵输入在查表处受控抛错。
+        // **enter 不真调**（官方实现对任意输入都会往 store 写入条目），它只有存在性 + 文本比对。
+        probe: (t) => callableWithSentinel(t, 'announce', PROBE_SENTINEL),
+    },
+    // ---- projection cache ---------------------------------------------------
+    {
+        id: 'projection.write',
+        label: '投影缓存写入路径',
+        kind: 'write',
+        owner: 'projectionCache',
+        fallback: 'disable-destructive',
+        methods: ['write', 'put', 'requireTable'],
+    },
+    {
+        // B2：此前它只是 bridge 运行时那句拒绝里的**临时 id**（`acquireCacheGuard` 里现场拼的），
+        // 于是客户端压根不知道它 —— 宿主表不可删时，"路由说可用、点下去必拒"（V13）。提升为
+        // 能力表的正式条目后，路由判定与运行时前提同一份依据。
+        id: 'projection.table-delete',
+        label: '投影缓存行删除',
+        kind: 'delete',
+        owner: 'projectionCache',
+        fallback: 'disable-destructive',
+        // 探测内容就是运行时那句硬前提：`requireTable().delete` 在不在。
+        probe: (target) => {
+            if (typeof target?.requireTable !== 'function')
+                return '宿主投影缓存缺少 requireTable';
+            let table;
+            try {
+                table = target.requireTable();
+            }
+            catch (error) {
+                return `宿主投影缓存 requireTable() 抛错：${String(error)}`;
+            }
+            if (typeof table?.delete !== 'function')
+                return '宿主投影缓存存储不支持安全删除（table.delete 缺失）';
+            return undefined;
+        },
+    },
+    {
+        id: 'projection.delete-native',
+        label: '投影缓存删除屏障',
+        kind: 'delete',
+        owner: 'projectionCache',
+        // Absent on rc.2: `sessions/bridge.ts` installs a checked write barrier
+        // instead, so absence is a routing fact, not a failure. Only a cache whose
+        // write path cannot be wrapped at all is a real problem.
+        fallback: 'native-entry',
+        optional: true,
+        probe: (t) => {
+            if (isFn(t?.delete) && isFn(t?.whenIdle))
+                return undefined;
+            const wrappable = ['write', 'put'].filter((name) => !isFn(t?.[name]));
+            if (wrappable.length > 0)
+                return `宿主缓存无法安全包裹（缺少 ${wrappable.join(', ')}）`;
+            let table;
+            try {
+                table = t.requireTable();
+            }
+            catch (error) {
+                return `requireTable() 抛错：${String(error?.message ?? error)}`;
+            }
+            if (!isFn(table?.delete))
+                return '宿主缓存存储不支持行删除（table.delete 缺失）';
+            return undefined;
+        },
+    },
+    // ---- settings document path（0.1.7 的两处适配面之一）----------------------
+    // `prepareDocument()` 在 0.1.7 把返回值从「主目录下的设置文档路径」改成「profile 补丁
+    // 路径」（`configEditor.documentPath`）—— 方法一直在、语义变了，方法存在性探测抓不住
+    // （0.15.0 的 MCP 页事故就是这么静默发生的）。这一条能拦的是「方法消失 / 签名漂移到
+    // 同步抛 TypeError」；**返回值形状**是异步结果，同步探针看不到，那一半由 ensurePaths
+    // 的 await 后自检负责（src/index.ts：认 profile 形状上溯 + 主目录不变量检查，异常走
+    // noteRuntime）。两半合起来才是这个契约的完整探测。
+    {
+        id: 'settings.document-path',
+        label: '设置文档路径（主目录推导源）',
+        kind: 'read',
+        owner: 'settings',
+        fallback: 'refuse-operation',
+        methods: ['prepareDocument'],
+        // 零副作用真调：官方实现就是 `Promise.resolve(this.documentPath)`，纯读。拿不到
+        // 异步结果没关系 —— 同步 TypeError（签名漂移）才是这一层要拦的。
+        probe: (t) => callableWithSentinel(t, 'prepareDocument'),
+        // 健康行也常显观测路径（官方 SettingsForms 有同步的 `documentPath` getter，
+        // prepareDocument 就是它的 Promise 包装）：语义再变，页面上这行字一眼见底。
+        describe: (t) => {
+            try {
+                const p = t.documentPath;
+                return typeof p === 'string' && p !== '' ? `观测路径：${p}` : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+    },
+    // ---- ctx.fs：MCP 域补丁写路径的唯一出口（审查 §5 F5）----------------------
+    // 为什么值得单列：补丁文件在插件自己的数据目录**之外**（`~/.dsh/cordis.patch.yml` 与
+    // `profiles/<名>/cordis.patch.yml`），读写都得经 `ctx.fs` 显式升级沙箱策略。五个方法里
+    // 任何一个改名，19 处补丁写路径会**一起**报错 —— 报错是可见的（不是静默），但要等到用户
+    // 点下去才发现；钉在兼容页上就能在升级后第一眼看见。
+    //
+    // 能探到 / 探不到（如实标注）：成员存在性可探；`writeText` 的**实参个数**可观测（健康行
+    // 附注）。「五个位置参数的语义变了」**探不到** —— 真调它会写文件（有副作用），而本探针
+    // 的纪律是零副作用（见 callableWithSentinel 的副作用口径）。那半条只能靠宿主升级清单人工核对。
+    {
+        id: 'fs.patch-io',
+        label: '宿主文件读写（补丁文件出口）',
+        kind: 'write',
+        owner: 'fs',
+        fallback: 'refuse-operation',
+        methods: ['resolve', 'stat', 'readText', 'writeText', 'listDir'],
+        describe: (t) => {
+            const w = t.writeText;
+            return typeof w === 'function' ? `观测 writeText 实参个数=${w.length}` : undefined;
+        },
+    },
+    // ---- agent preset roster（0.1.7 的两处适配面之二）-------------------------
+    // 0.1.7 把 `read(id)`（直返组合文本）改名成 `readDocument(id)`（返回文档对象，组合
+    // YAML 在 `.content`）。读取口是「read 优先、readDocument 兜底」双入口
+    // （preset-reach.ts 的 readCompositionText），两个名字**任一在场即可** —— 这正是
+    // methods 列表表达不了的 either-or，用 probe 写。list / composedPreset 缺一个，
+    // 注入边界矩阵与边界提示就瞎一半，同为必需。
+    {
+        id: 'preset.roster-surface',
+        label: '预设名册读取面',
+        kind: 'read',
+        owner: 'presetRoster',
+        fallback: 'inform-only',
+        probe: (t) => {
+            const o = t;
+            const hasRead = isFn(o.read);
+            const hasDoc = isFn(o.readDocument);
+            if (!hasRead && !hasDoc)
+                return 'read 与 readDocument 都缺失：组合文本读不到，注入边界矩阵与极简兜底注入失明';
+            const missing = ['list', 'composedPreset'].filter((name) => !isFn(o[name]));
+            if (missing.length > 0)
+                return `名册缺少 ${missing.join(', ')}：注入边界矩阵不完整`;
+            return undefined;
+        },
+        // 健康行附注实际走的读取路。0.1.7 起 `read` 改名 `readDocument`，兜底成功是**正常形态**
+        // 而非降级 —— 这句话只出现在绿色行上（运行时上报会渲染成问题行，那里不放）。
+        describe: (t) => {
+            const o = t;
+            if (!isFn(o.read) && isFn(o.readDocument))
+                return '读取走 readDocument（宿主 0.1.7 起的形态）';
+            return undefined;
+        },
+    },
+];

package/lib/compat/host-probe.js

@@ -0,0 +1,261 @@
+// 宿主能力探测的取数原语：解析包路径、读版本、比对实现文本、取原型、用哨兵实调。
+//
+// 与 probe.ts 的分工：这里只管「怎么探」（怎么把说明符变成一个磁盘路径、怎么读出版本、
+// 怎么真调一个方法而不制造副作用），判定与降级口径全在 probe.ts。搬移段的每一行都
+// 是从 probe.ts 整段剪切而来，未作任何改写；`safeResolve`/`classPrototypeOf` 用的
+// `import.meta.url` 解析基准与本文件原先同在 lib/compat/ 一层，换文件名不改目录，
+// 解析链才没有变（本插件按产物目录深度判形态，见 probe.ts 的 SOURCE_INSTALL）。
+import { createRequire } from 'node:module';
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const isFn = (value) => typeof value === 'function';
+/**
+ * Resolve a package the way this plugin resolves it, without throwing.
+ *
+ * `import.meta.resolve` 给的是**URL**：目录里带空格的路径（桌面版装在
+ * `D:\DeepSeek Harness\...`）会以 `%20` 形式回来，直接当路径用会得到一个
+ * 永远打不开的名字 —— 版本号读不出来（显示 `unknown`）、asar 路径也匹配不上。
+ * 用 `fileURLToPath` 老实解码（它同时处理盘符与百分号转义）。
+ */
+export function safeResolve(specifier) {
+    try {
+        return fileURLToPath(import.meta.resolve(specifier));
+    }
+    catch {
+        try {
+            return createRequire(import.meta.url).resolve(specifier);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * Whether a path lives inside an electron `app.asar` archive.
+ *
+ * 桌面版把整个 DSH 装进 `resources/app.asar`：宿主的 `@deepseek-ai/*` 物理上就在
+ * 归档里，插件（装在 `$DSH_HOME/profiles/<name>/node_modules`）在外面的磁盘上。
+ * 归档里的模块**不可能**与外面的目录是同一个物理文件，`@deepseek-ai/*` 又是
+ * peer（官方包由宿主提供），所以「不同路径」是这种打包方式的必然结果，不是安装
+ * 故障。判据取 `.asar` 这个路径段（`join` 出来的分隔符在 Windows 上是 `\`）。
+ */
+export function isAsarPath(value) {
+    if (value === null)
+        return false;
+    return /[\\/][^\\/]+\.asar[\\/]/i.test(value);
+}
+/**
+ * Resolve a path through every junction/symlink to its physical file.
+ * Node loads modules by real path, so two different-looking paths that
+ * realpath to one file ARE the same module — which is exactly the property
+ * this plugin depends on, and the reason `@deepseek-ai/*` is junctioned into
+ * the host installation instead of being copied.
+ *
+ * 取不到真实形态时**不再拿输入去比**（issue #1 要求）：那会把「路径不可解析」
+ * 伪装成「两份不同拷贝」，给出一个编出来的结论。改由调用方把原因报成说明。
+ */
+export function realPathWithReason(value) {
+    if (value === null)
+        return { reason: '路径为空' };
+    try {
+        return { path: realpathSync.native !== undefined ? realpathSync.native(value) : realpathSync(value) };
+    }
+    catch (error) {
+        const detail = error;
+        const code = typeof detail.code === 'string' ? detail.code : '';
+        const message = typeof detail.message === 'string' ? detail.message : String(error);
+        return { reason: code === '' ? message : `${code} ${message}` };
+    }
+}
+/** Read a package version from a resolvable manifest. */
+export function versionOf(specifier) {
+    const entry = safeResolve(specifier);
+    if (entry === null)
+        return undefined;
+    let dir = dirname(entry);
+    for (let i = 0; i < 4; i += 1) {
+        try {
+            const parsed = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+            if (parsed.name === specifier && typeof parsed.version === 'string')
+                return parsed.version;
+        }
+        catch {
+            /* keep walking up */
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * Version of the package a resolved entry path belongs to: walk up until a
+ * `package.json` whose `name` matches the package directory we came from.
+ *
+ * 与 `versionOf` 的分工：那个从**说明符**出发（要能解析），这个从**已经拿到的路径**
+ * 出发。归档宿主那种「路径不同但版本相同」的判断只能用后者 —— 前者在 `.asar` 里
+ * 读得动，但两边路径不同时它无法回答「这两个文件各属于哪个版本」。
+ */
+export function versionOfPackageAt(entry) {
+    const expected = packageNameOfPath(entry);
+    let dir = dirname(entry);
+    for (let i = 0; i < 5; i += 1) {
+        try {
+            const parsed = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+            if (typeof parsed.version === 'string' && (expected === null || parsed.name === expected))
+                return parsed.version;
+        }
+        catch { /* keep walking up */ }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/** `.../node_modules/@scope/name/lib/index.js` -> `@scope/name` (null when the path has no such segment). */
+function packageNameOfPath(entry) {
+    const parts = entry.split(/[\\/]/);
+    const at = parts.lastIndexOf('node_modules');
+    if (at === -1 || at + 1 >= parts.length)
+        return null;
+    const first = parts[at + 1];
+    if (first === undefined)
+        return null;
+    if (first.startsWith('@')) {
+        const second = parts[at + 2];
+        return second === undefined ? null : `${first}/${second}`;
+    }
+    return first;
+}
+/**
+ * Compare a live member with this plugin's copy of the implementation.
+ * `undefined` means "not comparable" — the member is absent on the live object
+ * or the reference copy does not have it either.
+ */
+export function textMatchOf(live, reference) {
+    if (!isFn(live) || !isFn(reference))
+        return undefined;
+    if (live === reference)
+        return true;
+    try {
+        return Function.prototype.toString.call(live) === Function.prototype.toString.call(reference);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The prototype that defines a live instance's members, following the prototype
+ * chain so proxies, subclass instances and cross-realm objects all answer
+ * honestly.
+ */
+function prototypeOf(instance) {
+    if (instance === null || typeof instance !== 'object')
+        return undefined;
+    if (typeof instance === 'function')
+        return instance;
+    const proto = Object.getPrototypeOf(instance);
+    return proto !== null && typeof proto === 'object' ? proto : undefined;
+}
+// The official package + class each capability owner's members live on. This is
+// the single answer to "which class defines this owner" — both the live
+// reference-prototype lookup below and the exported static table read it, so a
+// host drift is described in exactly one place.
+const WORKSPACE_CLASS = { pkg: '@deepseek-ai/dsh-workspace', target: 'WorkspaceRegistry' };
+const PROJECTION_CLASS = { pkg: '@deepseek-ai/dsh-session-projection-cache', target: 'SessionProjectionCache' };
+// `sessions.*` members are host-private members, but they are still declared on
+// an official class: `@deepseek-ai/dsh-session` is a peer this plugin declares,
+// and `SessionStore` is where `flush`/`liveEntryFor`/`detachEntered`/`enter`/
+// `announce` live. Without this entry the doctor could not see the two
+// capabilities the delete route depends on.
+const SESSIONS_CLASS = { pkg: '@deepseek-ai/dsh-session', target: 'SessionStore' };
+// 0.15.0 新增的两块契约面 —— 恰是 0.1.7 升级咬人的两处（prepareDocument 返回语义变了、
+// read 改名 readDocument），此前不在表里，故障只能靠用户实测发现。类名按官方安装源码核对
+// （dsh-settings 导出 SettingsForms；dsh-agent-preset-registry 导出 AgentPresetRegistry）。
+const SETTINGS_CLASS = { pkg: '@deepseek-ai/dsh-settings', target: 'SettingsForms' };
+const ROSTER_CLASS = { pkg: '@deepseek-ai/dsh-agent-preset-registry', target: 'AgentPresetRegistry' };
+export const OWNER_CLASSES = {
+    workspace: WORKSPACE_CLASS,
+    projectionCache: PROJECTION_CLASS,
+    sessions: SESSIONS_CLASS,
+    settings: SETTINGS_CLASS,
+    presetRoster: ROSTER_CLASS,
+};
+/** The named export's prototype, or undefined when the package is absent/trimmed. */
+function classPrototypeOf(ref) {
+    try {
+        const mod = createRequire(import.meta.url)(ref.pkg);
+        const klass = mod[ref.target];
+        return klass?.prototype;
+    }
+    catch {
+        return undefined; // optional in tests and in trimmed deployments
+    }
+}
+/**
+ * 哨兵值：不可能命中任何真实会话/工作区（会话 id 由宿主生成，不含此串）。
+ * 行为探针真调宿主方法时一律传它 —— 最坏情形是宿主受控拒绝（not found），
+ * 而「哨兵输入都能产生意外效果」本身就是要探出来的「不该路由信任」。
+ */
+export const PROBE_SENTINEL = '__dshm_probe_never_exists__';
+/**
+ * 用哨兵实参**真调**一个宿主方法（2026-09-19 分层探针第二层），验证「存在且可调用」：
+ * - 同步抛 `TypeError` → 实现坏了/签名漂移，返回失败详情（shape-mismatch）；
+ * - 受控同步拒绝（普通 `Error`，如 not found）或返回值（含 rejected Promise）→ 通过。
+ *
+ * 只判同步段：探针框架是同步的（`assessHost` 不能 await），异步结果分类留待
+ * 异步化改造（见审查 07 跟进项）。返回的 Promise 一律挂 `.catch` 吞掉，探针
+ * 不制造 unhandled rejection。调用必须以 `target` 为 receiver —— 私有方法全靠
+ * `this.*` 拿内部状态，脱离 receiver 调用会把好实现误判成 TypeError。
+ *
+ * 副作用口径（按官方源码逐个核过）：liveEntryFor/announce/flush 哨兵输入在
+ * 查表处受控抛错，零副作用；detachEntered 传普通对象在未知 id 处早退；
+ * deleteSession/archiveSession 等原生入口对未知 id 是读路径校验后受控拒绝。
+ * `enter` 不在此列（会往 store 里写哨兵条目），它只做存在性 + 文本比对。
+ */
+export function callableWithSentinel(target, name, ...args) {
+    try {
+        const method = target[name];
+        if (!isFn(method))
+            return `${name} 不是函数（methods 检查应已拦下，此处兜底）`;
+        const returned = method.call(target, ...args);
+        if (returned !== null && typeof returned === 'object' && isFn(returned.then)) {
+            const settled = returned;
+            if (isFn(settled.catch))
+                settled.catch(() => { });
+        }
+        return undefined;
+    }
+    catch (error) {
+        if (error instanceof TypeError)
+            return `${name} 哨兵真调抛 TypeError：${String(error?.message ?? error)}`;
+        return undefined;
+    }
+}
+/** Official prototypes this plugin's adapters mirror, when importable. */
+export function referencePrototypes() {
+    const out = {};
+    const workspace = classPrototypeOf(WORKSPACE_CLASS);
+    if (workspace !== undefined)
+        out.workspace = workspace;
+    const cache = classPrototypeOf(PROJECTION_CLASS);
+    if (cache !== undefined)
+        out.cache = cache;
+    // sessions 的五个私有方法全声明在官方 SessionStore.prototype 上（本插件 peer 依赖
+    // 同包同版本），与 workspace/cache 同机制接入文本比对 —— 此前该域只有存在性检查。
+    const sessions = classPrototypeOf(SESSIONS_CLASS);
+    if (sessions !== undefined)
+        out.sessions = sessions;
+    // 两块新契约面的参考副本：包不在 devDeps/宿主锚点里时优雅缺省（textMatch 记 undefined），
+    // 存在性探测不依赖它们。
+    const settings = classPrototypeOf(SETTINGS_CLASS);
+    if (settings !== undefined)
+        out.settings = settings;
+    const roster = classPrototypeOf(ROSTER_CLASS);
+    if (roster !== undefined)
+        out.roster = roster;
+    return out;
+}