@lorion-org/capability-composition 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,52 @@
+# @lorion-org/capability-composition
+
+Framework-free capability composition over the LORION core.
+
+It resolves a descriptor-defined capability set (discovery, dependency-graph selection, provider selection, and seeding), detects surfaces by a host-defined convention, and composes the active capabilities into any runtime. One composition path is shared by build-time hosts (for example a Vite adapter) and runtime hosts (for example a Bun server); each host supplies only its activation convention and its registration.
+
+## Install
+
+```shell
+pnpm add @lorion-org/capability-composition
+```
+
+## API
+
+- `resolveSelectedCapabilities({ workspaceRoot, capabilitiesDir, seed })` resolves the active capabilities: base descriptors, the selection seed, transitive dependencies, and exactly one provider per capability.
+- `conventionActivation(surfaces)` builds an activation resolver from per-surface conventions (a file-layout marker plus an export-name derivation), so descriptors carry no surface config. Re-exported from [`@lorion-org/surface-activation`](../surface-activation), which owns the addressing convention.
+- `composeCapabilities({ workspaceRoot, capabilitiesDir, seed, surface, activation, load, register })` resolves the active set and, for each capability that provides the surface, loads its module and hands the exported value to the host's registration. Registry- and framework-agnostic.
+- Build-time hosts that code-generate static imports use `resolveSurfaceModules` from [`@lorion-org/surface-activation`](../surface-activation) directly — the same seam `composeCapabilities` uses internally. It is intentionally not re-exported here, so a build-time host depends only on the light addressing package, not this runtime host.
+
+## What It Is Not
+
+- not a framework runtime or plugin registry
+- not a bundler or a router
+- not an application naming convention
+
+## Composition timing: runtime vs build-time
+
+The same descriptor selection drives two host styles, differing only in _when_
+composition runs and _how_ modules are loaded:
+
+- **Runtime** — call `composeCapabilities` at boot with a dynamic
+  `load: (specifier) => import(specifier)`. Simple and fine for a source-run
+  server that starts once; resolution is a one-time boot cost.
+- **Build-time** — run `resolveSelectedCapabilities` (here) + `resolveSurfaceModules`
+  (from `@lorion-org/surface-activation`) in a build step and code-generate _static_
+  imports. The injected set is fixed and
+  auditable at build time, with no runtime discovery or dynamic `import()` —
+  suited to bundled or air-gapped artifacts.
+
+Both compose the identical set from one seam — `resolveSurfaceModules` in
+`@lorion-org/surface-activation`. See `snippets/buildtime-composition.ts` for the
+build-time manifest.
+
+## Local Commands
+
+```shell
+cd packages/capability-composition
+pnpm build
+pnpm test
+pnpm typecheck
+pnpm package:check
+```

package/dist/index.cjs

@@ -0,0 +1,86 @@
+"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, {
+  composeCapabilities: () => composeCapabilities,
+  conventionActivation: () => import_surface_activation2.conventionActivation,
+  fileSurfaceConvention: () => import_surface_activation2.fileSurfaceConvention,
+  resolveSelectedCapabilities: () => resolveSelectedCapabilities
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_descriptor_discovery = require("@lorion-org/descriptor-discovery");
+var import_descriptor_selection = require("@lorion-org/descriptor-selection");
+var import_surface_activation = require("@lorion-org/surface-activation");
+var import_surface_activation2 = require("@lorion-org/surface-activation");
+function readPackageName(directory) {
+  const path = (0, import_node_path.resolve)(directory, "package.json");
+  const json = JSON.parse((0, import_node_fs.readFileSync)(path, "utf8"));
+  return (0, import_descriptor_discovery.requirePackageName)(json, path);
+}
+function resolveSelectedCapabilities(options) {
+  const capabilitiesDir = options.capabilitiesDir ?? "capabilities";
+  const items = (0, import_descriptor_discovery.discoverDescriptors)({
+    cwd: options.workspaceRoot,
+    descriptorPaths: [`${capabilitiesDir}/*/capability.json`],
+    validation: { schema: import_descriptor_discovery.descriptorSchema }
+  }).map((entry) => ({
+    id: entry.descriptor.id,
+    directory: entry.cwd,
+    descriptor: entry.descriptor
+  }));
+  const selected = (0, import_descriptor_selection.selectDescriptors)({
+    items,
+    getDescriptor: (item) => item.descriptor,
+    withDescriptor: (item, descriptor) => ({ ...item, descriptor }),
+    seed: options.seed,
+    ...options.policy ? { policy: options.policy } : {}
+  });
+  return selected.map((item) => ({ ...item, packageName: readPackageName(item.directory) }));
+}
+async function composeCapabilities(options) {
+  const active = resolveSelectedCapabilities({
+    workspaceRoot: options.workspaceRoot,
+    capabilitiesDir: options.capabilitiesDir ?? "capabilities",
+    seed: options.seed
+  });
+  const activated = [];
+  for (const { capability, specifier, exportName } of (0, import_surface_activation.resolveSurfaceModules)(
+    active,
+    options.surface,
+    options.activation
+  )) {
+    const module2 = await options.load(specifier);
+    const exportValue = module2[exportName];
+    if (exportValue === void 0) continue;
+    await options.register(exportValue, capability);
+    activated.push(capability);
+  }
+  return activated;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  composeCapabilities,
+  conventionActivation,
+  fileSurfaceConvention,
+  resolveSelectedCapabilities
+});

package/dist/index.d.cts

@@ -0,0 +1,35 @@
+import { DescriptorId, Descriptor, CompositionPolicy } from '@lorion-org/composition-graph';
+import { SurfaceCapability, ActivationResolver } from '@lorion-org/surface-activation';
+export { ActivationResolver, FileSurfaceConventionOptions, SurfaceActivation, SurfaceConvention, conventionActivation, fileSurfaceConvention } from '@lorion-org/surface-activation';
+
+interface CapabilitySelectionSeed {
+    baseDescriptors?: readonly DescriptorId[];
+    defaultSelection?: readonly DescriptorId[];
+    selected?: readonly DescriptorId[];
+    selectionSeed?: false | {
+        argv?: string[];
+        cliKeys?: string[];
+        env?: Record<string, string | undefined>;
+        envKeys?: string[];
+    };
+}
+interface ResolvedCapability extends SurfaceCapability {
+    descriptor: Descriptor;
+}
+declare function resolveSelectedCapabilities(options: {
+    workspaceRoot: string;
+    capabilitiesDir?: string;
+    seed: CapabilitySelectionSeed;
+    policy?: Partial<CompositionPolicy>;
+}): ResolvedCapability[];
+declare function composeCapabilities(options: {
+    workspaceRoot: string;
+    capabilitiesDir?: string;
+    seed: CapabilitySelectionSeed;
+    surface: string;
+    activation: ActivationResolver;
+    load: (specifier: string) => Promise<Record<string, unknown>>;
+    register: (exportValue: unknown, capability: ResolvedCapability) => void | Promise<void>;
+}): Promise<ResolvedCapability[]>;
+
+export { type CapabilitySelectionSeed, type ResolvedCapability, composeCapabilities, resolveSelectedCapabilities };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import { DescriptorId, Descriptor, CompositionPolicy } from '@lorion-org/composition-graph';
+import { SurfaceCapability, ActivationResolver } from '@lorion-org/surface-activation';
+export { ActivationResolver, FileSurfaceConventionOptions, SurfaceActivation, SurfaceConvention, conventionActivation, fileSurfaceConvention } from '@lorion-org/surface-activation';
+
+interface CapabilitySelectionSeed {
+    baseDescriptors?: readonly DescriptorId[];
+    defaultSelection?: readonly DescriptorId[];
+    selected?: readonly DescriptorId[];
+    selectionSeed?: false | {
+        argv?: string[];
+        cliKeys?: string[];
+        env?: Record<string, string | undefined>;
+        envKeys?: string[];
+    };
+}
+interface ResolvedCapability extends SurfaceCapability {
+    descriptor: Descriptor;
+}
+declare function resolveSelectedCapabilities(options: {
+    workspaceRoot: string;
+    capabilitiesDir?: string;
+    seed: CapabilitySelectionSeed;
+    policy?: Partial<CompositionPolicy>;
+}): ResolvedCapability[];
+declare function composeCapabilities(options: {
+    workspaceRoot: string;
+    capabilitiesDir?: string;
+    seed: CapabilitySelectionSeed;
+    surface: string;
+    activation: ActivationResolver;
+    load: (specifier: string) => Promise<Record<string, unknown>>;
+    register: (exportValue: unknown, capability: ResolvedCapability) => void | Promise<void>;
+}): Promise<ResolvedCapability[]>;
+
+export { type CapabilitySelectionSeed, type ResolvedCapability, composeCapabilities, resolveSelectedCapabilities };

package/dist/index.js

@@ -0,0 +1,64 @@
+// src/index.ts
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import {
+  descriptorSchema,
+  discoverDescriptors,
+  requirePackageName
+} from "@lorion-org/descriptor-discovery";
+import { selectDescriptors } from "@lorion-org/descriptor-selection";
+import {
+  resolveSurfaceModules
+} from "@lorion-org/surface-activation";
+import { conventionActivation, fileSurfaceConvention } from "@lorion-org/surface-activation";
+function readPackageName(directory) {
+  const path = resolve(directory, "package.json");
+  const json = JSON.parse(readFileSync(path, "utf8"));
+  return requirePackageName(json, path);
+}
+function resolveSelectedCapabilities(options) {
+  const capabilitiesDir = options.capabilitiesDir ?? "capabilities";
+  const items = discoverDescriptors({
+    cwd: options.workspaceRoot,
+    descriptorPaths: [`${capabilitiesDir}/*/capability.json`],
+    validation: { schema: descriptorSchema }
+  }).map((entry) => ({
+    id: entry.descriptor.id,
+    directory: entry.cwd,
+    descriptor: entry.descriptor
+  }));
+  const selected = selectDescriptors({
+    items,
+    getDescriptor: (item) => item.descriptor,
+    withDescriptor: (item, descriptor) => ({ ...item, descriptor }),
+    seed: options.seed,
+    ...options.policy ? { policy: options.policy } : {}
+  });
+  return selected.map((item) => ({ ...item, packageName: readPackageName(item.directory) }));
+}
+async function composeCapabilities(options) {
+  const active = resolveSelectedCapabilities({
+    workspaceRoot: options.workspaceRoot,
+    capabilitiesDir: options.capabilitiesDir ?? "capabilities",
+    seed: options.seed
+  });
+  const activated = [];
+  for (const { capability, specifier, exportName } of resolveSurfaceModules(
+    active,
+    options.surface,
+    options.activation
+  )) {
+    const module = await options.load(specifier);
+    const exportValue = module[exportName];
+    if (exportValue === void 0) continue;
+    await options.register(exportValue, capability);
+    activated.push(capability);
+  }
+  return activated;
+}
+export {
+  composeCapabilities,
+  conventionActivation,
+  fileSurfaceConvention,
+  resolveSelectedCapabilities
+};

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@lorion-org/capability-composition",
+  "version": "1.0.0-beta.3",
+  "description": "Framework-free capability composition: on-disk descriptor selection and runtime/build-time composition, built on the surface-activation convention.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lorion-org/lorion.git",
+    "directory": "packages/capability-composition"
+  },
+  "homepage": "https://github.com/lorion-org/lorion/tree/main/packages/capability-composition#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/capability-composition/src/index.spec.ts",
+    "coverage": "node -e \"require('node:fs').mkdirSync('../../coverage/.tmp', { recursive: true })\" && vitest run --coverage --coverage.include=packages/capability-composition/src/**/*.ts --root ../.. --config vitest.config.mts packages/capability-composition/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/descriptor-discovery": "workspace:^",
+    "@lorion-org/descriptor-selection": "workspace:^",
+    "@lorion-org/surface-activation": "workspace:^"
+  },
+  "keywords": [
+    "lorion",
+    "capability",
+    "composition",
+    "typescript"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,127 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { CompositionPolicy, Descriptor, DescriptorId } from '@lorion-org/composition-graph';
+import {
+  descriptorSchema,
+  discoverDescriptors,
+  requirePackageName,
+} from '@lorion-org/descriptor-discovery';
+import { selectDescriptors } from '@lorion-org/descriptor-selection';
+import {
+  type ActivationResolver,
+  resolveSurfaceModules,
+  type SurfaceCapability,
+} from '@lorion-org/surface-activation';
+
+// Capability composition: descriptor-defined capabilities that live as filesystem
+// packages, composed into a host. This package owns disk discovery and the
+// runtime/build-time compose loop; resolving the active set (seed, dependencies,
+// one provider per capability) is delegated to @lorion-org/descriptor-selection and
+// the surface-addressing convention to @lorion-org/surface-activation, so no logic
+// is duplicated here.
+
+// Re-export the convention-building companions a `composeCapabilities` caller needs
+// to build the activation it passes in: `conventionActivation`, the
+// `fileSurfaceConvention` preset, and the describing types. The build-time
+// addressing tools (`resolveSurfaceModules`, `capabilitySpecifier`) stay owned
+// solely by @lorion-org/surface-activation, so a build-time host depends on that
+// light package directly instead of pulling in this runtime host.
+export { conventionActivation, fileSurfaceConvention } from '@lorion-org/surface-activation';
+export type {
+  ActivationResolver,
+  FileSurfaceConventionOptions,
+  SurfaceActivation,
+  SurfaceConvention,
+} from '@lorion-org/surface-activation';
+
+export interface CapabilitySelectionSeed {
+  baseDescriptors?: readonly DescriptorId[];
+  defaultSelection?: readonly DescriptorId[];
+  selected?: readonly DescriptorId[];
+  selectionSeed?:
+    | false
+    | {
+        argv?: string[];
+        cliKeys?: string[];
+        env?: Record<string, string | undefined>;
+        envKeys?: string[];
+      };
+}
+
+export interface ResolvedCapability extends SurfaceCapability {
+  descriptor: Descriptor;
+}
+
+function readPackageName(directory: string): string {
+  const path = resolve(directory, 'package.json');
+  const json = JSON.parse(readFileSync(path, 'utf8')) as { name?: unknown };
+  return requirePackageName(json, path);
+}
+
+// Resolves the active capability set: base + seed + transitive dependencies +
+// exactly one provider per capability, over capabilities discovered on disk.
+// The selection itself is owned by @lorion-org/descriptor-selection.
+export function resolveSelectedCapabilities(options: {
+  workspaceRoot: string;
+  capabilitiesDir?: string;
+  seed: CapabilitySelectionSeed;
+  policy?: Partial<CompositionPolicy>;
+}): ResolvedCapability[] {
+  const capabilitiesDir = options.capabilitiesDir ?? 'capabilities';
+  const items = discoverDescriptors({
+    cwd: options.workspaceRoot,
+    descriptorPaths: [`${capabilitiesDir}/*/capability.json`],
+    validation: { schema: descriptorSchema },
+  }).map((entry) => ({
+    id: entry.descriptor.id,
+    directory: entry.cwd,
+    descriptor: entry.descriptor,
+  }));
+
+  const selected = selectDescriptors({
+    items,
+    getDescriptor: (item) => item.descriptor,
+    withDescriptor: (item, descriptor) => ({ ...item, descriptor }),
+    seed: options.seed,
+    ...(options.policy ? { policy: options.policy } : {}),
+  });
+
+  // Read package.json only for the resolved set: an unrelated broken or nameless
+  // package.json must not abort a composition that never imports that capability.
+  return selected.map((item) => ({ ...item, packageName: readPackageName(item.directory) }));
+}
+
+// Runtime composition: resolve the active set, and for each capability that
+// provides the requested surface, load its module and hand the exported value to
+// the host's registration. Registry- and framework-agnostic. A build-time host
+// uses `resolveSurfaceModules` directly to emit static imports instead.
+export async function composeCapabilities(options: {
+  workspaceRoot: string;
+  capabilitiesDir?: string;
+  seed: CapabilitySelectionSeed;
+  surface: string;
+  activation: ActivationResolver;
+  load: (specifier: string) => Promise<Record<string, unknown>>;
+  register: (exportValue: unknown, capability: ResolvedCapability) => void | Promise<void>;
+}): Promise<ResolvedCapability[]> {
+  const active = resolveSelectedCapabilities({
+    workspaceRoot: options.workspaceRoot,
+    capabilitiesDir: options.capabilitiesDir ?? 'capabilities',
+    seed: options.seed,
+  });
+  const activated: ResolvedCapability[] = [];
+
+  for (const { capability, specifier, exportName } of resolveSurfaceModules(
+    active,
+    options.surface,
+    options.activation,
+  )) {
+    const module = await options.load(specifier);
+    const exportValue = module[exportName];
+    if (exportValue === undefined) continue;
+    await options.register(exportValue, capability);
+    activated.push(capability);
+  }
+
+  return activated;
+}