@unbrained/pm-cli 2026.6.21 → 2026.6.23

package/dist/sdk/testing.d.ts

@@ -3,8 +3,14 @@
  *
  * 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 { describeExtensionBlueprint, lintExtensionBlueprint } from "./compose.js";
+import type { ExtensionBlueprint, ExtensionBlueprintLintCode, ExtensionBlueprintLintFinding, ExtensionBlueprintLintResult, ExtensionBlueprintLintSeverity, LintExtensionBlueprintOptions } from "./compose.js";
+import type { GlobalOptions } from "../core/shared/command-types.js";
 import type { PmPackageManifest, PmPackageResourceKind } from "../core/packages/manifest.js";
+export { describeExtensionActivation, type DescribeExtensionActivationOptions, type ExtensionActivationSummary, } from "../core/extensions/activation-summary.js";
+export { describeExtensionBlueprint, lintExtensionBlueprint };
+export type { ExtensionBlueprint, ExtensionBlueprintLintCode, ExtensionBlueprintLintFinding, ExtensionBlueprintLintResult, ExtensionBlueprintLintSeverity, LintExtensionBlueprintOptions, };
 /**
  * Documents the activate extension for test options payload exchanged by command, SDK, and package integrations.
  */
@@ -14,6 +20,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 +386,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 +434,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 +796,157 @@ export declare function assertRegisteredServiceOverride(services: ExtensionServi
  * Migrations are surfaced via `ExtensionActivationResult.registrations.migrations`.
  */
 export declare function assertRegisteredMigration(registrations: ExtensionRegistrationRegistry, expectation: RegisteredMigrationExpectation): RegisteredExtensionSchemaMigrationDefinition;
-export {};
+/**
+ * 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;
+/**
+ * Preflight a declarative {@link ExtensionBlueprint} in a test, throwing if it has
+ * any `error`-severity issue (today: capability the blueprint exercises but the
+ * declared set omits, which would fail activation with `extension_capability_missing`).
+ *
+ * The throwing counterpart to {@link lintExtensionBlueprint} and the `assert*`
+ * family member for declarative authoring: drop `assertExtensionBlueprint(blueprint)`
+ * into a package's `node:test`/Vitest suite to fail CI before the blueprint is
+ * ever activated. The full {@link ExtensionBlueprintLintResult} is returned on
+ * success so a test can still inspect advisory warnings (unused capability,
+ * duplicate command, empty surface) without failing on them.
+ */
+export declare function assertExtensionBlueprint(blueprint: ExtensionBlueprint, options?: LintExtensionBlueprintOptions): ExtensionBlueprintLintResult;
+/**
+ * A fluent, single-extension test fixture returned by
+ * {@link createExtensionTestHarness}.
+ *
+ * Every method binds one of the standalone SDK testing helpers to the correct
+ * sub-registry of a single {@link ExtensionActivationResult}, so a package author
+ * never threads `activation.registrations` vs `activation.commands` vs
+ * `activation.hooks` (etc.) by hand — picking the wrong sub-registry is a common
+ * footgun that surfaces as a confusing `available: (none)` error. Methods do not
+ * use `this`; they close over the activation, so they remain safe to destructure
+ * (`const { runCommand, assertCommandContract } = harness;`).
+ *
+ * The `assert*` methods verify registration wiring (returning the matched
+ * registration); the `run*` methods invoke a registered surface through pm's real
+ * dispatch engine (returning its runtime result); {@link deactivate} runs the real
+ * teardown engine. The raw {@link activation} stays public as an escape hatch to
+ * the standalone helpers for any surface not covered by a convenience method.
+ */
+export interface ExtensionTestHarness {
+    /** The in-memory extension module supplied to {@link createExtensionTestHarness}. */
+    readonly module: unknown;
+    /** Resolved extension name (manifest name, explicit override, or `"test-extension"`). */
+    readonly name: string;
+    /** Layer recorded for the in-memory extension (defaults to `"project"`). */
+    readonly layer: ExtensionLayer;
+    /** The underlying activation result; use it to reach standalone helpers directly. */
+    readonly activation: ExtensionActivationResult;
+    /** Bound {@link assertRegisteredCommandContract} over `activation.registrations`. */
+    assertCommandContract(expectation: RegisteredCommandContractExpectation): RegisteredCommandContractAssertion;
+    /** Bound {@link assertRegisteredFlags} over `activation.registrations`. */
+    assertFlags(expectation: RegisteredFlagsExpectation): RegisteredExtensionFlagDefinitions;
+    /** Bound {@link assertRegisteredItemField} over `activation.registrations`. */
+    assertItemField(expectation: RegisteredItemFieldExpectation): RegisteredItemFieldAssertion;
+    /** Bound {@link assertRegisteredItemType} over `activation.registrations`. */
+    assertItemType(expectation: RegisteredItemTypeExpectation): RegisteredItemTypeAssertion;
+    /** Bound {@link assertRegisteredHook} over `activation.hooks`. */
+    assertHook<TKind extends RegisteredHookKind>(expectation: RegisteredHookExpectation & {
+        kind: TKind;
+    }): ExtensionHookRegistry[(typeof HOOK_KIND_TO_REGISTRY_FIELD)[TKind]][number];
+    /** Bound {@link assertRegisteredCommandOverride} over `activation.commands`. */
+    assertCommandOverride(expectation: RegisteredCommandOverrideExpectation): RegisteredExtensionCommandOverride;
+    /** Bound {@link assertRegisteredParserOverride} over `activation.parsers`. */
+    assertParserOverride(expectation: RegisteredParserOverrideExpectation): RegisteredExtensionParserOverride;
+    /** Bound {@link assertRegisteredPreflightOverride} over `activation.preflight`. */
+    assertPreflightOverride(expectation?: RegisteredPreflightOverrideExpectation): RegisteredExtensionPreflightOverride;
+    /** Bound {@link assertRegisteredRendererOverride} over `activation.renderers`. */
+    assertRendererOverride(expectation: RegisteredRendererOverrideExpectation): RegisteredExtensionRendererOverride;
+    /** Bound {@link assertRegisteredServiceOverride} over `activation.services`. */
+    assertServiceOverride(expectation: RegisteredServiceOverrideExpectation): RegisteredExtensionServiceOverride;
+    /** Bound {@link assertRegisteredSearchProvider} over `activation.registrations`. */
+    assertSearchProvider(expectation: RegisteredSearchProviderExpectation): RegisteredExtensionSearchProvider;
+    /** Bound {@link assertRegisteredVectorStoreAdapter} over `activation.registrations`. */
+    assertVectorStoreAdapter(expectation: RegisteredVectorStoreAdapterExpectation): RegisteredExtensionVectorStoreAdapter;
+    /** Bound {@link assertRegisteredImporter} over `activation.registrations`. */
+    assertImporter(expectation: RegisteredImporterExpectation): RegisteredExtensionImporter;
+    /** Bound {@link assertRegisteredExporter} over `activation.registrations`. */
+    assertExporter(expectation: RegisteredExporterExpectation): RegisteredExtensionExporter;
+    /** Bound {@link assertRegisteredMigration} over `activation.registrations`. */
+    assertMigration(expectation: RegisteredMigrationExpectation): RegisteredExtensionSchemaMigrationDefinition;
+    /** Bound {@link assertExtensionCapabilityUsage} over the whole `activation`. */
+    assertCapabilityUsage(expectation: ExtensionCapabilityUsageExpectation): ExtensionCapabilityUsageAssertion;
+    /** Bound {@link runRegisteredCommandForTest} over `activation.commands`. */
+    runCommand(options: RunRegisteredCommandForTestOptions): Promise<CommandHandlerResult>;
+    /** Bound {@link runRegisteredHookForTest} over `activation.hooks`. */
+    runHook(options: RunRegisteredHookForTestOptions): Promise<string[]>;
+    /** Bound {@link runRegisteredCommandOverrideForTest} over `activation.commands`. */
+    runCommandOverride(context: CommandOverrideContext): Promise<CommandOverrideResult>;
+    /** Bound {@link runRegisteredParserOverrideForTest} over `activation.parsers`. */
+    runParserOverride(context: ParserOverrideContext): Promise<ParserOverrideResult>;
+    /** Bound {@link runRegisteredPreflightOverrideForTest} over `activation.preflight`. */
+    runPreflightOverride(context: PreflightOverrideContext): Promise<PreflightOverrideResult>;
+    /** Bound {@link runRegisteredRendererOverrideForTest} over `activation.renderers`. */
+    runRendererOverride(context: RendererOverrideContext): Promise<RendererOverrideResult>;
+    /** Bound {@link runRegisteredServiceOverrideForTest} over `activation.services`. */
+    runServiceOverride(context: ServiceOverrideContext): Promise<ServiceOverrideResult>;
+    /** Bound {@link runRegisteredSearchProviderForTest} over `activation.registrations`. */
+    runSearchProvider<Operation extends keyof SearchProviderOperationContexts>(options: {
+        provider: string;
+        operation: Operation;
+        context: SearchProviderOperationContexts[Operation];
+    }): Promise<SearchProviderOperationResults[Operation]>;
+    /** Bound {@link runRegisteredVectorStoreAdapterForTest} over `activation.registrations`. */
+    runVectorStoreAdapter<Operation extends keyof VectorStoreAdapterOperationContexts>(options: {
+        adapter: string;
+        operation: Operation;
+        context: VectorStoreAdapterOperationContexts[Operation];
+    }): Promise<VectorStoreAdapterOperationResults[Operation]>;
+    /** Bound {@link runRegisteredMigrationForTest} over `activation.registrations`. */
+    runMigration(options: RunRegisteredMigrationForTestOptions): Promise<unknown>;
+    /** Bound {@link runRegisteredImporterForTest} over the whole `activation`. */
+    runImporter(options: RunRegisteredImporterForTestOptions): Promise<CommandHandlerResult>;
+    /** Bound {@link runRegisteredExporterForTest} over the whole `activation`. */
+    runExporter(options: RunRegisteredExporterForTestOptions): Promise<CommandHandlerResult>;
+    /**
+     * Bound {@link deactivateExtensionForTest} — runs the real teardown engine for
+     * this harness's module, forwarding its resolved `name`/`layer`/`activation` so
+     * the skip-key matches and a never-initialized extension is not deactivated.
+     */
+    deactivate(options?: {
+        deactivateTimeoutMs?: number;
+    }): Promise<ExtensionDeactivationResult>;
+}
+/**
+ * Activate one in-memory extension module and return a fluent
+ * {@link ExtensionTestHarness} that binds every SDK testing helper to the right
+ * sub-registry of the resulting activation.
+ *
+ * This is the ergonomic capstone over the standalone helpers: instead of
+ * `activateExtensionForTest(module)` followed by repeatedly threading
+ * `activation.registrations` / `activation.commands` / `activation.hooks` into
+ * each `assertRegistered*` / `runRegistered*` call, an author writes
+ * `const ext = await createExtensionTestHarness(module, { capabilities });` and
+ * then `ext.assertCommandContract(...)`, `await ext.runCommand(...)`,
+ * `await ext.deactivate()` — never needing to know pm's internal registry layout.
+ *
+ * `name` and `layer` are resolved exactly as {@link activateExtensionForTest}
+ * resolves them, and captured so {@link ExtensionTestHarness.deactivate} forwards
+ * a matching skip-key. Activation runs pm's real validation/activation engine, so
+ * every bound helper exercises real wiring and dispatch — not mocks.
+ *
+ * Fails fast: if the module does not activate cleanly (e.g. a registration is
+ * dropped because the manifest omits the required capability), this throws a
+ * descriptive error listing each failure instead of returning a harness whose
+ * registries are empty — which would otherwise surface later as the confusing
+ * `available: (none)` assertion error this helper exists to prevent. Tests that
+ * deliberately exercise a *failed* activation should call
+ * {@link activateExtensionForTest} directly and inspect `activation.failed`.
+ */
+export declare function createExtensionTestHarness(module: unknown, options?: ActivateExtensionForTestOptions): Promise<ExtensionTestHarness>;