@leaves615/dsh-llm-ctl 0.1.0

package/lib/visibility-settings.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Visibility settings adapter: the `llm-ctl` settings section that persists the
+ * two model-visibility tables.
+ *
+ * The settings provider is an optional dependency. {@link installVisibilitySettings}
+ * attaches through `ctx.inject(['settings'], …)`, so a deployment without a
+ * settings provider still loads: the handle keeps answering reads from the
+ * composition `base` and refuses writes with `SETTINGS_ERROR`. When a provider
+ * is present the section is registered with
+ * `settings.installSection(ctx, ns, schema, base, hooks)` — the owner is the
+ * plugin context, so disposing the plugin fiber removes the namespace — and the
+ * hooks keep the authoritative value and the section revision in sync.
+ *
+ * Writes are path-addressed (`settings.mutate`), never wholesale, so a caller
+ * holding a redacted view cannot delete fields it never saw; `expectedRevision`
+ * is forwarded verbatim so a stale writer is refused with `SETTINGS_CONFLICT`.
+ *
+ * @module dsh-llm-ctl/visibility-settings
+ */
+import z from '@deepseek-ai/schemastery';
+import { type VisibilitySettings } from './visibility.ts';
+/** Namespace the visibility tables are persisted under. */
+export declare const VISIBILITY_SETTINGS_NS = "llm-ctl";
+/** One path-addressed edit to the section's user layer. */
+export type SettingsPathOp = {
+    op: 'set';
+    path: readonly string[];
+    value: unknown;
+} | {
+    op: 'unset';
+    path: readonly string[];
+};
+/** Outcome of one settings write. */
+export interface VisibilityWriteResult {
+    /** True when the provider committed every op. */
+    ok: boolean;
+    /** Section revision after a successful write. */
+    revision?: number;
+    /** Machine-readable failure class, absent on success. */
+    code?: 'SETTINGS_CONFLICT' | 'SETTINGS_ERROR';
+    /** Human-readable failure detail, absent on success. */
+    message?: string;
+}
+/** Owner-facing handle over the persisted visibility switches. */
+export interface VisibilitySettingsHandle {
+    /** Detached snapshot of the authoritative switches; never a live reference. */
+    read(): VisibilitySettings;
+    /** Last observed section revision, or undefined before the first read/write. */
+    revision(): number | undefined;
+    /**
+     * Apply path-addressed edits to the section's user layer.
+     * @param ops - ordered edits, applied by the provider as it stands at write time.
+     * @param expectedRevision - revision the caller read; a moved section is refused.
+     * @returns the write outcome, never a rejection.
+     */
+    write(ops: readonly SettingsPathOp[], expectedRevision?: number): Promise<VisibilityWriteResult>;
+    /**
+     * Write one provider's switch.
+     * @param provider - provider id.
+     * @param visible - whether the provider is visible.
+     * @returns the write outcome.
+     */
+    setProvider(provider: string, visible: boolean): Promise<VisibilityWriteResult>;
+    /**
+     * Write one model's switch.
+     * @param provider - provider id.
+     * @param model - model id.
+     * @param visible - whether the model is visible.
+     * @returns the write outcome.
+     */
+    setModel(provider: string, model: string, visible: boolean): Promise<VisibilityWriteResult>;
+    /**
+     * Read the queue override slice; empty means the cordis base applies.
+     * @returns a detached override snapshot, never a live reference.
+     */
+    queue(): QueueSettingsOverride;
+    /**
+     * Write queue override fields; undefined fields are left untouched.
+     * @param partial - override fields to set.
+     * @param expectedRevision - revision the caller read; a moved section is refused.
+     * @returns the write outcome.
+     */
+    setQueue(partial: QueueSettingsOverride, expectedRevision?: number): Promise<VisibilityWriteResult>;
+    /**
+     * Drop the queue override, re-inheriting the cordis composition base.
+     * @param expectedRevision - revision the caller read; a moved section is refused.
+     * @returns the write outcome.
+     */
+    resetQueue(expectedRevision?: number): Promise<VisibilityWriteResult>;
+    /**
+     * Drop both tables, re-inheriting the composition base and schema defaults.
+     * @returns the write outcome.
+     */
+    resetAll(): Promise<VisibilityWriteResult>;
+    /** Release the handle; idempotent, and every later write fails. */
+    dispose(): void;
+}
+/**
+ * Structural subset of the Cordis context the adapter needs: optional-dependency
+ * injection plus effect scoping. Keeping it structural avoids a dependency on
+ * `@deepseek-ai/dsh-settings` and lets tests drive the seam with a stub.
+ */
+export interface SettingsContextLike {
+    /**
+     * Run `callback` once every named service is available, and again whenever
+     * one re-attaches.
+     * @param deps - required service names.
+     * @param callback - receives the dependency-injected context.
+     */
+    inject(deps: string[], callback: (ctx: unknown) => void): void;
+    /**
+     * Scope a teardown to the owning context.
+     * @param cb - returns the disposer to run on unload.
+     * @param label - diagnostic label.
+     */
+    effect?(cb: () => (() => void) | void, label?: string): void;
+}
+/** Options for {@link installVisibilitySettings}. */
+export interface InstallOptions {
+    /** Section namespace; defaults to {@link VISIBILITY_SETTINGS_NS}. */
+    namespace?: string;
+    /** Composition presets, normalized and retained for visibility surfaces. */
+    patterns?: readonly string[];
+    /** Composition-layer fallback entry, also used while no provider is attached. */
+    base?: VisibilitySettings;
+    /**
+     * Called after every committed change with a detached snapshot of the next
+     * switches, including the attach and detach transitions.
+     * @param next - the authoritative switches after the change.
+     */
+    onChange?: (next: VisibilitySettings) => void;
+}
+/** User-layer override of the global queue budget; every field is optional. */
+export interface QueueSettingsOverride {
+    /** Single wait budget in ms; undefined inherits the cordis composition base. */
+    maxWaitMs?: number | undefined;
+    /** Queue depth cap; undefined inherits the cordis composition base. */
+    maxQueueDepth?: number | undefined;
+    /** Default per-provider concurrency (`0` = unlimited); undefined inherits the base. */
+    defaultConcurrency?: number | undefined;
+    /** Provider-specific entries (`0` = unlimited); undefined inherits the base table. */
+    perProviderConcurrency?: Record<string, number> | undefined;
+}
+/** Section schema: both tables default to empty, i.e. everything visible. */
+export declare const VisibilitySettingsSchema: z<Schemastery.ObjectS<{
+    providers: z<import("@deepseek-ai/cosmokit").Dict<boolean, string>, import("@deepseek-ai/cosmokit").Dict<boolean, string>>;
+    models: z<import("@deepseek-ai/cosmokit").Dict<boolean, string>, import("@deepseek-ai/cosmokit").Dict<boolean, string>>;
+    queue: z<Schemastery.ObjectS<{
+        maxWaitMs: z<number, number>;
+        maxQueueDepth: z<number, number>;
+        defaultConcurrency: z<number, number>;
+        perProviderConcurrency: z<import("@deepseek-ai/cosmokit").Dict<number, string>, import("@deepseek-ai/cosmokit").Dict<number, string>>;
+    }>, Schemastery.ObjectT<{
+        maxWaitMs: z<number, number>;
+        maxQueueDepth: z<number, number>;
+        defaultConcurrency: z<number, number>;
+        perProviderConcurrency: z<import("@deepseek-ai/cosmokit").Dict<number, string>, import("@deepseek-ai/cosmokit").Dict<number, string>>;
+    }>>;
+}>, Schemastery.ObjectT<{
+    providers: z<import("@deepseek-ai/cosmokit").Dict<boolean, string>, import("@deepseek-ai/cosmokit").Dict<boolean, string>>;
+    models: z<import("@deepseek-ai/cosmokit").Dict<boolean, string>, import("@deepseek-ai/cosmokit").Dict<boolean, string>>;
+    queue: z<Schemastery.ObjectS<{
+        maxWaitMs: z<number, number>;
+        maxQueueDepth: z<number, number>;
+        defaultConcurrency: z<number, number>;
+        perProviderConcurrency: z<import("@deepseek-ai/cosmokit").Dict<number, string>, import("@deepseek-ai/cosmokit").Dict<number, string>>;
+    }>, Schemastery.ObjectT<{
+        maxWaitMs: z<number, number>;
+        maxQueueDepth: z<number, number>;
+        defaultConcurrency: z<number, number>;
+        perProviderConcurrency: z<import("@deepseek-ai/cosmokit").Dict<number, string>, import("@deepseek-ai/cosmokit").Dict<number, string>>;
+    }>>;
+}>>;
+/** A handle that additionally exposes the composition presets it was given. */
+export interface VisibilitySettingsHandleWithPatterns extends VisibilitySettingsHandle {
+    /** Normalized composition presets, in declaration order. */
+    patterns(): readonly string[];
+}
+/**
+ * Install the visibility settings section on an optional settings provider.
+ *
+ * The handle is usable immediately and stays usable when no provider is ever
+ * attached; `read()` then answers from `options.base` and every write fails
+ * with `SETTINGS_ERROR`. With a provider present the section is registered
+ * under `options.namespace`, `setSource` supplies the authoritative value, and
+ * `onChange` refreshes the revision before notifying `options.onChange`.
+ *
+ * @param ctx - plugin context owning the registration and its teardown.
+ * @param options - namespace, composition presets, base entry, and change sink.
+ * @returns the handle; at runtime it also implements
+ * {@link VisibilitySettingsHandleWithPatterns} for the composition presets.
+ */
+export declare function installVisibilitySettings(ctx: SettingsContextLike, options?: InstallOptions): VisibilitySettingsHandle;

package/lib/visibility-settings.js

@@ -0,0 +1,225 @@
+/**
+ * Visibility settings adapter: the `llm-ctl` settings section that persists the
+ * two model-visibility tables.
+ *
+ * The settings provider is an optional dependency. {@link installVisibilitySettings}
+ * attaches through `ctx.inject(['settings'], …)`, so a deployment without a
+ * settings provider still loads: the handle keeps answering reads from the
+ * composition `base` and refuses writes with `SETTINGS_ERROR`. When a provider
+ * is present the section is registered with
+ * `settings.installSection(ctx, ns, schema, base, hooks)` — the owner is the
+ * plugin context, so disposing the plugin fiber removes the namespace — and the
+ * hooks keep the authoritative value and the section revision in sync.
+ *
+ * Writes are path-addressed (`settings.mutate`), never wholesale, so a caller
+ * holding a redacted view cannot delete fields it never saw; `expectedRevision`
+ * is forwarded verbatim so a stale writer is refused with `SETTINGS_CONFLICT`.
+ *
+ * @module dsh-llm-ctl/visibility-settings
+ */
+import z from '@deepseek-ai/schemastery';
+import { modelKey, normalizePattern } from "./visibility.js";
+/** Namespace the visibility tables are persisted under. */
+export const VISIBILITY_SETTINGS_NS = 'llm-ctl';
+/** Message returned when no settings provider is attached. */
+const UNAVAILABLE_MESSAGE = 'settings provider unavailable';
+/** Message returned once the handle has been disposed. */
+const DISPOSED_MESSAGE = 'visibility settings handle disposed';
+/** Section schema: both tables default to empty, i.e. everything visible. */
+export const VisibilitySettingsSchema = z.object({
+    providers: z.dict(z.boolean()).default({}),
+    models: z.dict(z.boolean()).default({}),
+    queue: z.object({
+        maxWaitMs: z.number().min(0),
+        maxQueueDepth: z.number().step(1).min(1),
+        defaultConcurrency: z.number().step(1).min(0),
+        perProviderConcurrency: z.dict(z.number().step(1).min(0)),
+    }),
+});
+/** Copy one table, keeping only boolean entries; a missing or bad table is empty. */
+function copyTable(table) {
+    const out = {};
+    if (typeof table !== 'object' || table === null)
+        return out;
+    for (const [key, value] of Object.entries(table)) {
+        if (typeof value === 'boolean')
+            out[key] = value;
+    }
+    return out;
+}
+/** Detach the queue override slice of a resolved section value. */
+function detachQueue(value) {
+    const record = (typeof value === 'object' && value !== null ? value : {});
+    const queue = (typeof record.queue === 'object' && record.queue !== null ? record.queue : {});
+    const out = {};
+    if (typeof queue['maxWaitMs'] === 'number' && Number.isFinite(queue['maxWaitMs']) && queue['maxWaitMs'] >= 0) {
+        out.maxWaitMs = queue['maxWaitMs'];
+    }
+    if (typeof queue['maxQueueDepth'] === 'number' && Number.isFinite(queue['maxQueueDepth']) && queue['maxQueueDepth'] >= 1) {
+        out.maxQueueDepth = Math.floor(queue['maxQueueDepth']);
+    }
+    if (typeof queue['defaultConcurrency'] === 'number' && Number.isFinite(queue['defaultConcurrency']) && queue['defaultConcurrency'] >= 0) {
+        out.defaultConcurrency = Math.floor(queue['defaultConcurrency']);
+    }
+    const table = queue['perProviderConcurrency'];
+    if (typeof table === 'object' && table !== null) {
+        const entries = {};
+        for (const [key, value] of Object.entries(table)) {
+            if (key.length === 0 || typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+                continue;
+            entries[key] = Math.floor(value);
+        }
+        if (Object.keys(entries).length > 0)
+            out.perProviderConcurrency = entries;
+    }
+    return out;
+}
+/** Detach a resolved section into a fresh, deeply independent settings object. */
+function detach(value) {
+    const record = (typeof value === 'object' && value !== null ? value : {});
+    return { providers: copyTable(record.providers), models: copyTable(record.models) };
+}
+/** Render an unknown rejection as a message. */
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+/** Read the machine code off an unknown rejection. */
+function errorCode(error) {
+    if (typeof error !== 'object' || error === null)
+        return undefined;
+    return error.code;
+}
+/**
+ * Install the visibility settings section on an optional settings provider.
+ *
+ * The handle is usable immediately and stays usable when no provider is ever
+ * attached; `read()` then answers from `options.base` and every write fails
+ * with `SETTINGS_ERROR`. With a provider present the section is registered
+ * under `options.namespace`, `setSource` supplies the authoritative value, and
+ * `onChange` refreshes the revision before notifying `options.onChange`.
+ *
+ * @param ctx - plugin context owning the registration and its teardown.
+ * @param options - namespace, composition presets, base entry, and change sink.
+ * @returns the handle; at runtime it also implements
+ * {@link VisibilitySettingsHandleWithPatterns} for the composition presets.
+ */
+export function installVisibilitySettings(ctx, options = {}) {
+    const namespace = options.namespace ?? VISIBILITY_SETTINGS_NS;
+    const base = detach(options.base);
+    const patterns = (options.patterns ?? []).map((pattern) => normalizePattern(pattern));
+    let settingsProvider;
+    let source = () => base;
+    let revision;
+    let disposed = false;
+    /** Seed or refresh the revision from the provider's own descriptor. */
+    function refreshRevision(target) {
+        if (target === undefined)
+            return;
+        try {
+            const descriptor = target.describe().find((entry) => entry.ns === namespace);
+            if (descriptor !== undefined && typeof descriptor.revision === 'number')
+                revision = descriptor.revision;
+        }
+        catch {
+            // A provider that cannot describe itself keeps the last observed revision.
+        }
+    }
+    function read() {
+        if (disposed)
+            return detach(base);
+        try {
+            return detach(source());
+        }
+        catch {
+            return detach(base);
+        }
+    }
+    function readQueue() {
+        if (disposed)
+            return {};
+        try {
+            return detachQueue(source());
+        }
+        catch {
+            return {};
+        }
+    }
+    async function write(ops, expectedRevision) {
+        if (disposed)
+            return { ok: false, code: 'SETTINGS_ERROR', message: DISPOSED_MESSAGE };
+        const target = settingsProvider;
+        if (target === undefined)
+            return { ok: false, code: 'SETTINGS_ERROR', message: UNAVAILABLE_MESSAGE };
+        try {
+            await target.mutate(namespace, ops, expectedRevision);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                code: errorCode(error) === 'SETTINGS_CONFLICT' ? 'SETTINGS_CONFLICT' : 'SETTINGS_ERROR',
+                message: errorMessage(error),
+            };
+        }
+        refreshRevision(target);
+        return revision === undefined ? { ok: true } : { ok: true, revision };
+    }
+    /** Attach one provider: register the section and adopt its value source. */
+    function attach(target) {
+        target.installSection(ctx, namespace, VisibilitySettingsSchema, base, {
+            setSource(current) {
+                source = typeof current === 'function' ? current : () => current;
+            },
+            onChange() {
+                refreshRevision(settingsProvider);
+                options.onChange?.(read());
+            },
+        });
+        settingsProvider = target;
+        refreshRevision(target);
+    }
+    ctx.inject(['settings'], (settingsCtx) => {
+        const target = settingsCtx?.settings;
+        if (target === undefined)
+            return;
+        attach(target);
+    });
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        settingsProvider = undefined;
+        source = () => base;
+    }
+    ctx.effect?.(() => () => {
+        dispose();
+    }, 'llm-ctl: dispose visibility settings handle');
+    const handle = {
+        read,
+        revision: () => (disposed ? undefined : revision),
+        write,
+        setProvider: (provider, visible) => write([{ op: 'set', path: ['providers', provider], value: visible }]),
+        setModel: (provider, model, visible) => write([{ op: 'set', path: ['models', modelKey(provider, model)], value: visible }]),
+        queue: readQueue,
+        setQueue: (partial, expectedRevision) => {
+            const ops = [];
+            if (partial.maxWaitMs !== undefined)
+                ops.push({ op: 'set', path: ['queue', 'maxWaitMs'], value: partial.maxWaitMs });
+            if (partial.maxQueueDepth !== undefined)
+                ops.push({ op: 'set', path: ['queue', 'maxQueueDepth'], value: partial.maxQueueDepth });
+            if (partial.defaultConcurrency !== undefined)
+                ops.push({ op: 'set', path: ['queue', 'defaultConcurrency'], value: partial.defaultConcurrency });
+            if (partial.perProviderConcurrency !== undefined)
+                ops.push({ op: 'set', path: ['queue', 'perProviderConcurrency'], value: partial.perProviderConcurrency });
+            if (ops.length === 0)
+                return Promise.resolve({ ok: true });
+            return write(ops, expectedRevision);
+        },
+        resetQueue: (expectedRevision) => write([{ op: 'unset', path: ['queue'] }], expectedRevision),
+        resetAll: () => write([{ op: 'unset', path: ['providers'] }, { op: 'unset', path: ['models'] }]),
+        dispose,
+        patterns: () => [...patterns],
+    };
+    return handle;
+}

package/lib/visibility.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Model visibility: two-level switches plus wildcard presets.
+ *
+ * Priority, highest first: an explicit `models['provider:model']` entry, an
+ * explicit `providers[provider]` entry, a matching `hiddenPatterns` entry,
+ * visible by default. A provider switched off hides every one of its models,
+ * even one carrying an explicit `true`.
+ *
+ * @module dsh-llm-ctl/visibility
+ */
+/** Two-level visibility switches, keyed exactly as {@link modelKey} produces. */
+export interface VisibilitySettings {
+    /** Provider id → visible. An explicit `false` hides all of its models. */
+    providers: Record<string, boolean>;
+    /** {@link modelKey} → visible. Outranks the provider entry. */
+    models: Record<string, boolean>;
+}
+/** Composition-level presets, applied below the explicit switches. */
+export interface VisibilityConfig {
+    /** Wildcard patterns; only `*` is special, matching any run of characters. */
+    hiddenPatterns?: readonly string[] | undefined;
+}
+/** Minimal shape of one catalog row, e.g. an `ctx.llm` model listing. */
+export interface CatalogEntry {
+    provider: string;
+    model: string;
+    displayName?: string | undefined;
+}
+/**
+ * Canonical form of a wildcard pattern: surrounding whitespace trimmed and
+ * lower-cased. Matching is case-insensitive, so this is the form compared.
+ *
+ * @param pattern Raw pattern, as written in configuration.
+ * @returns The trimmed, lower-cased pattern.
+ */
+export declare function normalizePattern(pattern: string): string;
+/**
+ * Test one wildcard pattern against a provider/model pair.
+ *
+ * `*` is the only metacharacter and matches any run of characters, `:`
+ * included. A pattern may be written `provider:model` or, omitting the
+ * provider segment, as a model-only pattern that applies to every provider.
+ * When `model` is omitted only a pattern covering a whole provider
+ * (`p:*`, `p:`) can match.
+ *
+ * @param pattern Pattern to test, with or without a provider segment.
+ * @param provider Provider id to test.
+ * @param model Model id to test; omit to ask about the provider as a whole.
+ * @returns True when the pattern matches the pair.
+ */
+export declare function matchesPattern(pattern: string, provider: string, model?: string): boolean;
+/**
+ * Whether a provider is switched on.
+ *
+ * An explicit `providers[provider]` entry wins; otherwise a preset pattern
+ * covering the provider's whole model set (`p:*`, `p:`) hides it; otherwise
+ * it is visible.
+ *
+ * @param provider Provider id.
+ * @param settings Two-level switches.
+ * @param config Composition config with preset patterns; may be omitted.
+ * @returns True when the provider is visible.
+ */
+export declare function isProviderVisible(provider: string, settings: VisibilitySettings, config?: VisibilityConfig): boolean;
+/**
+ * Whether one model is switched on, resolving the full priority chain.
+ *
+ * A provider explicitly set to `false` hides all of its models. Otherwise an
+ * explicit `models` entry wins, then an explicit `providers` entry, then a
+ * matching preset pattern, then the visible default.
+ *
+ * @param provider Provider id.
+ * @param model Model id.
+ * @param settings Two-level switches.
+ * @param config Composition config with preset patterns; may be omitted.
+ * @returns True when the model is visible.
+ */
+export declare function isModelVisible(provider: string, model: string, settings: VisibilitySettings, config?: VisibilityConfig): boolean;
+/**
+ * Key under which one model's switch is stored.
+ *
+ * @param provider Provider id.
+ * @param model Model id.
+ * @returns The `provider:model` key used by {@link VisibilitySettings.models}.
+ */
+export declare function modelKey(provider: string, model: string): string;
+/**
+ * Return a new settings object with one provider switch written.
+ *
+ * The input is never mutated, and a repeated write of the same value still
+ * returns a fresh object so callers can diff by identity.
+ *
+ * @param settings Two-level switches; left untouched.
+ * @param provider Provider id.
+ * @param visible Whether the provider is visible.
+ * @returns A new settings object.
+ */
+export declare function setProviderVisible(settings: VisibilitySettings, provider: string, visible: boolean): VisibilitySettings;
+/**
+ * Return a new settings object with one model switch written.
+ *
+ * The input is never mutated, and a repeated write of the same value still
+ * returns a fresh object so callers can diff by identity.
+ *
+ * @param settings Two-level switches; left untouched.
+ * @param provider Provider id.
+ * @param model Model id.
+ * @param visible Whether the model is visible.
+ * @returns A new settings object.
+ */
+export declare function setModelVisible(settings: VisibilitySettings, provider: string, model: string, visible: boolean): VisibilitySettings;
+/**
+ * Return an empty settings object, i.e. every provider and model visible.
+ *
+ * @param settings Two-level switches; left untouched.
+ * @returns A new settings object with both tables empty.
+ */
+export declare function setAllVisible(settings: VisibilitySettings): VisibilitySettings;
+/**
+ * Split a catalog into visible and hidden rows, preserving input order.
+ *
+ * Rows are neither copied nor modified; both arrays hold the original objects.
+ *
+ * @param entries Catalog rows to partition.
+ * @param settings Two-level switches.
+ * @param config Composition config with preset patterns; may be omitted.
+ * @returns The visible rows and the hidden rows, each in input order.
+ */
+export declare function filterCatalog<T extends CatalogEntry>(entries: readonly T[], settings: VisibilitySettings, config?: VisibilityConfig): {
+    visible: T[];
+    hidden: T[];
+};
+/**
+ * How many catalog rows the current switches hide.
+ *
+ * @param entries Catalog rows to inspect.
+ * @param settings Two-level switches.
+ * @param config Composition config with preset patterns; may be omitted.
+ * @returns The hidden row count, equal to `filterCatalog(...).hidden.length`.
+ */
+export declare function hiddenCount<T extends CatalogEntry>(entries: readonly T[], settings: VisibilitySettings, config?: VisibilityConfig): number;
+/**
+ * Choose the fallback model when the current selection is hidden.
+ *
+ * @param current The selection to validate; it need not appear in `entries`.
+ * @param entries Candidate catalog rows, scanned in order.
+ * @param settings Two-level switches.
+ * @param config Composition config with preset patterns; may be omitted.
+ * @returns Undefined when `current` is visible, else the first visible entry,
+ * else undefined when nothing is visible.
+ */
+export declare function pickFallback<T extends CatalogEntry>(current: CatalogEntry, entries: readonly T[], settings: VisibilitySettings, config?: VisibilityConfig): T | undefined;