dsh-agent-plugins-market 0.9.0 → 0.9.2

package/lib/packages/market-runtime/src/runtime/core/reconciler.js

@@ -0,0 +1,457 @@
+import { isDeepStrictEqual } from 'node:util';
+import { CommandMountRegistry } from '../surfaces/commands-mounts.js';
+import { HooksMountRegistry } from '../surfaces/hooks-mounts.js';
+import { projectExtensionSuites } from '../../application/extension-suite-selection.js';
+import { captureExtensionSelection } from '../../../../market-contracts/src/contracts/extension-presets.js';
+import { bindHostLocale } from '../host/host-locale.js';
+export class RuntimeReconciler {
+    mcp;
+    commands;
+    hooks;
+    lspRegistry;
+    queues = new Map();
+    gates;
+    disposed = false;
+    agentScopedContributors = false;
+    authority;
+    authorityEpoch = 0;
+    globalSuites = [];
+    committed = new Map();
+    staged = new Map();
+    sharedQueue = Promise.resolve();
+    demandedMcp = new Map();
+    demandedLsp = new Set();
+    overridesProvider = async () => new Map();
+    disposal;
+    warn;
+    /**
+     * @param ctx - the context every mount registers through.
+     * @param dataRoot - the plugin data root the mount adapters store under.
+     * @param mounts - the transport adapters this coordinator drives. The
+     * composition root builds them, so no transport package is imported here.
+     * @param t - host translator for the command registry's own diagnostics.
+     */
+    constructor(ctx, dataRoot, mounts, t = bindHostLocale(undefined)) {
+        this.mcp = mounts.mcp;
+        this.commands = new CommandMountRegistry(ctx, t, dataRoot);
+        this.hooks = new HooksMountRegistry(ctx);
+        this.lspRegistry = mounts.lsp;
+        this.lspRegistry.setPluginDataRoot(dataRoot);
+        this.lspRegistry.setDemandedProviderIdsProvider(() => this.demandedLsp);
+        this.warn = message => ctx.logger?.warn(message);
+        this.mcp.setOverridesProvider(async () => {
+            const overrides = new Map(await this.overridesProvider());
+            for (const [suiteId, keys] of this.demandedMcp) {
+                const rows = { ...overrides.get(suiteId) };
+                for (const key of keys)
+                    rows[key] = { ...rows[key], enabled: true };
+                overrides.set(suiteId, rows);
+            }
+            return overrides;
+        });
+    }
+    /** Transfer commands and hooks to per-agent registries; call before the first reconcile. */
+    setAgentScopedContributors() {
+        this.agentScopedContributors = true;
+    }
+    /** Exact live MCP definitions and their owning extension resources. */
+    mcpToolOwnership() {
+        return this.mcp.toolOwnership();
+    }
+    /** The LSP mount registry, consumed by the LSP status surface. */
+    get lsp() {
+        return this.lspRegistry;
+    }
+    /** The suite commands the global layer currently holds, for the slash menu's row faces. */
+    commandRegistrations() {
+        return this.commands.registrations();
+    }
+    /** Install the per-workspace entry filter on the MCP mount registry. */
+    setMcpEntryFilter(filter) {
+        this.mcp.setEntryFilter(filter);
+    }
+    /** Install the per-workspace entry filter on the command mount registry. */
+    setCommandsEntryFilter(filter) {
+        this.commands.setEntryFilter(filter);
+    }
+    /**
+     * Install the per-workspace surface gates, read on every pass.
+     *
+     * Set after construction because the toggle service is built later in
+     * composition; until then every surface mounts, which is the all-on default.
+     */
+    setSurfaceGates(gates) {
+        this.gates = gates;
+    }
+    /** Install the per-suite MCP overrides provider used at mount time. */
+    setMcpOverridesProvider(provider) {
+        this.overridesProvider = provider;
+    }
+    /** Install the live tool-name provider used for foreign-namespace mount guards. */
+    setMcpToolNamesProvider(provider) {
+        this.mcp.setToolNamesProvider(provider);
+    }
+    /** Install the backend provider deciding which MCP client mounts each server. */
+    setMcpBackendProvider(provider) {
+        this.mcp.setBackendProvider(provider);
+    }
+    /** Whether the current MCP snapshot uses one credential reference. */
+    usesCredential(ref) {
+        return this.mcp.usesCredential(ref);
+    }
+    /** Flag one MCP mount for an explicit rebuild on the next reconcile. */
+    forceMcpRemount(suiteId, serverKey) {
+        this.mcp.forceRemount(suiteId, serverKey);
+    }
+    /** Flag every live MCP mount for a rebuild on the next reconcile. */
+    forceMcpRemountAll() {
+        this.mcp.forceRemountAll();
+    }
+    /** The mount key owning one derived serverName; undefined when not mounted here. */
+    mcpServerOwner(serverName) {
+        return this.mcp.serverOwner(serverName);
+    }
+    /** Publish fresh immutable authority without mounting or waiting behind network work. */
+    setCatalogAuthority(candidates, global) {
+        if (this.disposed)
+            return;
+        if (isDeepStrictEqual(this.authority, candidates) && isDeepStrictEqual(this.globalSuites, global))
+            return;
+        this.authorityEpoch++;
+        this.authority = structuredClone([...candidates]);
+        this.globalSuites = structuredClone([...global]);
+    }
+    /** Update full validated authority and the ordinary global base in one shared-service pass. */
+    refreshCatalog(candidates, global) {
+        return this.reconcileSnapshot(global, structuredClone([...candidates]));
+    }
+    /** Legacy enabled-only refresh never replaces full authority or session demand. */
+    reconcile(global) {
+        return this.reconcileSnapshot(global);
+    }
+    async reconcileSnapshot(global, authority) {
+        const diagnostics = emptyDiagnostics();
+        if (this.disposed)
+            return diagnostics;
+        const captured = structuredClone([...global]);
+        if (authority !== undefined)
+            this.setCatalogAuthority(authority, captured);
+        else if (!isDeepStrictEqual(this.globalSuites, captured)) {
+            this.authorityEpoch++;
+            this.globalSuites = captured;
+        }
+        const local = Promise.all([
+            this.surface('commands', diagnostics, () => this.commands.reconcile(this.agentScopedContributors || this.gates?.allows('commands') === false ? [] : captured)),
+            this.surface('hooks', diagnostics, () => this.hooks.reconcile(this.agentScopedContributors ? [] : captured))
+        ]);
+        const shared = this.enqueue(async () => {
+            if (this.disposed)
+                return;
+            const result = await this.reconcileShared();
+            diagnostics.mcp = result.mcp;
+            diagnostics.lsp = result.lsp;
+            diagnostics.errors.push(...result.errors);
+        });
+        await Promise.all([local, shared]);
+        return diagnostics;
+    }
+    surface(key, diagnostics, work) {
+        const run = (this.queues.get(key) ?? Promise.resolve()).then(async () => {
+            if (this.disposed)
+                return;
+            try {
+                diagnostics[key] = await work();
+            }
+            catch (error) {
+                diagnostics.errors.push({ surface: key, reason: messageOf(error) });
+            }
+        });
+        this.queues.set(key, run);
+        return run;
+    }
+    enqueue(work) {
+        const run = this.sharedQueue.then(work);
+        this.sharedQueue = run.catch(() => undefined);
+        return run;
+    }
+    /** Stage only identities; configuration always comes from current validated authority. */
+    stageSessionDemand(owner, requested, directLspIds = []) {
+        const ids = demandIds(requested);
+        for (const id of directLspIds) {
+            if (!id.startsWith('direct/') || id.length === 7 || Array.from(id).some(character => character.charCodeAt(0) < 32 || character.charCodeAt(0) === 127))
+                return Promise.reject(new Error('extension-shared-invalid-direct-lsp'));
+            ids.add('lsp:' + id);
+        }
+        return (async () => {
+            if (this.disposed || this.authority === undefined)
+                throw new Error('extension-shared-not-ready');
+            if (this.staged.has(owner))
+                throw new Error('extension-shared-demand-busy');
+            const token = { ids, active: true, ready: false };
+            this.staged.set(owner, token);
+            let mounted = false;
+            const covered = new Set();
+            try {
+                const epoch = this.authorityEpoch;
+                const projected = this.project(ids);
+                const eligible = demandIds(projected);
+                for (const id of ids)
+                    if (id.startsWith('lsp:direct/'))
+                        eligible.add(id);
+                if ([...ids].some(id => !eligible.has(id)))
+                    throw new Error('extension-shared-demand-unavailable');
+                const overrides = await this.overridesProvider();
+                const disabledLsp = await this.lspRegistry.globalDisabledProviderIds();
+                if (epoch !== this.authorityEpoch)
+                    throw new Error('extension-shared-catalog-conflict');
+                const activation = projected.map(suite => {
+                    const row = structuredClone(suite);
+                    const key = suiteKey(suite);
+                    const base = this.globalSuites.find(candidate => suiteKey(candidate) === key);
+                    if (row.mcp)
+                        row.mcp.servers = Object.fromEntries(Object.entries(row.mcp.servers).filter(([name]) => !(base?.enabled &&
+                            base.activeSurfaces.mcp &&
+                            this.gates?.allows('mcp') !== false &&
+                            Object.hasOwn(base.mcp?.servers ?? {}, name) &&
+                            overrides.get(key)?.[name]?.enabled !== false)));
+                    if (row.lsp)
+                        row.lsp.servers = Object.fromEntries(Object.entries(row.lsp.servers).filter(([, spec]) => !(base?.enabled &&
+                            base.activeSurfaces.lsp &&
+                            this.gates?.allows('lsp') !== false &&
+                            Object.values(base.lsp?.servers ?? {}).some(candidate => candidate.key === spec.key) &&
+                            !disabledLsp.has(key + '/' + spec.key))));
+                    return row;
+                });
+                const activationIds = demandIds(activation);
+                for (const id of ids) {
+                    if (id.startsWith('market:') || (!activationIds.has(id) && (!id.startsWith('lsp:direct/') || (!disabledLsp.has(id.slice(4)) && this.gates?.allows('lsp') !== false))))
+                        covered.add(id);
+                }
+                const needsActivation = [...ids].some(id => !covered.has(id));
+                if (!token.active || this.disposed || this.staged.get(owner) !== token)
+                    throw new Error('extension-shared-not-ready');
+                token.ready = true;
+                if (needsActivation)
+                    await this.enqueue(async () => {
+                        const current = demandIds(this.project(ids));
+                        if ([...ids].some(id => !id.startsWith('lsp:direct/') && !current.has(id)))
+                            throw new Error('extension-shared-demand-unavailable');
+                        mounted = true;
+                        const result = await this.reconcileShared();
+                        if (this.disposed)
+                            throw new Error('extension-shared-not-ready');
+                        this.assertMounted(activation, result);
+                        const owned = new Set(this.lspRegistry.providerOwnership().map(row => row.resourceId));
+                        for (const id of ids)
+                            if (id.startsWith('lsp:direct/') &&
+                                (disabledLsp.has(id.slice(4)) || this.gates?.allows('lsp') === false) &&
+                                (!owned.has(id) ||
+                                    result.errors.some(row => row.surface === 'lsp') ||
+                                    result.lsp.some(row => row.suiteId === 'direct' && (row.serverKey === id.slice(11) || row.serverKey === id.slice(4)))))
+                                throw new Error('extension-shared-lsp-unavailable: ' + id);
+                    });
+            }
+            catch (error) {
+                token.active = false;
+                this.staged.delete(owner);
+                try {
+                    const cleanup = mounted ? await this.enqueue(() => this.reconcileShared()) : emptyDiagnostics();
+                    if (cleanupFailed(cleanup))
+                        this.warn('extension shared stage rollback failed; retained mounts remain execution-gated');
+                }
+                catch (cleanupError) {
+                    this.warn('extension shared stage rollback failed: ' + messageOf(cleanupError));
+                }
+                throw error;
+            }
+            return {
+                commit: () => {
+                    if (!token.active || this.disposed || this.staged.get(owner) !== token)
+                        return;
+                    const removed = [...(this.committed.get(owner) ?? [])].some(id => !token.ids.has(id) && !covered.has(id));
+                    token.active = false;
+                    this.committed.set(owner, token.ids);
+                    this.staged.delete(owner);
+                    if (removed)
+                        void this.enqueue(() => this.reconcileShared())
+                            .then(result => {
+                            if (cleanupFailed(result))
+                                this.warn('extension shared cleanup failed; retained mounts remain execution-gated');
+                        })
+                            .catch(error => {
+                            this.warn('extension shared committed cleanup failed: ' + messageOf(error));
+                        });
+                },
+                rollback: async () => {
+                    if (!token.active || this.staged.get(owner) !== token)
+                        return;
+                    token.active = false;
+                    this.staged.delete(owner);
+                    if (mounted) {
+                        const result = await this.enqueue(() => this.reconcileShared());
+                        if (cleanupFailed(result))
+                            throw new Error('extension-shared-rollback-failed');
+                    }
+                    else if (token.ready && token.ids.size > 0) {
+                        void this.enqueue(() => this.reconcileShared()).catch(error => this.warn('extension shared rollback cleanup failed: ' + messageOf(error)));
+                    }
+                }
+            };
+        })();
+    }
+    releaseSessionDemand(owner) {
+        return this.enqueue(async () => {
+            const token = this.staged.get(owner);
+            if (token)
+                token.active = false;
+            this.staged.delete(owner);
+            this.committed.delete(owner);
+            const result = await this.reconcileShared();
+            if (cleanupFailed(result))
+                throw new Error('extension-shared-release-failed');
+        });
+    }
+    project(ids) {
+        return projectExtensionSuites((this.authority ?? []).filter(row => row.suite.dimension === 'user'), captureExtensionSelection(null, [...ids])).map(row => row.suite);
+    }
+    async reconcileShared() {
+        const diagnostics = emptyDiagnostics();
+        if (this.disposed)
+            return diagnostics;
+        const epoch = this.authorityEpoch;
+        const ids = new Set([...this.committed.values(), ...[...this.staged.values()].filter(row => row.ready).map(row => row.ids)].flatMap(set => [...set]));
+        const projected = this.project(ids);
+        this.demandedMcp = new Map();
+        this.demandedLsp = new Set([...ids].filter(id => id.startsWith('lsp:direct/')).map(id => id.slice(4)));
+        for (const row of projected) {
+            const key = suiteKey(row);
+            const mcp = Object.keys(row.mcp?.servers ?? {});
+            if (mcp.length)
+                this.demandedMcp.set(key, new Set(mcp));
+            for (const spec of Object.values(row.lsp?.servers ?? {}))
+                this.demandedLsp.add(key + '/' + spec.key);
+        }
+        const forSurface = (face) => {
+            const global = this.gates?.allows(face) === false ? [] : this.globalSuites;
+            const rows = new Map();
+            for (const base of global) {
+                if (!base.activeSurfaces[face])
+                    continue;
+                if (this.authority === undefined || base.dimension !== 'user') {
+                    rows.set(suiteKey(base), structuredClone(base));
+                    continue;
+                }
+                const current = this.authority.find(row => suiteKey(row.suite) === suiteKey(base));
+                if (!current || current.validSurfaces[face] !== true)
+                    continue;
+                const row = structuredClone(current.suite);
+                row.enabled = true;
+                row.activeSurfaces[face] = true;
+                if (face === 'mcp' && row.mcp)
+                    row.mcp.servers = Object.fromEntries(Object.entries(row.mcp.servers).filter(([key]) => Object.hasOwn(base.mcp?.servers ?? {}, key)));
+                if (face === 'lsp' && row.lsp) {
+                    const keys = new Set(Object.values(base.lsp?.servers ?? {}).map(spec => spec.key));
+                    row.lsp.servers = Object.fromEntries(Object.entries(row.lsp.servers).filter(([, spec]) => keys.has(spec.key)));
+                }
+                rows.set(suiteKey(base), row);
+            }
+            for (const demand of projected) {
+                if (!demand.activeSurfaces[face])
+                    continue;
+                const key = suiteKey(demand);
+                const base = rows.get(key);
+                const latest = this.authority?.find(row => suiteKey(row.suite) === key)?.suite;
+                const merged = structuredClone(latest ?? demand);
+                merged.enabled = true;
+                merged.activeSurfaces[face] = true;
+                if (face === 'mcp')
+                    merged.mcp = { ...demand.mcp, servers: { ...(base?.mcp?.servers ?? {}), ...demand.mcp.servers } };
+                else
+                    merged.lsp = { servers: { ...(base?.lsp?.servers ?? {}), ...demand.lsp.servers } };
+                rows.set(key, merged);
+            }
+            return [...rows.values()];
+        };
+        await Promise.all([
+            this.surface('mcp', diagnostics, () => this.mcp.reconcile(forSurface('mcp'))),
+            this.surface('lsp', diagnostics, () => this.lspRegistry.reconcile(forSurface('lsp')))
+        ]);
+        if (!this.disposed && epoch !== this.authorityEpoch) {
+            void this.enqueue(() => this.reconcileShared()).catch(error => this.warn('extension shared catalog refresh failed: ' + messageOf(error)));
+        }
+        return diagnostics;
+    }
+    assertMounted(suites, diagnostics) {
+        const mcpFailed = diagnostics.errors.some(row => row.surface === 'mcp');
+        const lspFailed = diagnostics.errors.some(row => row.surface === 'lsp');
+        const lsp = new Set(this.lspRegistry.providerOwnership().map(row => row.resourceId));
+        for (const suite of suites) {
+            const key = suiteKey(suite);
+            // Each suite proves its own surfaces in order: the MCP half needs this
+            // adapter's server-name derivation, so the adapter owns it.
+            this.mcp.assertMounted(suite, diagnostics.mcp, mcpFailed);
+            for (const spec of Object.values(suite.lsp?.servers ?? {})) {
+                if (!lsp.has('lsp:' + key + '/' + spec.key) ||
+                    diagnostics.lsp.some(row => row.suiteId === key && (row.serverKey === spec.key || row.serverKey.split(',').includes(key + '/' + spec.key))) ||
+                    lspFailed)
+                    throw new Error('extension-shared-lsp-unavailable: ' + key + '/' + spec.key);
+            }
+        }
+    }
+    /** Stop receipt admission before draining shared and independently queued local work. */
+    dispose() {
+        if (this.disposal)
+            return this.disposal;
+        this.disposed = true;
+        for (const token of this.staged.values())
+            token.active = false;
+        this.staged.clear();
+        this.committed.clear();
+        this.disposal = (async () => {
+            await this.sharedQueue;
+            await Promise.all(this.queues.values());
+            const outcomes = await Promise.allSettled([
+                Promise.resolve().then(() => this.commands.disposeAll()),
+                Promise.resolve().then(() => this.mcp.disposeAll()),
+                Promise.resolve().then(() => this.hooks.disposeAll()),
+                Promise.resolve().then(() => this.lspRegistry.disposeAll())
+            ]);
+            this.queues.clear();
+            const failures = outcomes.filter((result) => result.status === 'rejected').map(result => result.reason);
+            if (failures.length > 0)
+                throw new AggregateError(failures, 'runtime disposal failed: ' + failures.map(messageOf).join('; '));
+        })();
+        return this.disposal;
+    }
+}
+function cleanupFailed(result) {
+    return result.errors.length > 0 || [...result.mcp, ...result.lsp].some(row => row.code === 'unmount-failed');
+}
+function emptyDiagnostics() {
+    return { mcp: [], commands: [], hooks: [], lsp: [], errors: [] };
+}
+function suiteKey(suite) {
+    return suite.sourceId + '/' + suite.id;
+}
+function demandIds(suites) {
+    const ids = new Set();
+    for (const suite of suites) {
+        if (suite.dimension !== 'user')
+            continue;
+        const key = suiteKey(suite);
+        if (suite.activeSurfaces.mcp)
+            for (const name of Object.keys(suite.mcp?.servers ?? {})) {
+                ids.add('market:' + key);
+                ids.add('mcp:plugin:' + key + '/' + name);
+            }
+        if (suite.activeSurfaces.lsp)
+            for (const spec of Object.values(suite.lsp?.servers ?? {})) {
+                ids.add('market:' + key);
+                ids.add('lsp:' + key + '/' + spec.key);
+            }
+    }
+    return ids;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/lib/packages/market-runtime/src/runtime/host/command-name-allocator.js

@@ -0,0 +1,168 @@
+/**
+ * Unique call names for the commands this plugin registers.
+ *
+ * The host's command registry keys one name to one definition per layer:
+ * `NamedEntries.insert` throws `command "x" is already registered` when the
+ * name is taken, and the layer a registration lands in is chosen by the
+ * registry service's own context, never by the caller's. Two suites flattening
+ * to one call name, a host built-in such as `compact`, or a second mount
+ * registry feeding the same layer therefore collide — and a colliding
+ * definition is the one thing the slash menu drops, so the name has to be
+ * chosen before `register` is called. The layer's existing names cannot be
+ * enumerated from here, which leaves the refused registration as the only
+ * observable of a foreign occupant; {@link registerWithAllocatedName} retries
+ * with the next suffix.
+ *
+ * Allocation answers the preferred name while it is free and appends an
+ * increasing numeric suffix afterwards: the first conflict is `compact-1`,
+ * then `compact-2`. A name the host refused stays held as occupied, so the
+ * retry asks for the following suffix instead of repeating the name that just
+ * failed.
+ *
+ * @module runtime/command-name-allocator
+ */
+/** Suffixes one preferred name may spend before allocation gives up on it. */
+export const MAX_COMMAND_NAME_ATTEMPTS = 50;
+/** The host's duplicate-registration failure, as `CommandRuntime.register` renders it. */
+const DUPLICATE_COMMAND_NAME = /^command "[^"]+" is already registered/;
+/**
+ * Whether the host refused a registration because that exact name is taken.
+ *
+ * `CommandRuntime.register` renders one sentence for the global layer
+ * (`command "x" is already registered (for a per-agent variant, ...)`) and a
+ * shorter one for a scoped layer (`... in this scope`); both open with the
+ * same clause, and an error carrying any other text is a real failure rather
+ * than a name collision.
+ * @param error - the value thrown by `register`.
+ * @returns whether re-claiming under another name can succeed.
+ */
+export function isDuplicateCommandName(error) {
+    const message = error instanceof Error ? error.message : typeof error === 'string' ? error : '';
+    return DUPLICATE_COMMAND_NAME.test(message);
+}
+/**
+ * Build a naming policy over `taken`.
+ *
+ * The allocator owns the names it hands out, which is what makes
+ * {@link CommandNameAllocator.release} meaningful; `taken` adds the names
+ * occupied outside it (another surface's registrations in the same layer, and
+ * the names the host has already refused).
+ * @param taken - every name currently unavailable to this allocator.
+ * @returns the allocator.
+ */
+export function createCommandNameAllocator(taken) {
+    const claimed = new Set();
+    return {
+        claim(preferred) {
+            const busy = new Set(taken());
+            for (const name of claimed)
+                busy.add(name);
+            if (!busy.has(preferred)) {
+                claimed.add(preferred);
+                return preferred;
+            }
+            for (let suffix = 1; suffix <= MAX_COMMAND_NAME_ATTEMPTS; suffix += 1) {
+                const candidate = `${preferred}-${suffix}`;
+                if (busy.has(candidate))
+                    continue;
+                claimed.add(candidate);
+                return candidate;
+            }
+            throw new Error(`command name "${preferred}" has no free suffix within ${MAX_COMMAND_NAME_ATTEMPTS} attempts`);
+        },
+        release(name) {
+            claimed.delete(name);
+        }
+    };
+}
+/**
+ * The names one command layer holds for this plugin.
+ *
+ * A mount registry keeps one of these for the lifetime of its layer seat: it
+ * spans every reconcile pass, so a name stays reserved exactly as long as the
+ * registration carrying it is live, and it dies with the seat — a recomposed
+ * layer starts from the host's own occupancy alone. Names the host refused are
+ * held too, so a rename never retries a name this layer just rejected.
+ *
+ * Occupancy is per layer, not per process, because that is the unit the host
+ * checks: two agents' scoped layers each hold their own `review`, and neither
+ * registration sees the other. A process-wide ledger would rename the second
+ * one for a collision the host never reports.
+ */
+export class CommandNameRegistry {
+    /** Names held by this plugin in the layer, whether registered or refused. */
+    held = new Set();
+    allocator = createCommandNameAllocator(() => this.held);
+    /**
+     * Reserve the next free name for `preferred`.
+     * @param preferred - the name the command uses undisturbed.
+     * @returns the name to register under.
+     * @throws when every suffix within {@link MAX_COMMAND_NAME_ATTEMPTS} is taken.
+     */
+    claim(preferred) {
+        const name = this.allocator.claim(preferred);
+        this.held.add(name);
+        return name;
+    }
+    /**
+     * Drop a name this plugin no longer registers, freeing it for a later claim.
+     * @param name - the name whose registration ended.
+     */
+    forget(name) {
+        this.allocator.release(name);
+        this.held.delete(name);
+    }
+    /**
+     * Hold a name the host refused, so it stays occupied without a registration.
+     * @param name - the refused call name.
+     */
+    refuse(name) {
+        this.allocator.release(name);
+        this.held.add(name);
+    }
+    /**
+     * Every name this layer holds for the plugin.
+     * @returns the allocated and refused names, as one read-only view.
+     */
+    taken() {
+        return new Set(this.held);
+    }
+}
+/**
+ * Register under the first call name the layer accepts.
+ *
+ * The attempt loop is the only way past a foreign occupant: the layer's names
+ * are not enumerable, so a refusal is what moves allocation to the next
+ * suffix. A refusal is held on `names` before the retry, which is what makes
+ * the loop terminate — every iteration either registers or retires one
+ * candidate, and allocation itself fails once the suffix ceiling is reached.
+ * Any other failure ends the attempt immediately, because renaming around a
+ * malformed definition or an unavailable registry would report a rename
+ * instead of the bug that caused it.
+ * @param names - the layer's occupancy ledger.
+ * @param preferred - the name the command uses when nothing holds it.
+ * @param register - the host registration, called once per candidate name.
+ * @returns the accepted name and its registration, or the failure to diagnose.
+ */
+export function registerWithAllocatedName(names, preferred, register) {
+    for (;;) {
+        let name;
+        try {
+            name = names.claim(preferred);
+        }
+        catch (error) {
+            return { kind: 'failed', error };
+        }
+        try {
+            return { kind: 'registered', name, disposer: register(name) };
+        }
+        catch (error) {
+            if (!isDuplicateCommandName(error)) {
+                // The registration never landed, so the name is free again.
+                names.forget(name);
+                return { kind: 'failed', error };
+            }
+            names.refuse(name);
+        }
+    }
+}