@lorion-org/composition-graph 1.0.0-beta.1 → 1.0.0-beta.2

package/README.md

@@ -71,6 +71,7 @@ const catalog = createDescriptorCatalog({
     {
       id: 'payment-provider-stripe',
       version: '1.0.0',
+      defaultFor: 'payment-checkout',
       providesFor: 'payment-checkout',
       dependencies: { payments: '^1.0.0' },
     },
@@ -134,6 +135,33 @@ selection.getResolved();
 // => ['checkout', 'payments', 'shops', 'web']
 ```
 
+## Example: normalize selection seeds
+
+Host adapters often accept descriptor selections from CLI flags, package-manager
+config variables, environment variables, or static defaults. Use
+`resolveDescriptorSelectionSeed()` at that boundary and pass the resulting ids to
+the catalog or framework adapter.
+
+The graph package does not prescribe a domain word for selection. Pass `key`
+when you want derived CLI and environment names, or pass explicit `cliKeys` and
+`envKeys`. Framework adapters such as `@lorion-org/nuxt` and
+`@lorion-org/react` provide their own `capability` default.
+
+```ts
+import { resolveDescriptorSelectionSeed } from '@lorion-org/composition-graph';
+
+const selected = resolveDescriptorSelectionSeed({
+  argv: process.argv,
+  defaultValue: ['default'],
+  env: process.env,
+  key: 'capability',
+});
+
+// --capabilities=admin,checkout
+// LORION_CAPABILITIES="admin checkout"
+// => ['admin', 'checkout']
+```
+
 ## Example: explain why something is present
 
 The catalog and selection APIs expose path explanation helpers for diagnostics,
@@ -197,16 +225,29 @@ const catalog = createDescriptorCatalog({
 - `dependencies` is the only built-in relation
 - every additional relation must be registered via `relationDescriptors`
 - unconfigured descriptor fields are ignored by the graph
-- string parsing for user-facing selection input belongs in a higher adapter layer
+- selection seed parsing belongs at the host adapter boundary
 - nested descriptor authoring belongs in a discovery or normalization layer, not in this package
 
 `relationDescriptors` are intentionally small:
 
 - `id` identifies the relation in graph queries and policies
 - `field` optionally maps the relation to a descriptor field name
+- `targetMode: 'values'` reads object values instead of object keys
+- `direction: 'incoming'` builds inverse edges from a target field back to the descriptor
+
+The core graph does not prescribe provider policy, hinting, or weighting. Those
+concerns belong in higher layers. A framework adapter can, for example, register
+an inverse `defaultProviders` relation for provider-owned defaults:
+
+```ts
+const catalog = createDescriptorCatalog({
+  descriptors,
+  relationDescriptors: [{ id: 'defaultProviders', field: 'defaultFor', direction: 'incoming' }],
+});
+```
 
-The core graph does not prescribe directional interpretation, hinting, or
-weighting. Those concerns belong in higher layers.
+That turns `{ id: 'keycloak', defaultFor: 'auth' }` into a graph edge
+`auth -> keycloak`, as long as both descriptors exist.
 
 Dependency-specific projections are also intentionally outside the core. If a
 consumer needs a "what pulled this in?" view, derive that from

package/dist/index.cjs

@@ -33,7 +33,8 @@ __export(index_exports, {
   getDependents: () => getDependents,
   getIncomingRelationMap: () => getIncomingRelationMap,
   getTransitiveTargets: () => getTransitiveTargets,
-  parseDescriptorIds: () => parseDescriptorIds
+  parseDescriptorIds: () => parseDescriptorIds,
+  resolveDescriptorSelectionSeed: () => resolveDescriptorSelectionSeed
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -46,10 +47,66 @@ function buildDescriptorMap(descriptors) {
   return descriptorMap;
 }
 function parseDescriptorIds(input) {
-  if (!input) return [];
-  const items = Array.isArray(input) ? input : input.split(/[,\s]+/).map((item) => item.trim());
+  if (typeof input === "string") {
+    return Array.from(
+      new Set(
+        input.split(/[,\s]+/).map((item) => item.trim()).filter(Boolean)
+      )
+    ).sort();
+  }
+  if (!Array.isArray(input)) return [];
+  const items = input.flatMap((item) => typeof item === "string" ? parseDescriptorIds(item) : []);
   return Array.from(new Set(items.map((item) => item.trim()).filter(Boolean))).sort();
 }
+function readCliValue(argv, key) {
+  const arg = argv.find((entry) => entry === key || entry.startsWith(`${key}=`));
+  if (!arg) return void 0;
+  if (arg === key) {
+    const value = argv[argv.indexOf(arg) + 1];
+    return value?.startsWith("-") ? void 0 : value;
+  }
+  return arg.slice(`${key}=`.length);
+}
+function firstNonEmptyValue(values) {
+  return values.find((value) => {
+    if (typeof value === "string") return value.trim().length > 0;
+    return Array.isArray(value) && value.some((entry) => typeof entry === "string" && entry.trim());
+  });
+}
+function pluralizeSelectionKeySegment(value) {
+  if (value.endsWith("s")) return value;
+  if (value.endsWith("y")) return `${value.slice(0, -1)}ies`;
+  return `${value}s`;
+}
+function normalizeSelectionKey(value) {
+  const segments = value.trim().replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase().split("-").filter(Boolean);
+  if (!segments.length) return "";
+  const lastSegment = segments[segments.length - 1];
+  segments[segments.length - 1] = pluralizeSelectionKeySegment(lastSegment);
+  return segments.join("-");
+}
+function toEnvKey(value) {
+  return value.replaceAll("-", "_").toUpperCase();
+}
+function resolveCliKeys(input) {
+  if (input.cliKeys) return input.cliKeys;
+  const key = input.key ? normalizeSelectionKey(input.key) : "";
+  return key ? [`--${key}`] : [];
+}
+function resolveEnvKeys(input) {
+  if (input.envKeys) return input.envKeys;
+  const key = input.key ? normalizeSelectionKey(input.key) : "";
+  return key ? [`npm_config_${key.replaceAll("-", "_")}`, `LORION_${toEnvKey(key)}`] : [];
+}
+function resolveDescriptorSelectionSeed(input = {}) {
+  return parseDescriptorIds(
+    firstNonEmptyValue([
+      ...resolveCliKeys(input).map((key) => readCliValue(input.argv ?? [], key)),
+      ...resolveEnvKeys(input).map((key) => input.env?.[key]),
+      input.defaultValue
+    ])
+  );
+}
 function assertKnownDescriptorIds(descriptorMap, ids, label) {
   const missing = [...new Set(ids)].filter((id) => id && !descriptorMap.has(id)).sort();
   if (!missing.length) return;
@@ -73,14 +130,14 @@ var defaultRelationDescriptors = [
     field: "dependencies"
   }
 ];
-function isVersionConstraintMap(value) {
+function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function getRelationTargets(descriptor, relationDescriptor) {
   const field = relationDescriptor.field ?? relationDescriptor.id;
   const relationValue = descriptor[field];
-  if (!isVersionConstraintMap(relationValue)) return [];
-  return Object.keys(relationValue).sort();
+  const targets = Array.isArray(relationValue) ? relationValue : typeof relationValue === "string" ? [relationValue] : isRecord(relationValue) ? relationDescriptor.targetMode === "values" ? Object.values(relationValue) : Object.keys(relationValue) : [];
+  return targets.filter((target) => typeof target === "string" && target.length > 0).sort();
 }
 function createOriginType(path) {
   return path.length ? "resolved" : "selected";
@@ -104,15 +161,16 @@ function buildDescriptorGraph(input) {
     for (const relationDescriptor of descriptorRegistry.values()) {
       for (const target of getRelationTargets(descriptor, relationDescriptor)) {
         if (!input.descriptorMap.has(target)) continue;
+        const isIncoming = relationDescriptor.direction === "incoming";
         const edge = {
-          from: descriptor.id,
-          to: target,
+          from: isIncoming ? target : descriptor.id,
+          to: isIncoming ? descriptor.id : target,
           relation: relationDescriptor.id,
           source: "descriptor"
         };
         edges.push(edge);
-        outgoing.get(descriptor.id)?.push(edge);
-        incoming.get(target)?.push(edge);
+        outgoing.get(edge.from)?.push(edge);
+        incoming.get(edge.to)?.push(edge);
       }
     }
   }
@@ -366,7 +424,7 @@ function buildDescriptorProfile(descriptor, relationIds, graph) {
     disabled: descriptor.disabled === true,
     capabilities: [...descriptor.capabilities ?? []].sort(),
     ...descriptor.location ? { location: descriptor.location } : {},
-    ...typeof descriptor.providesFor === "string" ? { providesFor: descriptor.providesFor } : {},
+    ...typeof descriptor.providesFor === "string" || Array.isArray(descriptor.providesFor) ? { providesFor: descriptor.providesFor } : {},
     outgoing,
     incoming
   };
@@ -438,5 +496,6 @@ function createDescriptorCatalog(input) {
   getDependents,
   getIncomingRelationMap,
   getTransitiveTargets,
-  parseDescriptorIds
+  parseDescriptorIds,
+  resolveDescriptorSelectionSeed
 });

package/dist/index.d.cts

@@ -5,7 +5,8 @@ type RelationId = string;
 type Descriptor = {
     id: DescriptorId;
     version: string;
-    providesFor?: string;
+    providesFor?: DescriptorId | DescriptorId[];
+    defaultFor?: DescriptorId | DescriptorId[];
     capabilities?: string[];
     dependencies?: VersionConstraintMap;
     disabled?: boolean;
@@ -14,8 +15,10 @@ type Descriptor = {
 };
 type DescriptorMap = Map<DescriptorId, Descriptor>;
 type RelationDescriptor = {
+    direction?: 'outgoing' | 'incoming';
     id: RelationId;
     field?: string;
+    targetMode?: 'keys' | 'values';
 };
 type DescriptorEdge = {
     from: DescriptorId;
@@ -48,7 +51,7 @@ type DescriptorProfile = {
     id: DescriptorId;
     location?: string;
     disabled: boolean;
-    providesFor?: string;
+    providesFor?: DescriptorId | DescriptorId[];
     capabilities: string[];
     outgoing: Record<RelationId, string[]>;
     incoming: Record<RelationId, string[]>;
@@ -130,8 +133,17 @@ type CompositionSelection = {
     }>;
 };
 
+type DescriptorSelectionSeedInput = {
+    argv?: string[];
+    cliKeys?: string[];
+    defaultValue?: DescriptorId[] | string;
+    env?: Record<string, string | undefined>;
+    envKeys?: string[];
+    key?: string;
+};
 declare function buildDescriptorMap(descriptors: Iterable<Descriptor>): DescriptorMap;
-declare function parseDescriptorIds(input?: DescriptorId[] | string): DescriptorId[];
+declare function parseDescriptorIds(input?: unknown): DescriptorId[];
+declare function resolveDescriptorSelectionSeed(input?: DescriptorSelectionSeedInput): DescriptorId[];
 declare function assertKnownDescriptorIds(descriptorMap: DescriptorMap, ids: DescriptorId[], label: string): void;
 
 declare const defaultRelationDescriptors: RelationDescriptor[];
@@ -194,4 +206,4 @@ declare function createCompositionSelection(input: {
     policy?: Partial<CompositionPolicy>;
 }): CompositionSelection;
 
-export { type CompositionOriginType, type CompositionPolicy, type CompositionProvenance, type CompositionProvenanceOrigin, type CompositionSelection, type Descriptor, type DescriptorCatalog, type DescriptorEdge, type DescriptorGraph, type DescriptorId, type DescriptorIds, type DescriptorMap, type DescriptorProfile, type RelationDescriptor, type RelationId, type ResolutionStep, type VersionConstraintMap, assertKnownDescriptorIds, buildDescriptorGraph, buildDescriptorMap, createCompositionSelection, createDescriptorCatalog, defaultCompositionPolicy, defaultRelationDescriptors, explainPath, explainPathsBatch, getCompositionProvenance, getDependents, getIncomingRelationMap, getTransitiveTargets, parseDescriptorIds };
+export { type CompositionOriginType, type CompositionPolicy, type CompositionProvenance, type CompositionProvenanceOrigin, type CompositionSelection, type Descriptor, type DescriptorCatalog, type DescriptorEdge, type DescriptorGraph, type DescriptorId, type DescriptorIds, type DescriptorMap, type DescriptorProfile, type DescriptorSelectionSeedInput, type RelationDescriptor, type RelationId, type ResolutionStep, type VersionConstraintMap, assertKnownDescriptorIds, buildDescriptorGraph, buildDescriptorMap, createCompositionSelection, createDescriptorCatalog, defaultCompositionPolicy, defaultRelationDescriptors, explainPath, explainPathsBatch, getCompositionProvenance, getDependents, getIncomingRelationMap, getTransitiveTargets, parseDescriptorIds, resolveDescriptorSelectionSeed };

package/dist/index.d.ts

@@ -5,7 +5,8 @@ type RelationId = string;
 type Descriptor = {
     id: DescriptorId;
     version: string;
-    providesFor?: string;
+    providesFor?: DescriptorId | DescriptorId[];
+    defaultFor?: DescriptorId | DescriptorId[];
     capabilities?: string[];
     dependencies?: VersionConstraintMap;
     disabled?: boolean;
@@ -14,8 +15,10 @@ type Descriptor = {
 };
 type DescriptorMap = Map<DescriptorId, Descriptor>;
 type RelationDescriptor = {
+    direction?: 'outgoing' | 'incoming';
     id: RelationId;
     field?: string;
+    targetMode?: 'keys' | 'values';
 };
 type DescriptorEdge = {
     from: DescriptorId;
@@ -48,7 +51,7 @@ type DescriptorProfile = {
     id: DescriptorId;
     location?: string;
     disabled: boolean;
-    providesFor?: string;
+    providesFor?: DescriptorId | DescriptorId[];
     capabilities: string[];
     outgoing: Record<RelationId, string[]>;
     incoming: Record<RelationId, string[]>;
@@ -130,8 +133,17 @@ type CompositionSelection = {
     }>;
 };
 
+type DescriptorSelectionSeedInput = {
+    argv?: string[];
+    cliKeys?: string[];
+    defaultValue?: DescriptorId[] | string;
+    env?: Record<string, string | undefined>;
+    envKeys?: string[];
+    key?: string;
+};
 declare function buildDescriptorMap(descriptors: Iterable<Descriptor>): DescriptorMap;
-declare function parseDescriptorIds(input?: DescriptorId[] | string): DescriptorId[];
+declare function parseDescriptorIds(input?: unknown): DescriptorId[];
+declare function resolveDescriptorSelectionSeed(input?: DescriptorSelectionSeedInput): DescriptorId[];
 declare function assertKnownDescriptorIds(descriptorMap: DescriptorMap, ids: DescriptorId[], label: string): void;
 
 declare const defaultRelationDescriptors: RelationDescriptor[];
@@ -194,4 +206,4 @@ declare function createCompositionSelection(input: {
     policy?: Partial<CompositionPolicy>;
 }): CompositionSelection;
 
-export { type CompositionOriginType, type CompositionPolicy, type CompositionProvenance, type CompositionProvenanceOrigin, type CompositionSelection, type Descriptor, type DescriptorCatalog, type DescriptorEdge, type DescriptorGraph, type DescriptorId, type DescriptorIds, type DescriptorMap, type DescriptorProfile, type RelationDescriptor, type RelationId, type ResolutionStep, type VersionConstraintMap, assertKnownDescriptorIds, buildDescriptorGraph, buildDescriptorMap, createCompositionSelection, createDescriptorCatalog, defaultCompositionPolicy, defaultRelationDescriptors, explainPath, explainPathsBatch, getCompositionProvenance, getDependents, getIncomingRelationMap, getTransitiveTargets, parseDescriptorIds };
+export { type CompositionOriginType, type CompositionPolicy, type CompositionProvenance, type CompositionProvenanceOrigin, type CompositionSelection, type Descriptor, type DescriptorCatalog, type DescriptorEdge, type DescriptorGraph, type DescriptorId, type DescriptorIds, type DescriptorMap, type DescriptorProfile, type DescriptorSelectionSeedInput, type RelationDescriptor, type RelationId, type ResolutionStep, type VersionConstraintMap, assertKnownDescriptorIds, buildDescriptorGraph, buildDescriptorMap, createCompositionSelection, createDescriptorCatalog, defaultCompositionPolicy, defaultRelationDescriptors, explainPath, explainPathsBatch, getCompositionProvenance, getDependents, getIncomingRelationMap, getTransitiveTargets, parseDescriptorIds, resolveDescriptorSelectionSeed };

package/dist/index.js

@@ -7,10 +7,66 @@ function buildDescriptorMap(descriptors) {
   return descriptorMap;
 }
 function parseDescriptorIds(input) {
-  if (!input) return [];
-  const items = Array.isArray(input) ? input : input.split(/[,\s]+/).map((item) => item.trim());
+  if (typeof input === "string") {
+    return Array.from(
+      new Set(
+        input.split(/[,\s]+/).map((item) => item.trim()).filter(Boolean)
+      )
+    ).sort();
+  }
+  if (!Array.isArray(input)) return [];
+  const items = input.flatMap((item) => typeof item === "string" ? parseDescriptorIds(item) : []);
   return Array.from(new Set(items.map((item) => item.trim()).filter(Boolean))).sort();
 }
+function readCliValue(argv, key) {
+  const arg = argv.find((entry) => entry === key || entry.startsWith(`${key}=`));
+  if (!arg) return void 0;
+  if (arg === key) {
+    const value = argv[argv.indexOf(arg) + 1];
+    return value?.startsWith("-") ? void 0 : value;
+  }
+  return arg.slice(`${key}=`.length);
+}
+function firstNonEmptyValue(values) {
+  return values.find((value) => {
+    if (typeof value === "string") return value.trim().length > 0;
+    return Array.isArray(value) && value.some((entry) => typeof entry === "string" && entry.trim());
+  });
+}
+function pluralizeSelectionKeySegment(value) {
+  if (value.endsWith("s")) return value;
+  if (value.endsWith("y")) return `${value.slice(0, -1)}ies`;
+  return `${value}s`;
+}
+function normalizeSelectionKey(value) {
+  const segments = value.trim().replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[_\s]+/g, "-").toLowerCase().split("-").filter(Boolean);
+  if (!segments.length) return "";
+  const lastSegment = segments[segments.length - 1];
+  segments[segments.length - 1] = pluralizeSelectionKeySegment(lastSegment);
+  return segments.join("-");
+}
+function toEnvKey(value) {
+  return value.replaceAll("-", "_").toUpperCase();
+}
+function resolveCliKeys(input) {
+  if (input.cliKeys) return input.cliKeys;
+  const key = input.key ? normalizeSelectionKey(input.key) : "";
+  return key ? [`--${key}`] : [];
+}
+function resolveEnvKeys(input) {
+  if (input.envKeys) return input.envKeys;
+  const key = input.key ? normalizeSelectionKey(input.key) : "";
+  return key ? [`npm_config_${key.replaceAll("-", "_")}`, `LORION_${toEnvKey(key)}`] : [];
+}
+function resolveDescriptorSelectionSeed(input = {}) {
+  return parseDescriptorIds(
+    firstNonEmptyValue([
+      ...resolveCliKeys(input).map((key) => readCliValue(input.argv ?? [], key)),
+      ...resolveEnvKeys(input).map((key) => input.env?.[key]),
+      input.defaultValue
+    ])
+  );
+}
 function assertKnownDescriptorIds(descriptorMap, ids, label) {
   const missing = [...new Set(ids)].filter((id) => id && !descriptorMap.has(id)).sort();
   if (!missing.length) return;
@@ -34,14 +90,14 @@ var defaultRelationDescriptors = [
     field: "dependencies"
   }
 ];
-function isVersionConstraintMap(value) {
+function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function getRelationTargets(descriptor, relationDescriptor) {
   const field = relationDescriptor.field ?? relationDescriptor.id;
   const relationValue = descriptor[field];
-  if (!isVersionConstraintMap(relationValue)) return [];
-  return Object.keys(relationValue).sort();
+  const targets = Array.isArray(relationValue) ? relationValue : typeof relationValue === "string" ? [relationValue] : isRecord(relationValue) ? relationDescriptor.targetMode === "values" ? Object.values(relationValue) : Object.keys(relationValue) : [];
+  return targets.filter((target) => typeof target === "string" && target.length > 0).sort();
 }
 function createOriginType(path) {
   return path.length ? "resolved" : "selected";
@@ -65,15 +121,16 @@ function buildDescriptorGraph(input) {
     for (const relationDescriptor of descriptorRegistry.values()) {
       for (const target of getRelationTargets(descriptor, relationDescriptor)) {
         if (!input.descriptorMap.has(target)) continue;
+        const isIncoming = relationDescriptor.direction === "incoming";
         const edge = {
-          from: descriptor.id,
-          to: target,
+          from: isIncoming ? target : descriptor.id,
+          to: isIncoming ? descriptor.id : target,
           relation: relationDescriptor.id,
           source: "descriptor"
         };
         edges.push(edge);
-        outgoing.get(descriptor.id)?.push(edge);
-        incoming.get(target)?.push(edge);
+        outgoing.get(edge.from)?.push(edge);
+        incoming.get(edge.to)?.push(edge);
       }
     }
   }
@@ -327,7 +384,7 @@ function buildDescriptorProfile(descriptor, relationIds, graph) {
     disabled: descriptor.disabled === true,
     capabilities: [...descriptor.capabilities ?? []].sort(),
     ...descriptor.location ? { location: descriptor.location } : {},
-    ...typeof descriptor.providesFor === "string" ? { providesFor: descriptor.providesFor } : {},
+    ...typeof descriptor.providesFor === "string" || Array.isArray(descriptor.providesFor) ? { providesFor: descriptor.providesFor } : {},
     outgoing,
     incoming
   };
@@ -398,5 +455,6 @@ export {
   getDependents,
   getIncomingRelationMap,
   getTransitiveTargets,
-  parseDescriptorIds
+  parseDescriptorIds,
+  resolveDescriptorSelectionSeed
 };

package/examples/deployment-composition.js

@@ -36,6 +36,7 @@ const catalog = createDescriptorCatalog({
     {
       id: 'payment-provider-stripe',
       version: '1.0.0',
+      defaultFor: 'payment-checkout',
       providesFor: 'payment-checkout',
       dependencies: { payments: '^1.0.0' },
     },

package/examples/deployment-composition.ts

@@ -35,6 +35,7 @@ const catalog = createDescriptorCatalog({
     {
       id: 'payment-provider-stripe',
       version: '1.0.0',
+      defaultFor: 'payment-checkout',
       providesFor: 'payment-checkout',
       dependencies: { payments: '^1.0.0' },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorion-org/composition-graph",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "description": "Framework-free descriptor catalogs, relation graphs, and composition selection logic.",
   "license": "MIT",
   "repository": {
@@ -22,6 +22,10 @@
   "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"
@@ -35,7 +39,9 @@
   "files": [
     "dist",
     "examples",
-    "LICENSE"
+    "LICENSE",
+    "src/**/*.ts",
+    "!src/**/*.spec.ts"
   ],
   "keywords": [
     "composition",

package/src/compositionSelection.ts

@@ -0,0 +1,109 @@
+import { getCompositionProvenance } from './descriptorGraph';
+import { assertKnownDescriptorIds } from './descriptorMap';
+import type {
+  CompositionPolicy,
+  CompositionProvenance,
+  CompositionSelection,
+  Descriptor,
+  DescriptorCatalog,
+  DescriptorId,
+} from './types';
+
+export const defaultCompositionPolicy: CompositionPolicy = {
+  resolutionRelationIds: ['dependencies'],
+  provenanceRelationIds: ['dependencies'],
+  inspectionRelationIds: ['dependencies'],
+};
+
+function resolvePolicy(policy?: Partial<CompositionPolicy>): CompositionPolicy {
+  return {
+    ...defaultCompositionPolicy,
+    ...policy,
+    resolutionRelationIds:
+      policy?.resolutionRelationIds ?? defaultCompositionPolicy.resolutionRelationIds,
+    provenanceRelationIds:
+      policy?.provenanceRelationIds ?? defaultCompositionPolicy.provenanceRelationIds,
+    inspectionRelationIds:
+      policy?.inspectionRelationIds ?? defaultCompositionPolicy.inspectionRelationIds,
+  };
+}
+
+export function createCompositionSelection(input: {
+  catalog: DescriptorCatalog;
+  selected?: DescriptorId[];
+  baseDescriptors?: DescriptorId[];
+  policy?: Partial<CompositionPolicy>;
+}): CompositionSelection {
+  const catalog = input.catalog;
+  const descriptorMap = catalog.getDescriptorMap();
+  const selected = [...new Set(input.selected ?? [])].filter(Boolean).sort();
+  const baseDescriptors = [...new Set(input.baseDescriptors ?? [])].filter(Boolean).sort();
+
+  assertKnownDescriptorIds(descriptorMap, selected, 'selected descriptors');
+  assertKnownDescriptorIds(descriptorMap, baseDescriptors, 'base descriptors');
+
+  const policy = resolvePolicy(input.policy);
+  const resolved = catalog.getTransitiveTargets({
+    start: [...selected, ...baseDescriptors],
+    relationIds: policy.resolutionRelationIds,
+  });
+
+  let resolvedDescriptorsCache: Descriptor[] | undefined;
+  let provenanceCache: CompositionProvenance[] | undefined;
+
+  const getResolvedDescriptors = (): Descriptor[] => {
+    if (!resolvedDescriptorsCache) {
+      resolvedDescriptorsCache = resolved
+        .map((descriptorId) => descriptorMap.get(descriptorId))
+        .filter((descriptor): descriptor is Descriptor => Boolean(descriptor));
+    }
+
+    return resolvedDescriptorsCache;
+  };
+
+  const getProvenance = (): CompositionProvenance[] => {
+    if (!provenanceCache) {
+      provenanceCache = getCompositionProvenance({
+        graph: catalog.getGraph(),
+        descriptorIds: resolved,
+        selected,
+        baseDescriptors,
+        relationIds: policy.provenanceRelationIds,
+      });
+    }
+
+    return provenanceCache;
+  };
+
+  return {
+    getCatalog: () => catalog,
+    getGraph: () => catalog.getGraph(),
+    getSelected: () => [...selected],
+    getBaseDescriptors: () => [...baseDescriptors],
+    getResolved: () => [...resolved],
+    getResolvedDescriptors,
+    getProvenance,
+    getDependentsFor: (target, dependentsInput = {}) => {
+      return catalog.getDependents({
+        target,
+        relationIds: dependentsInput.relationIds ?? policy.resolutionRelationIds,
+        ...(dependentsInput.transitive !== undefined
+          ? { transitive: dependentsInput.transitive }
+          : {}),
+      });
+    },
+    explain: (explainInput) => {
+      return catalog.explain({
+        from: explainInput.from,
+        to: explainInput.to,
+        relationIds: explainInput.relationIds ?? policy.inspectionRelationIds,
+      });
+    },
+    explainPathsBatch: (batchInput) => {
+      return catalog.explainPathsBatch({
+        pairs: batchInput.pairs,
+        relationIds: batchInput.relationIds ?? policy.inspectionRelationIds,
+      });
+    },
+  };
+}