@unbrained/pm-cli 2026.6.21 → 2026.6.22

package/dist/sdk/testing.d.ts

@@ -3,7 +3,8 @@
  *
  * Defines public SDK APIs and package-author helpers for Testing.
  */
-import type { ExtensionActivationResult, ExtensionCapability, ExtensionCommandRegistry, ExtensionGovernancePolicy, ExtensionHookRegistry, ExtensionLayer, ExtensionParserRegistry, ExtensionPreflightRegistry, ExtensionRegistrationRegistry, ExtensionRendererRegistry, ExtensionServiceName, ExtensionServiceRegistry, FlagDefinition, OutputRendererFormat, RegisteredExtensionCommandDefinition, RegisteredExtensionCommandOverride, RegisteredExtensionExporter, RegisteredExtensionFlagDefinitions, RegisteredExtensionImporter, RegisteredExtensionParserOverride, RegisteredExtensionPreflightOverride, RegisteredExtensionRendererOverride, RegisteredExtensionSchemaFieldDefinitions, RegisteredExtensionSchemaItemTypeDefinitions, RegisteredExtensionSchemaMigrationDefinition, RegisteredExtensionSearchProvider, RegisteredExtensionServiceOverride, RegisteredExtensionVectorStoreAdapter, SchemaFieldDefinition, SchemaItemTypeDefinition } from "../core/extensions/loader.js";
+import type { AfterCommandHookContext, BeforeCommandHookContext, CommandHandlerResult, CommandOverrideContext, CommandOverrideResult, ExtensionActivationResult, ExtensionCapability, ExtensionCommandRegistry, ExtensionDeactivationResult, ExtensionGovernancePolicy, ExtensionHookRegistry, ExtensionLayer, ExtensionParserRegistry, ExtensionPreflightRegistry, ExtensionRegistrationRegistry, ExtensionRendererRegistry, ExtensionServiceName, ExtensionServiceRegistry, FlagDefinition, OnIndexHookContext, OnReadHookContext, OnWriteHookContext, OutputRendererFormat, ParserOverrideContext, ParserOverrideResult, PreflightOverrideContext, PreflightOverrideResult, RegisteredExtensionCommandDefinition, RegisteredExtensionCommandOverride, RegisteredExtensionExporter, RegisteredExtensionFlagDefinitions, RegisteredExtensionImporter, RegisteredExtensionParserOverride, RegisteredExtensionPreflightOverride, RegisteredExtensionRendererOverride, RegisteredExtensionSchemaFieldDefinitions, RegisteredExtensionSchemaItemTypeDefinitions, RegisteredExtensionSchemaMigrationDefinition, RegisteredExtensionSearchProvider, RegisteredExtensionServiceOverride, RegisteredExtensionVectorStoreAdapter, RendererOverrideContext, RendererOverrideResult, SchemaFieldDefinition, SchemaItemTypeDefinition, SearchProviderEmbedBatchContext, SearchProviderEmbedContext, SearchProviderQueryContext, SearchProviderQueryExpansionContext, SearchProviderQueryExpansionResult, SearchProviderQueryResult, SearchProviderRerankContext, SearchProviderRerankResult, ServiceOverrideContext, ServiceOverrideResult, VectorStoreDeleteContext, VectorStoreQueryContext, VectorStoreQueryHit, VectorStoreUpsertContext } from "../core/extensions/loader.js";
+import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { PmPackageManifest, PmPackageResourceKind } from "../core/packages/manifest.js";
 /**
  * Documents the activate extension for test options payload exchanged by command, SDK, and package integrations.
@@ -14,6 +15,235 @@ export interface ActivateExtensionForTestOptions {
     capabilities?: readonly ExtensionCapability[];
     policy?: ExtensionGovernancePolicy;
 }
+/**
+ * Documents the deactivate extension for test options payload exchanged by command, SDK, and package integrations.
+ */
+export interface DeactivateExtensionForTestOptions {
+    /** Overrides the in-memory extension name (defaults to `manifest.name` or `"test-extension"`). */
+    name?: string;
+    /** Overrides the layer recorded for the in-memory extension (defaults to `"project"`). */
+    layer?: ExtensionLayer;
+    /**
+     * Activation result returned by `activateExtensionForTest`. When provided, an
+     * extension whose `activate` failed is skipped — mirroring the host teardown
+     * contract that never deactivates a never-initialized extension. Pass the same
+     * `name`/`layer` to both helpers so the skip key matches.
+     */
+    activation?: Pick<ExtensionActivationResult, "failed">;
+    /**
+     * Per-hook teardown bound, forwarded as `deactivate_timeout_ms`. Use `0` (or
+     * `Infinity`) to wait indefinitely; omit to keep the host default.
+     */
+    deactivateTimeoutMs?: number;
+}
+/**
+ * Options for {@link runRegisteredCommandForTest} — the inputs forwarded to a
+ * registered extension command handler when exercising its behavior in a test.
+ */
+export interface RunRegisteredCommandForTestOptions {
+    /**
+     * Full registered command path to invoke, e.g. `"hello"` or `"todos import"`.
+     * Matched against `commands.handlers[].command` after normalization (trimmed,
+     * lower-cased, internal whitespace collapsed), mirroring runtime dispatch.
+     */
+    command: string;
+    /** Positional arguments forwarded as `context.args` (default: none). */
+    args?: readonly string[];
+    /** Parsed flags/options forwarded as `context.options` (default: none). */
+    options?: Record<string, unknown>;
+    /**
+     * Global option overrides merged onto the agent-safe test defaults
+     * (`{ json: true, quiet: true, noPager: true }`), forwarded as `context.global`.
+     */
+    global?: Partial<GlobalOptions>;
+    /**
+     * Resolved pm workspace root forwarded as `context.pm_root` (default: `""`).
+     * Most pure handlers ignore it; set it when the handler reads workspace files.
+     */
+    pmRoot?: string;
+}
+/**
+ * Options for {@link runRegisteredHookForTest} — the lifecycle `kind` to fire and
+ * the synthetic context handed to every registered hook of that kind.
+ *
+ * The union keeps `context` type-safe per kind: `kind: "on_write"` requires an
+ * {@link OnWriteHookContext}, `kind: "after_command"` an
+ * {@link AfterCommandHookContext}, and so on — so authors cannot accidentally
+ * pass an index context to a read hook.
+ */
+export type RunRegisteredHookForTestOptions = {
+    kind: "before_command";
+    context: BeforeCommandHookContext;
+} | {
+    kind: "after_command";
+    context: AfterCommandHookContext;
+} | {
+    kind: "on_read";
+    context: OnReadHookContext;
+} | {
+    kind: "on_write";
+    context: OnWriteHookContext;
+} | {
+    kind: "on_index";
+    context: OnIndexHookContext;
+};
+/**
+ * Maps each invokable search-provider operation to the context type its function
+ * receives, keeping {@link runRegisteredSearchProviderForTest} type-safe per
+ * operation. Mirrors the operations the host dispatches to a registered provider:
+ * semantic `query`, single/batch embedding (`embed`/`embedBatch`),
+ * `queryExpansion`, and `rerank`.
+ */
+export interface SearchProviderOperationContexts {
+    query: SearchProviderQueryContext;
+    embed: SearchProviderEmbedContext;
+    embedBatch: SearchProviderEmbedBatchContext;
+    queryExpansion: SearchProviderQueryExpansionContext;
+    rerank: SearchProviderRerankContext;
+}
+/**
+ * Maps each invokable search-provider operation to the result type its function
+ * returns, so {@link runRegisteredSearchProviderForTest} resolves a precise return
+ * type from the chosen `operation` instead of a union the caller must narrow.
+ */
+export interface SearchProviderOperationResults {
+    query: SearchProviderQueryResult;
+    embed: number[];
+    embedBatch: number[][];
+    queryExpansion: SearchProviderQueryExpansionResult;
+    rerank: SearchProviderRerankResult;
+}
+/**
+ * Options for {@link runRegisteredSearchProviderForTest}: the registered
+ * `provider` name to resolve, the `operation` to invoke, and the synthetic
+ * `context` handed to that operation. The discriminated union keeps `context`
+ * type-safe per operation — `operation: "embed"` requires a
+ * {@link SearchProviderEmbedContext}, `operation: "rerank"` a
+ * {@link SearchProviderRerankContext}, and so on.
+ */
+export type RunRegisteredSearchProviderForTestOptions = {
+    [Operation in keyof SearchProviderOperationContexts]: {
+        /** Registered provider name to resolve, matched case-insensitively as the host does. */
+        provider: string;
+        /** Provider operation to invoke. */
+        operation: Operation;
+        /** Synthetic context handed to the resolved operation function. */
+        context: SearchProviderOperationContexts[Operation];
+    };
+}[keyof SearchProviderOperationContexts];
+/**
+ * Maps each invokable vector-store-adapter operation to the context type its
+ * function receives, keeping {@link runRegisteredVectorStoreAdapterForTest}
+ * type-safe per operation. Mirrors the operations the host dispatches to a
+ * registered adapter: nearest-neighbour `query`, `upsert`, and `delete`.
+ */
+export interface VectorStoreAdapterOperationContexts {
+    query: VectorStoreQueryContext;
+    upsert: VectorStoreUpsertContext;
+    delete: VectorStoreDeleteContext;
+}
+/**
+ * Maps each invokable vector-store-adapter operation to the result type its
+ * function returns. Only `query` has a structured result
+ * ({@link VectorStoreQueryHit}[]); `upsert`/`delete` report success by not
+ * throwing, so their result is `unknown` and typically ignored.
+ */
+export interface VectorStoreAdapterOperationResults {
+    query: VectorStoreQueryHit[];
+    upsert: unknown;
+    delete: unknown;
+}
+/**
+ * Options for {@link runRegisteredVectorStoreAdapterForTest}: the registered
+ * `adapter` name to resolve, the `operation` to invoke, and the synthetic
+ * `context` handed to that operation. The discriminated union keeps `context`
+ * type-safe per operation — `operation: "upsert"` requires a
+ * {@link VectorStoreUpsertContext}, `operation: "delete"` a
+ * {@link VectorStoreDeleteContext}, and so on.
+ */
+export type RunRegisteredVectorStoreAdapterForTestOptions = {
+    [Operation in keyof VectorStoreAdapterOperationContexts]: {
+        /** Registered adapter name to resolve, matched case-insensitively as the host does. */
+        adapter: string;
+        /** Adapter operation to invoke. */
+        operation: Operation;
+        /** Synthetic context handed to the resolved operation function. */
+        context: VectorStoreAdapterOperationContexts[Operation];
+    };
+}[keyof VectorStoreAdapterOperationContexts];
+/**
+ * Options for {@link runRegisteredMigrationForTest}: which registered migration
+ * to invoke and the workspace root its run context reports.
+ */
+export interface RunRegisteredMigrationForTestOptions {
+    /** Registered migration id to resolve, matched case-insensitively against `definition.id`. */
+    migration: string;
+    /** Optional extension name to disambiguate when several extensions register the same id. */
+    extensionName?: string;
+    /** Resolved pm workspace root forwarded as `context.pm_root` (default `""`). */
+    pmRoot?: string;
+}
+/**
+ * Options for {@link runRegisteredImporterForTest} — the registered importer name
+ * to invoke plus the synthetic invocation context forwarded to its handler.
+ *
+ * The `importer` name is the value passed to `api.registerImporter(name, ...)`,
+ * resolved case-insensitively (and whitespace-collapsed) against
+ * `registrations.importers`; the helper derives the `"<name> import"` command
+ * path internally, so authors never hand-build it.
+ */
+export interface RunRegisteredImporterForTestOptions {
+    /** Registered importer name to resolve, e.g. `"csv"` for a `"csv import"` handler. */
+    importer: string;
+    /** Optional extension name to disambiguate when several extensions register the same importer. */
+    extensionName?: string;
+    /** Positional arguments forwarded as `context.args` (default: none). */
+    args?: readonly string[];
+    /** Parsed flags/options forwarded as `context.options` (default: none). */
+    options?: Record<string, unknown>;
+    /**
+     * Global option overrides merged onto the agent-safe test defaults
+     * (`{ json: true, quiet: true, noPager: true }`), forwarded as `context.global`.
+     */
+    global?: Partial<GlobalOptions>;
+    /** Resolved pm workspace root forwarded as `context.pm_root` (default: `""`). */
+    pmRoot?: string;
+}
+/**
+ * Options for {@link runRegisteredExporterForTest} — the registered exporter name
+ * to invoke plus the synthetic invocation context forwarded to its handler.
+ *
+ * The `exporter` name is the value passed to `api.registerExporter(name, ...)`,
+ * resolved case-insensitively (and whitespace-collapsed) against
+ * `registrations.exporters`; the helper derives the `"<name> export"` command
+ * path internally, so authors never hand-build it.
+ */
+export interface RunRegisteredExporterForTestOptions {
+    /** Registered exporter name to resolve, e.g. `"csv"` for a `"csv export"` handler. */
+    exporter: string;
+    /** Optional extension name to disambiguate when several extensions register the same exporter. */
+    extensionName?: string;
+    /** Positional arguments forwarded as `context.args` (default: none). */
+    args?: readonly string[];
+    /** Parsed flags/options forwarded as `context.options` (default: none). */
+    options?: Record<string, unknown>;
+    /**
+     * Global option overrides merged onto the agent-safe test defaults
+     * (`{ json: true, quiet: true, noPager: true }`), forwarded as `context.global`.
+     */
+    global?: Partial<GlobalOptions>;
+    /** Resolved pm workspace root forwarded as `context.pm_root` (default: `""`). */
+    pmRoot?: string;
+}
+/**
+ * Documents the extension deactivation expectation payload exchanged by command, SDK, and package integrations.
+ */
+export interface ExtensionDeactivationExpectation {
+    /** Expected count of extensions whose `deactivate` ran without throwing (default `1`). */
+    deactivated?: number;
+    /** Expected count of teardown failures (default `0`). */
+    failed?: number;
+}
 /**
  * Documents the registered command contract expectation payload exchanged by command, SDK, and package integrations.
  */
@@ -151,6 +381,35 @@ export interface RegisteredMigrationExpectation {
     extensionName?: string;
     mandatory?: boolean;
 }
+/**
+ * Documents the extension capability usage expectation payload exchanged by command, SDK, and package integrations.
+ */
+export interface ExtensionCapabilityUsageExpectation {
+    /**
+     * Capabilities the manifest declares. Mirror `manifest.capabilities` here so
+     * the assertion fails when the manifest grants more than the code uses.
+     */
+    declared: readonly ExtensionCapability[];
+    /** Restrict reconciliation to a single extension when the activation has several. */
+    extensionName?: string;
+    /**
+     * Capabilities allowed to be declared without being exercised (e.g. ones a
+     * runtime registers only behind a config flag). These are excluded from the
+     * least-privilege failure.
+     */
+    allowUnused?: readonly ExtensionCapability[];
+}
+/**
+ * Documents the extension capability usage assertion payload exchanged by command, SDK, and package integrations.
+ */
+export interface ExtensionCapabilityUsageAssertion {
+    /** Declared capabilities considered, sorted and de-duplicated. */
+    declared: ExtensionCapability[];
+    /** Capabilities the extension actually registered against, sorted. */
+    used: ExtensionCapability[];
+    /** Declared capabilities with no matching registration after the allowlist. */
+    unused: ExtensionCapability[];
+}
 /**
  * Restricts package manifest resource expectation values accepted by command, SDK, and storage contracts.
  */
@@ -170,6 +429,254 @@ export interface PackageManifestExpectation {
  * avoiding private loader imports, filesystem manifests, or workspace setup.
  */
 export declare function activateExtensionForTest(module: unknown, options?: ActivateExtensionForTestOptions): Promise<ExtensionActivationResult>;
+/**
+ * Deactivate one in-memory extension module for package tests — the teardown
+ * counterpart to {@link activateExtensionForTest}.
+ *
+ * Runs pm's real `deactivateExtensions` engine (including its bounded per-hook
+ * timeout and best-effort failure capture) over a single synthetic load entry,
+ * so authors can prove an extension's `deactivate` releases the resources its
+ * `activate` opened — without importing private loader internals or staging a
+ * workspace. Resolve `name`/`layer` the same way {@link activateExtensionForTest}
+ * does so a forwarded `activation` result skips a failed extension correctly.
+ */
+export declare function deactivateExtensionForTest(module: unknown, options?: DeactivateExtensionForTestOptions): Promise<ExtensionDeactivationResult>;
+/**
+ * Invoke a registered extension command handler and return its real
+ * {@link CommandHandlerResult} so package tests can assert on behavior — not
+ * just that the command was registered.
+ *
+ * This is the "invoke" verb that completes the package-author testing loop:
+ * `activateExtensionForTest` → `assertRegisteredCommandContract` → **run** →
+ * `deactivateExtensionForTest`. It runs pm's real handler-dispatch engine
+ * (`runCommandHandler`) over `activation.commands`, building the
+ * `CommandHandlerContext` with agent-safe global defaults
+ * (`{ json: true, quiet: true, noPager: true }`) that callers may override.
+ *
+ * Because `registerImporter`/`registerExporter` register their handlers under
+ * the `"<name> import"` / `"<name> export"` command paths, this same helper
+ * exercises importer and exporter handlers too.
+ *
+ * Throws a descriptive error (listing the available handler command paths) when
+ * no handler is registered for `command`, since that is a wiring/typo bug in the
+ * test rather than a behavior under test. When a handler is found, the result is
+ * returned verbatim: a clean run yields `{ handled: true, result, warnings: [] }`,
+ * while a handler that throws a non-exit error yields
+ * `{ handled: false, warnings: [code], errorMessage }` so the failure can be
+ * asserted. A handler that throws an error carrying a numeric `exitCode`
+ * propagates the throw, matching runtime semantics.
+ */
+export declare function runRegisteredCommandForTest(commands: ExtensionCommandRegistry, options: RunRegisteredCommandForTestOptions): Promise<CommandHandlerResult>;
+/**
+ * Fire every registered lifecycle hook of a given `kind` through pm's real hook
+ * runner and return the warnings array so package tests can assert on behavior —
+ * not just that a hook was registered.
+ *
+ * This is the hook counterpart to {@link runRegisteredCommandForTest}, extending
+ * the package-author "invoke" verb to the `api.hooks.*` surface. Pass the
+ * `ExtensionHookRegistry` from `activateExtensionForTest(...).hooks` together with
+ * the lifecycle `kind` and a synthetic context. Hooks observe their inputs via a
+ * cloned context snapshot (mutations never leak back to the caller), so the
+ * observable signal is twofold: any side effects the hook performs, and the
+ * returned warnings. A clean run returns `[]`; a hook that throws contributes one
+ * `extension_hook_failed:<layer>:<name>:<hookName>` warning, mirroring runtime
+ * dispatch which isolates a failing hook without aborting the others.
+ *
+ * Throws a descriptive error (listing the hook kinds that do have registrations)
+ * when no hook of `kind` is registered, since firing a hook the extension never
+ * registered is a wiring/typo bug in the test rather than a behavior under test.
+ */
+export declare function runRegisteredHookForTest(hooks: ExtensionHookRegistry, options: RunRegisteredHookForTestOptions): Promise<string[]>;
+/**
+ * Invoke a registered parser override through pm's real runner and return the
+ * resolved {@link ParserOverrideResult}, so package tests can assert the rewritten
+ * args/options/global an override produces for a command before dispatch.
+ *
+ * Guards that a parser override is registered for the (normalized) target command
+ * before delegating: without a match `runParserOverride` would silently return
+ * `overridden: false`, hiding a typo'd command name in the test. When a match
+ * exists the result is returned verbatim — `overridden: true` with the rewritten
+ * context on success, or `overridden: false` with an
+ * `extension_parser_override_failed:*` warning when the override throws.
+ */
+export declare function runRegisteredParserOverrideForTest(parsers: ExtensionParserRegistry, context: ParserOverrideContext): Promise<ParserOverrideResult>;
+/**
+ * Invoke the active preflight override through pm's real runner and return the
+ * resolved {@link PreflightOverrideResult}, so package tests can assert the
+ * migration/format gate decision an override yields.
+ *
+ * Unlike command-scoped overrides, the runtime applies the **last** registered
+ * preflight override regardless of command, so this helper guards only that at
+ * least one preflight override is registered before delegating. The result is
+ * returned verbatim — `overridden: true` with the adjusted decision on success,
+ * or `overridden: false` with an `extension_preflight_override_failed:*` warning
+ * when the override throws.
+ */
+export declare function runRegisteredPreflightOverrideForTest(preflight: ExtensionPreflightRegistry, context: PreflightOverrideContext): Promise<PreflightOverrideResult>;
+/**
+ * Invoke a registered command-result override through pm's real runner and return
+ * the resolved {@link CommandOverrideResult}, so package tests can assert how an
+ * override transforms a command's result payload.
+ *
+ * Accepts the same `ExtensionCommandRegistry` exposed as
+ * `activateExtensionForTest(...).commands` (it carries both handlers and
+ * overrides). Guards that an override is registered for the (normalized) target
+ * command before delegating, so a typo'd command name surfaces as a clear error
+ * rather than a silent `overridden: false`. The result is returned verbatim —
+ * including the `extension_command_override_async_unsupported:*` warning the
+ * runtime emits when an override returns a Promise (command overrides are
+ * synchronous), or an `extension_command_override_failed:*` warning on throw.
+ */
+export declare function runRegisteredCommandOverrideForTest(commands: ExtensionCommandRegistry, context: CommandOverrideContext): Promise<CommandOverrideResult>;
+/**
+ * Invoke a registered renderer override through pm's real runner and return the
+ * resolved {@link RendererOverrideResult}, so package tests can assert the custom
+ * string an override renders for a given output `format`.
+ *
+ * Guards that a renderer override is registered for `context.format` before
+ * delegating, so a wrong format surfaces as a clear error rather than a silent
+ * `overridden: false`. The result is returned verbatim — `overridden: true` with
+ * the rendered string on success, or `overridden: false` (with an
+ * `extension_renderer_invalid_result:*` / `extension_renderer_failed:*` warning
+ * where applicable) when the override returns a non-string or throws.
+ */
+export declare function runRegisteredRendererOverrideForTest(renderers: ExtensionRendererRegistry, context: RendererOverrideContext): Promise<RendererOverrideResult>;
+/**
+ * Invoke a registered service override through pm's real runner and return the
+ * resolved {@link ServiceOverrideResult}, so package tests can assert how an
+ * override handles an internal service payload (e.g. `output_format`).
+ *
+ * Guards that a service override is registered for `context.service` before
+ * delegating, so a wrong service name surfaces as a clear error rather than a
+ * silent `handled: false`. The result is returned verbatim — `handled: true` with
+ * the override's result when it claims the payload, or `handled: false` with the
+ * original payload (and any `extension_service_override_*` warnings) otherwise.
+ */
+export declare function runRegisteredServiceOverrideForTest(services: ExtensionServiceRegistry, context: ServiceOverrideContext): Promise<ServiceOverrideResult>;
+/**
+ * Invoke an operation of a registered search provider through the same name
+ * resolution the host uses and return the operation's result, so package tests
+ * can assert a custom provider's runtime behavior — not just that it registered.
+ *
+ * This is the search-provider counterpart to {@link runRegisteredCommandForTest},
+ * extending the package-author "invoke" verb to the `api.registerSearchProvider`
+ * surface. Pass the `ExtensionRegistrationRegistry` from
+ * `activateExtensionForTest(...).registrations`, the registered provider name, the
+ * `operation` to exercise (`query`, `embed`, `embedBatch`, `queryExpansion`, or
+ * `rerank`), and a synthetic context. The provider is resolved via
+ * {@link resolveRegisteredSearchProvider} (case-insensitive, last registration
+ * wins) and the operation is invoked on its `runtime_definition` — the clone that
+ * preserves live functions, matching what the runtime dispatches.
+ *
+ * Throws a descriptive error listing the available providers when the name is not
+ * registered, and a separate error when the resolved provider does not implement
+ * the requested operation, since invoking an absent provider/operation is a
+ * wiring bug in the test rather than a behavior under test.
+ */
+export declare function runRegisteredSearchProviderForTest<Operation extends keyof SearchProviderOperationContexts>(registrations: ExtensionRegistrationRegistry, options: {
+    provider: string;
+    operation: Operation;
+    context: SearchProviderOperationContexts[Operation];
+}): Promise<SearchProviderOperationResults[Operation]>;
+/**
+ * Invoke an operation of a registered vector store adapter through the same name
+ * resolution the host uses and return the operation's result, so package tests
+ * can assert a custom adapter's runtime behavior — not just that it registered.
+ *
+ * This is the vector-store counterpart to {@link runRegisteredSearchProviderForTest}.
+ * Pass the `ExtensionRegistrationRegistry` from
+ * `activateExtensionForTest(...).registrations`, the registered adapter name, the
+ * `operation` to exercise (`query`, `upsert`, or `delete`), and a synthetic
+ * context. The adapter is resolved via {@link resolveRegisteredVectorStoreAdapter}
+ * (case-insensitive, last registration wins) and the operation is invoked on its
+ * `runtime_definition` — the clone that preserves live functions, matching what
+ * the runtime dispatches.
+ *
+ * Throws a descriptive error listing the available adapters when the name is not
+ * registered, and a separate error when the resolved adapter does not implement
+ * the requested operation.
+ */
+export declare function runRegisteredVectorStoreAdapterForTest<Operation extends keyof VectorStoreAdapterOperationContexts>(registrations: ExtensionRegistrationRegistry, options: {
+    adapter: string;
+    operation: Operation;
+    context: VectorStoreAdapterOperationContexts[Operation];
+}): Promise<VectorStoreAdapterOperationResults[Operation]>;
+/**
+ * Invoke a registered schema migration's `run` function through the same runtime
+ * definition the host executes and return its result, so package tests can assert
+ * a migration's behavior — not just that it registered.
+ *
+ * This completes the package-author "invoke" verb across every executable
+ * registration surface. The migration is resolved by id via
+ * {@link assertRegisteredMigration} (which throws a descriptive "available
+ * migrations" error when absent), then `run` is invoked on its
+ * `runtime_definition` with a context mirroring the one
+ * `executeRegisteredRuntimeMigrations` builds at runtime: the resolved id,
+ * `command: "migration"`, the registering extension's layer/name, the supplied
+ * `pmRoot`, and the migration's normalized status. Unlike the runtime — which
+ * skips already-applied migrations and folds a throw into a warning — this helper
+ * always invokes `run` and lets a throw propagate, so authors can assert both the
+ * success result and failure via rejection.
+ *
+ * Throws when the resolved migration declares no `run` function, since invoking a
+ * runless migration is a wiring bug in the test rather than a behavior under test.
+ */
+export declare function runRegisteredMigrationForTest(registrations: ExtensionRegistrationRegistry, options: RunRegisteredMigrationForTestOptions): Promise<unknown>;
+/**
+ * Invoke a registered extension importer through pm's real handler-dispatch
+ * engine and return its {@link CommandHandlerResult}, so package tests can assert
+ * an importer's behavior — not just that it registered.
+ *
+ * This is the importer counterpart to {@link runRegisteredCommandForTest},
+ * extending the package-author "invoke" verb to the `api.registerImporter`
+ * surface. Because `registerImporter(name, fn)` wraps `fn` into a command handler
+ * at the `"<name> import"` path, invoking it through `runRegisteredCommandForTest`
+ * requires the author to know that naming convention and to remember that an
+ * importer is reachable as a command at all. This helper closes both gaps: it
+ * accepts the registered importer name directly, validates via
+ * {@link assertRegisteredImporter} that it is genuinely a registered importer
+ * (not merely some command parked at that path), derives the command path, and
+ * dispatches through the same engine.
+ *
+ * The full activation result is required because importer execution spans two
+ * sub-registries: `registrations.importers` proves the importer exists, while
+ * `commands` holds the wrapped handler. The result is returned verbatim from the
+ * command engine: a clean run yields `{ handled: true, result, warnings: [] }`
+ * (where `result` is the importer's return value), a non-exit throw yields
+ * `{ handled: false, warnings: [code], errorMessage }`, and an error carrying a
+ * numeric `exitCode` propagates — matching runtime import semantics.
+ *
+ * Throws a descriptive "available importers" error (via `assertRegisteredImporter`)
+ * when no importer matches, since that is a wiring/typo bug in the test rather
+ * than a behavior under test.
+ */
+export declare function runRegisteredImporterForTest(activation: ExtensionActivationResult, options: RunRegisteredImporterForTestOptions): Promise<CommandHandlerResult>;
+/**
+ * Invoke a registered extension exporter through pm's real handler-dispatch
+ * engine and return its {@link CommandHandlerResult}, so package tests can assert
+ * an exporter's behavior — not just that it registered.
+ *
+ * This is the exporter counterpart to {@link runRegisteredImporterForTest} and
+ * the final surface in the package-author "invoke" verb. Because
+ * `registerExporter(name, fn)` wraps `fn` into a command handler at the
+ * `"<name> export"` path, this helper accepts the registered exporter name
+ * directly, validates via {@link assertRegisteredExporter} that it is genuinely a
+ * registered exporter, derives the command path, and dispatches through the same
+ * engine. See {@link runRegisteredImporterForTest} for the full activation
+ * rationale and return semantics (which apply identically here).
+ *
+ * Throws a descriptive "available exporters" error (via `assertRegisteredExporter`)
+ * when no exporter matches, since that is a wiring/typo bug in the test rather
+ * than a behavior under test.
+ */
+export declare function runRegisteredExporterForTest(activation: ExtensionActivationResult, options: RunRegisteredExporterForTestOptions): Promise<CommandHandlerResult>;
+/**
+ * Assert that an {@link ExtensionDeactivationResult} reports the expected clean
+ * teardown counts, throwing a descriptive error otherwise. Defaults assert the
+ * single-extension happy path — exactly one extension deactivated and none
+ * failed. Returns the result so assertions can chain.
+ */
+export declare function assertExtensionDeactivated(result: ExtensionDeactivationResult, expectation?: ExtensionDeactivationExpectation): ExtensionDeactivationResult;
 /**
  * Assert that a normalized package manifest advertises expected package
  * resources. Pair with `readPmPackageManifest(packageRoot)` in package tests.
@@ -284,4 +791,16 @@ export declare function assertRegisteredServiceOverride(services: ExtensionServi
  * Migrations are surfaced via `ExtensionActivationResult.registrations.migrations`.
  */
 export declare function assertRegisteredMigration(registrations: ExtensionRegistrationRegistry, expectation: RegisteredMigrationExpectation): RegisteredExtensionSchemaMigrationDefinition;
+/**
+ * Assert that an activated extension declares no capability it never uses
+ * (least privilege). Pass the same capabilities as `manifest.capabilities` via
+ * `expectation.declared`; the helper computes what the extension actually
+ * registered against and throws when any declared capability is unused.
+ *
+ * This is the package-test counterpart of the advisory
+ * `extension_capability_unused` warning `pm package doctor` emits, letting an
+ * author catch an over-broad manifest at `npm test` time. Returns the
+ * declared/used/unused breakdown for further assertions.
+ */
+export declare function assertExtensionCapabilityUsage(activation: ExtensionActivationResult, expectation: ExtensionCapabilityUsageExpectation): ExtensionCapabilityUsageAssertion;
 export {};