@unbrained/pm-cli 2026.6.22 → 2026.6.24

package/dist/sdk/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sources":["sdk/define.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/define\n *\n * Authoring-time typed builders for every extension registration surface.\n *\n * These `define*` helpers are the third leg of the SDK ergonomics tripod:\n * {@link ../core/extensions/loader.js#ExtensionApi | `api.register*`} registers\n * a definition at activation, the `assert*`/`run*` testing helpers verify and\n * invoke it, and these builders let authors *write* the definition with full\n * type-checking and editor inference before it ever reaches `activate`.\n *\n * Every builder is a zero-cost identity function that returns its argument\n * unchanged — exactly like the SDK's {@link ./index.js#defineExtension} and the\n * wider `defineConfig`/`defineComponent` ecosystem convention. Extensions are\n * authored fully in TypeScript (ADR pm-2c28); these builders are where that type\n * safety is anchored at the definition site. Their value is entirely at the type\n * level:\n *\n * - A bare `const cmd = { ... }` satisfies the registration type only\n *   structurally and widens its literals; `const cmd = defineCommand({ ... })`\n *   checks the object against the contract *and* preserves the narrow literal\n *   type, while inferring the nested handler's `context` parameter from the\n *   builder signature.\n * - Definitions can be colocated, exported, reused, and unit-tested apart from\n *   the `activate` call instead of being trapped as inline literals.\n *\n * Object-definition builders use a generic constraint (`<T extends Def>`) so the\n * narrow literal type survives the round-trip, mirroring `defineExtension`.\n * Function-definition builders are intentionally non-generic: a generic\n * constrained to a whole function type suppresses contextual typing of a bare\n * arrow's parameter (it would fall back to implicit `any`), whereas the\n * non-generic signature lets TypeScript type the handler parameter from the\n * declared function type.\n */\nimport type {\n  AfterCommandHook,\n  BeforeCommandHook,\n  CommandDefinition,\n  CommandOverride,\n  Exporter,\n  ExtensionManifest,\n  FlagDefinition,\n  Importer,\n  OnIndexHook,\n  OnReadHook,\n  OnWriteHook,\n  ParserOverride,\n  PreflightOverride,\n  RendererOverride,\n  SchemaFieldDefinition,\n  SchemaItemTypeDefinition,\n  SchemaMigrationDefinition,\n  SearchProviderDefinition,\n  ServiceOverride,\n  VectorStoreAdapterDefinition,\n} from \"../core/extensions/loader.js\";\n\n/**\n * Type an extension's in-module manifest mirror (the `manifest` export / field).\n *\n * Completes the `define*` family: the manifest is the one authoring surface that\n * otherwise had no builder. Contract-checks the object against\n * {@link ExtensionManifest} where it is authored, catching a missing required\n * field or a mistyped key at edit time instead of at load time. Pair with\n * {@link ./compose.js#deriveExtensionCapabilities | `deriveExtensionCapabilities`}\n * to keep `capabilities` matched to the surfaces the extension actually registers.\n */\nexport function defineExtensionManifest<TManifest extends ExtensionManifest>(manifest: TManifest): TManifest {\n  return manifest;\n}\n\n/**\n * Type a command definition for `api.registerCommand(definition)`.\n *\n * Checks the object against {@link CommandDefinition} and infers the `run`\n * handler's `context` parameter while preserving the literal `name`/`action`\n * types. Pass the result straight to `registerCommand`, or export it so the\n * command can be invoked in tests via `runRegisteredCommandForTest`.\n */\nexport function defineCommand<TDefinition extends CommandDefinition>(definition: TDefinition): TDefinition {\n  return definition;\n}\n\n/**\n * Type a single flag definition for a `api.registerFlags(command, flags)` array.\n *\n * Authors compose builders into the array\n * (`api.registerFlags(\"list\", [defineFlag({ long: \"--mine\" })])`) to get\n * per-flag contract checking — `value_type`, `list`, and `default` included —\n * instead of validating a loosely-typed literal array all at once.\n */\nexport function defineFlag<TFlag extends FlagDefinition>(flag: TFlag): TFlag {\n  return flag;\n}\n\n/**\n * Type a custom item-type definition for `api.registerItemTypes([...])`.\n *\n * Preserves the literal `name`/`folder`/`aliases` so a project archetype's\n * domain types stay strongly typed where the definition is declared and reused.\n */\nexport function defineItemType<TType extends SchemaItemTypeDefinition>(type: TType): TType {\n  return type;\n}\n\n/**\n * Type a custom front-matter field definition for `api.registerItemFields([...])`.\n *\n * Checks `name`/`type`/`optional` against {@link SchemaFieldDefinition} while\n * keeping the field's extra metadata (the contract carries an index signature)\n * intact.\n */\nexport function defineItemField<TField extends SchemaFieldDefinition>(field: TField): TField {\n  return field;\n}\n\n/**\n * Type a schema migration definition for `api.registerMigration(definition)`.\n *\n * Preserves the literal `id` and, when `run` is provided, infers the migration\n * runner's context, so the same definition can be registered and later exercised\n * through `runRegisteredMigrationForTest`.\n */\nexport function defineMigration<TMigration extends SchemaMigrationDefinition>(migration: TMigration): TMigration {\n  return migration;\n}\n\n/**\n * Type a search-provider definition for `api.registerSearchProvider(provider)`.\n *\n * Infers the `query`/`embed`/`embedBatch` operation contexts and result shapes\n * so a custom retrieval backend is type-checked at the definition site and\n * reusable in `runRegisteredSearchProviderForTest`.\n */\nexport function defineSearchProvider<TProvider extends SearchProviderDefinition>(provider: TProvider): TProvider {\n  return provider;\n}\n\n/**\n * Type a vector-store adapter definition for `api.registerVectorStoreAdapter(adapter)`.\n *\n * Infers the `query`/`upsert`/`delete` operation contexts so a package that owns\n * its own semantic index storage gets contract checking before activation and a\n * definition it can drive through `runRegisteredVectorStoreAdapterForTest`.\n */\nexport function defineVectorStoreAdapter<TAdapter extends VectorStoreAdapterDefinition>(adapter: TAdapter): TAdapter {\n  return adapter;\n}\n\n/**\n * Type a command-override handler for `api.registerCommand(command, override)`.\n *\n * The non-generic signature lets TypeScript contextually type the override's\n * `context` parameter from {@link CommandOverride}, so a bare arrow authored in\n * a `.js` package still gets a fully-typed argument.\n */\nexport function defineCommandOverride(override: CommandOverride): CommandOverride {\n  return override;\n}\n\n/**\n * Type a parser-override handler for `api.registerParser(command, override)`.\n *\n * Contextually types the `context` parameter and the returned\n * {@link ParserOverride} delta so an argument-rewriting override is checked\n * where it is written.\n */\nexport function defineParserOverride(override: ParserOverride): ParserOverride {\n  return override;\n}\n\n/**\n * Type a preflight-override handler for `api.registerPreflight(override)`.\n *\n * Contextually types the `context` parameter and the returned gate decision so a\n * package's pre-run validation override is checked at the definition site.\n */\nexport function definePreflightOverride(override: PreflightOverride): PreflightOverride {\n  return override;\n}\n\n/**\n * Type a service-override handler for `api.registerService(service, override)`.\n *\n * Contextually types the `context` parameter from {@link ServiceOverride} so a\n * package overriding a built-in service (output formatting, embeddings, and the\n * like) keeps its handler argument typed without an explicit annotation.\n */\nexport function defineServiceOverride(override: ServiceOverride): ServiceOverride {\n  return override;\n}\n\n/**\n * Type a renderer-override handler for `api.registerRenderer(format, renderer)`.\n *\n * Contextually types the `context` parameter and the `string | null | undefined`\n * return contract so a custom output renderer is checked where it is authored.\n */\nexport function defineRendererOverride(renderer: RendererOverride): RendererOverride {\n  return renderer;\n}\n\n/**\n * Type an importer handler for `api.registerImporter(name, importer, options)`.\n *\n * Contextually types the {@link Importer} `context` (registration, args,\n * options, pm root) so the bridge from an external system into the pm context\n * graph is type-checked and reusable in `runRegisteredImporterForTest`.\n */\nexport function defineImporter(importer: Importer): Importer {\n  return importer;\n}\n\n/**\n * Type an exporter handler for `api.registerExporter(name, exporter, options)`.\n *\n * Contextually types the {@link Exporter} `context` so the bridge from the pm\n * context graph out to an external system is checked at the definition site and\n * reusable in `runRegisteredExporterForTest`.\n */\nexport function defineExporter(exporter: Exporter): Exporter {\n  return exporter;\n}\n\n/**\n * Type a `before_command` hook for `api.hooks.beforeCommand(hook)`.\n *\n * Contextually types the {@link BeforeCommandHook} `context` so a hook that\n * inspects or annotates a command before it runs keeps its argument typed when\n * authored as a standalone, exportable, testable value.\n */\nexport function defineBeforeCommandHook(hook: BeforeCommandHook): BeforeCommandHook {\n  return hook;\n}\n\n/**\n * Type an `after_command` hook for `api.hooks.afterCommand(hook)`.\n *\n * Contextually types the {@link AfterCommandHook} `context` — including the\n * `affected` items pm mutated — so the natural place to react to every change\n * (\"project management = context management\") is checked where it is written.\n */\nexport function defineAfterCommandHook(hook: AfterCommandHook): AfterCommandHook {\n  return hook;\n}\n\n/**\n * Type an `on_write` hook for `api.hooks.onWrite(hook)`.\n *\n * Contextually types the {@link OnWriteHook} `context` so a hook reacting to\n * item persistence keeps its argument typed without an explicit annotation.\n */\nexport function defineOnWriteHook(hook: OnWriteHook): OnWriteHook {\n  return hook;\n}\n\n/**\n * Type an `on_read` hook for `api.hooks.onRead(hook)`.\n *\n * Contextually types the {@link OnReadHook} `context` so a hook augmenting items\n * as they are read is type-checked at the definition site.\n */\nexport function defineOnReadHook(hook: OnReadHook): OnReadHook {\n  return hook;\n}\n\n/**\n * Type an `on_index` hook for `api.hooks.onIndex(hook)`.\n *\n * Contextually types the {@link OnIndexHook} `context` so a hook participating\n * in index/search refresh keeps its argument typed even without TypeScript\n * annotations.\n */\nexport function defineOnIndexHook(hook: OnIndexHook): OnIndexHook {\n  return hook;\n}\n"],"names":[],"mappings":"AAyDA;;;;;;;;;GASG;;;AACH,MAAM,UAAU,uBAAuB,CAAsC,QAAmB;IAC9F,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAwC,UAAuB;IAC1F,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAA+B,IAAW;IAClE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAyC,IAAW;IAChF,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAuC,KAAa;IACjF,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAA+C,SAAqB;IACjG,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAA6C,QAAmB;IAClG,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAgD,OAAiB;IACvG,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAyB;IAC7D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAwB;IAC3D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAA2B;IACjE,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAyB;IAC7D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAA0B;IAC/D,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAkB;IAC/C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAkB;IAC/C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAAuB;IAC7D,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAsB;IAC3D,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAiB;IACjD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAgB;IAC/C,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAiB;IACjD,OAAO,IAAI,CAAC;AACd,CAAC","debugId":"20a69cdc-ebc4-5a43-8701-0a5c867f8229"}

package/dist/sdk/index.d.ts

@@ -3,11 +3,13 @@
  *
  * Defines public SDK APIs and package-author helpers for Index.
  */
-import { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES, type ExtensionApi, type ExtensionManifest } from "../core/extensions/loader.js";
+import { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES } from "../core/extensions/loader.js";
 export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, collectPackageExtensionDirectories, readPmPackageManifest, type PmPackageCatalogLinkMap, type PmPackageCatalogMediaMap, type PmPackageCatalogMetadata, type PmPackageManifest, type PmPackageResourceKind, type PmPackageResourceMap, } from "../core/packages/manifest.js";
 export * from "./cli-contracts.js";
+export * from "./compose.js";
+export * from "./define.js";
 export * from "./runtime.js";
-export { assertExtensionCapabilityUsage, assertExtensionDeactivated, assertPackageManifest, assertRegisteredCommandContract, assertRegisteredCommandOverride, assertRegisteredExporter, assertRegisteredFlags, assertRegisteredHook, assertRegisteredImporter, assertRegisteredItemField, assertRegisteredItemType, assertRegisteredMigration, assertRegisteredParserOverride, assertRegisteredPreflightOverride, assertRegisteredRendererOverride, assertRegisteredSearchProvider, assertRegisteredServiceOverride, assertRegisteredVectorStoreAdapter, activateExtensionForTest, deactivateExtensionForTest, runRegisteredCommandForTest, runRegisteredCommandOverrideForTest, runRegisteredExporterForTest, runRegisteredHookForTest, runRegisteredImporterForTest, runRegisteredMigrationForTest, runRegisteredParserOverrideForTest, runRegisteredPreflightOverrideForTest, runRegisteredRendererOverrideForTest, runRegisteredSearchProviderForTest, runRegisteredServiceOverrideForTest, runRegisteredVectorStoreAdapterForTest, type ActivateExtensionForTestOptions, type DeactivateExtensionForTestOptions, type RunRegisteredCommandForTestOptions, type RunRegisteredExporterForTestOptions, type RunRegisteredHookForTestOptions, type RunRegisteredImporterForTestOptions, type RunRegisteredMigrationForTestOptions, type RunRegisteredSearchProviderForTestOptions, type RunRegisteredVectorStoreAdapterForTestOptions, type SearchProviderOperationContexts, type SearchProviderOperationResults, type VectorStoreAdapterOperationContexts, type VectorStoreAdapterOperationResults, type ExtensionCapabilityUsageAssertion, type ExtensionCapabilityUsageExpectation, type ExtensionDeactivationExpectation, type PackageManifestExpectation, type PackageManifestResourceExpectation, type RegisteredCommandContractAssertion, type RegisteredCommandContractExpectation, type RegisteredCommandOverrideExpectation, type RegisteredExporterExpectation, type RegisteredFlagsExpectation, type RegisteredHookExpectation, type RegisteredHookKind, type RegisteredImporterExpectation, type RegisteredItemFieldAssertion, type RegisteredItemFieldExpectation, type RegisteredItemTypeAssertion, type RegisteredItemTypeExpectation, type RegisteredMigrationExpectation, type RegisteredParserOverrideExpectation, type RegisteredPreflightOverrideExpectation, type RegisteredRendererOverrideExpectation, type RegisteredSearchProviderExpectation, type RegisteredServiceOverrideExpectation, type RegisteredVectorStoreAdapterExpectation, } from "./testing.js";
+export { assertExtensionBlueprint, assertExtensionCapabilityUsage, assertExtensionDeactivated, assertExtensionManifestCompatible, assertExtensionManifestMatchesBlueprint, assertExtensionPreflight, assertPackageManifest, assertRegisteredCommandContract, assertRegisteredCommandOverride, assertRegisteredExporter, assertRegisteredFlags, assertRegisteredHook, assertRegisteredImporter, assertRegisteredItemField, assertRegisteredItemType, assertRegisteredMigration, assertRegisteredParserOverride, assertRegisteredPreflightOverride, assertRegisteredRendererOverride, assertRegisteredSearchProvider, assertRegisteredServiceOverride, assertRegisteredVectorStoreAdapter, activateExtensionForTest, createExtensionTestHarness, deactivateExtensionForTest, describeExtensionActivation, runRegisteredCommandForTest, runRegisteredCommandOverrideForTest, runRegisteredExporterForTest, runRegisteredHookForTest, runRegisteredImporterForTest, runRegisteredMigrationForTest, runRegisteredParserOverrideForTest, runRegisteredPreflightOverrideForTest, runRegisteredRendererOverrideForTest, runRegisteredSearchProviderForTest, runRegisteredServiceOverrideForTest, runRegisteredVectorStoreAdapterForTest, type ActivateExtensionForTestOptions, type DeactivateExtensionForTestOptions, type DescribeExtensionActivationOptions, type ExtensionActivationSummary, type RunRegisteredCommandForTestOptions, type RunRegisteredExporterForTestOptions, type RunRegisteredHookForTestOptions, type RunRegisteredImporterForTestOptions, type RunRegisteredMigrationForTestOptions, type RunRegisteredSearchProviderForTestOptions, type RunRegisteredVectorStoreAdapterForTestOptions, type SearchProviderOperationContexts, type SearchProviderOperationResults, type VectorStoreAdapterOperationContexts, type VectorStoreAdapterOperationResults, type ExtensionCapabilityUsageAssertion, type ExtensionCapabilityUsageExpectation, type ExtensionDeactivationExpectation, type ExtensionManifestBlueprintMatch, type ExtensionTestHarness, type PackageManifestExpectation, type PackageManifestResourceExpectation, type RegisteredCommandContractAssertion, type RegisteredCommandContractExpectation, type RegisteredCommandOverrideExpectation, type RegisteredExporterExpectation, type RegisteredFlagsExpectation, type RegisteredHookExpectation, type RegisteredHookKind, type RegisteredImporterExpectation, type RegisteredItemFieldAssertion, type RegisteredItemFieldExpectation, type RegisteredItemTypeAssertion, type RegisteredItemTypeExpectation, type RegisteredMigrationExpectation, type RegisteredParserOverrideExpectation, type RegisteredPreflightOverrideExpectation, type RegisteredRendererOverrideExpectation, type RegisteredSearchProviderExpectation, type RegisteredServiceOverrideExpectation, type RegisteredVectorStoreAdapterExpectation, } from "./testing.js";
 /**
  * Canonical extension capability names accepted by pm.
  *
@@ -51,31 +53,6 @@ export { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, E
  * against the registration surfaces a package actually exercises at activation.
  */
 export { EXTENSION_CAPABILITY_REGISTRATION_SURFACES, collectUsedExtensionCapabilities, reconcileExtensionCapabilityUsage, type CollectUsedExtensionCapabilitiesOptions, type ExtensionCapabilityUsageReconciliation, } from "../core/extensions/capability-usage.js";
-/**
- * Documents the extension module payload exchanged by command, SDK, and package integrations.
- */
-export interface ExtensionModule {
-    /**
-     * Optional in-module metadata mirror.
-     *
-     * The authoritative manifest remains on-disk `manifest.json`; this field is
-     * useful when authors want colocated metadata for tooling/tests.
-     */
-    manifest?: ExtensionManifest;
-    activate(api: ExtensionApi): void | Promise<void>;
-    /**
-     * Optional teardown lifecycle hook (VS Code-style `deactivate`). Invoked by
-     * the host on shutdown/reload to release resources opened during `activate`.
-     */
-    deactivate?(): void | Promise<void>;
-}
-/**
- * Typed identity helper for extension module exports.
- *
- * Use as:
- * `export default defineExtension({ activate(api) { ... } })`
- */
-export declare function defineExtension<TModule extends ExtensionModule>(module: TModule): TModule;
 export type { AfterCommandAffectedItem, AfterCommandHook, AfterCommandHookContext, BeforeCommandHook, BeforeCommandHookContext, CommandDefinition, ExtensionCommandArgumentDefinition, CommandHandler, CommandHandlerContext, CommandHandlerResult, CommandOverride, CommandOverrideContext, ExtensionServiceName, Exporter, ExtensionActivationResult, ExtensionApi, ExtensionCommandRegistry, ExtensionDeactivationFailure, ExtensionDeactivationOptions, ExtensionDeactivationResult, ExtensionDiagnostic, ExtensionDiscoveryResult, ExtensionHookRegistry, ExtensionSelfIdentity, ExtensionLoadResult, ExtensionManifest, ExtensionManifestEngines, ExtensionGovernancePolicy, ExtensionPolicyOverride, ExtensionProvenanceMetadata, ExtensionRuntimePermissionDeclaration, ExtensionSearchMode, ExtensionParserRegistry, ExtensionPreflightRegistry, ExtensionRegistrationRegistry, ExtensionRendererRegistry, ExtensionServiceRegistry, FlagValueType, FlagDefinition, ImportExportContext, ImportExportRegistrationOptions, Importer, OnIndexHook, OnIndexHookContext, OnReadHook, OnReadHookContext, OnWriteHook, OnWriteHookContext, OutputRendererFormat, ParserOverride, ParserOverrideContext, ParserOverrideDelta, PreflightOverride, PreflightOverrideContext, PreflightOverrideDelta, PreflightRuntimeDecision, RegisteredExtensionExporter, RegisteredExtensionFlagDefinitions, RegisteredExtensionHook, RegisteredExtensionImporter, RegisteredExtensionSchemaMigrationDefinition, RegisteredExtensionSearchProvider, RegisteredExtensionServiceOverride, RegisteredExtensionVectorStoreAdapter, RendererOverride, RendererOverrideContext, SchemaFieldDefinition, SchemaItemTypeCommandOptionPolicyDefinition, SchemaItemTypeOptionDefinition, SchemaItemTypeDefinition, SchemaMigrationDefinition, SchemaMigrationRunContext, SchemaMigrationRunner, SearchProviderEmbedBatchContext, SearchProviderEmbedContext, SearchProviderDefinition, SearchProviderHit, SearchProviderQueryContext, SearchProviderQueryResult, ServiceOverride, ServiceOverrideContext, VectorStoreAdapterDefinition, VectorStoreDeleteContext, VectorStoreQueryContext, VectorStoreQueryHit, VectorStoreUpsertContext, VectorStoreUpsertPoint, } from "../core/extensions/loader.js";
 export type { GlobalOptions } from "../core/shared/command-types.js";
 export type { ItemDocument, ItemFrontMatter, ItemStatus, ItemType, PmSettings } from "../types/index.js";

package/dist/sdk/index.js

@@ -4,12 +4,14 @@
  * Defines public SDK APIs and package-author helpers for Index.
  */
 
-!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]="1d24d2b1-5d34-5796-9315-61c8ea1f4095")}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]="a6b61a03-0082-5871-88e3-b0b1dbad480b")}catch(e){}}();
 import { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES, KNOWN_EXTENSION_CAPABILITIES, KNOWN_EXTENSION_POLICY_MODES, KNOWN_EXTENSION_POLICY_SURFACES, KNOWN_EXTENSION_SANDBOX_PROFILES, KNOWN_EXTENSION_TRUST_MODES, } from "../core/extensions/loader.js";
 export { PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS, PM_PACKAGE_RESOURCE_KINDS, collectPackageExtensionDirectories, readPmPackageManifest, } from "../core/packages/manifest.js";
 export * from "./cli-contracts.js";
+export * from "./compose.js";
+export * from "./define.js";
 export * from "./runtime.js";
-export { assertExtensionCapabilityUsage, assertExtensionDeactivated, assertPackageManifest, assertRegisteredCommandContract, assertRegisteredCommandOverride, assertRegisteredExporter, assertRegisteredFlags, assertRegisteredHook, assertRegisteredImporter, assertRegisteredItemField, assertRegisteredItemType, assertRegisteredMigration, assertRegisteredParserOverride, assertRegisteredPreflightOverride, assertRegisteredRendererOverride, assertRegisteredSearchProvider, assertRegisteredServiceOverride, assertRegisteredVectorStoreAdapter, activateExtensionForTest, deactivateExtensionForTest, runRegisteredCommandForTest, runRegisteredCommandOverrideForTest, runRegisteredExporterForTest, runRegisteredHookForTest, runRegisteredImporterForTest, runRegisteredMigrationForTest, runRegisteredParserOverrideForTest, runRegisteredPreflightOverrideForTest, runRegisteredRendererOverrideForTest, runRegisteredSearchProviderForTest, runRegisteredServiceOverrideForTest, runRegisteredVectorStoreAdapterForTest, } from "./testing.js";
+export { assertExtensionBlueprint, assertExtensionCapabilityUsage, assertExtensionDeactivated, assertExtensionManifestCompatible, assertExtensionManifestMatchesBlueprint, assertExtensionPreflight, assertPackageManifest, assertRegisteredCommandContract, assertRegisteredCommandOverride, assertRegisteredExporter, assertRegisteredFlags, assertRegisteredHook, assertRegisteredImporter, assertRegisteredItemField, assertRegisteredItemType, assertRegisteredMigration, assertRegisteredParserOverride, assertRegisteredPreflightOverride, assertRegisteredRendererOverride, assertRegisteredSearchProvider, assertRegisteredServiceOverride, assertRegisteredVectorStoreAdapter, activateExtensionForTest, createExtensionTestHarness, deactivateExtensionForTest, describeExtensionActivation, runRegisteredCommandForTest, runRegisteredCommandOverrideForTest, runRegisteredExporterForTest, runRegisteredHookForTest, runRegisteredImporterForTest, runRegisteredMigrationForTest, runRegisteredParserOverrideForTest, runRegisteredPreflightOverrideForTest, runRegisteredRendererOverrideForTest, runRegisteredSearchProviderForTest, runRegisteredServiceOverrideForTest, runRegisteredVectorStoreAdapterForTest, } from "./testing.js";
 /**
  * Canonical extension capability names accepted by pm.
  *
@@ -33,14 +35,5 @@ export { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, E
  * against the registration surfaces a package actually exercises at activation.
  */
 export { EXTENSION_CAPABILITY_REGISTRATION_SURFACES, collectUsedExtensionCapabilities, reconcileExtensionCapabilityUsage, } from "../core/extensions/capability-usage.js";
-/**
- * Typed identity helper for extension module exports.
- *
- * Use as:
- * `export default defineExtension({ activate(api) { ... } })`
- */
-export function defineExtension(module) {
-    return module;
-}
 //# sourceMappingURL=index.js.map
-//# debugId=1d24d2b1-5d34-5796-9315-61c8ea1f4095
+//# debugId=a6b61a03-0082-5871-88e3-b0b1dbad480b

package/dist/sdk/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["sdk/index.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/index\n *\n * Defines public SDK APIs and package-author helpers for Index.\n */\nimport {\n  EXTENSION_CAPABILITY_CONTRACT,\n  EXTENSION_CAPABILITY_CONTRACT_VERSION,\n  EXTENSION_CAPABILITY_LEGACY_ALIASES,\n  KNOWN_EXTENSION_CAPABILITIES,\n  KNOWN_EXTENSION_POLICY_MODES,\n  KNOWN_EXTENSION_POLICY_SURFACES,\n  KNOWN_EXTENSION_SANDBOX_PROFILES,\n  KNOWN_EXTENSION_TRUST_MODES,\n  type ExtensionApi,\n  type ExtensionManifest,\n} from \"../core/extensions/loader.js\";\nexport {\n  PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS,\n  PM_PACKAGE_RESOURCE_KINDS,\n  collectPackageExtensionDirectories,\n  readPmPackageManifest,\n  type PmPackageCatalogLinkMap,\n  type PmPackageCatalogMediaMap,\n  type PmPackageCatalogMetadata,\n  type PmPackageManifest,\n  type PmPackageResourceKind,\n  type PmPackageResourceMap,\n} from \"../core/packages/manifest.js\";\nexport * from \"./cli-contracts.js\";\nexport * from \"./runtime.js\";\nexport {\n  assertExtensionCapabilityUsage,\n  assertExtensionDeactivated,\n  assertPackageManifest,\n  assertRegisteredCommandContract,\n  assertRegisteredCommandOverride,\n  assertRegisteredExporter,\n  assertRegisteredFlags,\n  assertRegisteredHook,\n  assertRegisteredImporter,\n  assertRegisteredItemField,\n  assertRegisteredItemType,\n  assertRegisteredMigration,\n  assertRegisteredParserOverride,\n  assertRegisteredPreflightOverride,\n  assertRegisteredRendererOverride,\n  assertRegisteredSearchProvider,\n  assertRegisteredServiceOverride,\n  assertRegisteredVectorStoreAdapter,\n  activateExtensionForTest,\n  deactivateExtensionForTest,\n  runRegisteredCommandForTest,\n  runRegisteredCommandOverrideForTest,\n  runRegisteredExporterForTest,\n  runRegisteredHookForTest,\n  runRegisteredImporterForTest,\n  runRegisteredMigrationForTest,\n  runRegisteredParserOverrideForTest,\n  runRegisteredPreflightOverrideForTest,\n  runRegisteredRendererOverrideForTest,\n  runRegisteredSearchProviderForTest,\n  runRegisteredServiceOverrideForTest,\n  runRegisteredVectorStoreAdapterForTest,\n  type ActivateExtensionForTestOptions,\n  type DeactivateExtensionForTestOptions,\n  type RunRegisteredCommandForTestOptions,\n  type RunRegisteredExporterForTestOptions,\n  type RunRegisteredHookForTestOptions,\n  type RunRegisteredImporterForTestOptions,\n  type RunRegisteredMigrationForTestOptions,\n  type RunRegisteredSearchProviderForTestOptions,\n  type RunRegisteredVectorStoreAdapterForTestOptions,\n  type SearchProviderOperationContexts,\n  type SearchProviderOperationResults,\n  type VectorStoreAdapterOperationContexts,\n  type VectorStoreAdapterOperationResults,\n  type ExtensionCapabilityUsageAssertion,\n  type ExtensionCapabilityUsageExpectation,\n  type ExtensionDeactivationExpectation,\n  type PackageManifestExpectation,\n  type PackageManifestResourceExpectation,\n  type RegisteredCommandContractAssertion,\n  type RegisteredCommandContractExpectation,\n  type RegisteredCommandOverrideExpectation,\n  type RegisteredExporterExpectation,\n  type RegisteredFlagsExpectation,\n  type RegisteredHookExpectation,\n  type RegisteredHookKind,\n  type RegisteredImporterExpectation,\n  type RegisteredItemFieldAssertion,\n  type RegisteredItemFieldExpectation,\n  type RegisteredItemTypeAssertion,\n  type RegisteredItemTypeExpectation,\n  type RegisteredMigrationExpectation,\n  type RegisteredParserOverrideExpectation,\n  type RegisteredPreflightOverrideExpectation,\n  type RegisteredRendererOverrideExpectation,\n  type RegisteredSearchProviderExpectation,\n  type RegisteredServiceOverrideExpectation,\n  type RegisteredVectorStoreAdapterExpectation,\n} from \"./testing.js\";\n\n/**\n * Canonical extension capability names accepted by pm.\n *\n * Extension manifests should declare one or more of these values in\n * `capabilities`.\n */\nexport const EXTENSION_CAPABILITIES = KNOWN_EXTENSION_CAPABILITIES;\n/**\n * Restricts extension capability values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionCapability = (typeof EXTENSION_CAPABILITIES)[number];\n\n/**\n * Canonical extension governance policy modes and registration surfaces.\n */\nexport const EXTENSION_POLICY_MODES = KNOWN_EXTENSION_POLICY_MODES;\nexport const EXTENSION_POLICY_SURFACES = KNOWN_EXTENSION_POLICY_SURFACES;\nexport const EXTENSION_TRUST_MODES = KNOWN_EXTENSION_TRUST_MODES;\nexport const EXTENSION_SANDBOX_PROFILES = KNOWN_EXTENSION_SANDBOX_PROFILES;\n/**\n * Restricts extension policy mode values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionPolicyMode = (typeof EXTENSION_POLICY_MODES)[number];\n/**\n * Restricts extension policy surface values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionPolicySurface = (typeof EXTENSION_POLICY_SURFACES)[number];\n/**\n * Restricts extension trust mode values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionTrustMode = (typeof EXTENSION_TRUST_MODES)[number];\n/**\n * Restricts extension sandbox profile values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionSandboxProfile = (typeof EXTENSION_SANDBOX_PROFILES)[number];\n\n/**\n * Versioned capability contract metadata emitted by runtime diagnostics.\n */\nexport { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES };\n\n/**\n * Least-privilege capability reconciliation helpers: map declared capabilities\n * against the registration surfaces a package actually exercises at activation.\n */\nexport {\n  EXTENSION_CAPABILITY_REGISTRATION_SURFACES,\n  collectUsedExtensionCapabilities,\n  reconcileExtensionCapabilityUsage,\n  type CollectUsedExtensionCapabilitiesOptions,\n  type ExtensionCapabilityUsageReconciliation,\n} from \"../core/extensions/capability-usage.js\";\n\n/**\n * Documents the extension module payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionModule {\n  /**\n   * Optional in-module metadata mirror.\n   *\n   * The authoritative manifest remains on-disk `manifest.json`; this field is\n   * useful when authors want colocated metadata for tooling/tests.\n   */\n  manifest?: ExtensionManifest;\n  activate(api: ExtensionApi): void | Promise<void>;\n  /**\n   * Optional teardown lifecycle hook (VS Code-style `deactivate`). Invoked by\n   * the host on shutdown/reload to release resources opened during `activate`.\n   */\n  deactivate?(): void | Promise<void>;\n}\n\n/**\n * Typed identity helper for extension module exports.\n *\n * Use as:\n * `export default defineExtension({ activate(api) { ... } })`\n */\nexport function defineExtension<TModule extends ExtensionModule>(module: TModule): TModule {\n  return module;\n}\n\nexport type {\n  AfterCommandAffectedItem,\n  AfterCommandHook,\n  AfterCommandHookContext,\n  BeforeCommandHook,\n  BeforeCommandHookContext,\n  CommandDefinition,\n  ExtensionCommandArgumentDefinition,\n  CommandHandler,\n  CommandHandlerContext,\n  CommandHandlerResult,\n  CommandOverride,\n  CommandOverrideContext,\n  ExtensionServiceName,\n  Exporter,\n  ExtensionActivationResult,\n  ExtensionApi,\n  ExtensionCommandRegistry,\n  ExtensionDeactivationFailure,\n  ExtensionDeactivationOptions,\n  ExtensionDeactivationResult,\n  ExtensionDiagnostic,\n  ExtensionDiscoveryResult,\n  ExtensionHookRegistry,\n  ExtensionSelfIdentity,\n  ExtensionLoadResult,\n  ExtensionManifest,\n  ExtensionManifestEngines,\n  ExtensionGovernancePolicy,\n  ExtensionPolicyOverride,\n  ExtensionProvenanceMetadata,\n  ExtensionRuntimePermissionDeclaration,\n  ExtensionSearchMode,\n  ExtensionParserRegistry,\n  ExtensionPreflightRegistry,\n  ExtensionRegistrationRegistry,\n  ExtensionRendererRegistry,\n  ExtensionServiceRegistry,\n  FlagValueType,\n  FlagDefinition,\n  ImportExportContext,\n  ImportExportRegistrationOptions,\n  Importer,\n  OnIndexHook,\n  OnIndexHookContext,\n  OnReadHook,\n  OnReadHookContext,\n  OnWriteHook,\n  OnWriteHookContext,\n  OutputRendererFormat,\n  ParserOverride,\n  ParserOverrideContext,\n  ParserOverrideDelta,\n  PreflightOverride,\n  PreflightOverrideContext,\n  PreflightOverrideDelta,\n  PreflightRuntimeDecision,\n  RegisteredExtensionExporter,\n  RegisteredExtensionFlagDefinitions,\n  RegisteredExtensionHook,\n  RegisteredExtensionImporter,\n  RegisteredExtensionSchemaMigrationDefinition,\n  RegisteredExtensionSearchProvider,\n  RegisteredExtensionServiceOverride,\n  RegisteredExtensionVectorStoreAdapter,\n  RendererOverride,\n  RendererOverrideContext,\n  SchemaFieldDefinition,\n  SchemaItemTypeCommandOptionPolicyDefinition,\n  SchemaItemTypeOptionDefinition,\n  SchemaItemTypeDefinition,\n  SchemaMigrationDefinition,\n  SchemaMigrationRunContext,\n  SchemaMigrationRunner,\n  SearchProviderEmbedBatchContext,\n  SearchProviderEmbedContext,\n  SearchProviderDefinition,\n  SearchProviderHit,\n  SearchProviderQueryContext,\n  SearchProviderQueryResult,\n  ServiceOverride,\n  ServiceOverrideContext,\n  VectorStoreAdapterDefinition,\n  VectorStoreDeleteContext,\n  VectorStoreQueryContext,\n  VectorStoreQueryHit,\n  VectorStoreUpsertContext,\n  VectorStoreUpsertPoint,\n} from \"../core/extensions/loader.js\";\n\nexport type { GlobalOptions } from \"../core/shared/command-types.js\";\nexport type { ItemDocument, ItemFrontMatter, ItemStatus, ItemType, PmSettings } from \"../types/index.js\";\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,OAAO,EACL,6BAA6B,EAC7B,qCAAqC,EACrC,mCAAmC,EACnC,4BAA4B,EAC5B,4BAA4B,EAC5B,+BAA+B,EAC/B,gCAAgC,EAChC,2BAA2B,GAG5B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,sCAAsC,EACtC,yBAAyB,EACzB,kCAAkC,EAClC,qBAAqB,GAOtB,MAAM,8BAA8B,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,qBAAqB,EACrB,+BAA+B,EAC/B,+BAA+B,EAC/B,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,8BAA8B,EAC9B,iCAAiC,EACjC,gCAAgC,EAChC,8BAA8B,EAC9B,+BAA+B,EAC/B,kCAAkC,EAClC,wBAAwB,EACxB,0BAA0B,EAC1B,2BAA2B,EAC3B,mCAAmC,EACnC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,EAC5B,6BAA6B,EAC7B,kCAAkC,EAClC,qCAAqC,EACrC,oCAAoC,EACpC,kCAAkC,EAClC,mCAAmC,EACnC,sCAAsC,GAsCvC,MAAM,cAAc,CAAC;AAEtB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AAMnE;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AACnE,MAAM,CAAC,MAAM,yBAAyB,GAAG,+BAA+B,CAAC;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AACjE,MAAM,CAAC,MAAM,0BAA0B,GAAG,gCAAgC,CAAC;AAkB3E;;GAEG;AACH,OAAO,EAAE,6BAA6B,EAAE,qCAAqC,EAAE,mCAAmC,EAAE,CAAC;AAErH;;;GAGG;AACH,OAAO,EACL,0CAA0C,EAC1C,gCAAgC,EAChC,iCAAiC,GAGlC,MAAM,wCAAwC,CAAC;AAqBhD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAkC,MAAe;IAC9E,OAAO,MAAM,CAAC;AAChB,CAAC","debugId":"1d24d2b1-5d34-5796-9315-61c8ea1f4095"}
+{"version":3,"file":"index.js","sources":["sdk/index.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module sdk/index\n *\n * Defines public SDK APIs and package-author helpers for Index.\n */\nimport {\n  EXTENSION_CAPABILITY_CONTRACT,\n  EXTENSION_CAPABILITY_CONTRACT_VERSION,\n  EXTENSION_CAPABILITY_LEGACY_ALIASES,\n  KNOWN_EXTENSION_CAPABILITIES,\n  KNOWN_EXTENSION_POLICY_MODES,\n  KNOWN_EXTENSION_POLICY_SURFACES,\n  KNOWN_EXTENSION_SANDBOX_PROFILES,\n  KNOWN_EXTENSION_TRUST_MODES,\n} from \"../core/extensions/loader.js\";\nexport {\n  PM_PACKAGE_CONVENTIONAL_RESOURCE_ROOTS,\n  PM_PACKAGE_RESOURCE_KINDS,\n  collectPackageExtensionDirectories,\n  readPmPackageManifest,\n  type PmPackageCatalogLinkMap,\n  type PmPackageCatalogMediaMap,\n  type PmPackageCatalogMetadata,\n  type PmPackageManifest,\n  type PmPackageResourceKind,\n  type PmPackageResourceMap,\n} from \"../core/packages/manifest.js\";\nexport * from \"./cli-contracts.js\";\nexport * from \"./compose.js\";\nexport * from \"./define.js\";\nexport * from \"./runtime.js\";\nexport {\n  assertExtensionBlueprint,\n  assertExtensionCapabilityUsage,\n  assertExtensionDeactivated,\n  assertExtensionManifestCompatible,\n  assertExtensionManifestMatchesBlueprint,\n  assertExtensionPreflight,\n  assertPackageManifest,\n  assertRegisteredCommandContract,\n  assertRegisteredCommandOverride,\n  assertRegisteredExporter,\n  assertRegisteredFlags,\n  assertRegisteredHook,\n  assertRegisteredImporter,\n  assertRegisteredItemField,\n  assertRegisteredItemType,\n  assertRegisteredMigration,\n  assertRegisteredParserOverride,\n  assertRegisteredPreflightOverride,\n  assertRegisteredRendererOverride,\n  assertRegisteredSearchProvider,\n  assertRegisteredServiceOverride,\n  assertRegisteredVectorStoreAdapter,\n  activateExtensionForTest,\n  createExtensionTestHarness,\n  deactivateExtensionForTest,\n  describeExtensionActivation,\n  runRegisteredCommandForTest,\n  runRegisteredCommandOverrideForTest,\n  runRegisteredExporterForTest,\n  runRegisteredHookForTest,\n  runRegisteredImporterForTest,\n  runRegisteredMigrationForTest,\n  runRegisteredParserOverrideForTest,\n  runRegisteredPreflightOverrideForTest,\n  runRegisteredRendererOverrideForTest,\n  runRegisteredSearchProviderForTest,\n  runRegisteredServiceOverrideForTest,\n  runRegisteredVectorStoreAdapterForTest,\n  type ActivateExtensionForTestOptions,\n  type DeactivateExtensionForTestOptions,\n  type DescribeExtensionActivationOptions,\n  type ExtensionActivationSummary,\n  type RunRegisteredCommandForTestOptions,\n  type RunRegisteredExporterForTestOptions,\n  type RunRegisteredHookForTestOptions,\n  type RunRegisteredImporterForTestOptions,\n  type RunRegisteredMigrationForTestOptions,\n  type RunRegisteredSearchProviderForTestOptions,\n  type RunRegisteredVectorStoreAdapterForTestOptions,\n  type SearchProviderOperationContexts,\n  type SearchProviderOperationResults,\n  type VectorStoreAdapterOperationContexts,\n  type VectorStoreAdapterOperationResults,\n  type ExtensionCapabilityUsageAssertion,\n  type ExtensionCapabilityUsageExpectation,\n  type ExtensionDeactivationExpectation,\n  type ExtensionManifestBlueprintMatch,\n  type ExtensionTestHarness,\n  type PackageManifestExpectation,\n  type PackageManifestResourceExpectation,\n  type RegisteredCommandContractAssertion,\n  type RegisteredCommandContractExpectation,\n  type RegisteredCommandOverrideExpectation,\n  type RegisteredExporterExpectation,\n  type RegisteredFlagsExpectation,\n  type RegisteredHookExpectation,\n  type RegisteredHookKind,\n  type RegisteredImporterExpectation,\n  type RegisteredItemFieldAssertion,\n  type RegisteredItemFieldExpectation,\n  type RegisteredItemTypeAssertion,\n  type RegisteredItemTypeExpectation,\n  type RegisteredMigrationExpectation,\n  type RegisteredParserOverrideExpectation,\n  type RegisteredPreflightOverrideExpectation,\n  type RegisteredRendererOverrideExpectation,\n  type RegisteredSearchProviderExpectation,\n  type RegisteredServiceOverrideExpectation,\n  type RegisteredVectorStoreAdapterExpectation,\n} from \"./testing.js\";\n\n/**\n * Canonical extension capability names accepted by pm.\n *\n * Extension manifests should declare one or more of these values in\n * `capabilities`.\n */\nexport const EXTENSION_CAPABILITIES = KNOWN_EXTENSION_CAPABILITIES;\n/**\n * Restricts extension capability values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionCapability = (typeof EXTENSION_CAPABILITIES)[number];\n\n/**\n * Canonical extension governance policy modes and registration surfaces.\n */\nexport const EXTENSION_POLICY_MODES = KNOWN_EXTENSION_POLICY_MODES;\nexport const EXTENSION_POLICY_SURFACES = KNOWN_EXTENSION_POLICY_SURFACES;\nexport const EXTENSION_TRUST_MODES = KNOWN_EXTENSION_TRUST_MODES;\nexport const EXTENSION_SANDBOX_PROFILES = KNOWN_EXTENSION_SANDBOX_PROFILES;\n/**\n * Restricts extension policy mode values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionPolicyMode = (typeof EXTENSION_POLICY_MODES)[number];\n/**\n * Restricts extension policy surface values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionPolicySurface = (typeof EXTENSION_POLICY_SURFACES)[number];\n/**\n * Restricts extension trust mode values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionTrustMode = (typeof EXTENSION_TRUST_MODES)[number];\n/**\n * Restricts extension sandbox profile values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionSandboxProfile = (typeof EXTENSION_SANDBOX_PROFILES)[number];\n\n/**\n * Versioned capability contract metadata emitted by runtime diagnostics.\n */\nexport { EXTENSION_CAPABILITY_CONTRACT, EXTENSION_CAPABILITY_CONTRACT_VERSION, EXTENSION_CAPABILITY_LEGACY_ALIASES };\n\n/**\n * Least-privilege capability reconciliation helpers: map declared capabilities\n * against the registration surfaces a package actually exercises at activation.\n */\nexport {\n  EXTENSION_CAPABILITY_REGISTRATION_SURFACES,\n  collectUsedExtensionCapabilities,\n  reconcileExtensionCapabilityUsage,\n  type CollectUsedExtensionCapabilitiesOptions,\n  type ExtensionCapabilityUsageReconciliation,\n} from \"../core/extensions/capability-usage.js\";\n\nexport type {\n  AfterCommandAffectedItem,\n  AfterCommandHook,\n  AfterCommandHookContext,\n  BeforeCommandHook,\n  BeforeCommandHookContext,\n  CommandDefinition,\n  ExtensionCommandArgumentDefinition,\n  CommandHandler,\n  CommandHandlerContext,\n  CommandHandlerResult,\n  CommandOverride,\n  CommandOverrideContext,\n  ExtensionServiceName,\n  Exporter,\n  ExtensionActivationResult,\n  ExtensionApi,\n  ExtensionCommandRegistry,\n  ExtensionDeactivationFailure,\n  ExtensionDeactivationOptions,\n  ExtensionDeactivationResult,\n  ExtensionDiagnostic,\n  ExtensionDiscoveryResult,\n  ExtensionHookRegistry,\n  ExtensionSelfIdentity,\n  ExtensionLoadResult,\n  ExtensionManifest,\n  ExtensionManifestEngines,\n  ExtensionGovernancePolicy,\n  ExtensionPolicyOverride,\n  ExtensionProvenanceMetadata,\n  ExtensionRuntimePermissionDeclaration,\n  ExtensionSearchMode,\n  ExtensionParserRegistry,\n  ExtensionPreflightRegistry,\n  ExtensionRegistrationRegistry,\n  ExtensionRendererRegistry,\n  ExtensionServiceRegistry,\n  FlagValueType,\n  FlagDefinition,\n  ImportExportContext,\n  ImportExportRegistrationOptions,\n  Importer,\n  OnIndexHook,\n  OnIndexHookContext,\n  OnReadHook,\n  OnReadHookContext,\n  OnWriteHook,\n  OnWriteHookContext,\n  OutputRendererFormat,\n  ParserOverride,\n  ParserOverrideContext,\n  ParserOverrideDelta,\n  PreflightOverride,\n  PreflightOverrideContext,\n  PreflightOverrideDelta,\n  PreflightRuntimeDecision,\n  RegisteredExtensionExporter,\n  RegisteredExtensionFlagDefinitions,\n  RegisteredExtensionHook,\n  RegisteredExtensionImporter,\n  RegisteredExtensionSchemaMigrationDefinition,\n  RegisteredExtensionSearchProvider,\n  RegisteredExtensionServiceOverride,\n  RegisteredExtensionVectorStoreAdapter,\n  RendererOverride,\n  RendererOverrideContext,\n  SchemaFieldDefinition,\n  SchemaItemTypeCommandOptionPolicyDefinition,\n  SchemaItemTypeOptionDefinition,\n  SchemaItemTypeDefinition,\n  SchemaMigrationDefinition,\n  SchemaMigrationRunContext,\n  SchemaMigrationRunner,\n  SearchProviderEmbedBatchContext,\n  SearchProviderEmbedContext,\n  SearchProviderDefinition,\n  SearchProviderHit,\n  SearchProviderQueryContext,\n  SearchProviderQueryResult,\n  ServiceOverride,\n  ServiceOverrideContext,\n  VectorStoreAdapterDefinition,\n  VectorStoreDeleteContext,\n  VectorStoreQueryContext,\n  VectorStoreQueryHit,\n  VectorStoreUpsertContext,\n  VectorStoreUpsertPoint,\n} from \"../core/extensions/loader.js\";\n\nexport type { GlobalOptions } from \"../core/shared/command-types.js\";\nexport type { ItemDocument, ItemFrontMatter, ItemStatus, ItemType, PmSettings } from \"../types/index.js\";\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,OAAO,EACL,6BAA6B,EAC7B,qCAAqC,EACrC,mCAAmC,EACnC,4BAA4B,EAC5B,4BAA4B,EAC5B,+BAA+B,EAC/B,gCAAgC,EAChC,2BAA2B,GAC5B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACL,sCAAsC,EACtC,yBAAyB,EACzB,kCAAkC,EAClC,qBAAqB,GAOtB,MAAM,8BAA8B,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,OAAO,EACL,wBAAwB,EACxB,8BAA8B,EAC9B,0BAA0B,EAC1B,iCAAiC,EACjC,uCAAuC,EACvC,wBAAwB,EACxB,qBAAqB,EACrB,+BAA+B,EAC/B,+BAA+B,EAC/B,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,8BAA8B,EAC9B,iCAAiC,EACjC,gCAAgC,EAChC,8BAA8B,EAC9B,+BAA+B,EAC/B,kCAAkC,EAClC,wBAAwB,EACxB,0BAA0B,EAC1B,0BAA0B,EAC1B,2BAA2B,EAC3B,2BAA2B,EAC3B,mCAAmC,EACnC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,EAC5B,6BAA6B,EAC7B,kCAAkC,EAClC,qCAAqC,EACrC,oCAAoC,EACpC,kCAAkC,EAClC,mCAAmC,EACnC,sCAAsC,GA0CvC,MAAM,cAAc,CAAC;AAEtB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AAMnE;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AACnE,MAAM,CAAC,MAAM,yBAAyB,GAAG,+BAA+B,CAAC;AACzE,MAAM,CAAC,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AACjE,MAAM,CAAC,MAAM,0BAA0B,GAAG,gCAAgC,CAAC;AAkB3E;;GAEG;AACH,OAAO,EAAE,6BAA6B,EAAE,qCAAqC,EAAE,mCAAmC,EAAE,CAAC;AAErH;;;GAGG;AACH,OAAO,EACL,0CAA0C,EAC1C,gCAAgC,EAChC,iCAAiC,GAGlC,MAAM,wCAAwC,CAAC","debugId":"a6b61a03-0082-5871-88e3-b0b1dbad480b"}

package/dist/sdk/testing.d.ts

@@ -3,9 +3,14 @@
  *
  * Defines public SDK APIs and package-author helpers for Testing.
  */
-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 { AfterCommandHookContext, BeforeCommandHookContext, CommandHandlerResult, CommandOverrideContext, CommandOverrideResult, ExtensionActivationResult, ExtensionCapability, ExtensionCommandRegistry, ExtensionDeactivationResult, ExtensionGovernancePolicy, ExtensionHookRegistry, ExtensionLayer, ExtensionManifest, 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, ExtensionManifestCompatibilityManifest, ExtensionManifestCompatibilityResult, ExtensionManifestCompatibilityTarget, ExtensionPreflightReport, LintExtensionBlueprintOptions, PreflightExtensionOptions } 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.
  */
@@ -803,4 +808,218 @@ export declare function assertRegisteredMigration(registrations: ExtensionRegist
  * declared/used/unused breakdown for further assertions.
  */
 export declare function assertExtensionCapabilityUsage(activation: ExtensionActivationResult, expectation: ExtensionCapabilityUsageExpectation): ExtensionCapabilityUsageAssertion;
-export {};
+/**
+ * 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;
+/**
+ * The structured result of {@link assertExtensionManifestMatchesBlueprint}: the
+ * reconciliation between a manifest's declared capabilities and the set the
+ * blueprint actually exercises. Returned only when they match exactly (the
+ * assertion throws otherwise).
+ */
+export interface ExtensionManifestBlueprintMatch {
+    /** The least-privilege capability set the blueprint exercises (from `deriveExtensionCapabilities`). */
+    used: ExtensionCapability[];
+    /** The manifest's declared capabilities, legacy-alias resolved and normalized. */
+    declared: ExtensionCapability[];
+    /** Capabilities the blueprint uses but the manifest omits — would crash activation. Empty on success. */
+    missing: ExtensionCapability[];
+    /** Capabilities the manifest declares but no surface exercises — violates least privilege. Empty on success. */
+    unused: ExtensionCapability[];
+    /** Every lint finding for the blueprint, so callers can inspect advisory warnings. */
+    findings: ExtensionBlueprintLintFinding[];
+}
+/**
+ * Strictly assert a manifest's `capabilities` equal the least-privilege set a
+ * declarative {@link ExtensionBlueprint} exercises, throwing on any drift in
+ * either direction.
+ *
+ * This is the strict bookend to the lenient {@link assertExtensionBlueprint}:
+ * where that helper fails only on an *undeclared* capability (the `error`-severity
+ * `extension_capability_missing` activation crash) and merely *warns* on an unused
+ * one, this assertion fails on **both** — an undeclared capability (`missing`) and
+ * a declared-but-unused one (`unused`) — so a hand-maintained `manifest.json` stays
+ * exactly the set the blueprint requires. Drop it into a package's
+ * `node:test`/Vitest suite to guard against capability drift in CI, the natural
+ * companion to {@link ../sdk/compose.js#synthesizeExtensionManifest} (assert what
+ * you would otherwise generate). Only `capabilities` are reconciled because that is
+ * the one manifest field a blueprint determines.
+ *
+ * The reconciliation is returned on success so a test can still inspect advisory
+ * warnings (duplicate command, empty surface) without failing on them.
+ */
+export declare function assertExtensionManifestMatchesBlueprint(manifest: Pick<ExtensionManifest, "capabilities">, blueprint: ExtensionBlueprint): ExtensionManifestBlueprintMatch;
+/**
+ * Assert an extension manifest's declared version bounds permit it to load on a
+ * target pm CLI version, throwing when a bound blocks the load.
+ *
+ * This is the throwing CI/test counterpart to
+ * {@link ../sdk/compose.js#checkExtensionManifestCompatibility}: it runs the same
+ * author-time version-bound analysis and fails on any blocking incompatibility — a
+ * malformed bound (`*_invalid`), a `pm_min_version` the target is below
+ * (`pm_min_version_unmet`), or a `block`-mode `pm_max_version` the target exceeds
+ * (`pm_max_version_exceeded`). Advisory `warning` findings (`*_unchecked`, or a
+ * `warn`-mode `pm_max_version_exceeded_warn`) never throw, because the loader
+ * would still load the extension. Pin it to the pm version a package commits to
+ * supporting so a too-tight or malformed bound fails the package's own suite, not
+ * a user's install. The full compatibility result is returned on success so a test
+ * can still inspect advisory warnings.
+ */
+export declare function assertExtensionManifestCompatible(manifest: ExtensionManifestCompatibilityManifest, target: ExtensionManifestCompatibilityTarget): ExtensionManifestCompatibilityResult;
+/**
+ * Preflight a declarative {@link ExtensionBlueprint} through every author-time
+ * check in one test, throwing if any stage produced an `error`-severity finding.
+ *
+ * This is the throwing CI/test bookend over
+ * {@link ../sdk/compose.js#preflightExtension} — the single guard that replaces
+ * chaining {@link assertExtensionBlueprint}, {@link assertExtensionManifestMatchesBlueprint},
+ * and {@link assertExtensionManifestCompatible} in a package's
+ * `node:test`/Vitest suite. It runs the same consolidated analysis (always lints
+ * the blueprint; synthesizes the manifest when `options.identity` is given; checks
+ * version bounds when `options.target` is given) and throws one error listing every
+ * blocking finding tagged by its `source:code`. Advisory `warning` findings (an
+ * unused capability, a duplicate command, an `*_unchecked` bound) never throw,
+ * matching the underlying stages. The full {@link ExtensionPreflightReport} is
+ * returned on success so a test can still inspect those warnings, the synthesized
+ * manifest, and the derived capability set without failing on them.
+ */
+export declare function assertExtensionPreflight(blueprint: ExtensionBlueprint, options?: PreflightExtensionOptions): ExtensionPreflightReport;
+/**
+ * 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>;