@lorion-org/descriptor-selection 1.0.0-beta.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the 'Software'), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @lorion-org/descriptor-selection
+
+Framework-free, provider-aware descriptor selection.
+
+Given a set of items that each carry a descriptor and a selection seed, it
+resolves the active subset: it parses the seed (explicit selection, or CLI/env
+with a default fallback), applies **one-provider-per-capability** selection,
+builds the dependency graph, and returns the items reachable from the selection
+and the always-on base — in their original order.
+
+It is the shared selection brain: build-time bundler plugins, runtime hosts, and
+framework adapters all reuse it instead of re-gluing the graph and provider
+layers themselves.
+
+## Install
+
+```shell
+pnpm add @lorion-org/descriptor-selection
+```
+
+## API
+
+- `selectDescriptors({ items, getDescriptor, withDescriptor, seed, relationDescriptors?, policy? })`
+  resolves the active subset of `items`. It is generic over the item type via the
+  `getDescriptor` / `withDescriptor` accessors, so a "capability", an "extension",
+  or a plain descriptor record all work.
+- `resolveDescriptorSelection(seed)` resolves just the selection ids from a seed.
+- `applyProviderSelection({ items, selected, getDescriptor, withDescriptor })` applies one-provider-per-capability selection to a set of items (the step a host reuses when it drives its own graph resolution, e.g. the Nuxt adapter).
+- `assertSingleDefaultProvider(descriptors)` throws if two descriptors claim
+  `defaultFor` the same capability.
+- `providerRelationDescriptors`, `defaultResolutionRelations`, and
+  `descriptorSelectionPolicy(policy?)` expose the provider relations and the
+  default resolution policy.
+
+## What It Is Not
+
+- not a disk reader (see `@lorion-org/descriptor-discovery`)
+- not a graph engine (see `@lorion-org/composition-graph`)
+- not a host runtime or activation convention (see `@lorion-org/capability-composition`)
+
+## Local Commands
+
+```shell
+cd packages/descriptor-selection
+pnpm build
+pnpm test
+pnpm typecheck
+```

package/dist/index.cjs

@@ -0,0 +1,138 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  applyProviderSelection: () => applyProviderSelection,
+  assertSingleDefaultProvider: () => assertSingleDefaultProvider,
+  defaultResolutionRelations: () => defaultResolutionRelations,
+  descriptorSelectionPolicy: () => descriptorSelectionPolicy,
+  providerRelationDescriptors: () => providerRelationDescriptors,
+  resolveDescriptorSelection: () => resolveDescriptorSelection,
+  selectDescriptors: () => selectDescriptors
+});
+module.exports = __toCommonJS(index_exports);
+var import_composition_graph = require("@lorion-org/composition-graph");
+var import_provider_selection = require("@lorion-org/provider-selection");
+var providerRelationDescriptors = [
+  { direction: "incoming", field: "defaultFor", id: "defaultProviders" },
+  { field: "providerPreferences", id: "providerPreferences", targetMode: "values" }
+];
+var defaultResolutionRelations = [
+  "dependencies",
+  "defaultProviders",
+  "providerPreferences"
+];
+function descriptorSelectionPolicy(policy) {
+  return {
+    ...policy,
+    inspectionRelationIds: policy?.inspectionRelationIds ?? [...defaultResolutionRelations],
+    provenanceRelationIds: policy?.provenanceRelationIds ?? [...defaultResolutionRelations],
+    resolutionRelationIds: policy?.resolutionRelationIds ?? [...defaultResolutionRelations]
+  };
+}
+function resolveDescriptorSelection(seed) {
+  if (seed.selected?.length) return [...seed.selected];
+  if (seed.selectionSeed === false) return [...seed.defaultSelection ?? []];
+  const options = seed.selectionSeed ?? {};
+  const selected = (0, import_composition_graph.resolveDescriptorSelectionSeed)({
+    argv: options.argv ?? process.argv,
+    env: options.env ?? process.env,
+    key: options.key ?? "capability",
+    ...options.cliKeys ? { cliKeys: options.cliKeys } : {},
+    ...options.envKeys ? { envKeys: options.envKeys } : {}
+  });
+  return selected.length ? selected : [...seed.defaultSelection ?? []];
+}
+function assertSingleDefaultProvider(descriptors) {
+  const providersByCapability = /* @__PURE__ */ new Map();
+  for (const descriptor of descriptors) {
+    const { defaultFor } = descriptor;
+    if (!defaultFor) continue;
+    for (const capabilityId of Array.isArray(defaultFor) ? defaultFor : [defaultFor]) {
+      const providers = providersByCapability.get(capabilityId) ?? [];
+      providers.push(descriptor.id);
+      providersByCapability.set(capabilityId, providers);
+    }
+  }
+  const conflicts = [...providersByCapability.entries()].filter(([, providers]) => providers.length > 1).map(([capabilityId, providers]) => `${capabilityId}: ${[...providers].sort().join(", ")}`);
+  if (conflicts.length) {
+    throw new Error(
+      `Descriptor selection requires exactly one defaultFor provider per capability, but found multiple (${conflicts.join("; ")}).`
+    );
+  }
+}
+function applyProviderSelection(input) {
+  const { items, selected, getDescriptor, withDescriptor } = input;
+  const selectedProviders = (0, import_provider_selection.collectSelectedProviderPreferences)({
+    items,
+    getCapabilityId: (item) => getDescriptor(item).providesFor,
+    getProviderId: (item) => getDescriptor(item).id,
+    selectedProviderIds: selected
+  });
+  if (!Object.keys(selectedProviders).length) return [...items];
+  return items.map((item) => {
+    const descriptor = { ...getDescriptor(item) };
+    const preferences = (0, import_provider_selection.resolveSelectedProviderRelationPreferences)({
+      providerId: descriptor.id,
+      defaultFor: descriptor.defaultFor,
+      providerPreferences: descriptor.providerPreferences,
+      selectedProviders
+    });
+    delete descriptor.defaultFor;
+    delete descriptor.providerPreferences;
+    return withDescriptor(item, { ...descriptor, ...preferences });
+  });
+}
+function selectDescriptors(input) {
+  const { items, getDescriptor, withDescriptor, seed } = input;
+  const enabled = items.filter((item) => getDescriptor(item).disabled !== true);
+  assertSingleDefaultProvider(enabled.map(getDescriptor));
+  const selected = resolveDescriptorSelection(seed);
+  if (!selected.length && !seed.baseDescriptors?.length) return [...enabled];
+  const selectionItems = applyProviderSelection({
+    items: enabled,
+    selected,
+    getDescriptor,
+    withDescriptor
+  });
+  const catalog = (0, import_composition_graph.createDescriptorCatalog)({
+    descriptors: selectionItems.map(getDescriptor),
+    relationDescriptors: [...providerRelationDescriptors, ...input.relationDescriptors ?? []]
+  });
+  const selection = (0, import_composition_graph.createCompositionSelection)({
+    catalog,
+    selected: [...selected],
+    baseDescriptors: [...seed.baseDescriptors ?? []],
+    policy: descriptorSelectionPolicy(input.policy)
+  });
+  const resolvedIds = new Set(selection.getResolved());
+  return selectionItems.filter((item) => resolvedIds.has(getDescriptor(item).id));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  applyProviderSelection,
+  assertSingleDefaultProvider,
+  defaultResolutionRelations,
+  descriptorSelectionPolicy,
+  providerRelationDescriptors,
+  resolveDescriptorSelection,
+  selectDescriptors
+});

package/dist/index.d.cts

@@ -0,0 +1,37 @@
+import { Descriptor, DescriptorId, RelationDescriptor, CompositionPolicy } from '@lorion-org/composition-graph';
+
+declare const providerRelationDescriptors: RelationDescriptor[];
+declare const defaultResolutionRelations: readonly ["dependencies", "defaultProviders", "providerPreferences"];
+declare function descriptorSelectionPolicy(policy?: Partial<CompositionPolicy>): Partial<CompositionPolicy>;
+interface DescriptorSelectionSeed {
+    baseDescriptors?: readonly DescriptorId[];
+    defaultSelection?: readonly DescriptorId[];
+    selected?: readonly DescriptorId[];
+    selectionSeed?: false | {
+        argv?: string[];
+        env?: Record<string, string | undefined>;
+        key?: string;
+        cliKeys?: string[];
+        envKeys?: string[];
+    };
+}
+declare function resolveDescriptorSelection(seed: DescriptorSelectionSeed): DescriptorId[];
+declare function assertSingleDefaultProvider(descriptors: readonly Descriptor[]): void;
+interface ProviderSelectionInput<T> {
+    items: readonly T[];
+    selected: readonly DescriptorId[];
+    getDescriptor: (item: T) => Descriptor;
+    withDescriptor: (item: T, descriptor: Descriptor) => T;
+}
+declare function applyProviderSelection<T>(input: ProviderSelectionInput<T>): T[];
+interface DescriptorSelectionInput<T> {
+    items: readonly T[];
+    getDescriptor: (item: T) => Descriptor;
+    withDescriptor: (item: T, descriptor: Descriptor) => T;
+    seed: DescriptorSelectionSeed;
+    relationDescriptors?: readonly RelationDescriptor[];
+    policy?: Partial<CompositionPolicy>;
+}
+declare function selectDescriptors<T>(input: DescriptorSelectionInput<T>): T[];
+
+export { type DescriptorSelectionInput, type DescriptorSelectionSeed, type ProviderSelectionInput, applyProviderSelection, assertSingleDefaultProvider, defaultResolutionRelations, descriptorSelectionPolicy, providerRelationDescriptors, resolveDescriptorSelection, selectDescriptors };

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import { Descriptor, DescriptorId, RelationDescriptor, CompositionPolicy } from '@lorion-org/composition-graph';
+
+declare const providerRelationDescriptors: RelationDescriptor[];
+declare const defaultResolutionRelations: readonly ["dependencies", "defaultProviders", "providerPreferences"];
+declare function descriptorSelectionPolicy(policy?: Partial<CompositionPolicy>): Partial<CompositionPolicy>;
+interface DescriptorSelectionSeed {
+    baseDescriptors?: readonly DescriptorId[];
+    defaultSelection?: readonly DescriptorId[];
+    selected?: readonly DescriptorId[];
+    selectionSeed?: false | {
+        argv?: string[];
+        env?: Record<string, string | undefined>;
+        key?: string;
+        cliKeys?: string[];
+        envKeys?: string[];
+    };
+}
+declare function resolveDescriptorSelection(seed: DescriptorSelectionSeed): DescriptorId[];
+declare function assertSingleDefaultProvider(descriptors: readonly Descriptor[]): void;
+interface ProviderSelectionInput<T> {
+    items: readonly T[];
+    selected: readonly DescriptorId[];
+    getDescriptor: (item: T) => Descriptor;
+    withDescriptor: (item: T, descriptor: Descriptor) => T;
+}
+declare function applyProviderSelection<T>(input: ProviderSelectionInput<T>): T[];
+interface DescriptorSelectionInput<T> {
+    items: readonly T[];
+    getDescriptor: (item: T) => Descriptor;
+    withDescriptor: (item: T, descriptor: Descriptor) => T;
+    seed: DescriptorSelectionSeed;
+    relationDescriptors?: readonly RelationDescriptor[];
+    policy?: Partial<CompositionPolicy>;
+}
+declare function selectDescriptors<T>(input: DescriptorSelectionInput<T>): T[];
+
+export { type DescriptorSelectionInput, type DescriptorSelectionSeed, type ProviderSelectionInput, applyProviderSelection, assertSingleDefaultProvider, defaultResolutionRelations, descriptorSelectionPolicy, providerRelationDescriptors, resolveDescriptorSelection, selectDescriptors };

package/dist/index.js

@@ -0,0 +1,114 @@
+// src/index.ts
+import {
+  createCompositionSelection,
+  createDescriptorCatalog,
+  resolveDescriptorSelectionSeed
+} from "@lorion-org/composition-graph";
+import {
+  collectSelectedProviderPreferences,
+  resolveSelectedProviderRelationPreferences
+} from "@lorion-org/provider-selection";
+var providerRelationDescriptors = [
+  { direction: "incoming", field: "defaultFor", id: "defaultProviders" },
+  { field: "providerPreferences", id: "providerPreferences", targetMode: "values" }
+];
+var defaultResolutionRelations = [
+  "dependencies",
+  "defaultProviders",
+  "providerPreferences"
+];
+function descriptorSelectionPolicy(policy) {
+  return {
+    ...policy,
+    inspectionRelationIds: policy?.inspectionRelationIds ?? [...defaultResolutionRelations],
+    provenanceRelationIds: policy?.provenanceRelationIds ?? [...defaultResolutionRelations],
+    resolutionRelationIds: policy?.resolutionRelationIds ?? [...defaultResolutionRelations]
+  };
+}
+function resolveDescriptorSelection(seed) {
+  if (seed.selected?.length) return [...seed.selected];
+  if (seed.selectionSeed === false) return [...seed.defaultSelection ?? []];
+  const options = seed.selectionSeed ?? {};
+  const selected = resolveDescriptorSelectionSeed({
+    argv: options.argv ?? process.argv,
+    env: options.env ?? process.env,
+    key: options.key ?? "capability",
+    ...options.cliKeys ? { cliKeys: options.cliKeys } : {},
+    ...options.envKeys ? { envKeys: options.envKeys } : {}
+  });
+  return selected.length ? selected : [...seed.defaultSelection ?? []];
+}
+function assertSingleDefaultProvider(descriptors) {
+  const providersByCapability = /* @__PURE__ */ new Map();
+  for (const descriptor of descriptors) {
+    const { defaultFor } = descriptor;
+    if (!defaultFor) continue;
+    for (const capabilityId of Array.isArray(defaultFor) ? defaultFor : [defaultFor]) {
+      const providers = providersByCapability.get(capabilityId) ?? [];
+      providers.push(descriptor.id);
+      providersByCapability.set(capabilityId, providers);
+    }
+  }
+  const conflicts = [...providersByCapability.entries()].filter(([, providers]) => providers.length > 1).map(([capabilityId, providers]) => `${capabilityId}: ${[...providers].sort().join(", ")}`);
+  if (conflicts.length) {
+    throw new Error(
+      `Descriptor selection requires exactly one defaultFor provider per capability, but found multiple (${conflicts.join("; ")}).`
+    );
+  }
+}
+function applyProviderSelection(input) {
+  const { items, selected, getDescriptor, withDescriptor } = input;
+  const selectedProviders = collectSelectedProviderPreferences({
+    items,
+    getCapabilityId: (item) => getDescriptor(item).providesFor,
+    getProviderId: (item) => getDescriptor(item).id,
+    selectedProviderIds: selected
+  });
+  if (!Object.keys(selectedProviders).length) return [...items];
+  return items.map((item) => {
+    const descriptor = { ...getDescriptor(item) };
+    const preferences = resolveSelectedProviderRelationPreferences({
+      providerId: descriptor.id,
+      defaultFor: descriptor.defaultFor,
+      providerPreferences: descriptor.providerPreferences,
+      selectedProviders
+    });
+    delete descriptor.defaultFor;
+    delete descriptor.providerPreferences;
+    return withDescriptor(item, { ...descriptor, ...preferences });
+  });
+}
+function selectDescriptors(input) {
+  const { items, getDescriptor, withDescriptor, seed } = input;
+  const enabled = items.filter((item) => getDescriptor(item).disabled !== true);
+  assertSingleDefaultProvider(enabled.map(getDescriptor));
+  const selected = resolveDescriptorSelection(seed);
+  if (!selected.length && !seed.baseDescriptors?.length) return [...enabled];
+  const selectionItems = applyProviderSelection({
+    items: enabled,
+    selected,
+    getDescriptor,
+    withDescriptor
+  });
+  const catalog = createDescriptorCatalog({
+    descriptors: selectionItems.map(getDescriptor),
+    relationDescriptors: [...providerRelationDescriptors, ...input.relationDescriptors ?? []]
+  });
+  const selection = createCompositionSelection({
+    catalog,
+    selected: [...selected],
+    baseDescriptors: [...seed.baseDescriptors ?? []],
+    policy: descriptorSelectionPolicy(input.policy)
+  });
+  const resolvedIds = new Set(selection.getResolved());
+  return selectionItems.filter((item) => resolvedIds.has(getDescriptor(item).id));
+}
+export {
+  applyProviderSelection,
+  assertSingleDefaultProvider,
+  defaultResolutionRelations,
+  descriptorSelectionPolicy,
+  providerRelationDescriptors,
+  resolveDescriptorSelection,
+  selectDescriptors
+};

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@lorion-org/descriptor-selection",
+  "version": "1.0.0-beta.3",
+  "description": "Framework-free provider-aware descriptor selection: resolve the active set from a seed with dependency and single-provider resolution.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lorion-org/lorion.git",
+    "directory": "packages/descriptor-selection"
+  },
+  "homepage": "https://github.com/lorion-org/lorion/tree/main/packages/descriptor-selection#readme",
+  "bugs": {
+    "url": "https://github.com/lorion-org/lorion/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "lorion-source": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "src/**/*.ts",
+    "!src/**/*.spec.ts"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "clean": "rimraf coverage dist tsconfig.tsbuildinfo",
+    "lint": "eslint src --ext .ts",
+    "prepack": "pnpm build",
+    "test": "vitest run --root ../.. --config vitest.config.mts packages/descriptor-selection/src/index.spec.ts",
+    "coverage": "node -e \"require('node:fs').mkdirSync('../../coverage/.tmp', { recursive: true })\" && vitest run --coverage --coverage.include=packages/descriptor-selection/src/**/*.ts --root ../.. --config vitest.config.mts packages/descriptor-selection/src/index.spec.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "package:check": "pnpm build && pnpm pack --dry-run && publint"
+  },
+  "dependencies": {
+    "@lorion-org/composition-graph": "workspace:^",
+    "@lorion-org/provider-selection": "workspace:^"
+  },
+  "keywords": [
+    "descriptor",
+    "selection",
+    "composition",
+    "provider",
+    "typescript"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,191 @@
+import {
+  createCompositionSelection,
+  createDescriptorCatalog,
+  resolveDescriptorSelectionSeed,
+  type CompositionPolicy,
+  type Descriptor,
+  type DescriptorId,
+  type RelationDescriptor,
+} from '@lorion-org/composition-graph';
+import {
+  collectSelectedProviderPreferences,
+  resolveSelectedProviderRelationPreferences,
+  type ProviderPreferenceMap,
+} from '@lorion-org/provider-selection';
+
+// Provider-aware descriptor selection: given a set of items that each carry a
+// descriptor and a selection seed, resolve the active subset — applying
+// dependency resolution and one-provider-per-capability selection. Generic over
+// the item type, so build-time bundlers, runtime hosts, and framework adapters
+// share one selection brain instead of re-gluing the graph and provider layers.
+
+// The relations that make provider resolution work: a capability's default
+// provider (an incoming `defaultFor` edge) and its explicit provider preferences.
+export const providerRelationDescriptors: RelationDescriptor[] = [
+  { direction: 'incoming', field: 'defaultFor', id: 'defaultProviders' },
+  { field: 'providerPreferences', id: 'providerPreferences', targetMode: 'values' },
+];
+
+// The relations walked when resolving, inspecting, and tracing provenance.
+export const defaultResolutionRelations = [
+  'dependencies',
+  'defaultProviders',
+  'providerPreferences',
+] as const;
+
+export function descriptorSelectionPolicy(
+  policy?: Partial<CompositionPolicy>,
+): Partial<CompositionPolicy> {
+  return {
+    ...policy,
+    inspectionRelationIds: policy?.inspectionRelationIds ?? [...defaultResolutionRelations],
+    provenanceRelationIds: policy?.provenanceRelationIds ?? [...defaultResolutionRelations],
+    resolutionRelationIds: policy?.resolutionRelationIds ?? [...defaultResolutionRelations],
+  };
+}
+
+export interface DescriptorSelectionSeed {
+  baseDescriptors?: readonly DescriptorId[];
+  defaultSelection?: readonly DescriptorId[];
+  selected?: readonly DescriptorId[];
+  selectionSeed?:
+    | false
+    | {
+        argv?: string[];
+        env?: Record<string, string | undefined>;
+        key?: string;
+        cliKeys?: string[];
+        envKeys?: string[];
+      };
+}
+
+// The active selection ids from a seed: explicit `selected` wins; otherwise the
+// CLI/env seed is parsed, falling back to `defaultSelection`. Base descriptors are
+// resolved separately by the graph and are not part of this list.
+export function resolveDescriptorSelection(seed: DescriptorSelectionSeed): DescriptorId[] {
+  if (seed.selected?.length) return [...seed.selected];
+  if (seed.selectionSeed === false) return [...(seed.defaultSelection ?? [])];
+
+  const options = seed.selectionSeed ?? {};
+  const selected = resolveDescriptorSelectionSeed({
+    argv: options.argv ?? process.argv,
+    env: options.env ?? process.env,
+    key: options.key ?? 'capability',
+    ...(options.cliKeys ? { cliKeys: options.cliKeys } : {}),
+    ...(options.envKeys ? { envKeys: options.envKeys } : {}),
+  });
+
+  return selected.length ? selected : [...(seed.defaultSelection ?? [])];
+}
+
+// A capability may declare exactly one default provider. Two descriptors both
+// claiming `defaultFor` the same capability is a misconfiguration: without an
+// explicit provider selection nothing disambiguates them and both would resolve.
+export function assertSingleDefaultProvider(descriptors: readonly Descriptor[]): void {
+  const providersByCapability = new Map<string, string[]>();
+
+  for (const descriptor of descriptors) {
+    const { defaultFor } = descriptor;
+    if (!defaultFor) continue;
+    for (const capabilityId of Array.isArray(defaultFor) ? defaultFor : [defaultFor]) {
+      const providers = providersByCapability.get(capabilityId) ?? [];
+      providers.push(descriptor.id);
+      providersByCapability.set(capabilityId, providers);
+    }
+  }
+
+  const conflicts = [...providersByCapability.entries()]
+    .filter(([, providers]) => providers.length > 1)
+    .map(([capabilityId, providers]) => `${capabilityId}: ${[...providers].sort().join(', ')}`);
+
+  if (conflicts.length) {
+    throw new Error(
+      `Descriptor selection requires exactly one defaultFor provider per capability, but found multiple (${conflicts.join('; ')}).`,
+    );
+  }
+}
+
+export interface ProviderSelectionInput<T> {
+  items: readonly T[];
+  selected: readonly DescriptorId[];
+  getDescriptor: (item: T) => Descriptor;
+  withDescriptor: (item: T, descriptor: Descriptor) => T;
+}
+
+// Apply one-provider-per-capability selection: for each explicitly selected
+// provider, drop the competing `defaultFor`/`providerPreferences` from the other
+// items so the graph resolves exactly one provider. Items are returned untouched
+// when no provider is selected.
+export function applyProviderSelection<T>(input: ProviderSelectionInput<T>): T[] {
+  const { items, selected, getDescriptor, withDescriptor } = input;
+
+  const selectedProviders = collectSelectedProviderPreferences({
+    items,
+    getCapabilityId: (item) => getDescriptor(item).providesFor,
+    getProviderId: (item) => getDescriptor(item).id,
+    selectedProviderIds: selected,
+  });
+
+  if (!Object.keys(selectedProviders).length) return [...items];
+
+  return items.map((item) => {
+    const descriptor: Descriptor = { ...getDescriptor(item) };
+    const preferences = resolveSelectedProviderRelationPreferences({
+      providerId: descriptor.id,
+      defaultFor: descriptor.defaultFor,
+      providerPreferences: descriptor.providerPreferences as ProviderPreferenceMap | undefined,
+      selectedProviders,
+    });
+    delete descriptor.defaultFor;
+    delete descriptor.providerPreferences;
+    return withDescriptor(item, { ...descriptor, ...preferences });
+  });
+}
+
+export interface DescriptorSelectionInput<T> {
+  items: readonly T[];
+  // Read the descriptor an item carries.
+  getDescriptor: (item: T) => Descriptor;
+  // Return a copy of the item with a rewritten descriptor (provider preferences
+  // applied). Keeps the item type opaque to this package.
+  withDescriptor: (item: T, descriptor: Descriptor) => T;
+  seed: DescriptorSelectionSeed;
+  // Extra relations to resolve alongside the provider relations (for example a
+  // host's own dependency or grouping edges).
+  relationDescriptors?: readonly RelationDescriptor[];
+  policy?: Partial<CompositionPolicy>;
+}
+
+// Resolve the active subset of items: apply provider selection, build the
+// descriptor graph, resolve the seed + base + transitive dependencies, and return
+// the items whose descriptor is in the resolved set — in their original order.
+export function selectDescriptors<T>(input: DescriptorSelectionInput<T>): T[] {
+  const { items, getDescriptor, withDescriptor, seed } = input;
+
+  const enabled = items.filter((item) => getDescriptor(item).disabled !== true);
+  assertSingleDefaultProvider(enabled.map(getDescriptor));
+
+  const selected = resolveDescriptorSelection(seed);
+  if (!selected.length && !seed.baseDescriptors?.length) return [...enabled];
+
+  const selectionItems = applyProviderSelection({
+    items: enabled,
+    selected,
+    getDescriptor,
+    withDescriptor,
+  });
+
+  const catalog = createDescriptorCatalog({
+    descriptors: selectionItems.map(getDescriptor),
+    relationDescriptors: [...providerRelationDescriptors, ...(input.relationDescriptors ?? [])],
+  });
+  const selection = createCompositionSelection({
+    catalog,
+    selected: [...selected],
+    baseDescriptors: [...(seed.baseDescriptors ?? [])],
+    policy: descriptorSelectionPolicy(input.policy),
+  });
+  const resolvedIds = new Set(selection.getResolved());
+
+  return selectionItems.filter((item) => resolvedIds.has(getDescriptor(item).id));
+}