@intentius/chant 0.13.1 → 0.15.0

package/src/components/capability-plugin-loader.ts

@@ -0,0 +1,218 @@
+/**
+ * Discovery + loading for capability plugins — the capability-side analogue
+ * of ../cli/plugins.ts's `loadPlugin`/`loadPlugins` for lexicons.
+ *
+ * Naming convention mirrors lexicons exactly, substituting "capability" for
+ * "lexicon": a capability plugin package is
+ * `@intentius/chant-capability-<name>` and is expected to export a value
+ * satisfying `CapabilityPlugin` (./capability-plugin.ts), detected at
+ * runtime with `isCapabilityPlugin` — the same dynamic-import + shape-guard
+ * strategy `loadPlugin` uses for `@intentius/chant-lexicon-<name>`.
+ *
+ * `buildCapabilityRegistry` is the Phase 2 replacement for Phase 1's
+ * `createCapabilityRegistry` (./registry.ts): it always loads the built-in
+ * `starterCapabilityPlugin` (./starter-plugin.ts) first — preserving every
+ * Phase 1 kind with zero behavior change — then loads any additional
+ * requested plugin packages on top, registering every capability they
+ * contribute into one `CapabilityRegistry` the driver resolves verbs
+ * through. Duplicate `kind` registration across plugins throws (via
+ * `CapabilityRegistry.register`'s existing guard), the same hard-conflict
+ * discipline `checkConflicts` (../cli/conflict-check.ts) applies to
+ * duplicate lexicon rule IDs.
+ */
+
+import { CapabilityRegistry } from "./capability";
+import type { CapabilityPlugin } from "./capability-plugin";
+import { isCapabilityPlugin } from "./capability-plugin";
+import { starterCapabilityPlugin } from "./starter-plugin";
+
+/** Thrown when a dynamically-imported capability package does not satisfy `CapabilityPlugin` — the "malformed capability package" case #559 asks doctor/validation to detect. */
+export class MalformedCapabilityPluginError extends Error {
+  constructor(
+    public readonly packageName: string,
+    reason: string,
+  ) {
+    super(`capability plugin package "${packageName}" is malformed: ${reason}`);
+    this.name = "MalformedCapabilityPluginError";
+  }
+}
+
+/** Thrown when two loaded capability plugins register the same `kind` — mirrors the lexicon loader's hard rule-ID conflict. */
+export class DuplicateCapabilityKindError extends Error {
+  constructor(
+    public readonly kind: string,
+    public readonly plugins: string[],
+  ) {
+    super(`capability "${kind}" is registered by more than one plugin: ${plugins.join(", ")}`);
+    this.name = "DuplicateCapabilityKindError";
+  }
+}
+
+/**
+ * Dynamically import and validate a single capability plugin package by
+ * name. Mirrors ../cli/plugins.ts's `loadPlugin` for lexicons: imports
+ * `@intentius/chant-capability-{name}`, scans its exports for a value
+ * satisfying `isCapabilityPlugin`, and throws a descriptive
+ * `MalformedCapabilityPluginError` if the package exists but exports nothing
+ * usable (the malformed-package case), or the original import error if the
+ * package cannot be found at all.
+ */
+export async function loadCapabilityPlugin(name: string): Promise<CapabilityPlugin> {
+  const packageName = `@intentius/chant-capability-${name}`;
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(packageName)) as Record<string, unknown>;
+  } catch (err) {
+    throw new Error(
+      `capability plugin package "${packageName}" could not be loaded: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  for (const value of Object.values(mod)) {
+    if (isCapabilityPlugin(value)) {
+      return value;
+    }
+  }
+
+  throw new MalformedCapabilityPluginError(
+    packageName,
+    `does not export a CapabilityPlugin (expected an export with string "name", string "version", and a "capabilities" function)`,
+  );
+}
+
+/**
+ * Load and initialize multiple named capability plugins, in order. Calls
+ * `init()` on each plugin if present — mirrors `loadPlugins`'s lexicon
+ * `init()` hook.
+ */
+export async function loadCapabilityPlugins(names: string[]): Promise<CapabilityPlugin[]> {
+  const plugins: CapabilityPlugin[] = [];
+  for (const name of names) {
+    const plugin = await loadCapabilityPlugin(name);
+    if (plugin.init) {
+      await plugin.init();
+    }
+    plugins.push(plugin);
+  }
+  return plugins;
+}
+
+/**
+ * Load the capability plugin a *lexicon* package contributes, if any. A cloud
+ * lexicon (`@intentius/chant-lexicon-<name>`) is the natural home for that
+ * cloud's operational leaves (`cfn-deploy`, `emr-*`, …) — the same seam that
+ * already carries the lexicon's synthesis, `describeResources`, and ownership
+ * markers (docs/components/cloud-boundary). So when a project declares
+ * `lexicons: ["aws"]`, its aws leaves come along automatically: this imports
+ * the lexicon package and returns the first export satisfying
+ * `isCapabilityPlugin`.
+ *
+ * Tolerant by design — a lexicon that contributes *no* capabilities (most do
+ * not yet) simply returns `null` rather than throwing, unlike
+ * `loadCapabilityPlugin`'s strict `@intentius/chant-capability-<name>` contract
+ * where the package's whole reason to exist is the plugin.
+ */
+export async function loadCapabilityPluginFromLexicon(name: string): Promise<CapabilityPlugin | null> {
+  const packageName = `@intentius/chant-lexicon-${name}`;
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(packageName)) as Record<string, unknown>;
+  } catch {
+    return null; // lexicon not installed / not resolvable here — nothing to contribute.
+  }
+  for (const value of Object.values(mod)) {
+    if (isCapabilityPlugin(value)) return value;
+  }
+  return null; // lexicon present but contributes no capability plugin.
+}
+
+/** Load the capability plugins contributed by the given lexicons (skipping those that contribute none), initializing each. */
+export async function loadCapabilityPluginsFromLexicons(names: string[]): Promise<CapabilityPlugin[]> {
+  const plugins: CapabilityPlugin[] = [];
+  for (const name of names) {
+    const plugin = await loadCapabilityPluginFromLexicon(name);
+    if (!plugin) continue;
+    if (plugin.init) await plugin.init();
+    plugins.push(plugin);
+  }
+  return plugins;
+}
+
+/**
+ * Register every capability every plugin contributes into one registry, in
+ * plugin order. Throws `DuplicateCapabilityKindError` if two plugins
+ * register the same `kind` (via a pre-check, so the error names every
+ * offending plugin rather than surfacing only the second registration
+ * attempt's generic `CapabilityRegistry.register` message).
+ */
+export function registerCapabilityPlugins(
+  registry: CapabilityRegistry,
+  plugins: CapabilityPlugin[],
+): CapabilityRegistry {
+  const owners = new Map<string, string[]>();
+  for (const plugin of plugins) {
+    for (const capability of plugin.capabilities()) {
+      const existing = owners.get(capability.kind) ?? [];
+      existing.push(plugin.name);
+      owners.set(capability.kind, existing);
+    }
+  }
+  for (const [kind, pluginNames] of owners) {
+    if (pluginNames.length > 1) {
+      throw new DuplicateCapabilityKindError(kind, pluginNames);
+    }
+  }
+
+  for (const plugin of plugins) {
+    for (const capability of plugin.capabilities()) {
+      registry.register(capability);
+    }
+  }
+  return registry;
+}
+
+export interface BuildCapabilityRegistryOptions {
+  /**
+   * Additional capability plugin package names to load and register on top
+   * of the built-in starter plugin (e.g. third-party/cloud-specific
+   * capability packages `@intentius/chant-capability-<name>`). Defaults to
+   * none — Phase 1 behavior (just the starter set) is preserved when omitted.
+   */
+  plugins?: string[];
+  /**
+   * Lexicon names (from `chant.config.ts`'s `lexicons`) whose packages may
+   * *also* contribute a capability plugin — the primary way a cloud's
+   * operational leaves are loaded (e.g. `["aws"]` pulls the aws lexicon's
+   * `cfn-deploy`/`emr-*`/… leaves). Lexicons contributing no capabilities are
+   * silently skipped; see `loadCapabilityPluginsFromLexicons`.
+   */
+  lexicons?: string[];
+  /**
+   * Skip loading the built-in starter plugin. Only meaningful for tests that
+   * want a registry seeded purely from explicit `plugins`; real callers
+   * should leave this unset so the Phase 1 verb set is always present.
+   */
+  includeStarter?: boolean;
+}
+
+/**
+ * Build a `CapabilityRegistry` through the Phase 2 plugin contract: always
+ * registers the built-in `starterCapabilityPlugin` first (preserving every
+ * Phase 1 `kind` — see ./starter-plugin.ts), then loads and registers any
+ * additional named plugin packages. This is the Phase 2 entry point;
+ * `createCapabilityRegistry` (./registry.ts) remains available and now
+ * delegates to this same starter plugin, so existing Phase 1 callers (and
+ * the pilots) are unaffected.
+ */
+export async function buildCapabilityRegistry(
+  options: BuildCapabilityRegistryOptions = {},
+): Promise<CapabilityRegistry> {
+  const registry = new CapabilityRegistry();
+  const plugins: CapabilityPlugin[] = [];
+  if (options.includeStarter !== false) {
+    plugins.push(starterCapabilityPlugin);
+  }
+  plugins.push(...(await loadCapabilityPluginsFromLexicons(options.lexicons ?? [])));
+  plugins.push(...(await loadCapabilityPlugins(options.plugins ?? [])));
+  return registerCapabilityPlugins(registry, plugins);
+}

package/src/components/capability-plugin-schema.ts

@@ -0,0 +1,56 @@
+/**
+ * Zod schema + validation for `CapabilityManifest` (./capability-plugin.ts) —
+ * the capability-side analogue of ../lexicon-schema.ts's
+ * `LexiconManifestSchema`/`validateManifest`. Used to detect a malformed
+ * capability package's manifest (#559 acceptance criteria: "Doctor/validation
+ * covers a malformed capability package") with the same descriptive-error
+ * shape lexicon manifest validation uses.
+ */
+
+import { z } from "zod";
+import type { CapabilityManifest } from "./capability-plugin";
+
+const semverRegex = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$/;
+
+export const CapabilityManifestSchema = z.object({
+  name: z.string().min(1, "manifest name must not be empty"),
+  version: z.string().regex(semverRegex, "version must be valid semver (X.Y.Z)"),
+  chantVersion: z.string().optional(),
+  kinds: z.array(z.string().min(1)).optional(),
+});
+
+export type CapabilityManifestParsed = z.infer<typeof CapabilityManifestSchema>;
+
+/**
+ * Validate a capability manifest from unknown input (object or JSON string).
+ * Throws a descriptive error on invalid input — mirrors
+ * ../lexicon-schema.ts's `validateManifest`.
+ */
+export function validateCapabilityManifest(data: unknown): CapabilityManifest {
+  if (data === null || data === undefined) {
+    throw new Error("capability manifest data is empty");
+  }
+
+  if (typeof data === "string") {
+    try {
+      data = JSON.parse(data);
+    } catch (err) {
+      const msg = err instanceof SyntaxError ? err.message : String(err);
+      throw new Error(`invalid JSON in capability manifest: ${msg}`);
+    }
+  }
+
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    throw new Error("capability manifest must be a JSON object");
+  }
+
+  const result = CapabilityManifestSchema.safeParse(data);
+  if (!result.success) {
+    const issue = result.error.issues[0];
+    const path = issue.path.length > 0 ? issue.path.join(".") : undefined;
+    const prefix = path ? `capability manifest field ${path}` : "capability manifest";
+    throw new Error(`${prefix}: ${issue.message}`);
+  }
+
+  return result.data as CapabilityManifest;
+}

package/src/components/capability-plugin.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Tests for the Phase 2 capability plugin contract (#559, epic #551):
+ * `isCapabilityPlugin` (./capability-plugin.ts), manifest validation
+ * (./capability-plugin-schema.ts), and plugin loading/registration/registry
+ * building (./capability-plugin-loader.ts) — mirroring how
+ * ../lexicon.test-equivalent coverage (../cli/plugins.test.ts,
+ * ../lexicon-schema.test.ts) validates the lexicon plugin contract.
+ */
+
+import { describe, expect, test } from "vitest";
+import { isCapabilityPlugin, type CapabilityPlugin } from "./capability-plugin";
+import { validateCapabilityManifest, CapabilityManifestSchema } from "./capability-plugin-schema";
+import {
+  loadCapabilityPlugin,
+  loadCapabilityPluginFromLexicon,
+  loadCapabilityPluginsFromLexicons,
+  registerCapabilityPlugins,
+  buildCapabilityRegistry,
+  MalformedCapabilityPluginError,
+  DuplicateCapabilityKindError,
+} from "./capability-plugin-loader";
+import { CapabilityRegistry } from "./capability";
+import { STARTER_VERB_FAMILIES } from "./registry";
+import { starterCapabilityPlugin } from "./starter-plugin";
+
+const ALL_STARTER_KINDS = Object.values(STARTER_VERB_FAMILIES).flat();
+
+// A trivial well-formed plugin used across several tests below.
+function fakePlugin(name: string, kinds: string[]): CapabilityPlugin {
+  return {
+    name,
+    version: "1.0.0",
+    capabilities: () => kinds.map((kind) => ({ kind, run: async () => ({}) })),
+  };
+}
+
+describe("isCapabilityPlugin", () => {
+  test("accepts a well-formed plugin", () => {
+    expect(isCapabilityPlugin(fakePlugin("demo", ["demo-verb"]))).toBe(true);
+  });
+
+  test("accepts the real starter plugin", () => {
+    expect(isCapabilityPlugin(starterCapabilityPlugin)).toBe(true);
+  });
+
+  test("rejects null/non-object", () => {
+    expect(isCapabilityPlugin(null)).toBe(false);
+    expect(isCapabilityPlugin(undefined)).toBe(false);
+    expect(isCapabilityPlugin("a string")).toBe(false);
+    expect(isCapabilityPlugin(42)).toBe(false);
+  });
+
+  test("rejects a value missing name", () => {
+    expect(isCapabilityPlugin({ version: "1.0.0", capabilities: () => [] })).toBe(false);
+  });
+
+  test("rejects a value missing version", () => {
+    expect(isCapabilityPlugin({ name: "demo", capabilities: () => [] })).toBe(false);
+  });
+
+  test("rejects a value whose capabilities is not a function (malformed package)", () => {
+    expect(isCapabilityPlugin({ name: "demo", version: "1.0.0", capabilities: [] })).toBe(false);
+  });
+
+  test("rejects a value with no capabilities field at all (malformed package)", () => {
+    expect(isCapabilityPlugin({ name: "demo", version: "1.0.0" })).toBe(false);
+  });
+
+  test("rejects a value whose name/version are the wrong type", () => {
+    expect(isCapabilityPlugin({ name: 123, version: "1.0.0", capabilities: () => [] })).toBe(false);
+    expect(isCapabilityPlugin({ name: "demo", version: 1, capabilities: () => [] })).toBe(false);
+  });
+});
+
+describe("validateCapabilityManifest", () => {
+  test("parses a valid manifest object", () => {
+    const m = validateCapabilityManifest({
+      name: "aws",
+      version: "1.0.0",
+      chantVersion: ">=0.1.0",
+      kinds: ["cfn-deploy", "ecs-update-service"],
+    });
+    expect(m.name).toBe("aws");
+    expect(m.version).toBe("1.0.0");
+    expect(m.chantVersion).toBe(">=0.1.0");
+    expect(m.kinds).toEqual(["cfn-deploy", "ecs-update-service"]);
+  });
+
+  test("parses a valid JSON string", () => {
+    const m = validateCapabilityManifest(JSON.stringify({ name: "gcp", version: "0.1.0" }));
+    expect(m.name).toBe("gcp");
+    expect(m.version).toBe("0.1.0");
+  });
+
+  test("optional fields can be omitted", () => {
+    const m = validateCapabilityManifest({ name: "gcp", version: "2.0.0" });
+    expect(m.chantVersion).toBeUndefined();
+    expect(m.kinds).toBeUndefined();
+  });
+
+  test("rejects empty input", () => {
+    expect(() => validateCapabilityManifest(null)).toThrow(/empty/);
+    expect(() => validateCapabilityManifest(undefined)).toThrow(/empty/);
+  });
+
+  test("rejects invalid JSON string (malformed package manifest)", () => {
+    expect(() => validateCapabilityManifest("not valid json{{{")).toThrow(/invalid JSON/);
+  });
+
+  test("rejects a non-object (malformed package manifest)", () => {
+    expect(() => validateCapabilityManifest("just a string")).toThrow(/invalid JSON|must be a JSON object/);
+    expect(() => validateCapabilityManifest(["array", "not", "object"])).toThrow(/must be a JSON object/);
+  });
+
+  test("rejects a manifest missing name", () => {
+    expect(() => validateCapabilityManifest({ version: "1.0.0" })).toThrow(/name/);
+  });
+
+  test("rejects a manifest with an empty name", () => {
+    expect(() => validateCapabilityManifest({ name: "", version: "1.0.0" })).toThrow(/must not be empty/);
+  });
+
+  test("rejects a manifest with a non-semver version (malformed package)", () => {
+    expect(() => validateCapabilityManifest({ name: "aws", version: "not-a-version" })).toThrow(/semver/);
+  });
+
+  test("rejects a manifest with an empty kind entry", () => {
+    const result = CapabilityManifestSchema.safeParse({ name: "aws", version: "1.0.0", kinds: [""] });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("loadCapabilityPlugin", () => {
+  test("throws a descriptive error for a package that cannot be found", async () => {
+    await expect(loadCapabilityPlugin("nonexistent-does-not-exist")).rejects.toThrow(
+      /could not be loaded/,
+    );
+  });
+});
+
+describe("registerCapabilityPlugins", () => {
+  test("registers every capability every plugin contributes", () => {
+    const registry = new CapabilityRegistry();
+    registerCapabilityPlugins(registry, [fakePlugin("demo-a", ["verb-a", "verb-b"]), fakePlugin("demo-b", ["verb-c"])]);
+    expect(registry.has("verb-a")).toBe(true);
+    expect(registry.has("verb-b")).toBe(true);
+    expect(registry.has("verb-c")).toBe(true);
+  });
+
+  test("throws DuplicateCapabilityKindError when two plugins register the same kind (malformed/conflicting package set)", () => {
+    const registry = new CapabilityRegistry();
+    expect(() =>
+      registerCapabilityPlugins(registry, [fakePlugin("demo-a", ["shared-verb"]), fakePlugin("demo-b", ["shared-verb"])]),
+    ).toThrow(DuplicateCapabilityKindError);
+  });
+
+  test("DuplicateCapabilityKindError names every offending plugin", () => {
+    const registry = new CapabilityRegistry();
+    try {
+      registerCapabilityPlugins(registry, [fakePlugin("demo-a", ["shared-verb"]), fakePlugin("demo-b", ["shared-verb"])]);
+      expect.unreachable();
+    } catch (err) {
+      expect(err).toBeInstanceOf(DuplicateCapabilityKindError);
+      const dup = err as DuplicateCapabilityKindError;
+      expect(dup.kind).toBe("shared-verb");
+      expect(dup.plugins).toEqual(["demo-a", "demo-b"]);
+    }
+  });
+
+  test("a duplicate-kind conflict leaves the registry unmodified (all-or-nothing)", () => {
+    const registry = new CapabilityRegistry();
+    try {
+      registerCapabilityPlugins(registry, [fakePlugin("demo-a", ["shared-verb"]), fakePlugin("demo-b", ["shared-verb"])]);
+    } catch {
+      /* expected */
+    }
+    expect(registry.has("shared-verb")).toBe(false);
+  });
+});
+
+describe("buildCapabilityRegistry (Phase 2 entry point)", () => {
+  test("preserves every Phase 1 starter kind with no behavior change", async () => {
+    const registry = await buildCapabilityRegistry();
+    for (const kind of ALL_STARTER_KINDS) {
+      expect(registry.has(kind)).toBe(true);
+    }
+    expect(registry.kinds()).toEqual([...ALL_STARTER_KINDS].sort());
+  });
+
+  test("layers an explicitly-provided plugin on top of the starter set", async () => {
+    // buildCapabilityRegistry's `plugins` option loads packages by name via
+    // loadCapabilityPlugin; exercise the registration/layering behavior
+    // directly through registerCapabilityPlugins + the starter plugin,
+    // since a real third-party package isn't installed in this repo.
+    const registry = new CapabilityRegistry();
+    registerCapabilityPlugins(registry, [starterCapabilityPlugin, fakePlugin("acme", ["acme-verb"])]);
+    for (const kind of ALL_STARTER_KINDS) {
+      expect(registry.has(kind)).toBe(true);
+    }
+    expect(registry.has("acme-verb")).toBe(true);
+  });
+
+  test("includeStarter: false omits the starter plugin", async () => {
+    const registry = await buildCapabilityRegistry({ includeStarter: false, plugins: [] });
+    expect(registry.kinds()).toEqual([]);
+  });
+
+  test("a lexicon that contributes no capability plugin is silently skipped (starter set intact)", async () => {
+    // `loadCapabilityPluginsFromLexicons` is tolerant: an unresolvable or
+    // capability-less lexicon contributes nothing rather than throwing, unlike
+    // the strict `@intentius/chant-capability-<name>` path.
+    const registry = await buildCapabilityRegistry({ lexicons: ["definitely-not-a-real-lexicon"] });
+    expect(registry.kinds()).toEqual([...ALL_STARTER_KINDS].sort());
+  });
+});
+
+describe("loadCapabilityPluginFromLexicon", () => {
+  test("returns null for a lexicon package that cannot be resolved", async () => {
+    expect(await loadCapabilityPluginFromLexicon("definitely-not-a-real-lexicon")).toBeNull();
+  });
+
+  test("loadCapabilityPluginsFromLexicons skips unresolvable lexicons without throwing", async () => {
+    expect(await loadCapabilityPluginsFromLexicons(["definitely-not-a-real-lexicon"])).toEqual([]);
+  });
+});
+
+describe("MalformedCapabilityPluginError", () => {
+  test("carries the offending package name and a descriptive message", () => {
+    const err = new MalformedCapabilityPluginError("@intentius/chant-capability-broken", "no capabilities() export");
+    expect(err.packageName).toBe("@intentius/chant-capability-broken");
+    expect(err.message).toContain("@intentius/chant-capability-broken");
+    expect(err.message).toContain("no capabilities() export");
+    expect(err.name).toBe("MalformedCapabilityPluginError");
+  });
+});

package/src/components/capability-plugin.ts

@@ -0,0 +1,108 @@
+/**
+ * Capability plugin contract — Phase 2 (#559, epic #551).
+ *
+ * Promotes the Phase 1 capability registry convention
+ * (`createCapabilityRegistry`/`STARTER_VERB_FAMILIES`, ./registry.ts) to a
+ * first-class chant plugin contract, mirroring the lexicon plugin contract
+ * (../lexicon.ts, ../cli/plugins.ts) so capabilities become typed,
+ * discoverable packages resolved by `kind`, the same way lexicons are
+ * discovered and resolved by resource type.
+ *
+ * Shape parity with `LexiconPlugin` (../lexicon.ts):
+ *  - `name`/`version` mirror `LexiconManifest.name`/`.version`.
+ *  - `capabilities()` is the required lifecycle method (like a lexicon's
+ *    `serializer`/`generate`/`validate`) every capability package must
+ *    implement — it returns the typed `Capability` instances this package
+ *    contributes, registered by `kind` the same way a lexicon's resource
+ *    types are registered by `resourceType`.
+ *  - `families()`, `init()` are optional extensions, mirroring
+ *    `LexiconPlugin`'s optional `lintRules`/`init`/etc.
+ *  - `isCapabilityPlugin` is the runtime type guard `loadCapabilityPlugin`
+ *    (./capability-plugin-loader.ts) uses to validate a dynamically-imported
+ *    package before trusting it — the same defensive shape check
+ *    `isLexiconPlugin` performs for lexicons.
+ *
+ * The starter verb set (./registry.ts) becomes the built-in, always-loaded
+ * plugin (`starterCapabilityPlugin`, ./starter-plugin.ts) under this same
+ * contract — see that module's docstring for the Phase 1 -> Phase 2
+ * migration path and the "no behavior change" guarantee.
+ */
+
+import type { Capability } from "./capability";
+
+/**
+ * Manifest for a packaged capability plugin — the capability-side analogue
+ * of `LexiconManifest` (../lexicon.ts). Kept as a plain data shape (rather
+ * than folded into `CapabilityPlugin`) so it can be serialized alongside a
+ * package (e.g. into a future tarball/`meta.json`, matching how lexicons
+ * carry `LexiconManifest` in their `BundleSpec`) independent of the runtime
+ * plugin object.
+ */
+export interface CapabilityManifest {
+  /** Package/plugin name (e.g. "aws", "gcp"), not a capability `kind`. */
+  name: string;
+  /** Plugin package version (semver). */
+  version: string;
+  /** Minimum/compatible chant core version, checked the same way as `LexiconManifest.chantVersion` (see ../lexicon-manifest.ts's `checkVersionCompatibility`). */
+  chantVersion?: string;
+  /** Every capability `kind` this plugin contributes — informational/validation aid; must match what `capabilities()` actually returns. */
+  kinds?: string[];
+}
+
+/**
+ * Plugin interface for capability packages — the capability-side analogue of
+ * `LexiconPlugin` (../lexicon.ts). A capability plugin ships one or more
+ * typed `Capability` implementations, discovered and loaded the same way a
+ * lexicon plugin is: dynamically imported by a package-naming convention
+ * (`@intentius/chant-capability-<name>`, see ./capability-plugin-loader.ts),
+ * validated with a runtime shape guard, then registered into a
+ * `CapabilityRegistry` the driver resolves verbs through by `kind`.
+ *
+ * Required lifecycle method enforces consistency: every capability package
+ * must be able to enumerate the capabilities it contributes.
+ */
+export interface CapabilityPlugin {
+  // ── Required ──────────────────────────────────────────────
+  /** Human-readable plugin/package name (e.g. "aws", "gcp"), not a capability `kind`. */
+  readonly name: string;
+
+  /** Plugin package version (semver), mirrors `LexiconManifest.version`. */
+  readonly version: string;
+
+  /** Return every `Capability` this plugin contributes, keyed for registration by its own `kind`. */
+  capabilities(): Array<Capability<never, unknown>>;
+
+  // ── Optional extensions ───────────────────────────────────
+  /** Minimum/compatible chant core version this plugin requires (checked via ../lexicon-manifest.ts's `checkVersionCompatibility`). */
+  readonly chantVersion?: string;
+
+  /** Capability kinds grouped by family, informational — mirrors `STARTER_VERB_FAMILIES` (./registry.ts) shape for third-party plugins that want to publish the same grouping. */
+  families?(): Record<string, readonly string[]>;
+
+  /** Optional initialization hook, called once after load (mirrors `LexiconPlugin.init`). */
+  init?(): void | Promise<void>;
+}
+
+/**
+ * Type guard to check if a value is a `CapabilityPlugin`. Checks for the
+ * required `name`/`version`/`capabilities` shape, the same defensive check
+ * `isLexiconPlugin` (../lexicon.ts) performs before a dynamically-imported
+ * package is trusted and registered. This is also chant's detector for a
+ * *malformed* capability package (#559 acceptance criteria): a package
+ * missing any of these fails the guard and is rejected by the loader with a
+ * descriptive error rather than registered half-working.
+ */
+export function isCapabilityPlugin(value: unknown): value is CapabilityPlugin {
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    !("name" in value) ||
+    typeof (value as Record<string, unknown>).name !== "string" ||
+    !("version" in value) ||
+    typeof (value as Record<string, unknown>).version !== "string"
+  ) {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return typeof obj.capabilities === "function";
+}