@unbrained/pm-cli 2026.6.22 → 2026.6.24

package/dist/core/extensions/activation-summary.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @module core/extensions/activation-summary
+ *
+ * Enumerates *what* an extension activation registered, by name, in one pass.
+ *
+ * {@link ./extension-types.js#ExtensionActivationResult | `ExtensionActivationResult`}
+ * already carries per-surface *counts* (`hook_counts`, `registration_counts`,
+ * the various `*_count` fields), but answering "what does this extension
+ * register?" otherwise means walking fifteen-plus sub-registries by hand
+ * (`registrations.commands`/`flags`/`item_types`/`item_fields`/`migrations`/
+ * `importers`/`exporters`/`search_providers`/`vector_store_adapters`,
+ * `commands.overrides`/`handlers`, the `parsers`/`preflight`/`services`/
+ * `renderers` override registries, and the five `hooks.*` arrays).
+ *
+ * {@link describeExtensionActivation} flattens all of them into one sorted,
+ * deterministic {@link ExtensionActivationSummary} of identifiers — the
+ * `describe` (enumerate-all) verb that complements the SDK's `assert*`
+ * (verify-one) and `run*` (invoke-one) testing helpers. It serves two callers:
+ *
+ * - **Agents** get a single token-efficient view of an activation instead of
+ *   traversing every registry ("project management = context management").
+ * - **Package authors** can assert their *entire* registration surface in one
+ *   `deepEqual` — a least-privilege "I register exactly these surfaces and
+ *   nothing more" check, the positive counterpart to
+ *   {@link ./capability-usage.js#reconcileExtensionCapabilityUsage}.
+ */
+import type { ExtensionActivationResult, ExtensionCapability, ExtensionServiceName, OutputRendererFormat } from "./extension-types.js";
+/**
+ * Flat, name-level enumeration of every surface an activation registered.
+ *
+ * Arrays are de-duplicated for deterministic equality. Most are locale-sorted;
+ * {@link ExtensionActivationSummary.hooks} is the exception — it is emitted in
+ * canonical lifecycle order to mirror `ExtensionActivationResult.hook_counts`,
+ * not alphabetically. The three command fields capture distinct dimensions and
+ * can overlap: a command
+ * registered via `api.registerCommand(definition)` appears in both
+ * {@link ExtensionActivationSummary.commands} (its declared definition) and
+ * {@link ExtensionActivationSummary.command_handlers} (its executable handler),
+ * whereas a built-in command replaced via `api.registerCommand(name, override)`
+ * appears only in {@link ExtensionActivationSummary.command_overrides}.
+ */
+export interface ExtensionActivationSummary {
+    /** Known capabilities the registered surfaces exercise (sorted, de-duplicated). */
+    capabilities: ExtensionCapability[];
+    /** Full command paths declared via `registerCommand`'s definition form. */
+    commands: string[];
+    /** Built-in command paths replaced by an `registerCommand(name, override)` handler. */
+    command_overrides: string[];
+    /**
+     * Full command paths backed by an extension-provided handler. A superset of
+     * {@link ExtensionActivationSummary.commands} that also includes the
+     * `<name> import`/`<name> export` paths synthesized for importers/exporters.
+     */
+    command_handlers: string[];
+    /** Lifecycle hook kinds with at least one registered hook (canonical order). */
+    hooks: string[];
+    /** Command paths that received extension-registered flags. */
+    flag_commands: string[];
+    /** Custom item-type names registered via `registerItemTypes`. */
+    item_types: string[];
+    /** Custom front-matter field names registered via `registerItemFields`. */
+    item_fields: string[];
+    /** Schema migration ids registered via `registerMigration` (id-less migrations are omitted — they carry no identifier). */
+    migrations: string[];
+    /** Importer names registered via `registerImporter`. */
+    importers: string[];
+    /** Exporter names registered via `registerExporter`. */
+    exporters: string[];
+    /** Search-provider names registered via `registerSearchProvider`. */
+    search_providers: string[];
+    /** Vector-store adapter names registered via `registerVectorStoreAdapter`. */
+    vector_store_adapters: string[];
+    /** Command paths with a parser override registered via `registerParser`. */
+    parser_overrides: string[];
+    /** Built-in service names overridden via `registerService`. */
+    service_overrides: ExtensionServiceName[];
+    /** Output formats with a renderer override registered via `registerRenderer`. */
+    renderer_overrides: OutputRendererFormat[];
+    /**
+     * Count of registered preflight overrides. The surface carries no per-entry
+     * identifier, so this is a `number` rather than `string[]` — the only numeric
+     * field in the summary.
+     */
+    preflight_overrides: number;
+}
+/**
+ * Options for {@link describeExtensionActivation}.
+ */
+export interface DescribeExtensionActivationOptions {
+    /**
+     * Restrict the summary to a single extension by name. Names are matched
+     * case-insensitively after trimming, mirroring
+     * {@link ./capability-usage.js#collectUsedExtensionCapabilities}. Omit to
+     * union across every extension in the activation result.
+     */
+    extensionName?: string;
+}
+/**
+ * Summarize, by name, every registration surface an activation exercised.
+ *
+ * Walks the same sub-registries the loader populates and the capability
+ * reconciler attributes, returning a flat {@link ExtensionActivationSummary}
+ * whose arrays are sorted and de-duplicated. With
+ * {@link DescribeExtensionActivationOptions.extensionName} only the matching
+ * extension's registrations contribute (across both layers); without it the
+ * summary unions every extension in the activation. Failed activations register
+ * nothing, so they contribute only an empty summary.
+ */
+export declare function describeExtensionActivation(activation: ExtensionActivationResult, options?: DescribeExtensionActivationOptions): ExtensionActivationSummary;

package/dist/core/extensions/activation-summary.js

@@ -0,0 +1,60 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="13c88992-4da1-549d-8644-3ac448f6960e")}catch(e){}}();
+import { collectUsedExtensionCapabilities, normalizeExtensionName } from "./capability-usage.js";
+/**
+ * Canonical lifecycle hook kinds paired with their {@link ExtensionHookRegistry}
+ * field, ordered to match `ExtensionActivationResult.hook_counts` so a summary's
+ * `hooks` list reads in the same stable order the runtime reports counts in.
+ */
+const HOOK_REGISTRY_FIELD_TO_KIND = [
+    ["beforeCommand", "before_command"],
+    ["afterCommand", "after_command"],
+    ["onWrite", "on_write"],
+    ["onRead", "on_read"],
+    ["onIndex", "on_index"],
+];
+/**
+ * Summarize, by name, every registration surface an activation exercised.
+ *
+ * Walks the same sub-registries the loader populates and the capability
+ * reconciler attributes, returning a flat {@link ExtensionActivationSummary}
+ * whose arrays are sorted and de-duplicated. With
+ * {@link DescribeExtensionActivationOptions.extensionName} only the matching
+ * extension's registrations contribute (across both layers); without it the
+ * summary unions every extension in the activation. Failed activations register
+ * nothing, so they contribute only an empty summary.
+ */
+export function describeExtensionActivation(activation, options = {}) {
+    // Match both sides with the same normalizer collectUsedExtensionCapabilities
+    // uses for the `capabilities` field below, so a filtered summary's named
+    // surfaces and capabilities never disagree for a stored name with whitespace.
+    const filter = options.extensionName !== undefined ? normalizeExtensionName(options.extensionName) : null;
+    const matches = (name) => filter === null || normalizeExtensionName(name) === filter;
+    const collect = (entries, identify) => sortUnique(entries.filter((entry) => matches(entry.name)).map(identify));
+    const collectFlat = (entries, expand) => sortUnique(entries.filter((entry) => matches(entry.name)).flatMap(expand));
+    const { registrations, commands, parsers, preflight, services, renderers, hooks } = activation;
+    return {
+        capabilities: collectUsedExtensionCapabilities(activation, options),
+        commands: collect(registrations.commands, (entry) => entry.command),
+        command_overrides: collect(commands.overrides, (entry) => entry.command),
+        command_handlers: collect(commands.handlers, (entry) => entry.command),
+        hooks: HOOK_REGISTRY_FIELD_TO_KIND.filter(([field]) => hooks[field].some((entry) => matches(entry.name))).map(([, kind]) => kind),
+        flag_commands: collect(registrations.flags, (entry) => entry.target_command),
+        item_types: collectFlat(registrations.item_types, (entry) => entry.types.map((type) => type.name)),
+        item_fields: collectFlat(registrations.item_fields, (entry) => entry.fields.map((field) => field.name)),
+        migrations: collectFlat(registrations.migrations, (entry) => typeof entry.definition.id === "string" ? [entry.definition.id] : []),
+        importers: collect(registrations.importers, (entry) => entry.importer),
+        exporters: collect(registrations.exporters, (entry) => entry.exporter),
+        search_providers: collect(registrations.search_providers, (entry) => entry.definition.name),
+        vector_store_adapters: collect(registrations.vector_store_adapters, (entry) => entry.definition.name),
+        parser_overrides: collect(parsers.overrides, (entry) => entry.command),
+        service_overrides: collect(services.overrides, (entry) => entry.service),
+        renderer_overrides: collect(renderers.overrides, (entry) => entry.format),
+        preflight_overrides: preflight.overrides.filter((entry) => matches(entry.name)).length,
+    };
+}
+function sortUnique(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+//# sourceMappingURL=activation-summary.js.map
+//# debugId=13c88992-4da1-549d-8644-3ac448f6960e

package/dist/core/extensions/activation-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation-summary.js","sources":["core/extensions/activation-summary.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/activation-summary\n *\n * Enumerates *what* an extension activation registered, by name, in one pass.\n *\n * {@link ./extension-types.js#ExtensionActivationResult | `ExtensionActivationResult`}\n * already carries per-surface *counts* (`hook_counts`, `registration_counts`,\n * the various `*_count` fields), but answering \"what does this extension\n * register?\" otherwise means walking fifteen-plus sub-registries by hand\n * (`registrations.commands`/`flags`/`item_types`/`item_fields`/`migrations`/\n * `importers`/`exporters`/`search_providers`/`vector_store_adapters`,\n * `commands.overrides`/`handlers`, the `parsers`/`preflight`/`services`/\n * `renderers` override registries, and the five `hooks.*` arrays).\n *\n * {@link describeExtensionActivation} flattens all of them into one sorted,\n * deterministic {@link ExtensionActivationSummary} of identifiers — the\n * `describe` (enumerate-all) verb that complements the SDK's `assert*`\n * (verify-one) and `run*` (invoke-one) testing helpers. It serves two callers:\n *\n * - **Agents** get a single token-efficient view of an activation instead of\n *   traversing every registry (\"project management = context management\").\n * - **Package authors** can assert their *entire* registration surface in one\n *   `deepEqual` — a least-privilege \"I register exactly these surfaces and\n *   nothing more\" check, the positive counterpart to\n *   {@link ./capability-usage.js#reconcileExtensionCapabilityUsage}.\n */\nimport type {\n  ExtensionActivationResult,\n  ExtensionCapability,\n  ExtensionHookRegistry,\n  ExtensionServiceName,\n  OutputRendererFormat,\n} from \"./extension-types.js\";\nimport { collectUsedExtensionCapabilities, normalizeExtensionName } from \"./capability-usage.js\";\n\n/**\n * Canonical lifecycle hook kinds paired with their {@link ExtensionHookRegistry}\n * field, ordered to match `ExtensionActivationResult.hook_counts` so a summary's\n * `hooks` list reads in the same stable order the runtime reports counts in.\n */\nconst HOOK_REGISTRY_FIELD_TO_KIND = [\n  [\"beforeCommand\", \"before_command\"],\n  [\"afterCommand\", \"after_command\"],\n  [\"onWrite\", \"on_write\"],\n  [\"onRead\", \"on_read\"],\n  [\"onIndex\", \"on_index\"],\n] as const satisfies ReadonlyArray<readonly [keyof ExtensionHookRegistry, string]>;\n\n/**\n * Flat, name-level enumeration of every surface an activation registered.\n *\n * Arrays are de-duplicated for deterministic equality. Most are locale-sorted;\n * {@link ExtensionActivationSummary.hooks} is the exception — it is emitted in\n * canonical lifecycle order to mirror `ExtensionActivationResult.hook_counts`,\n * not alphabetically. The three command fields capture distinct dimensions and\n * can overlap: a command\n * registered via `api.registerCommand(definition)` appears in both\n * {@link ExtensionActivationSummary.commands} (its declared definition) and\n * {@link ExtensionActivationSummary.command_handlers} (its executable handler),\n * whereas a built-in command replaced via `api.registerCommand(name, override)`\n * appears only in {@link ExtensionActivationSummary.command_overrides}.\n */\nexport interface ExtensionActivationSummary {\n  /** Known capabilities the registered surfaces exercise (sorted, de-duplicated). */\n  capabilities: ExtensionCapability[];\n  /** Full command paths declared via `registerCommand`'s definition form. */\n  commands: string[];\n  /** Built-in command paths replaced by an `registerCommand(name, override)` handler. */\n  command_overrides: string[];\n  /**\n   * Full command paths backed by an extension-provided handler. A superset of\n   * {@link ExtensionActivationSummary.commands} that also includes the\n   * `<name> import`/`<name> export` paths synthesized for importers/exporters.\n   */\n  command_handlers: string[];\n  /** Lifecycle hook kinds with at least one registered hook (canonical order). */\n  hooks: string[];\n  /** Command paths that received extension-registered flags. */\n  flag_commands: string[];\n  /** Custom item-type names registered via `registerItemTypes`. */\n  item_types: string[];\n  /** Custom front-matter field names registered via `registerItemFields`. */\n  item_fields: string[];\n  /** Schema migration ids registered via `registerMigration` (id-less migrations are omitted — they carry no identifier). */\n  migrations: string[];\n  /** Importer names registered via `registerImporter`. */\n  importers: string[];\n  /** Exporter names registered via `registerExporter`. */\n  exporters: string[];\n  /** Search-provider names registered via `registerSearchProvider`. */\n  search_providers: string[];\n  /** Vector-store adapter names registered via `registerVectorStoreAdapter`. */\n  vector_store_adapters: string[];\n  /** Command paths with a parser override registered via `registerParser`. */\n  parser_overrides: string[];\n  /** Built-in service names overridden via `registerService`. */\n  service_overrides: ExtensionServiceName[];\n  /** Output formats with a renderer override registered via `registerRenderer`. */\n  renderer_overrides: OutputRendererFormat[];\n  /**\n   * Count of registered preflight overrides. The surface carries no per-entry\n   * identifier, so this is a `number` rather than `string[]` — the only numeric\n   * field in the summary.\n   */\n  preflight_overrides: number;\n}\n\n/**\n * Options for {@link describeExtensionActivation}.\n */\nexport interface DescribeExtensionActivationOptions {\n  /**\n   * Restrict the summary to a single extension by name. Names are matched\n   * case-insensitively after trimming, mirroring\n   * {@link ./capability-usage.js#collectUsedExtensionCapabilities}. Omit to\n   * union across every extension in the activation result.\n   */\n  extensionName?: string;\n}\n\n/**\n * Summarize, by name, every registration surface an activation exercised.\n *\n * Walks the same sub-registries the loader populates and the capability\n * reconciler attributes, returning a flat {@link ExtensionActivationSummary}\n * whose arrays are sorted and de-duplicated. With\n * {@link DescribeExtensionActivationOptions.extensionName} only the matching\n * extension's registrations contribute (across both layers); without it the\n * summary unions every extension in the activation. Failed activations register\n * nothing, so they contribute only an empty summary.\n */\nexport function describeExtensionActivation(\n  activation: ExtensionActivationResult,\n  options: DescribeExtensionActivationOptions = {},\n): ExtensionActivationSummary {\n  // Match both sides with the same normalizer collectUsedExtensionCapabilities\n  // uses for the `capabilities` field below, so a filtered summary's named\n  // surfaces and capabilities never disagree for a stored name with whitespace.\n  const filter = options.extensionName !== undefined ? normalizeExtensionName(options.extensionName) : null;\n  const matches = (name: string): boolean => filter === null || normalizeExtensionName(name) === filter;\n  const collect = <TEntry extends { name: string }, TValue extends string>(\n    entries: readonly TEntry[],\n    identify: (entry: TEntry) => TValue,\n  ): TValue[] => sortUnique(entries.filter((entry) => matches(entry.name)).map(identify));\n  const collectFlat = <TEntry extends { name: string }>(\n    entries: readonly TEntry[],\n    expand: (entry: TEntry) => readonly string[],\n  ): string[] => sortUnique(entries.filter((entry) => matches(entry.name)).flatMap(expand));\n  const { registrations, commands, parsers, preflight, services, renderers, hooks } = activation;\n  return {\n    capabilities: collectUsedExtensionCapabilities(activation, options),\n    commands: collect(registrations.commands, (entry) => entry.command),\n    command_overrides: collect(commands.overrides, (entry) => entry.command),\n    command_handlers: collect(commands.handlers, (entry) => entry.command),\n    hooks: HOOK_REGISTRY_FIELD_TO_KIND.filter(([field]) => hooks[field].some((entry) => matches(entry.name))).map(\n      ([, kind]) => kind,\n    ),\n    flag_commands: collect(registrations.flags, (entry) => entry.target_command),\n    item_types: collectFlat(registrations.item_types, (entry) => entry.types.map((type) => type.name)),\n    item_fields: collectFlat(registrations.item_fields, (entry) => entry.fields.map((field) => field.name)),\n    migrations: collectFlat(registrations.migrations, (entry) =>\n      typeof entry.definition.id === \"string\" ? [entry.definition.id] : [],\n    ),\n    importers: collect(registrations.importers, (entry) => entry.importer),\n    exporters: collect(registrations.exporters, (entry) => entry.exporter),\n    search_providers: collect(registrations.search_providers, (entry) => entry.definition.name),\n    vector_store_adapters: collect(registrations.vector_store_adapters, (entry) => entry.definition.name),\n    parser_overrides: collect(parsers.overrides, (entry) => entry.command),\n    service_overrides: collect(services.overrides, (entry) => entry.service),\n    renderer_overrides: collect(renderers.overrides, (entry) => entry.format),\n    preflight_overrides: preflight.overrides.filter((entry) => matches(entry.name)).length,\n  };\n}\n\nfunction sortUnique<TValue extends string>(values: readonly TValue[]): TValue[] {\n  return [...new Set(values)].sort((left, right) => left.localeCompare(right));\n}\n"],"names":[],"mappings":"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","debugId":"13c88992-4da1-549d-8644-3ac448f6960e"}

package/dist/core/extensions/capability-usage.d.ts

@@ -59,6 +59,16 @@ export interface CollectUsedExtensionCapabilitiesOptions {
      */
     extensionName?: string;
 }
+/**
+ * Canonical extension-name normalization (trim + lowercase) used to match an
+ * `extensionName` filter against a registration's stored `name`.
+ *
+ * Activation stores `extension.name` verbatim — the synthetic test-activation
+ * path (`activateExtensionForTest`) never trims it — so any helper that filters
+ * by extension name must normalize both sides with this function to stay
+ * consistent, including {@link ../extensions/activation-summary.js#describeExtensionActivation}.
+ */
+export declare function normalizeExtensionName(name: string): string;
 /**
  * Collect the known capabilities exercised across an activation result.
  *

package/dist/core/extensions/capability-usage.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b74f7cd3-95ed-5473-a724-d3afb634a68b")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="f6134b79-a7d0-57d9-b25a-8e3e7b4af416")}catch(e){}}();
 import { normalizeKnownExtensionCapability } from "./extension-capability-aliases.js";
 /**
  * Canonical map from each known extension capability to the human-readable
@@ -31,7 +31,16 @@ function usageKey(layer, name) {
 function usageKeyName(key) {
     return key.slice(key.indexOf(USAGE_KEY_SEPARATOR) + 1);
 }
-function normalizeExtensionName(name) {
+/**
+ * Canonical extension-name normalization (trim + lowercase) used to match an
+ * `extensionName` filter against a registration's stored `name`.
+ *
+ * Activation stores `extension.name` verbatim — the synthetic test-activation
+ * path (`activateExtensionForTest`) never trims it — so any helper that filters
+ * by extension name must normalize both sides with this function to stay
+ * consistent, including {@link ../extensions/activation-summary.js#describeExtensionActivation}.
+ */
+export function normalizeExtensionName(name) {
     return name.trim().toLowerCase();
 }
 function normalizeDeclaredCapabilities(capabilities) {
@@ -130,4 +139,4 @@ export function reconcileExtensionCapabilityUsage(loaded, activation) {
     return reconciliations;
 }
 //# sourceMappingURL=capability-usage.js.map
-//# debugId=b74f7cd3-95ed-5473-a724-d3afb634a68b
+//# debugId=f6134b79-a7d0-57d9-b25a-8e3e7b4af416

package/dist/core/extensions/capability-usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"capability-usage.js","sources":["core/extensions/capability-usage.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/capability-usage\n *\n * Reconciles the capabilities an extension manifest *declares* against the\n * capabilities it actually *exercises* during activation.\n *\n * The loader already enforces the opposite direction — registering a surface\n * whose capability is absent from `manifest.capabilities` throws an\n * `extension_capability_missing` activation failure. This module closes the\n * least-privilege loop by detecting capabilities a manifest declares but never\n * registers against, so package authors can trim manifests to the minimum\n * grant. Every declared-but-unused capability is an over-broad permission a\n * reviewer would otherwise have to catch by hand.\n */\nimport type { ExtensionActivationResult, ExtensionCapability, ExtensionLayer } from \"./extension-types.js\";\nimport { normalizeKnownExtensionCapability } from \"./extension-capability-aliases.js\";\n\n/**\n * Canonical map from each known extension capability to the human-readable\n * registration surfaces that exercise it.\n *\n * The `satisfies Record<ExtensionCapability, ...>` guard makes this exhaustive\n * at compile time: adding a capability to `KNOWN_EXTENSION_CAPABILITIES`\n * without giving it a registration surface here fails the build, which prevents\n * a capability that has *no* surface from being perpetually flagged as unused.\n */\nexport const EXTENSION_CAPABILITY_REGISTRATION_SURFACES = {\n  commands: [\"registerCommand\", \"command override\", \"command handler\"],\n  renderers: [\"registerRenderer\"],\n  hooks: [\"hooks.beforeCommand\", \"hooks.afterCommand\", \"hooks.onWrite\", \"hooks.onRead\", \"hooks.onIndex\"],\n  schema: [\"registerFlags\", \"registerItemFields\", \"registerItemTypes\", \"registerMigration\"],\n  importers: [\"registerImporter\", \"registerExporter\"],\n  search: [\"registerSearchProvider\", \"registerVectorStoreAdapter\"],\n  parser: [\"registerParser\"],\n  preflight: [\"registerPreflight\"],\n  services: [\"registerService\"],\n} as const satisfies Record<ExtensionCapability, readonly string[]>;\n\n/**\n * Per-extension reconciliation of declared versus exercised capabilities.\n */\nexport interface ExtensionCapabilityUsageReconciliation {\n  /** Layer the extension was loaded from (`global` or `project`). */\n  layer: ExtensionLayer;\n  /** Extension name as it appears in the manifest. */\n  name: string;\n  /** Known capabilities declared in the manifest, sorted and de-duplicated. */\n  declared: ExtensionCapability[];\n  /** Known capabilities the extension actually registered against, sorted. */\n  used: ExtensionCapability[];\n  /** Declared capabilities with no matching registration (least-privilege gap). */\n  unused: ExtensionCapability[];\n}\n\n/**\n * Options for {@link collectUsedExtensionCapabilities}.\n */\nexport interface CollectUsedExtensionCapabilitiesOptions {\n  /**\n   * Restrict the result to a single extension by name. Names are matched\n   * case-insensitively after trimming. Omit to union across every extension in\n   * the activation result.\n   */\n  extensionName?: string;\n}\n\n// `layer` is a closed enum (`\"global\" | \"project\"`) that never contains a\n// colon, so the first colon always separates the layer from the (possibly\n// colon-bearing) name — making the key collision-proof without serialization.\nconst USAGE_KEY_SEPARATOR = \":\";\n\nfunction usageKey(layer: ExtensionLayer, name: string): string {\n  return `${layer}${USAGE_KEY_SEPARATOR}${normalizeExtensionName(name)}`;\n}\n\nfunction usageKeyName(key: string): string {\n  return key.slice(key.indexOf(USAGE_KEY_SEPARATOR) + 1);\n}\n\nfunction normalizeExtensionName(name: string): string {\n  return name.trim().toLowerCase();\n}\n\nfunction normalizeDeclaredCapabilities(capabilities: readonly string[] | undefined): ExtensionCapability[] {\n  if (!Array.isArray(capabilities)) {\n    return [];\n  }\n  const known = new Set<ExtensionCapability>();\n  for (const capability of capabilities) {\n    // Unknown capabilities are reported by the separate unknown-capability\n    // diagnostic; reconciling them here would double-report a typo as \"unused\".\n    const normalized = normalizeKnownExtensionCapability(capability);\n    if (normalized !== null) {\n      known.add(normalized);\n    }\n  }\n  return [...known].sort((left, right) => left.localeCompare(right));\n}\n\nfunction attributeCapabilityUsage(activation: ExtensionActivationResult): Map<string, Set<ExtensionCapability>> {\n  const usage = new Map<string, Set<ExtensionCapability>>();\n  const record = (\n    entries: ReadonlyArray<{ layer: ExtensionLayer; name: string }>,\n    capability: ExtensionCapability,\n  ): void => {\n    for (const entry of entries) {\n      const key = usageKey(entry.layer, entry.name);\n      let exercised = usage.get(key);\n      if (exercised === undefined) {\n        exercised = new Set<ExtensionCapability>();\n        usage.set(key, exercised);\n      }\n      exercised.add(capability);\n    }\n  };\n  const { registrations, commands, parsers, preflight, services, renderers, hooks } = activation;\n  record(registrations.commands, \"commands\");\n  record(commands.overrides, \"commands\");\n  record(commands.handlers, \"commands\");\n  record(registrations.flags, \"schema\");\n  record(registrations.item_fields, \"schema\");\n  record(registrations.item_types, \"schema\");\n  record(registrations.migrations, \"schema\");\n  record(registrations.importers, \"importers\");\n  record(registrations.exporters, \"importers\");\n  record(registrations.search_providers, \"search\");\n  record(registrations.vector_store_adapters, \"search\");\n  record(parsers.overrides, \"parser\");\n  record(preflight.overrides, \"preflight\");\n  record(services.overrides, \"services\");\n  record(renderers.overrides, \"renderers\");\n  record(hooks.beforeCommand, \"hooks\");\n  record(hooks.afterCommand, \"hooks\");\n  record(hooks.onWrite, \"hooks\");\n  record(hooks.onRead, \"hooks\");\n  record(hooks.onIndex, \"hooks\");\n  return usage;\n}\n\n/**\n * Collect the known capabilities exercised across an activation result.\n *\n * Without {@link CollectUsedExtensionCapabilitiesOptions.extensionName} the\n * result unions every extension in the activation; with it, only the matching\n * extension's registrations contribute (across both layers).\n */\nexport function collectUsedExtensionCapabilities(\n  activation: ExtensionActivationResult,\n  options: CollectUsedExtensionCapabilitiesOptions = {},\n): ExtensionCapability[] {\n  const usage = attributeCapabilityUsage(activation);\n  const filter = options.extensionName !== undefined ? normalizeExtensionName(options.extensionName) : null;\n  const used = new Set<ExtensionCapability>();\n  for (const [key, capabilities] of usage) {\n    if (filter !== null && usageKeyName(key) !== filter) {\n      continue;\n    }\n    for (const capability of capabilities) {\n      used.add(capability);\n    }\n  }\n  return [...used].sort((left, right) => left.localeCompare(right));\n}\n\n/**\n * Reconcile each loaded extension's declared capabilities against what it\n * exercised during activation.\n *\n * Extensions with no known declared capabilities are skipped — there is nothing\n * to reconcile. The returned entries preserve every reconcilable extension even\n * when `unused` is empty so callers can report fully-minimal manifests too.\n */\nexport function reconcileExtensionCapabilityUsage(\n  loaded: ReadonlyArray<{ layer: ExtensionLayer; name: string; capabilities?: readonly string[] }>,\n  activation: ExtensionActivationResult,\n): ExtensionCapabilityUsageReconciliation[] {\n  const usage = attributeCapabilityUsage(activation);\n  const reconciliations: ExtensionCapabilityUsageReconciliation[] = [];\n  for (const extension of loaded) {\n    const declared = normalizeDeclaredCapabilities(extension.capabilities);\n    if (declared.length === 0) {\n      continue;\n    }\n    const exercised = usage.get(usageKey(extension.layer, extension.name)) ?? new Set<ExtensionCapability>();\n    const used = [...exercised].sort((left, right) => left.localeCompare(right));\n    const unused = declared.filter((capability) => !exercised.has(capability));\n    reconciliations.push({ layer: extension.layer, name: extension.name, declared, used, unused });\n  }\n  return reconciliations;\n}\n"],"names":[],"mappings":"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","debugId":"b74f7cd3-95ed-5473-a724-d3afb634a68b"}
+{"version":3,"file":"capability-usage.js","sources":["core/extensions/capability-usage.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/capability-usage\n *\n * Reconciles the capabilities an extension manifest *declares* against the\n * capabilities it actually *exercises* during activation.\n *\n * The loader already enforces the opposite direction — registering a surface\n * whose capability is absent from `manifest.capabilities` throws an\n * `extension_capability_missing` activation failure. This module closes the\n * least-privilege loop by detecting capabilities a manifest declares but never\n * registers against, so package authors can trim manifests to the minimum\n * grant. Every declared-but-unused capability is an over-broad permission a\n * reviewer would otherwise have to catch by hand.\n */\nimport type { ExtensionActivationResult, ExtensionCapability, ExtensionLayer } from \"./extension-types.js\";\nimport { normalizeKnownExtensionCapability } from \"./extension-capability-aliases.js\";\n\n/**\n * Canonical map from each known extension capability to the human-readable\n * registration surfaces that exercise it.\n *\n * The `satisfies Record<ExtensionCapability, ...>` guard makes this exhaustive\n * at compile time: adding a capability to `KNOWN_EXTENSION_CAPABILITIES`\n * without giving it a registration surface here fails the build, which prevents\n * a capability that has *no* surface from being perpetually flagged as unused.\n */\nexport const EXTENSION_CAPABILITY_REGISTRATION_SURFACES = {\n  commands: [\"registerCommand\", \"command override\", \"command handler\"],\n  renderers: [\"registerRenderer\"],\n  hooks: [\"hooks.beforeCommand\", \"hooks.afterCommand\", \"hooks.onWrite\", \"hooks.onRead\", \"hooks.onIndex\"],\n  schema: [\"registerFlags\", \"registerItemFields\", \"registerItemTypes\", \"registerMigration\"],\n  importers: [\"registerImporter\", \"registerExporter\"],\n  search: [\"registerSearchProvider\", \"registerVectorStoreAdapter\"],\n  parser: [\"registerParser\"],\n  preflight: [\"registerPreflight\"],\n  services: [\"registerService\"],\n} as const satisfies Record<ExtensionCapability, readonly string[]>;\n\n/**\n * Per-extension reconciliation of declared versus exercised capabilities.\n */\nexport interface ExtensionCapabilityUsageReconciliation {\n  /** Layer the extension was loaded from (`global` or `project`). */\n  layer: ExtensionLayer;\n  /** Extension name as it appears in the manifest. */\n  name: string;\n  /** Known capabilities declared in the manifest, sorted and de-duplicated. */\n  declared: ExtensionCapability[];\n  /** Known capabilities the extension actually registered against, sorted. */\n  used: ExtensionCapability[];\n  /** Declared capabilities with no matching registration (least-privilege gap). */\n  unused: ExtensionCapability[];\n}\n\n/**\n * Options for {@link collectUsedExtensionCapabilities}.\n */\nexport interface CollectUsedExtensionCapabilitiesOptions {\n  /**\n   * Restrict the result to a single extension by name. Names are matched\n   * case-insensitively after trimming. Omit to union across every extension in\n   * the activation result.\n   */\n  extensionName?: string;\n}\n\n// `layer` is a closed enum (`\"global\" | \"project\"`) that never contains a\n// colon, so the first colon always separates the layer from the (possibly\n// colon-bearing) name — making the key collision-proof without serialization.\nconst USAGE_KEY_SEPARATOR = \":\";\n\nfunction usageKey(layer: ExtensionLayer, name: string): string {\n  return `${layer}${USAGE_KEY_SEPARATOR}${normalizeExtensionName(name)}`;\n}\n\nfunction usageKeyName(key: string): string {\n  return key.slice(key.indexOf(USAGE_KEY_SEPARATOR) + 1);\n}\n\n/**\n * Canonical extension-name normalization (trim + lowercase) used to match an\n * `extensionName` filter against a registration's stored `name`.\n *\n * Activation stores `extension.name` verbatim — the synthetic test-activation\n * path (`activateExtensionForTest`) never trims it — so any helper that filters\n * by extension name must normalize both sides with this function to stay\n * consistent, including {@link ../extensions/activation-summary.js#describeExtensionActivation}.\n */\nexport function normalizeExtensionName(name: string): string {\n  return name.trim().toLowerCase();\n}\n\nfunction normalizeDeclaredCapabilities(capabilities: readonly string[] | undefined): ExtensionCapability[] {\n  if (!Array.isArray(capabilities)) {\n    return [];\n  }\n  const known = new Set<ExtensionCapability>();\n  for (const capability of capabilities) {\n    // Unknown capabilities are reported by the separate unknown-capability\n    // diagnostic; reconciling them here would double-report a typo as \"unused\".\n    const normalized = normalizeKnownExtensionCapability(capability);\n    if (normalized !== null) {\n      known.add(normalized);\n    }\n  }\n  return [...known].sort((left, right) => left.localeCompare(right));\n}\n\nfunction attributeCapabilityUsage(activation: ExtensionActivationResult): Map<string, Set<ExtensionCapability>> {\n  const usage = new Map<string, Set<ExtensionCapability>>();\n  const record = (\n    entries: ReadonlyArray<{ layer: ExtensionLayer; name: string }>,\n    capability: ExtensionCapability,\n  ): void => {\n    for (const entry of entries) {\n      const key = usageKey(entry.layer, entry.name);\n      let exercised = usage.get(key);\n      if (exercised === undefined) {\n        exercised = new Set<ExtensionCapability>();\n        usage.set(key, exercised);\n      }\n      exercised.add(capability);\n    }\n  };\n  const { registrations, commands, parsers, preflight, services, renderers, hooks } = activation;\n  record(registrations.commands, \"commands\");\n  record(commands.overrides, \"commands\");\n  record(commands.handlers, \"commands\");\n  record(registrations.flags, \"schema\");\n  record(registrations.item_fields, \"schema\");\n  record(registrations.item_types, \"schema\");\n  record(registrations.migrations, \"schema\");\n  record(registrations.importers, \"importers\");\n  record(registrations.exporters, \"importers\");\n  record(registrations.search_providers, \"search\");\n  record(registrations.vector_store_adapters, \"search\");\n  record(parsers.overrides, \"parser\");\n  record(preflight.overrides, \"preflight\");\n  record(services.overrides, \"services\");\n  record(renderers.overrides, \"renderers\");\n  record(hooks.beforeCommand, \"hooks\");\n  record(hooks.afterCommand, \"hooks\");\n  record(hooks.onWrite, \"hooks\");\n  record(hooks.onRead, \"hooks\");\n  record(hooks.onIndex, \"hooks\");\n  return usage;\n}\n\n/**\n * Collect the known capabilities exercised across an activation result.\n *\n * Without {@link CollectUsedExtensionCapabilitiesOptions.extensionName} the\n * result unions every extension in the activation; with it, only the matching\n * extension's registrations contribute (across both layers).\n */\nexport function collectUsedExtensionCapabilities(\n  activation: ExtensionActivationResult,\n  options: CollectUsedExtensionCapabilitiesOptions = {},\n): ExtensionCapability[] {\n  const usage = attributeCapabilityUsage(activation);\n  const filter = options.extensionName !== undefined ? normalizeExtensionName(options.extensionName) : null;\n  const used = new Set<ExtensionCapability>();\n  for (const [key, capabilities] of usage) {\n    if (filter !== null && usageKeyName(key) !== filter) {\n      continue;\n    }\n    for (const capability of capabilities) {\n      used.add(capability);\n    }\n  }\n  return [...used].sort((left, right) => left.localeCompare(right));\n}\n\n/**\n * Reconcile each loaded extension's declared capabilities against what it\n * exercised during activation.\n *\n * Extensions with no known declared capabilities are skipped — there is nothing\n * to reconcile. The returned entries preserve every reconcilable extension even\n * when `unused` is empty so callers can report fully-minimal manifests too.\n */\nexport function reconcileExtensionCapabilityUsage(\n  loaded: ReadonlyArray<{ layer: ExtensionLayer; name: string; capabilities?: readonly string[] }>,\n  activation: ExtensionActivationResult,\n): ExtensionCapabilityUsageReconciliation[] {\n  const usage = attributeCapabilityUsage(activation);\n  const reconciliations: ExtensionCapabilityUsageReconciliation[] = [];\n  for (const extension of loaded) {\n    const declared = normalizeDeclaredCapabilities(extension.capabilities);\n    if (declared.length === 0) {\n      continue;\n    }\n    const exercised = usage.get(usageKey(extension.layer, extension.name)) ?? new Set<ExtensionCapability>();\n    const used = [...exercised].sort((left, right) => left.localeCompare(right));\n    const unused = declared.filter((capability) => !exercised.has(capability));\n    reconciliations.push({ layer: extension.layer, name: extension.name, declared, used, unused });\n  }\n  return reconciliations;\n}\n"],"names":[],"mappings":"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","debugId":"f6134b79-a7d0-57d9-b25a-8e3e7b4af416"}

package/dist/core/extensions/loader.d.ts

@@ -1,3 +1,4 @@
+import { compareComparableVersions, parseComparableVersion } from "./version-compat.js";
 import { type NormalizedExtensionPolicy } from "./extension-policy.js";
 export { parseUnknownExtensionCapabilityWarning, parseLegacyExtensionCapabilityAliasWarning, } from "./extension-capability-aliases.js";
 export { createEmptyExtensionHookRegistry, createEmptyExtensionCommandRegistry, createEmptyExtensionParserRegistry, createEmptyExtensionPreflightRegistry, createEmptyExtensionServiceRegistry, createEmptyExtensionRendererRegistry, createEmptyExtensionRegistrationRegistry, } from "./extension-registries.js";
@@ -21,8 +22,6 @@ declare function readManagedExtensionSourcePackages(extensionsRoot: string): Pro
  * Implements discover extensions for the public runtime surface of this module.
  */
 export declare function discoverExtensions(options: DiscoverExtensionsOptions): Promise<ExtensionDiscoveryResult>;
-declare function parseComparableVersion(value: string): number[] | null;
-declare function compareComparableVersions(currentVersion: string, minimumVersion: string): number | null;
 declare function readCurrentPmCliVersion(): Promise<string | null>;
 declare function resolveCurrentPmCliVersion(): Promise<string | null>;
 declare function evaluatePmMinVersionCompatibility(layer: ExtensionLayer, manifest: ExtensionManifest): Promise<{

package/dist/core/extensions/loader.js

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Loader.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7c9e6f67-48e5-5952-a7a7-341aafa36244")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7c5d988c-8be5-5308-90c9-b1245d50fbab")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -15,6 +15,7 @@ import { resolveGlobalPmRoot } from "../store/paths.js";
 import { asRecordLoose } from "../shared/primitives.js";
 import { flattenFlagListValue, isFlagDefaultValueCoercible, resolveFlagValueKind } from "./flag-value-types.js";
 import { KNOWN_ITEM_FIELD_TYPES, normalizeItemFieldType, suggestKnownItemFieldType } from "./item-field-types.js";
+import { compareComparableVersions, evaluatePmMaxVersionBound, evaluatePmMinVersionBound, parseComparableVersion, } from "./version-compat.js";
 // Cohesive helper groups now live in sibling modules. They are imported for the
 // discovery/activation code that stays here and re-exported below so existing
 // import sites (sdk/index.ts, commands/extension.ts, health.ts, tests, …) keep
@@ -563,33 +564,6 @@ function formatUnknownError(error) {
     }
     return String(error);
 }
-function parseComparableVersion(value) {
-    const normalized = value.trim().replace(/^>=\s*/, "").replace(/^v/i, "");
-    const release = normalized.split(/[+-]/, 1)[0];
-    if (!/^\d+(?:[.-]\d+)*$/.test(release)) {
-        return null;
-    }
-    return release.split(/[.-]/).map((part) => Number(part));
-}
-function compareComparableVersions(currentVersion, minimumVersion) {
-    const currentParts = parseComparableVersion(currentVersion);
-    const minimumParts = parseComparableVersion(minimumVersion);
-    if (!currentParts || !minimumParts) {
-        return null;
-    }
-    const width = Math.max(currentParts.length, minimumParts.length);
-    for (let index = 0; index < width; index += 1) {
-        const current = currentParts[index] ?? 0;
-        const minimum = minimumParts[index] ?? 0;
-        if (current > minimum) {
-            return 1;
-        }
-        if (current < minimum) {
-            return -1;
-        }
-    }
-    return 0;
-}
 async function readCurrentPmCliVersion() {
     try {
         const packageRoot = resolvePmPackageRootFromModule(import.meta.url, ["../../.."]);
@@ -605,87 +579,50 @@ function resolveCurrentPmCliVersion() {
     currentPmCliVersionPromise ??= readCurrentPmCliVersion();
     return currentPmCliVersionPromise;
 }
-async function evaluatePmMinVersionCompatibility(layer, manifest) {
-    if (typeof manifest.pm_min_version !== "string" || manifest.pm_min_version.trim().length === 0) {
-        return { allowed: true };
-    }
-    if (!parseComparableVersion(manifest.pm_min_version)) {
-        return {
-            allowed: false,
-            warning: `extension_pm_min_version_invalid:${layer}:${manifest.name}:required=${manifest.pm_min_version}`,
-        };
-    }
-    const currentVersion = await resolveCurrentPmCliVersion();
-    if (!currentVersion) {
-        return {
-            allowed: true,
-            warning: `extension_pm_min_version_unchecked:${layer}:${manifest.name}:required=${manifest.pm_min_version}:current=unknown`,
-        };
+function formatPmVersionCompatibilityWarning(layer, manifest, evaluation) {
+    const current = evaluation.current ?? "unknown";
+    if (evaluation.kind === "pm_min_version") {
+        switch (evaluation.status) {
+            case "invalid":
+                return `extension_pm_min_version_invalid:${layer}:${manifest.name}:required=${evaluation.required}`;
+            case "unchecked":
+                return `extension_pm_min_version_unchecked:${layer}:${manifest.name}:required=${evaluation.required}:current=${current}`;
+            case "unmet":
+                return `extension_pm_min_version_unmet:${layer}:${manifest.name}:required=${evaluation.required}:current=${current}`;
+            default:
+                return undefined;
+        }
     }
-    const comparison = compareComparableVersions(currentVersion, manifest.pm_min_version);
-    if (comparison === null) {
-        return {
-            allowed: true,
-            warning: `extension_pm_min_version_unchecked:${layer}:${manifest.name}:required=${manifest.pm_min_version}:current=${currentVersion}`,
-        };
+    switch (evaluation.status) {
+        case "invalid":
+            return `extension_pm_max_version_invalid:${layer}:${manifest.name}:allowed=${evaluation.required}`;
+        case "unchecked":
+            return `extension_pm_max_version_unchecked:${layer}:${manifest.name}:allowed=${evaluation.required}:current=${current}`;
+        case "exceeded_warn":
+            return `extension_pm_max_version_exceeded_warn:${layer}:${manifest.name}:allowed=${evaluation.required}:current=${current}`;
+        case "exceeded":
+            return `extension_pm_max_version_exceeded:${layer}:${manifest.name}:allowed=${evaluation.required}:current=${current}`;
+        default:
+            return undefined;
     }
-    if (comparison < 0) {
-        return {
-            allowed: false,
-            warning: `extension_pm_min_version_unmet:${layer}:${manifest.name}:required=${manifest.pm_min_version}:current=${currentVersion}`,
-        };
+}
+async function evaluatePmMinVersionCompatibility(layer, manifest) {
+    // Resolve the current CLI version only when a bound is declared, so the common
+    // no-bound case never reads package.json.
+    if (manifest.pm_min_version === undefined) {
+        return { allowed: true };
     }
-    return { allowed: true };
+    const evaluation = evaluatePmMinVersionBound(manifest.pm_min_version, await resolveCurrentPmCliVersion());
+    const warning = formatPmVersionCompatibilityWarning(layer, manifest, evaluation);
+    return warning ? { allowed: evaluation.allowed, warning } : { allowed: evaluation.allowed };
 }
 async function evaluatePmMaxVersionCompatibility(layer, manifest, exceededMode) {
-    if (typeof manifest.pm_max_version !== "string" || manifest.pm_max_version.trim().length === 0) {
+    if (manifest.pm_max_version === undefined) {
         return { allowed: true };
     }
-    // An upper bound must be an exact version. parseComparableVersion leniently strips a
-    // leading ">=" (for engines.pm min-version compat), which would turn a range-like
-    // ">=2026.6.1" into an inclusive max and wrongly block newer CLIs — reject range prefixes.
-    if (/^[<>=~^]/.test(manifest.pm_max_version.trim())) {
-        return {
-            allowed: false,
-            warning: `extension_pm_max_version_invalid:${layer}:${manifest.name}:allowed=${manifest.pm_max_version}`,
-        };
-    }
-    if (!parseComparableVersion(manifest.pm_max_version)) {
-        return {
-            allowed: false,
-            warning: `extension_pm_max_version_invalid:${layer}:${manifest.name}:allowed=${manifest.pm_max_version}`,
-        };
-    }
-    const currentVersion = await resolveCurrentPmCliVersion();
-    if (!currentVersion) {
-        return {
-            allowed: true,
-            warning: `extension_pm_max_version_unchecked:${layer}:${manifest.name}:allowed=${manifest.pm_max_version}:current=unknown`,
-        };
-    }
-    const comparison = compareComparableVersions(currentVersion, manifest.pm_max_version);
-    if (comparison === null) {
-        return {
-            allowed: true,
-            warning: `extension_pm_max_version_unchecked:${layer}:${manifest.name}:allowed=${manifest.pm_max_version}:current=${currentVersion}`,
-        };
-    }
-    if (comparison > 0) {
-        // pm-k5e8: `extensions.policy.pm_max_version_exceeded_mode` (default "block",
-        // per-layer overridable) relaxes this to warn-only so operators can keep
-        // pinned extensions loading during a CLI upgrade window.
-        if (exceededMode === "warn") {
-            return {
-                allowed: true,
-                warning: `extension_pm_max_version_exceeded_warn:${layer}:${manifest.name}:allowed=${manifest.pm_max_version}:current=${currentVersion}`,
-            };
-        }
-        return {
-            allowed: false,
-            warning: `extension_pm_max_version_exceeded:${layer}:${manifest.name}:allowed=${manifest.pm_max_version}:current=${currentVersion}`,
-        };
-    }
-    return { allowed: true };
+    const evaluation = evaluatePmMaxVersionBound(manifest.pm_max_version, await resolveCurrentPmCliVersion(), exceededMode);
+    const warning = formatPmVersionCompatibilityWarning(layer, manifest, evaluation);
+    return warning ? { allowed: evaluation.allowed, warning } : { allowed: evaluation.allowed };
 }
 async function fingerprintPath(pathToInspect) {
     try {
@@ -1997,4 +1934,4 @@ export const _testOnlyLoader = {
     },
 };
 //# sourceMappingURL=loader.js.map
-//# debugId=7c9e6f67-48e5-5952-a7a7-341aafa36244
+//# debugId=7c5d988c-8be5-5308-90c9-b1245d50fbab