@khorsheed/dsh-capability-catalog 0.1.95

package/lib/types/scoped-delivery.js

@@ -0,0 +1,686 @@
+/**
+ * Preset-scoped skill delivery: a plugin-owned skills root whose entries are
+ * delivered **into one preset's scope layer** instead of into the global layer.
+ *
+ * The skill registry is layered by the scope a registration is made from, and a
+ * read merges the global layer with the viewing agent's scope chain. A provider
+ * registered through a context scoped to a preset's standing key is therefore
+ * consulted only for sessions on that preset — no read-time identity guessing,
+ * and no dependence on the borrowed lookup options.
+ *
+ * The per-skill policy lives in the skill's own frontmatter
+ * (`metadata.presetScope: [<preset-id>, …]`); an absent or empty list means the
+ * entry is not delivered by this module at all. A managed name that ALSO exists
+ * in a default skill root is refused delivery and reported: a leftover copy is
+ * served by the host provider in every preset, so silently delivering a second
+ * candidate would make the scope a lie.
+ *
+ * Scope of enforcement: this is a discovery/delivery policy for one Harness
+ * instance, not an authorization boundary. `ScopeKey` values are ordinary
+ * objects and the roster hands real ones to any caller, so a same-process plugin
+ * can claim membership. In-process agents and children joining the parent's
+ * composition are covered; native codex/claude-code and ACP backends start their
+ * own runtime and never consult this registry at all.
+ * @module @khorsheed/dsh-capability-catalog/scoped-delivery
+ */
+import { existsSync } from 'node:fs';
+import { watch } from 'node:fs';
+import { mkdir, readFile, readdir, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createScope } from '@deepseek-ai/dsh-scope';
+import { acquireStandingScope } from './preset-scope.js';
+let presetRegistryProbe;
+/**
+ * Resolve the preset-registry module by name. The 0.1.7-rc.1 host renamed
+ * `@deepseek-ai/dsh-agent-presets` to `@deepseek-ai/dsh-agent-preset-registry`
+ * (the livePresetMounts API carried over); 0.1.5/0.1.6 hosts install only the
+ * old name, and a host without preset composition installs neither — `null`,
+ * and {@link ScopedSkillDelivery.liveKeys} then reports nothing live, the same
+ * degrade the call's own catch encodes. A STATIC import of either name is a
+ * module-resolution failure at load on hosts installing only the other —
+ * pack-dist strips `dependencies`, so the specifier resolves against the
+ * host's install tree. Both specifiers stay static string literals so tsdown
+ * externalizes them and tsc type-checks them.
+ * @returns the module namespace, or null when neither name resolves.
+ */
+export function loadPresetRegistry() {
+    presetRegistryProbe ??= import('@deepseek-ai/dsh-agent-preset-registry')
+        .catch(() => import('@deepseek-ai/dsh-agent-presets'))
+        .catch(() => null);
+    return presetRegistryProbe;
+}
+/** Test seam: drop the cached probe so a mocked resolution path re-runs. */
+export function resetPresetRegistryProbeForTest() {
+    presetRegistryProbe = undefined;
+}
+/** Provider label for managed entries; also the candidate's `provider` field. */
+export const SCOPED_PROVIDER_NAME = 'capability-catalog';
+/** Candidate rank, beside the filesystem provider's `custom` roots. */
+export const MANAGED_SKILL_RANK = 300;
+/** Directory under the harness home that holds preset-scoped skills. */
+export const SCOPED_SKILLS_DIR = join('capability-catalog', 'skills');
+/** Debounce for filesystem-triggered rescans. */
+const RESCAN_DEBOUNCE_MS = 150;
+/** Frontmatter block, then the body it precedes. */
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+/** Kebab-case skill / preset id grammar (the registry's own). */
+const KEBAB_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** The managed root for one harness home. */
+export function scopedSkillsRoot(dshHome) {
+    return join(dshHome, SCOPED_SKILLS_DIR);
+}
+/**
+ * Read the `presetScope` list out of a frontmatter block.
+ *
+ * Accepted forms, at any indentation (the canonical one is
+ * `metadata.presetScope`):
+ *
+ * ```yaml
+ * metadata:
+ *   presetScope: [dsh-writing, dev]
+ *   presetScope:
+ *     - dsh-writing
+ * ```
+ * @param front - the frontmatter text without its `---` fences.
+ * @returns the declared ids, or undefined when the key is absent.
+ */
+export function parsePresetScopeFrontmatter(front) {
+    const lines = front.split('\n');
+    for (let index = 0; index < lines.length; index += 1) {
+        const match = /^(\s*)presetScope\s*:\s*(.*)$/.exec(lines[index] ?? '');
+        if (match === null)
+            continue;
+        const indent = (match[1] ?? '').length;
+        const rest = (match[2] ?? '').trim();
+        if (rest.startsWith('[')) {
+            const inner = rest.slice(1, rest.lastIndexOf(']') === -1 ? undefined : rest.lastIndexOf(']'));
+            return presetIdsOf(inner.split(','));
+        }
+        if (rest !== '')
+            return presetIdsOf([rest]);
+        const block = [];
+        for (let item = index + 1; item < lines.length; item += 1) {
+            const entry = /^(\s*)-\s*(.*?)\s*$/.exec(lines[item] ?? '');
+            if (entry === null)
+                break;
+            if ((entry[1] ?? '').length <= indent)
+                break;
+            block.push(entry[2] ?? '');
+        }
+        return presetIdsOf(block);
+    }
+    return undefined;
+}
+/** Normalize YAML scalars onto the preset-id grammar. */
+function presetIdsOf(values) {
+    const ids = [];
+    for (const value of values) {
+        const id = value.trim().replace(/^['"]|['"]$/g, '');
+        if (id === '' || !KEBAB_ID.test(id))
+            continue;
+        if (!ids.includes(id))
+            ids.push(id);
+    }
+    return ids;
+}
+/** Whether a string is a usable skill / preset id. */
+export function isKebabId(value) {
+    return KEBAB_ID.test(value);
+}
+/** Split a SKILL.md into its frontmatter block and body. */
+export function splitFrontmatter(content) {
+    const match = FRONTMATTER.exec(content);
+    if (match === null)
+        return undefined;
+    return { front: match[1] ?? '', body: match[2] ?? '' };
+}
+/** Read a boolean frontmatter flag (`key: true|false`). */
+function frontmatterFlag(front, key) {
+    const match = new RegExp(`^\\s*${key}\\s*:\\s*(true|false)\\s*$`, 'm').exec(front);
+    if (match === null)
+        return undefined;
+    return match[1] === 'true';
+}
+/** Read a scalar frontmatter value, unquoting a simple quoted or plain form. */
+function frontmatterScalar(front, key) {
+    const match = new RegExp(`^\\s*${key}\\s*:\\s*(.+)$`, 'm').exec(front);
+    if (match === null)
+        return undefined;
+    const value = (match[1] ?? '').trim().replace(/^['"]|['"]$/g, '');
+    return value === '' ? undefined : value;
+}
+/**
+ * Parse one managed `SKILL.md` into its delivery record.
+ * @param content - the file text.
+ * @param dir - the skill's directory (its resource base).
+ * @param path - the absolute `SKILL.md` path.
+ * @returns the record, or undefined when the frontmatter is unusable.
+ */
+export function managedSkillFrom(content, dir, path) {
+    const split = splitFrontmatter(content);
+    if (split === undefined)
+        return undefined;
+    const name = frontmatterScalar(split.front, 'name');
+    const description = frontmatterScalar(split.front, 'description');
+    if (name === undefined || description === undefined || !KEBAB_ID.test(name))
+        return undefined;
+    const whenToUse = frontmatterScalar(split.front, 'when-to-use') ?? frontmatterScalar(split.front, 'whenToUse');
+    const presetScope = parsePresetScopeFrontmatter(split.front);
+    return {
+        name,
+        description,
+        ...whenToUse === undefined ? {} : { whenToUse },
+        modelInvocable: frontmatterFlag(split.front, 'disable-model-invocation') !== true,
+        userInvocable: frontmatterFlag(split.front, 'user-invocable') !== false,
+        presetScope,
+        dir,
+        path,
+        content,
+    };
+}
+/** Whether this skill asks to be delivered to a specific preset set. */
+export function isScoped(skill) {
+    return skill.presetScope !== undefined && skill.presetScope.length > 0;
+}
+/** Project one managed skill onto a provider candidate for one preset. */
+export function candidateFor(skill) {
+    return {
+        name: skill.name,
+        description: skill.description,
+        ...skill.whenToUse === undefined ? {} : { whenToUse: skill.whenToUse },
+        invocation: { modelInvocable: skill.modelInvocable, userInvocable: skill.userInvocable },
+        source: 'custom',
+        provider: SCOPED_PROVIDER_NAME,
+        rank: MANAGED_SKILL_RANK,
+        locator: skill.path,
+        path: skill.path,
+        metadata: { presetScope: [...(skill.presetScope ?? [])] },
+        resourceBase: { kind: 'directory', path: skill.dir },
+    };
+}
+/** Project one managed skill onto the complete definition the loader returns. */
+export function definitionFor(skill) {
+    return { ...candidateFor(skill), content: skill.content };
+}
+/** The default roots a duplicate copy could live in. */
+export function defaultSkillRoots(dshHome, workdir) {
+    const roots = [
+        join(dshHome, 'skills'),
+        join(dshHome, '.agents', 'skills'),
+        join(process.env.DSH_AGENTS_HOME ?? join(homedir(), '.agents'), 'skills'),
+    ];
+    if (workdir !== undefined && workdir !== '') {
+        roots.push(join(workdir, '.dsh', 'skills'), join(workdir, '.agents', 'skills'));
+    }
+    return roots;
+}
+/**
+ * Find managed names that a default root also supplies.
+ *
+ * A duplicate is what makes a scope claim false: the host provider delivers the
+ * default root's copy into every preset regardless of this module's decision.
+ * @param skills - the managed entries under consideration.
+ * @param dshHome - the harness home.
+ * @param workdir - the session workspace, when known.
+ * @returns skill name → the default root that already supplies it.
+ */
+export function detectConflicts(skills, dshHome, workdir) {
+    const conflicts = new Map();
+    for (const root of defaultSkillRoots(dshHome, workdir)) {
+        for (const skill of skills) {
+            if (conflicts.has(skill.name))
+                continue;
+            if (existsSync(join(root, skill.name, 'SKILL.md')) || existsSync(join(root, `${skill.name}.md`))) {
+                conflicts.set(skill.name, root);
+            }
+        }
+    }
+    return conflicts;
+}
+/**
+ * Scan the managed root for skill directories.
+ * @param root - the managed skills root.
+ * @returns every readable, usable entry, sorted by name.
+ */
+export async function scanManagedSkills(root) {
+    let children;
+    try {
+        children = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const child of children) {
+        if (!child.isDirectory() || !KEBAB_ID.test(child.name))
+            continue;
+        const dir = join(root, child.name);
+        const path = join(dir, 'SKILL.md');
+        try {
+            const [content, info] = await Promise.all([readFile(path, 'utf8'), stat(path)]);
+            if (!info.isFile())
+                continue;
+            const skill = managedSkillFrom(content, dir, path);
+            if (skill !== undefined)
+                found.push(skill);
+        }
+        catch {
+            // An unreadable entry is reported by omission; the settings surface lists
+            // only what could actually be delivered.
+        }
+    }
+    return found.sort((left, right) => left.name.localeCompare(right.name));
+}
+/** The sentinel preset id of the delivery that serves every preset. */
+const GLOBAL_PRESET = '*';
+/**
+ * Delivers managed skills into the scope layers of the presets their
+ * frontmatter names.
+ *
+ * Lifecycle: {@link start} once (watcher + first reconcile), {@link reconcile}
+ * whenever policy or files may have changed, {@link dispose} when the owning
+ * plugin unloads. Reconciliation never fails loudly: every problem becomes a
+ * status field, because a catalog must not fail the boot of the instance it is
+ * describing.
+ */
+export class ScopedSkillDelivery {
+    ctx;
+    deps;
+    entries = [];
+    managed = [];
+    conflicts = new Map();
+    presetErrors = new Map();
+    watcher;
+    timer;
+    watching = false;
+    failure;
+    started = false;
+    disposed = false;
+    /** The probed registry's mount list (undefined until start()'s probe resolves). */
+    presetMounts;
+    /**
+     * @param ctx - the host context the delivery scopes are minted under.
+     * @param deps - borrowed services and paths, all optional at runtime.
+     */
+    constructor(ctx, deps) {
+        this.ctx = ctx;
+        this.deps = deps;
+    }
+    /** Start watching the managed root and deliver what it currently holds. */
+    async start() {
+        if (this.started || this.disposed)
+            return;
+        this.started = true;
+        // Resolve the registry's mount list before the first reconcile: the
+        // 0.1.7-rc.1 host renamed the package (see loadPresetRegistry). An
+        // unresolved probe leaves presetMounts undefined and liveKeys() reports
+        // nothing live — the same degrade the call's own catch encodes.
+        this.presetMounts = (await loadPresetRegistry())?.livePresetMounts;
+        await this.ensureRoot();
+        this.watchRoot();
+        this.ctx.on('agent-preset/selected', () => { void this.reconcile(); });
+        await this.reconcile();
+    }
+    /** Re-read policy and files, then converge the delivery registrations. */
+    async reconcile() {
+        if (this.disposed)
+            return;
+        const registry = this.deps.registry();
+        const roster = this.deps.roster();
+        if (registry?.registerProvider === undefined) {
+            this.failure = 'the skill registry exposes no provider registration';
+            this.disposeEntries();
+            this.managed = [];
+            return;
+        }
+        if (roster?.standingKeyFor === undefined && roster?.acquireScope === undefined) {
+            this.failure = 'no agent-preset roster is composed';
+            this.disposeEntries();
+            this.managed = [];
+            return;
+        }
+        const root = this.root();
+        this.managed = await scanManagedSkills(root);
+        this.conflicts = detectConflicts(this.managed, this.deps.dshHome(), this.deps.workdir?.());
+        // presetId → the skills it must serve. A conflicted skill is excluded: the
+        // default root already supplies that name everywhere, so delivering a
+        // second candidate could not change what any preset sees.
+        const byPreset = new Map();
+        for (const skill of this.managed) {
+            if (!isScoped(skill) || this.conflicts.has(skill.name))
+                continue;
+            for (const presetId of skill.presetScope ?? []) {
+                const list = byPreset.get(presetId) ?? [];
+                list.push(skill);
+                byPreset.set(presetId, list);
+            }
+        }
+        // A managed skill with no declared scope is delivered to EVERY preset —
+        // through one provider in the global layer, because the managed root is
+        // scanned by no host provider.
+        const unscoped = this.managed.filter(skill => !this.conflicts.has(skill.name) && !isScoped(skill));
+        this.presetErrors = new Map();
+        const live = this.liveKeys();
+        // Resolve each named preset once: the roster's standing-scope acquisition
+        // (either roster face) ensures the standing mount, so repeated calls are
+        // wasted work and repeated mounts.
+        const resolved = new Map();
+        for (const presetId of byPreset.keys()) {
+            resolved.set(presetId, await this.resolveKey(roster, presetId));
+        }
+        // Drop registrations that no longer have work, or whose generation is gone.
+        for (const entry of [...this.entries]) {
+            if (entry.presetId === GLOBAL_PRESET)
+                continue;
+            if (!byPreset.has(entry.presetId)) {
+                await this.dropEntry(entry);
+                continue;
+            }
+            const wantedKey = resolved.get(entry.presetId);
+            if (wantedKey === entry.key)
+                continue;
+            // A newer generation of the same preset: keep serving sessions that are
+            // still joined to the old key, and let the new key get its own entry.
+            if (wantedKey !== undefined && entry.key !== undefined && live.has(entry.key))
+                continue;
+            await this.dropEntry(entry);
+        }
+        for (const presetId of byPreset.keys()) {
+            const key = resolved.get(presetId);
+            if (key === undefined)
+                continue;
+            if (this.entries.some(entry => entry.presetId === presetId && entry.key === key))
+                continue;
+            await this.register(presetId, key);
+        }
+        const globalEntry = this.entries.find(entry => entry.presetId === GLOBAL_PRESET);
+        if (unscoped.length > 0) {
+            if (globalEntry === undefined)
+                await this.registerGlobal();
+        }
+        else if (globalEntry !== undefined) {
+            await this.dropEntry(globalEntry);
+        }
+        this.failure = undefined;
+        this.invalidateAll();
+    }
+    /** The current status, for the settings surface and the model-facing tool. */
+    status() {
+        const delivered = new Set();
+        for (const entry of this.entries) {
+            for (const skill of this.skillsFor(entry.presetId))
+                delivered.add(skill.name);
+        }
+        const skills = this.managed.map(skill => {
+            const conflict = this.conflicts.get(skill.name);
+            return {
+                name: skill.name,
+                description: skill.description,
+                modelInvocable: skill.modelInvocable,
+                userInvocable: skill.userInvocable,
+                path: skill.path,
+                presets: [...(skill.presetScope ?? [])],
+                delivered: delivered.has(skill.name),
+                ...conflict === undefined ? {} : { conflict: join(conflict, skill.name) },
+            };
+        });
+        const presets = [...new Set(this.entries.map(entry => entry.presetId))]
+            .sort((left, right) => left.localeCompare(right))
+            .map(presetId => {
+            const skills = this.managed
+                .filter(skill => !this.conflicts.has(skill.name) && (skill.presetScope ?? []).includes(presetId))
+                .map(skill => skill.name);
+            const error = this.presetErrors.get(presetId);
+            return { presetId, skills, ...error === undefined ? {} : { error } };
+        });
+        for (const [presetId, error] of this.presetErrors) {
+            if (!presets.some(row => row.presetId === presetId))
+                presets.push({ presetId, skills: [], error });
+        }
+        return {
+            enabled: this.failure === undefined && this.entries.length > 0,
+            ...this.failure === undefined ? {} : { reason: this.failure },
+            root: this.root(),
+            watching: this.watching,
+            skills,
+            presets,
+            // Custom roots are configured inside host compositions this plugin cannot
+            // read; a duplicate there would not be detected.
+            customRootsUnverifiable: true,
+        };
+    }
+    /** Stop watching and dispose every delivery registration. */
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        this.watcher?.close();
+        this.watcher = undefined;
+        this.watching = false;
+        await this.disposeEntries();
+        this.managed = [];
+    }
+    /** The managed root under the current harness home. */
+    root() {
+        return scopedSkillsRoot(this.deps.dshHome());
+    }
+    /** Create the managed root if it is still absent. */
+    async ensureRoot() {
+        try {
+            await mkdir(this.root(), { recursive: true });
+        }
+        catch (error) {
+            this.failure = `the managed root could not be created: ${describeError(error)}`;
+        }
+    }
+    /** Watch the managed root, degrading to on-demand rescans when it cannot. */
+    watchRoot() {
+        try {
+            this.watcher = watch(this.root(), { recursive: true }, () => this.scheduleRescan());
+            this.watching = true;
+        }
+        catch (error) {
+            this.watching = false;
+            this.deps.log(`capability-catalog: managed root is not watched (${describeError(error)}); scope changes apply on the next reconcile`);
+        }
+    }
+    /** Coalesce a burst of filesystem events into one reconcile. */
+    scheduleRescan() {
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.reconcile().catch((error) => {
+                this.deps.log(`capability-catalog: scoped skill reconcile failed: ${describeError(error)}`);
+            });
+        }, RESCAN_DEBOUNCE_MS);
+    }
+    /** The standing keys that still have a live mount in this process. */
+    liveKeys() {
+        const keys = new Set();
+        const livePresetMounts = this.presetMounts;
+        // Undefined until start()'s probe resolves (a file event can fire first),
+        // or forever on a host with neither registry name — the same degrade the
+        // catch below encodes: nothing is KNOWN to be live, registrations for
+        // needed presets are still kept, only stale generations are dropped.
+        if (livePresetMounts === undefined)
+            return keys;
+        try {
+            for (const mount of livePresetMounts()) {
+                if (mount.key !== undefined)
+                    keys.add(mount.key);
+            }
+        }
+        catch {
+            // Without the mount list nothing is known to be live; registrations for
+            // needed presets are still kept, only stale generations are dropped.
+        }
+        return keys;
+    }
+    /** Resolve one preset's standing key, remembering why it failed. */
+    async resolveKey(roster, presetId) {
+        try {
+            const read = await acquireStandingScope(roster, presetId);
+            try {
+                if (read.key === undefined) {
+                    this.presetErrors.set(presetId, 'the roster resolved no standing scope');
+                    return undefined;
+                }
+                return read.key;
+            }
+            finally {
+                // The key outlives the lease (a generation is reaped only once its
+                // preset is unregistered AND unleased), so entries keep it; a release
+                // failure is logged, not mistaken for a resolution failure.
+                await read.dispose?.().catch((error) => {
+                    this.deps.log(`capability-catalog: scope lease release failed: ${describeError(error)}`);
+                });
+            }
+        }
+        catch (error) {
+            this.presetErrors.set(presetId, describeError(error));
+            return undefined;
+        }
+    }
+    /** Register one delivery provider into a preset's layer. */
+    async register(presetId, key) {
+        const scope = createScope(this.ctx, key);
+        try {
+            // A scope-minted context owns no dependency access of its own, and the
+            // registry only records the layer a registration was made *through* — so
+            // the provider is registered through an injected child of that scope. The
+            // scope tag survives the extra level.
+            const injected = await injectableScope(scope.ctx);
+            if (injected === undefined) {
+                await scope.dispose();
+                this.presetErrors.set(presetId, `the ${SKILLS_SERVICE} service was not injectable in the delivery scope`);
+                return;
+            }
+            let invalidate;
+            injected.skills.registerProvider((control) => {
+                invalidate = control.invalidate;
+                return this.providerFor(presetId, control);
+            });
+            this.entries.push({
+                presetId,
+                key,
+                dispose: () => scope.dispose(),
+                invalidate: () => invalidate?.(),
+            });
+        }
+        catch (error) {
+            await scope.dispose().catch(() => { });
+            this.presetErrors.set(presetId, `delivery scope could not be created: ${describeError(error)}`);
+        }
+    }
+    /** Register the provider that serves every preset (the unscoped skills). */
+    async registerGlobal() {
+        try {
+            const injected = await injectableScope(this.ctx);
+            if (injected === undefined) {
+                this.failure = `the ${SKILLS_SERVICE} service was not injectable for the global delivery`;
+                return;
+            }
+            let invalidate;
+            const dispose = injected.skills.registerProvider((control) => {
+                invalidate = control.invalidate;
+                return this.providerFor(GLOBAL_PRESET, control);
+            });
+            this.entries.push({
+                presetId: GLOBAL_PRESET,
+                dispose: () => { dispose(); },
+                invalidate: () => invalidate?.(),
+            });
+        }
+        catch (error) {
+            this.failure = `the global delivery scope could not be created: ${describeError(error)}`;
+        }
+    }
+    /**
+     * The provider serving one preset. It reads only its own preset's assignment
+     * and re-reads the files, so a policy or content edit needs no re-registration
+     * beyond the invalidation reconcile already performs.
+     */
+    providerFor(presetId, _control) {
+        return {
+            name: SCOPED_PROVIDER_NAME,
+            list: async () => this.skillsFor(presetId).map(skill => candidateFor(skill)),
+            get: async (candidate) => {
+                const skill = this.skillsFor(presetId).find(entry => entry.name === candidate.name);
+                return skill === undefined ? undefined : definitionFor(skill);
+            },
+        };
+    }
+    /** The managed skills one delivery currently serves. */
+    skillsFor(presetId) {
+        return this.managed.filter(skill => !this.conflicts.has(skill.name)
+            && (presetId === GLOBAL_PRESET
+                ? !isScoped(skill)
+                : (skill.presetScope ?? []).includes(presetId)));
+    }
+    /** Invalidate every registration's completed catalogs. */
+    invalidateAll() {
+        for (const entry of this.entries)
+            entry.invalidate();
+    }
+    /** Dispose every registration. */
+    async disposeEntries() {
+        const entries = this.entries.splice(0, this.entries.length);
+        for (const entry of entries) {
+            try {
+                await entry.dispose();
+            }
+            catch (error) {
+                this.deps.log(`capability-catalog: delivery scope disposal failed: ${describeError(error)}`);
+            }
+        }
+    }
+    /** Dispose one registration and forget it. */
+    async dropEntry(entry) {
+        const index = this.entries.indexOf(entry);
+        if (index >= 0)
+            this.entries.splice(index, 1);
+        try {
+            await entry.dispose();
+        }
+        catch (error) {
+            this.deps.log(`capability-catalog: delivery scope disposal failed: ${describeError(error)}`);
+        }
+    }
+}
+/** Render an unknown failure for a status field or a log line. */
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** The registry every delivery registration is made through. */
+const SKILLS_SERVICE = 'skills';
+/** How long an injection may take before the registration is abandoned. */
+const INJECT_TIMEOUT_MS = 500;
+/**
+ * A context within `scope` that may access the skill registry.
+ *
+ * A scope-minted context carries no dependency access by itself, and Cordis
+ * resolves an `inject` callback after the current task — hence the bounded
+ * await, which gives `reconcile()` a settled answer instead of a registration
+ * that appears at some later tick.
+ * @param scopeCtx - the context minted for one preset's standing key.
+ * @returns the injected context, or undefined when it never became available.
+ */
+function injectableScope(scopeCtx) {
+    return new Promise(resolve => {
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        const timer = setTimeout(() => finish(undefined), INJECT_TIMEOUT_MS);
+        scopeCtx.inject([SKILLS_SERVICE], (injected) => finish(injected));
+    });
+}