`resolveCapabilities`

(no submodules)

Purpose

Decide whether a plugin can boot against the host's registered capability set. Missing required capabilities block resolution; missing optional capabilities surface as warnings; version mismatches against the host's adapter version block resolution.

Features

Discriminated result type — { ok: true; warnings } or { ok: false; error }
Optional versionRanges map drives per-capability semver checks
Warnings carry the same code surface as errors
Returns the full warning list (every missing optional, not just the first)

Basic Example

import { resolveCapabilities } from "@suaveplan/api-manifest/capability-resolver";
resolveCapabilities({
  manifest,
  registered: [{ id: "db.transactions", version: "1.4.0" }],
});

Advanced Example

import { resolveCapabilities, type CapabilityDescriptor } from "@suaveplan/api-manifest/capability-resolver";

const registered: CapabilityDescriptor[] = host.listCapabilities();
const result = resolveCapabilities({
  manifest,
  registered,
  versionRanges: { "db.transactions": "^1" },
});
if (!result.ok) throw result.error;
for (const w of result.warnings) logger.warn(w.code, w.details);

API Reference

resolveCapabilities(input: ResolveCapabilitiesInput): CapabilityResolution
Failure codes: CAPABILITY_REQUIRED_MISSING, CAPABILITY_VERSION_MISMATCH.
Warning code: OPTIONAL_CAPABILITY_MISSING.

Implementation Notes

Version ranges are supplied by the caller rather than the manifest because the manifest declares which capabilities it needs, not which versions — the host's compat policy decides the range. This keeps the manifest forward-compatible across host upgrades; only the host needs to be updated when a capability's wire format changes. Warnings are kept distinct from errors so the host can log them and continue boot, which is the whole point of marking a capability optional.

Cross-package Notes

This module is part of the @suaveplan/api-manifest Stage-1 contract package. It sits beneath every Stage-2 consumer (api-host, api-loader, the admin CLI, the IDE plugin) and above the foundation packages (@suaveplan/error, @suaveplan/types). The strict-mode top-level rejection of unknown keys means upgrading from manifest v1 to v2 is an OpenSpec-driven event: a new key landing in a consumer manifest is a parse failure rather than a silent drift, which is exactly the contract this stage exists to guarantee.

When the host reloads a plugin without a full restart, every manifest field this module validates is compared against the install-time manifestHash. A mismatch triggers a hard rollback via the RollbackJournal because the host's invariants (route mounts, registered capabilities, declared scopes) are derived from these exact bytes. Treat the schemas and validators here as the contract surface, not just an input filter — downstream code reads manifest.foo.bar and relies on those keys being present, well-typed, and non-undefined in the documented optionality regions.

3.1 KiB Raw Blame History

resolveCapabilities