dsh-plugin-tool-management 0.5.1 → 0.6.0

package/lib/compat/probe.js

@@ -0,0 +1,665 @@
+/**
+ * Host capability probe — the single place that decides what this plugin may
+ * do to the running host's data, and why not when it may not.
+ *
+ * WHY THIS REPLACES THE TEXT-COMPARISON GATE
+ * ------------------------------------------
+ * The previous gate in `history/bridge.js` compared each host method against
+ * this plugin's own copy of the official prototype with
+ * `Function.prototype.toString()`. That only ever answered one question —
+ * "is the host running the same release I was written against?" — and it
+ * answered it with a hard throw, so a harmless upstream refactor disabled
+ * whole features. It also quietly assumed the plugin and the host load two
+ * *different* copies of the same package.
+ *
+ * The durable questions are different:
+ *
+ *   - IDENTITY: do the plugin and the host share the same physical module?
+ *     (If yes, `===`, `instanceof` and symbol lookups cross the boundary and
+ *     every "same implementation" concern disappears. Missing identity is a
+ *     deployment defect, reported as such, not something to guess around.)
+ *   - PRESENCE: does the live host object expose the members the adapter
+ *     calls? Members are checked as live values with their shape, because a
+ *     host may have been upgraded, proxied, or replaced wholesale.
+ *   - BEHAVIOUR: for anything that can be observed without mutating host
+ *     state, call it and look at the result — a getter that no longer returns
+ *     a Map is a fact, a version string is a hint.
+ *
+ * Every answer is reported per capability instead of collapsing into one
+ * boolean, so a caller can degrade exactly the feature that lost support and
+ * leave the rest working.
+ */
+import { createRequire } from 'node:module';
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/** Packages whose physical module identity matters to this plugin. */
+export const IDENTITY_PACKAGES = [
+    '@deepseek-ai/cordis',
+    '@deepseek-ai/dsh-tools',
+    '@deepseek-ai/dsh-workspace',
+    '@deepseek-ai/dsh-session-projection-cache',
+    '@deepseek-ai/dsh-storage-domain',
+    '@deepseek-ai/dsh-spill-local',
+];
+/** Peers this plugin was written and verified against. */
+export const EXPECTED_PEER_RANGE = '>=0.1.5-rc.2 <0.2.0-0';
+/** The release this plugin's adapters were last verified against. */
+export const VERIFIED_HOST_VERSION = '0.1.5-rc.2';
+const isFn = (value) => typeof value === 'function';
+/** Resolve a package the way this plugin resolves it, without throwing. */
+function safeResolve(specifier) {
+    try {
+        return import.meta.resolve(specifier).replace(/^file:\/\/\//, '').replace(/\//g, process.platform === 'win32' ? '\\' : '/');
+    }
+    catch {
+        try {
+            return createRequire(import.meta.url).resolve(specifier);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * 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.
+ */
+function realPathOf(value) {
+    if (value === null)
+        return null;
+    try {
+        return realpathSync.native !== undefined ? realpathSync.native(value) : realpathSync(value);
+    }
+    catch {
+        return value;
+    }
+}
+/** Read a package version from a resolvable manifest. */
+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;
+}
+/**
+ * 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.
+ */
+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;
+}
+/** Official prototypes this plugin's adapters mirror, when importable. */
+function referencePrototypes() {
+    const out = {};
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const ws = createRequire(import.meta.url)('@deepseek-ai/dsh-workspace');
+        if (ws.WorkspaceRegistry?.prototype !== undefined)
+            out.workspace = ws.WorkspaceRegistry.prototype;
+    }
+    catch { /* optional in tests and in trimmed deployments */ }
+    try {
+        const pc = createRequire(import.meta.url)('@deepseek-ai/dsh-session-projection-cache');
+        if (pc.SessionProjectionCache?.prototype !== undefined)
+            out.cache = pc.SessionProjectionCache.prototype;
+    }
+    catch { /* optional in tests */ }
+    return out;
+}
+/**
+ * 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.
+ */
+const CAPABILITY_SPECS = [
+    // ---- workspace registry: read side -------------------------------------
+    {
+        id: 'workspace.read-state',
+        label: '读取工作区状态',
+        kind: 'read',
+        owner: 'workspace',
+        fallback: 'degrade-read',
+        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: 'degrade-read',
+        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: 'degrade-read',
+        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: 'degrade-read',
+        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: 'workspace.unarchive-native',
+        label: '宿主原生恢复入口',
+        kind: 'write',
+        owner: 'workspace',
+        fallback: 'native-entry',
+        methods: ['unarchiveSession'],
+        optional: true,
+    },
+    {
+        id: 'workspace.batch-native',
+        label: '宿主原生批量入口',
+        kind: 'write',
+        owner: 'workspace',
+        fallback: 'native-entry',
+        methods: ['archiveWorkspaceSessions'],
+        optional: true,
+    },
+    {
+        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,
+    },
+    // ---- 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'],
+    },
+    {
+        id: 'sessions.cold-announce',
+        label: '冷会话移除广播',
+        kind: 'delete',
+        owner: 'sessions',
+        fallback: 'disable-destructive',
+        methods: ['enter', 'announce'],
+    },
+    // ---- projection cache ---------------------------------------------------
+    {
+        id: 'projection.write',
+        label: '投影缓存写入路径',
+        kind: 'write',
+        owner: 'projectionCache',
+        fallback: 'disable-destructive',
+        methods: ['write', 'put', 'requireTable'],
+    },
+    {
+        id: 'projection.delete-native',
+        label: '投影缓存删除屏障',
+        kind: 'delete',
+        owner: 'projectionCache',
+        // Absent on rc.2: `history/bridge.js` 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;
+        },
+    },
+];
+/**
+ * The capability sets each operation depends on, grouped by how the plugin
+ * reaches the same outcome when a member is missing. Order matters: the first
+ * viable route wins.
+ *
+ * - `native`: host entry points that already implement the whole operation.
+ * - `adapter`: the checked compatibility adapter (the only route that touches
+ *   private members), used when the host has no native entry.
+ */
+export const OPERATION_ROUTES = {
+    archive: { native: ['workspace.archive-native'], adapter: ['workspace.enqueue', 'workspace.set-state'] },
+    unarchive: { native: ['workspace.unarchive-native'], adapter: ['workspace.enqueue', 'workspace.set-state'] },
+    batch: { native: ['workspace.batch-native'], adapter: ['workspace.enqueue', 'workspace.set-state'] },
+    delete: {
+        native: ['workspace.delete-native'],
+        // NOTE: `projection.delete-native` is deliberately NOT a route requirement.
+        // A host cache without its own delete barrier is expected on rc.2; the
+        // bridge wraps it (`workspace.js` / `history/bridge.js`) and reports a
+        // refusal itself when even that is impossible. Requiring the native barrier
+        // here would disable deletion on exactly the host this plugin was verified
+        // against.
+        adapter: [
+            'workspace.enqueue', 'workspace.set-state', 'workspace.index-header',
+            'sessions.detach-live', 'sessions.cold-announce', 'projection.write',
+        ],
+    },
+    list: { native: [], adapter: ['workspace.read-state', 'workspace.read-table', 'workspace.index-shape'] },
+};
+/** Texts a user can act on, per capability, when it is the reason for a refusal. */
+function recoveryFor(_finding) {
+    return `宿主 ${VERIFIED_HOST_VERSION} 的该项能力未通过探测；请更新本插件到与本机 DSH 匹配的版本，或改用宿主原生入口（先运行 node scripts/doctor.mjs 查看差异）。`;
+}
+/**
+ * One capability's result. `target` is the live host object; `reference` is
+ * this plugin's copy of the same implementation when the package is importable.
+ */
+function inspectCapability(spec, target, reference) {
+    const base = {
+        id: spec.id,
+        label: spec.label,
+        kind: spec.kind,
+        owner: spec.owner,
+        fallback: spec.fallback,
+        ...(spec.optional === true ? { optional: true } : {}),
+    };
+    if (target === undefined || target === null) {
+        return { ...base, state: 'not-available', detail: '宿主未提供该服务（ctx.get 返回 undefined）', missing: [] };
+    }
+    if (spec.when !== undefined && !spec.when(target)) {
+        return { ...base, state: 'ok', detail: '当前分支不需要（按实时/冷会话路径判定）', missing: [] };
+    }
+    const missing = [];
+    let textMatch;
+    for (const name of spec.methods ?? []) {
+        const live = target[name];
+        if (!isFn(live)) {
+            missing.push(name);
+            continue;
+        }
+        const match = textMatchOf(live, reference?.[name]);
+        if (match === false && textMatch !== false)
+            textMatch = false;
+        else if (match === true && textMatch === undefined)
+            textMatch = true;
+    }
+    for (const field of spec.fields ?? []) {
+        const value = target[field.name];
+        if (field.instanceOf === 'Map' && !(value instanceof Map))
+            missing.push(`${field.name}(非 Map)`);
+        else if (field.instanceOf === 'Array' && !Array.isArray(value))
+            missing.push(`${field.name}(非数组)`);
+        else if (field.instanceOf === 'Set' && !(value instanceof Set))
+            missing.push(`${field.name}(非 Set)`);
+    }
+    if (missing.length > 0) {
+        return {
+            ...base,
+            state: 'missing-member',
+            detail: `宿主实现缺少 ${missing.join(', ')}`,
+            missing,
+            ...(textMatch === undefined ? {} : { textMatch }),
+        };
+    }
+    if (spec.probe !== undefined) {
+        const failure = spec.probe(target);
+        if (failure !== undefined) {
+            return { ...base, state: 'shape-mismatch', detail: failure, missing: [], ...(textMatch === undefined ? {} : { textMatch }) };
+        }
+    }
+    return {
+        ...base,
+        state: 'ok',
+        detail: textMatch === false ? '成员齐备（实现文本与本插件适配的版本不同，按能力使用）' : '成员齐备',
+        missing: [],
+        ...(textMatch === undefined ? {} : { textMatch }),
+    };
+}
+/**
+ * Capability ids whose absence is a routing fact rather than a failure: the
+ * plugin substitutes its own implementation. They never appear as degraded and
+ * never block a route.
+ *
+ * Superseded by {@link CapabilityFinding.optional}, which marks the same fact on
+ * the finding itself (the UI and the doctor both read that flag). Kept as the
+ * exported id list so callers can ask "which slots does the plugin itself back?"
+ * without duplicating the table.
+ */
+export const SUBSTITUTED_CAPABILITIES = CAPABILITY_SPECS
+    .filter((spec) => spec.optional === true)
+    .map((spec) => spec.id);
+/**
+ * Inspect the live host behind one plugin context.
+ *
+ * Everything is read-only: the only host code paths touched are getters and
+ * `requireState()`/`requireTable()`, both of which the plugin already calls on
+ * every list request. A failure inside a probe is a finding, never a throw.
+ *
+ * @param ctx - the plugin's cordis context.
+ * @returns the assessment snapshot surfaced to the UI, the tools and the log.
+ */
+export function assessHost(ctx) {
+    const get = (name) => {
+        try {
+            return typeof ctx.get === 'function' ? ctx.get(name) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    // Cordis exposes traceable proxies; compare and inspect the original objects.
+    const unwrap = (value) => {
+        if (value === null || typeof value !== 'object')
+            return value;
+        try {
+            const original = value[Symbol.for('cordis.original')];
+            if (original !== undefined)
+                return original;
+        }
+        catch { /* ignore */ }
+        return value;
+    };
+    const registry = unwrap(get('workspaceRegistry'));
+    const cache = unwrap(get('sessionProjectionCache'));
+    const sessions = unwrap(ctx.sessions !== undefined ? ctx.sessions : get('sessions'));
+    const references = referencePrototypes();
+    const targets = {
+        workspace: { target: registry, reference: references.workspace },
+        projectionCache: { target: cache, reference: references.cache },
+        sessions: { target: sessions, reference: undefined },
+        persistence: { target: unwrap(get('sessionPersistence')), reference: undefined },
+    };
+    const findings = CAPABILITY_SPECS.map((spec) => {
+        const slot = targets[spec.owner];
+        return inspectCapability(spec, slot.target, slot.reference);
+    });
+    // Identity: is the plugin loading the same physical modules the host runs?
+    const modules = {};
+    const sameAsHost = {};
+    const blockers = [];
+    const hostRoot = hostPackageRoot();
+    for (const name of IDENTITY_PACKAGES) {
+        const resolved = safeResolve(name);
+        modules[name] = resolved;
+        if (resolved === null) {
+            sameAsHost[name] = null;
+            blockers.push(`${name}：无法解析`);
+            continue;
+        }
+        if (hostRoot === null) {
+            sameAsHost[name] = null;
+            continue;
+        }
+        // Resolve the same name from the host installation's own anchor, then
+        // compare PHYSICAL files: a junction is the same module, not a copy.
+        let hostResolved = null;
+        try {
+            const hostRequire = createRequire(join(dirname(hostRoot), 'package.json'));
+            hostResolved = hostRequire.resolve(name);
+        }
+        catch {
+            hostResolved = null;
+        }
+        const same = hostResolved === null ? null : realPathOf(hostResolved) === realPathOf(resolved);
+        sameAsHost[name] = same;
+        if (same === false)
+            blockers.push(`${name}：插件与宿主加载的是两份不同拷贝（运行 node scripts/host-deps.mjs --fix）`);
+    }
+    // Degraded = something is genuinely unavailable. Optional slots are excluded:
+    // their absence selects the adapter route and leaves the feature fully
+    // working, so listing them here would tell the user a working feature is
+    // broken (and, with the destructive wording, that its buttons are disabled).
+    const degraded = findings.filter((finding) => finding.state !== 'ok' && finding.optional !== true);
+    // Deletion is possible when SOME route reaches it. The optional native
+    // delegate slots (`workspace.delete-native`, `workspace.unarchive-native`,
+    // `workspace.batch-native`) are expected to be ABSENT on hosts whose official
+    // API lacks those entry points — that absence selects the adapter route, it
+    // does not mean deletion is impossible.
+    const delta = routeFor({ findings }, 'delete').via !== 'none';
+    return {
+        identity: {
+            version: versionOf('@deepseek-ai/dsh-workspace') ?? 'unknown',
+            modules,
+            sameAsHost,
+            blockers,
+        },
+        findings,
+        degraded,
+        mayDelete: delta,
+        generatedAt: Date.now(),
+    };
+}
+/** True when two paths denote the same file; falls back to string equality. */
+function samePath(a, b) {
+    const normalize = (value) => value.replace(/\\/g, '/').toLowerCase();
+    return normalize(realPathOf(a) ?? a) === normalize(realPathOf(b) ?? b);
+}
+/**
+ * The `@deepseek-ai` directory of the DSH installation this plugin is attached
+ * to, derived from where a shared package physically lives.
+ *
+ * Anchoring on the resolved entry rather than on `require.resolve('@deepseek-ai/dsh')`
+ * matters: the plugin never imports the `dsh` app package, so it need not be
+ * resolvable from the plugin at all — only the shared libraries are.
+ */
+function hostPackageRoot() {
+    for (const anchor of IDENTITY_PACKAGES) {
+        const resolved = realPathOf(safeResolve(anchor));
+        if (resolved === null)
+            continue;
+        let dir = dirname(resolved);
+        for (let i = 0; i < 3; i += 1) {
+            if (dir.endsWith(join('node_modules', '@deepseek-ai')))
+                return dir;
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return null;
+}
+/** Human-readable summary line for logs and the settings page header. */
+export function summarize(assessment) {
+    const total = assessment.findings.length;
+    const ok = total - assessment.degraded.length;
+    const state = assessment.degraded.length === 0 ? '全部可用' : `降级 ${assessment.degraded.length} 项`;
+    return `宿主 ${assessment.identity.version} · 能力 ${ok}/${total} · ${state}`;
+}
+/** Findings by id, for route decisions. */
+export function findingsById(assessment) {
+    return new Map(assessment.findings.map((finding) => [finding.id, finding]));
+}
+/** Refusals for every degraded capability in the list, in list order. */
+export function refusalsFor(assessment, ids) {
+    const index = findingsById(assessment);
+    const out = [];
+    for (const id of ids) {
+        const finding = index.get(id);
+        if (finding === undefined || finding.state === 'ok')
+            continue;
+        out.push({ id: finding.id, label: finding.label, detail: finding.detail, recovery: recoveryFor(finding) });
+    }
+    return out;
+}
+/**
+ * Choose how one operation should reach the host.
+ *
+ * Never silently falls back from a partially available route into a destructive
+ * one: a route is chosen only when every capability it needs is `ok`.
+ *
+ * @param assessment - latest host assessment.
+ * @param operation - operation name from {@link OPERATION_ROUTES}.
+ * @returns the route to take plus, when `none`, what is missing and why.
+ */
+export function routeFor(assessment, operation) {
+    const routes = OPERATION_ROUTES[operation];
+    const index = findingsById(assessment);
+    const allOk = (ids) => ids.every((id) => {
+        const finding = index.get(id);
+        // A capability that the host does not expose at all cannot block a route
+        // it is not part of; absent ids are treated as satisfied.
+        return finding === undefined || finding.state === 'ok';
+    });
+    if (routes.native.length > 0 && allOk(routes.native))
+        return { via: 'native', refusals: [] };
+    if (allOk(routes.adapter))
+        return { via: 'adapter', refusals: [] };
+    const needed = routes.native.length > 0 ? [...new Set([...routes.native, ...routes.adapter])] : routes.adapter;
+    const refusals = refusalsFor(assessment, needed);
+    if (refusals.length > 0)
+        return { via: 'none', refusals };
+    return {
+        via: 'none',
+        refusals: [{
+                id: operation,
+                label: operation,
+                detail: '宿主未提供该操作的任何可用路径',
+                recovery: recoveryFor({ id: operation }),
+            }],
+    };
+}
+/**
+ * The error a refused operation throws. Kept as a distinct class so callers can
+ * tell "the host cannot do this safely" from "the operation failed".
+ */
+export class CapabilityRefusalError extends Error {
+    operation;
+    refusals;
+    constructor(operation, refusals) {
+        super(`宿主不支持该操作（${operation}）：`
+            + refusals.map((item) => `${item.label} — ${item.detail}`).join('；')
+            + '。为避免用未知实现改动数据，操作在任何写入之前停止。'
+            + (refusals[0]?.recovery !== undefined ? ` ${refusals[0].recovery}` : ''));
+        this.name = 'CapabilityRefusalError';
+        this.operation = operation;
+        this.refusals = refusals;
+    }
+}
+/** Throw unless the assessment allows the operation through some route. */
+export function requireRoute(assessment, operation) {
+    const decision = routeFor(assessment, operation);
+    if (decision.via === 'none')
+        throw new CapabilityRefusalError(operation, decision.refusals);
+    return decision;
+}