@unbrained/pm-cli 2026.7.2 → 2026.7.4

package/dist/core/extensions/extension-types.d.ts

@@ -376,8 +376,7 @@ export interface CommandHandlerContext {
 /**
  * Documents the parser override context payload exchanged by command, SDK, and package integrations.
  */
-export interface ParserOverrideContext extends CommandHandlerContext {
-}
+export type ParserOverrideContext = CommandHandlerContext;
 /**
  * Documents the parser override delta payload exchanged by command, SDK, and package integrations.
  */

package/dist/core/extensions/extension-types.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="add4a412-10a4-5c04-b3a2-998cc74fdd38")}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]="75a0fe7b-f263-5311-acda-2a527cb2d17d")}catch(e){}}();
 export const KNOWN_EXTENSION_CAPABILITIES = [
     "commands",
     "renderers",
@@ -83,4 +83,4 @@ export function createDefaultExtensionGovernancePolicy() {
     };
 }
 //# sourceMappingURL=extension-types.js.map
-//# debugId=add4a412-10a4-5c04-b3a2-998cc74fdd38
+//# debugId=75a0fe7b-f263-5311-acda-2a527cb2d17d

package/dist/core/extensions/extension-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"extension-types.js","sources":["core/extensions/extension-types.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/extension-types\n *\n * Implements extension runtime contracts and governance for Extension Types.\n */\nimport type {\n  ExtensionPolicyOverrideSettings,\n  ExtensionPolicySettings,\n  ItemDocument,\n  ItemFrontMatter,\n  ItemStatus,\n  PmSettings,\n} from \"../../types/index.js\";\nimport type { GlobalOptions } from \"../shared/command-types.js\";\nimport type { ProjectProfileDefinition, ProjectProfileRegistrationInput } from \"../profile/profile-presets.js\";\n\nexport const KNOWN_EXTENSION_CAPABILITIES = [\n  \"commands\",\n  \"renderers\",\n  \"hooks\",\n  \"schema\",\n  \"importers\",\n  \"search\",\n  \"parser\",\n  \"preflight\",\n  \"services\",\n] as const;\n/**\n * Restricts extension capability values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionCapability = (typeof KNOWN_EXTENSION_CAPABILITIES)[number];\nexport const EXTENSION_CAPABILITY_CONTRACT_VERSION = 2;\nexport const EXTENSION_CAPABILITY_LEGACY_ALIASES: Readonly<Record<string, ExtensionCapability>> = Object.freeze({\n  migration: \"schema\",\n  validation: \"schema\",\n});\nexport const EXTENSION_CAPABILITY_CONTRACT = Object.freeze({\n  version: EXTENSION_CAPABILITY_CONTRACT_VERSION,\n  capabilities: [...KNOWN_EXTENSION_CAPABILITIES],\n  legacy_aliases: { ...EXTENSION_CAPABILITY_LEGACY_ALIASES },\n});\n\nexport const KNOWN_EXTENSION_POLICY_MODES = [\"off\", \"warn\", \"enforce\"] as const;\n/**\n * Restricts extension policy mode values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionPolicyMode = (typeof KNOWN_EXTENSION_POLICY_MODES)[number];\nexport const KNOWN_EXTENSION_TRUST_MODES = [\"off\", \"warn\", \"enforce\"] as const;\n/**\n * Restricts extension trust mode values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionTrustMode = (typeof KNOWN_EXTENSION_TRUST_MODES)[number];\nexport const KNOWN_EXTENSION_SANDBOX_PROFILES = [\"none\", \"restricted\", \"strict\"] as const;\n/**\n * Restricts extension sandbox profile values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionSandboxProfile = (typeof KNOWN_EXTENSION_SANDBOX_PROFILES)[number];\n\nexport const KNOWN_PM_MAX_VERSION_EXCEEDED_MODES = [\"block\", \"warn\"] as const;\n/** How a `pm_max_version` violation is handled for an extension layer. */\nexport type PmMaxVersionExceededMode = (typeof KNOWN_PM_MAX_VERSION_EXCEEDED_MODES)[number];\n/** Optional per-layer override map for `extensions.policy.pm_max_version_exceeded_mode`. */\nexport interface PmMaxVersionExceededModeByLayer {\n  global?: PmMaxVersionExceededMode;\n  project?: PmMaxVersionExceededMode;\n}\n/**\n * Settings value for `extensions.policy.pm_max_version_exceeded_mode`: either a\n * single mode applied to both layers, or a per-layer override map. Unset (and\n * any unset layer key) defaults to `\"block\"`.\n */\nexport type PmMaxVersionExceededModeSetting = PmMaxVersionExceededMode | PmMaxVersionExceededModeByLayer;\n\nexport const KNOWN_EXTENSION_POLICY_SURFACES = [\n  \"commands.override\",\n  \"commands.handler\",\n  \"hooks.beforecommand\",\n  \"hooks.aftercommand\",\n  \"hooks.onwrite\",\n  \"hooks.onread\",\n  \"hooks.onindex\",\n  \"schema.flags\",\n  \"schema.itemfields\",\n  \"schema.itemtypes\",\n  \"schema.migrations\",\n  \"schema.profiles\",\n  \"parser.override\",\n  \"preflight.override\",\n  \"services.override\",\n  \"renderers.override\",\n  \"importers.importer\",\n  \"importers.exporter\",\n  \"search.provider\",\n  \"search.vectorstore\",\n] as const;\n/**\n * Restricts extension policy surface values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionPolicySurface = (typeof KNOWN_EXTENSION_POLICY_SURFACES)[number];\n\nexport const KNOWN_EXTENSION_SERVICE_NAMES = [\n  \"output_format\",\n  \"error_format\",\n  \"help_format\",\n  \"lock_acquire\",\n  \"lock_release\",\n  \"history_append\",\n  \"item_store_write\",\n  \"item_store_delete\",\n] as const;\n/**\n * Restricts extension service name values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionServiceName = (typeof KNOWN_EXTENSION_SERVICE_NAMES)[number];\n\n/**\n * Documents the extension provenance metadata payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionProvenanceMetadata {\n  source?: string;\n  signature?: string;\n  attestation?: string;\n  verified?: boolean;\n}\n\n/**\n * Documents the extension runtime permission declaration payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionRuntimePermissionDeclaration {\n  fs_read?: boolean;\n  fs_write?: boolean;\n  network?: boolean;\n  env_read?: boolean;\n  env_write?: boolean;\n  process_spawn?: boolean;\n}\n\n/**\n * Documents the extension activation metadata payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionActivationMetadata {\n  commands?: string[];\n}\n\n/**\n * Restricts extension policy override values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionPolicyOverride = ExtensionPolicyOverrideSettings;\n/**\n * Extension governance policy as read from / serialized to settings. Extends the\n * stored settings shape with `pm_max_version_exceeded_mode` (pm-k5e8), which\n * relaxes the default-BLOCK on `pm_max_version` violations to warn-only —\n * globally or per extension layer.\n */\nexport type ExtensionGovernancePolicy = ExtensionPolicySettings & {\n  pm_max_version_exceeded_mode?: PmMaxVersionExceededModeSetting;\n};\n\n/**\n * Documents the extension manifest engines payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionManifestEngines {\n  pm?: string;\n  node?: string;\n  [engine: string]: string | undefined;\n}\n\n/**\n * Implements create default extension governance policy for the public runtime surface of this module.\n */\nexport function createDefaultExtensionGovernancePolicy(): ExtensionGovernancePolicy {\n  return {\n    mode: \"off\",\n    trust_mode: \"off\",\n    require_provenance: false,\n    trusted_extensions: [],\n    default_sandbox_profile: \"none\",\n    allowed_extensions: [],\n    blocked_extensions: [],\n    allowed_capabilities: [],\n    blocked_capabilities: [],\n    allowed_surfaces: [],\n    blocked_surfaces: [],\n    allowed_commands: [],\n    blocked_commands: [],\n    allowed_actions: [],\n    blocked_actions: [],\n    allowed_services: [],\n    blocked_services: [],\n    extension_overrides: [],\n  };\n}\n\n/**\n * Restricts extension layer values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionLayer = \"global\" | \"project\";\n/**\n * Restricts extension status values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionStatus = \"ok\" | \"warn\";\n\n/**\n * Documents the extension manifest payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionManifest {\n  name: string;\n  version: string;\n  entry: string;\n  priority: number;\n  capabilities: string[];\n  manifest_version?: number;\n  pm_min_version?: string;\n  pm_max_version?: string;\n  engines?: ExtensionManifestEngines;\n  trusted?: boolean;\n  provenance?: ExtensionProvenanceMetadata;\n  sandbox_profile?: ExtensionSandboxProfile;\n  permissions?: ExtensionRuntimePermissionDeclaration;\n  activation?: ExtensionActivationMetadata;\n  legacy_capability_aliases?: LegacyExtensionCapabilityAliasMapping[];\n}\n\n/**\n * Documents the extension diagnostic payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionDiagnostic {\n  layer: ExtensionLayer;\n  directory: string;\n  manifest_path: string;\n  name: string | null;\n  version: string | null;\n  entry: string | null;\n  priority: number | null;\n  entry_path: string | null;\n  enabled: boolean | null;\n  status: ExtensionStatus;\n}\n\n/**\n * Documents the effective extension payload exchanged by command, SDK, and package integrations.\n */\nexport interface EffectiveExtension {\n  layer: ExtensionLayer;\n  directory: string;\n  manifest_path: string;\n  name: string;\n  source_package?: string;\n  version: string;\n  entry: string;\n  priority: number;\n  entry_path: string;\n  manifest_version?: number;\n  pm_min_version?: string;\n  pm_max_version?: string;\n  engines?: ExtensionManifestEngines;\n  trusted?: boolean;\n  provenance?: ExtensionProvenanceMetadata;\n  sandbox_profile?: ExtensionSandboxProfile;\n  permissions?: ExtensionRuntimePermissionDeclaration;\n  capabilities?: string[];\n  activation?: ExtensionActivationMetadata;\n}\n\n/**\n * Documents the extension discovery result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionDiscoveryResult {\n  disabled_by_flag: boolean;\n  roots: {\n    global: string;\n    project: string;\n  };\n  configured_enabled: string[];\n  configured_disabled: string[];\n  discovered: ExtensionDiagnostic[];\n  effective: EffectiveExtension[];\n  warnings: string[];\n  policy: ExtensionGovernancePolicy;\n}\n\n/**\n * Documents the loaded extension payload exchanged by command, SDK, and package integrations.\n */\nexport interface LoadedExtension extends EffectiveExtension {\n  module: unknown;\n}\n\n/**\n * Documents the failed extension load payload exchanged by command, SDK, and package integrations.\n */\nexport interface FailedExtensionLoad {\n  layer: ExtensionLayer;\n  name: string;\n  entry_path: string;\n  error: string;\n}\n\n/**\n * Documents the extension load result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionLoadResult extends ExtensionDiscoveryResult {\n  loaded: LoadedExtension[];\n  failed: FailedExtensionLoad[];\n}\n\n/**\n * Documents the before command hook context payload exchanged by command, SDK, and package integrations.\n */\nexport interface BeforeCommandHookContext {\n  command: string;\n  args: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n  pm_root: string;\n}\n\n/**\n * Documents the after command hook context payload exchanged by command, SDK, and package integrations.\n */\nexport interface AfterCommandHookContext extends BeforeCommandHookContext {\n  ok: boolean;\n  error?: string;\n  result?: unknown;\n  affected?: AfterCommandAffectedItem[];\n}\n\n/**\n * Documents the after command affected item payload exchanged by command, SDK, and package integrations.\n */\nexport interface AfterCommandAffectedItem {\n  id: string;\n  op?: string;\n  item_type?: string;\n  previous_status?: ItemStatus;\n  status?: ItemStatus;\n  previous?: Partial<ItemFrontMatter>;\n  current?: Partial<ItemFrontMatter>;\n  changed_fields?: string[];\n}\n\n/**\n * Documents the on write hook context payload exchanged by command, SDK, and package integrations.\n */\nexport interface OnWriteHookContext {\n  path: string;\n  scope: \"project\" | \"global\";\n  op: string;\n  item_id?: string;\n  item_type?: string;\n  before?: ItemDocument;\n  after?: ItemDocument;\n  changed_fields?: string[];\n}\n\n/**\n * Documents the on read hook context payload exchanged by command, SDK, and package integrations.\n */\nexport interface OnReadHookContext {\n  path: string;\n  scope: \"project\" | \"global\";\n}\n\n/**\n * Documents the on index hook context payload exchanged by command, SDK, and package integrations.\n */\nexport interface OnIndexHookContext {\n  mode: string;\n  total_items?: number;\n}\n\n/**\n * Restricts before command hook values accepted by command, SDK, and storage contracts.\n */\nexport type BeforeCommandHook = (context: BeforeCommandHookContext) => Promise<void> | void;\n/**\n * Restricts after command hook values accepted by command, SDK, and storage contracts.\n */\nexport type AfterCommandHook = (context: AfterCommandHookContext) => Promise<void> | void;\n/**\n * Restricts on write hook values accepted by command, SDK, and storage contracts.\n */\nexport type OnWriteHook = (context: OnWriteHookContext) => Promise<void> | void;\n/**\n * Restricts on read hook values accepted by command, SDK, and storage contracts.\n */\nexport type OnReadHook = (context: OnReadHookContext) => Promise<void> | void;\n/**\n * Restricts on index hook values accepted by command, SDK, and storage contracts.\n */\nexport type OnIndexHook = (context: OnIndexHookContext) => Promise<void> | void;\n/**\n * Restricts output renderer format values accepted by command, SDK, and storage contracts.\n */\nexport type OutputRendererFormat = \"toon\" | \"json\";\n/**\n * Restricts command override values accepted by command, SDK, and storage contracts.\n */\nexport type CommandOverride = (context: CommandOverrideContext) => unknown;\n/**\n * Restricts renderer override values accepted by command, SDK, and storage contracts.\n */\nexport type RendererOverride = (context: RendererOverrideContext) => string | null | undefined;\n/**\n * Restricts command handler values accepted by command, SDK, and storage contracts.\n */\nexport type CommandHandler = (context: CommandHandlerContext) => unknown;\n/**\n * Restricts parser override values accepted by command, SDK, and storage contracts.\n */\nexport type ParserOverride = (context: ParserOverrideContext) => ParserOverrideDelta | Promise<ParserOverrideDelta>;\n/**\n * Restricts preflight override values accepted by command, SDK, and storage contracts.\n */\nexport type PreflightOverride = (context: PreflightOverrideContext) => PreflightOverrideDelta | Promise<PreflightOverrideDelta>;\n/**\n * Restricts service override values accepted by command, SDK, and storage contracts.\n */\nexport type ServiceOverride = (context: ServiceOverrideContext) => unknown;\n\n/**\n * Documents the registered extension hook payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionHook<THook> {\n  layer: ExtensionLayer;\n  name: string;\n  run: THook;\n}\n\n/**\n * Documents the extension hook registry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionHookRegistry {\n  beforeCommand: Array<RegisteredExtensionHook<BeforeCommandHook>>;\n  afterCommand: Array<RegisteredExtensionHook<AfterCommandHook>>;\n  onWrite: Array<RegisteredExtensionHook<OnWriteHook>>;\n  onRead: Array<RegisteredExtensionHook<OnReadHook>>;\n  onIndex: Array<RegisteredExtensionHook<OnIndexHook>>;\n}\n\n/**\n * Documents the command override context payload exchanged by command, SDK, and package integrations.\n */\nexport interface CommandOverrideContext {\n  command: string;\n  args: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n  pm_root: string;\n  result: unknown;\n}\n\n/**\n * Documents the renderer override context payload exchanged by command, SDK, and package integrations.\n */\nexport interface RendererOverrideContext {\n  format: OutputRendererFormat;\n  command?: string;\n  args?: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n  pm_root?: string;\n  result: unknown;\n}\n\n/**\n * Documents the command handler context payload exchanged by command, SDK, and package integrations.\n */\nexport interface CommandHandlerContext {\n  command: string;\n  args: string[];\n  options: Record<string, unknown>;\n  global: GlobalOptions;\n  pm_root: string;\n}\n\n/**\n * Documents the parser override context payload exchanged by command, SDK, and package integrations.\n */\nexport interface ParserOverrideContext extends CommandHandlerContext {}\n\n/**\n * Documents the parser override delta payload exchanged by command, SDK, and package integrations.\n */\nexport interface ParserOverrideDelta {\n  args?: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n}\n\n/**\n * Documents the preflight override context payload exchanged by command, SDK, and package integrations.\n */\nexport interface PreflightOverrideContext extends CommandHandlerContext {\n  decision: PreflightRuntimeDecision;\n}\n\n/**\n * Documents the preflight runtime decision payload exchanged by command, SDK, and package integrations.\n */\nexport interface PreflightRuntimeDecision {\n  enforce_item_format_gate: boolean;\n  run_preflight_item_format_sync: boolean;\n  run_extension_migrations: boolean;\n  enforce_mandatory_migration_gate: boolean;\n}\n\n/**\n * Documents the preflight override delta payload exchanged by command, SDK, and package integrations.\n */\nexport interface PreflightOverrideDelta extends ParserOverrideDelta {\n  enforce_item_format_gate?: boolean;\n  run_preflight_item_format_sync?: boolean;\n  run_extension_migrations?: boolean;\n  enforce_mandatory_migration_gate?: boolean;\n}\n\n/**\n * Documents the service override context payload exchanged by command, SDK, and package integrations.\n */\nexport interface ServiceOverrideContext {\n  service: ExtensionServiceName;\n  command?: string;\n  args?: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n  pm_root?: string;\n  payload: unknown;\n}\n\n/**\n * Documents the extension command argument definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionCommandArgumentDefinition {\n  name: string;\n  required?: boolean;\n  variadic?: boolean;\n  description?: string;\n}\n\n/**\n * Documents the command definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface CommandDefinition {\n  name: string;\n  run?: CommandHandler;\n  /**\n   * @deprecated Use `run` instead. This alias remains for backward compatibility.\n   */\n  handler?: CommandHandler;\n  action?: string;\n  description?: string;\n  intent?: string;\n  examples?: string[];\n  failure_hints?: string[];\n  arguments?: ExtensionCommandArgumentDefinition[];\n  flags?: FlagDefinition[];\n}\n\n/**\n * Optional command-definition metadata for first-class importer/exporter\n * registration.\n *\n * `registerImporter`/`registerExporter` always create a `<name> import` /\n * `<name> export` command path. By default that path only has a handler. When\n * these options are supplied, the auto-created command also gains a full command\n * definition (description, flags, intent, examples, failure hints, positional\n * arguments) — surfaced in help and runtime contracts exactly like\n * `registerCommand`. The registration `name` and `run` handler are implicit, so\n * they are not part of this options object.\n */\nexport interface ImportExportRegistrationOptions {\n  action?: string;\n  description?: string;\n  intent?: string;\n  examples?: string[];\n  failure_hints?: string[];\n  arguments?: ExtensionCommandArgumentDefinition[];\n  flags?: FlagDefinition[];\n}\n\n/**\n * Restricts flag value type values accepted by command, SDK, and storage contracts.\n */\nexport type FlagValueType = \"string\" | \"number\" | \"boolean\";\n\n/**\n * Documents the flag definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface FlagDefinition {\n  long?: string;\n  short?: string;\n  value_name?: string;\n  description?: string;\n  required?: boolean;\n  enabled?: boolean;\n  visible?: boolean;\n  /**\n   * Canonical flag value type. Prefer this field; it is the one runtime\n   * contracts and help output read first.\n   */\n  value_type?: FlagValueType;\n  /**\n   * @deprecated Use `value_type`. Retained for backward compatibility: when\n   * both are present `value_type` wins, and `type` resolves only when\n   * `value_type` is absent (`value_type ?? type`).\n   */\n  type?: FlagValueType;\n  /**\n   * When true, a repeated comma-list flag accumulates values across repeats\n   * — parity with core list flags such as `--tags` — instead of the last\n   * value winning. Mirrors the core `CliFlagContract.list` field so\n   * extension-registered list flags coalesce through the same bootstrap path.\n   */\n  list?: boolean;\n  /**\n   * Default value applied when the flag is omitted. Surfaced to runtime\n   * contracts and help output. A `list` flag may default to an array of scalars\n   * (e.g. `[\"a\", \"b\"]`); the array is flattened/coerced like any list value.\n   */\n  default?: string | number | boolean | Array<string | number | boolean>;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the schema field definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface SchemaFieldDefinition {\n  name: string;\n  type: string;\n  optional?: boolean;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the schema item type command option policy definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface SchemaItemTypeCommandOptionPolicyDefinition {\n  command: string;\n  option: string;\n  enabled?: boolean;\n  required?: boolean;\n  visible?: boolean;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the schema item type option definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface SchemaItemTypeOptionDefinition {\n  key: string;\n  values?: string[];\n  required?: boolean;\n  aliases?: string[];\n  [key: string]: unknown;\n}\n\n/**\n * Documents the schema item type definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface SchemaItemTypeDefinition {\n  name: string;\n  folder?: string;\n  aliases?: string[];\n  required_create_fields?: string[];\n  required_create_repeatables?: string[];\n  command_option_policies?: SchemaItemTypeCommandOptionPolicyDefinition[];\n  options?: SchemaItemTypeOptionDefinition[];\n  [key: string]: unknown;\n}\n\n/**\n * Documents the schema migration run context payload exchanged by command, SDK, and package integrations.\n */\nexport interface SchemaMigrationRunContext {\n  id: string;\n  command: \"migration\";\n  layer: ExtensionLayer;\n  extension: string;\n  pm_root: string;\n  status: string;\n}\n\n/**\n * Restricts schema migration runner values accepted by command, SDK, and storage contracts.\n */\nexport type SchemaMigrationRunner = (context: SchemaMigrationRunContext) => unknown | Promise<unknown>;\n\n/**\n * Documents the schema migration definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface SchemaMigrationDefinition {\n  id?: string;\n  description?: string;\n  status?: string;\n  mandatory?: boolean;\n  run?: SchemaMigrationRunner;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the import export context payload exchanged by command, SDK, and package integrations.\n */\nexport interface ImportExportContext {\n  registration: string;\n  action: \"import\" | \"export\";\n  command: string;\n  args: string[];\n  options: Record<string, unknown>;\n  global: GlobalOptions;\n  pm_root: string;\n}\n\n/**\n * Restricts importer values accepted by command, SDK, and storage contracts.\n */\nexport type Importer = (context: ImportExportContext) => unknown | Promise<unknown>;\n/**\n * Restricts exporter values accepted by command, SDK, and storage contracts.\n */\nexport type Exporter = (context: ImportExportContext) => unknown | Promise<unknown>;\n\n/**\n * Restricts extension search mode values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionSearchMode = \"keyword\" | \"semantic\" | \"hybrid\";\n\n/**\n * Documents the search provider query context payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderQueryContext {\n  query: string;\n  mode: ExtensionSearchMode;\n  tokens: string[];\n  options: Record<string, unknown>;\n  settings: PmSettings;\n  documents: ItemDocument[];\n  [key: string]: unknown;\n}\n\n/**\n * Documents the search provider hit payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderHit {\n  id: string;\n  score: number;\n  matched_fields?: string[];\n  [key: string]: unknown;\n}\n\n/**\n * Restricts search provider query result values accepted by command, SDK, and storage contracts.\n */\nexport type SearchProviderQueryResult = SearchProviderHit[] | { hits?: SearchProviderHit[] };\n\n/**\n * Documents the search provider query expansion context payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderQueryExpansionContext {\n  query: string;\n  mode: Exclude<ExtensionSearchMode, \"keyword\">;\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/**\n * Restricts search provider query expansion result values accepted by command, SDK, and storage contracts.\n */\nexport type SearchProviderQueryExpansionResult = string[] | { queries?: string[] };\n\n/**\n * Documents the search provider rerank candidate payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderRerankCandidate {\n  id: string;\n  text: string;\n  score: number;\n}\n\n/**\n * Documents the search provider rerank hit payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderRerankHit {\n  id: string;\n  score: number;\n}\n\n/**\n * Restricts search provider rerank result values accepted by command, SDK, and storage contracts.\n */\nexport type SearchProviderRerankResult = SearchProviderRerankHit[] | { hits?: SearchProviderRerankHit[] };\n\n/**\n * Documents the search provider rerank context payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderRerankContext {\n  query: string;\n  mode: \"hybrid\";\n  model: string;\n  top_k: number;\n  settings: PmSettings;\n  candidates: SearchProviderRerankCandidate[];\n  [key: string]: unknown;\n}\n\n/**\n * Documents the search provider embed batch context payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderEmbedBatchContext {\n  inputs: string[];\n  settings: PmSettings;\n  model: string;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the search provider embed context payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderEmbedContext {\n  input: string;\n  settings: PmSettings;\n  model: string;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the search provider definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderDefinition {\n  name: string;\n  query?: (context: SearchProviderQueryContext) => SearchProviderQueryResult | Promise<SearchProviderQueryResult>;\n  queryExpansion?: (\n    context: SearchProviderQueryExpansionContext,\n  ) => SearchProviderQueryExpansionResult | Promise<SearchProviderQueryExpansionResult>;\n  query_expansion?: (\n    context: SearchProviderQueryExpansionContext,\n  ) => SearchProviderQueryExpansionResult | Promise<SearchProviderQueryExpansionResult>;\n  rerank?: (context: SearchProviderRerankContext) => SearchProviderRerankResult | Promise<SearchProviderRerankResult>;\n  embedBatch?: (context: SearchProviderEmbedBatchContext) => number[][] | Promise<number[][]>;\n  embed_batch?: (context: SearchProviderEmbedBatchContext) => number[][] | Promise<number[][]>;\n  embed?: (context: SearchProviderEmbedContext) => number[] | Promise<number[]>;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the vector store query hit payload exchanged by command, SDK, and package integrations.\n */\nexport interface VectorStoreQueryHit {\n  id: string;\n  score: number;\n  payload?: Record<string, unknown>;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the vector store query context payload exchanged by command, SDK, and package integrations.\n */\nexport interface VectorStoreQueryContext {\n  vector: number[];\n  limit: number;\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the vector store upsert point payload exchanged by command, SDK, and package integrations.\n */\nexport interface VectorStoreUpsertPoint {\n  id: string;\n  vector: number[];\n  payload?: Record<string, unknown>;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the vector store upsert context payload exchanged by command, SDK, and package integrations.\n */\nexport interface VectorStoreUpsertContext {\n  points: VectorStoreUpsertPoint[];\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the vector store delete context payload exchanged by command, SDK, and package integrations.\n */\nexport interface VectorStoreDeleteContext {\n  ids: string[];\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the vector store adapter definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface VectorStoreAdapterDefinition {\n  name: string;\n  query?: (context: VectorStoreQueryContext) => VectorStoreQueryHit[] | Promise<VectorStoreQueryHit[]>;\n  upsert?: (context: VectorStoreUpsertContext) => unknown | Promise<unknown>;\n  delete?: (context: VectorStoreDeleteContext) => unknown | Promise<unknown>;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the registered extension command override payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionCommandOverride {\n  layer: ExtensionLayer;\n  name: string;\n  command: string;\n  run: CommandOverride;\n}\n\n/**\n * Documents the registered extension command handler payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionCommandHandler {\n  layer: ExtensionLayer;\n  name: string;\n  command: string;\n  run: CommandHandler;\n}\n\n/**\n * Documents the registered extension parser override payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionParserOverride {\n  layer: ExtensionLayer;\n  name: string;\n  command: string;\n  run: ParserOverride;\n}\n\n/**\n * Documents the registered extension preflight override payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionPreflightOverride {\n  layer: ExtensionLayer;\n  name: string;\n  run: PreflightOverride;\n}\n\n/**\n * Documents the registered extension service override payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionServiceOverride {\n  layer: ExtensionLayer;\n  name: string;\n  service: ExtensionServiceName;\n  run: ServiceOverride;\n}\n\n/**\n * Documents the registered extension renderer override payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionRendererOverride {\n  layer: ExtensionLayer;\n  name: string;\n  format: OutputRendererFormat;\n  run: RendererOverride;\n}\n\n/**\n * Documents the extension command registry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionCommandRegistry {\n  overrides: RegisteredExtensionCommandOverride[];\n  handlers: RegisteredExtensionCommandHandler[];\n}\n\n/**\n * Documents the extension parser registry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionParserRegistry {\n  overrides: RegisteredExtensionParserOverride[];\n}\n\n/**\n * Documents the extension preflight registry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionPreflightRegistry {\n  overrides: RegisteredExtensionPreflightOverride[];\n}\n\n/**\n * Documents the extension service registry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionServiceRegistry {\n  overrides: RegisteredExtensionServiceOverride[];\n}\n\n/**\n * Documents the extension renderer registry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionRendererRegistry {\n  overrides: RegisteredExtensionRendererOverride[];\n}\n\n/**\n * Documents the registered extension flag definitions payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionFlagDefinitions {\n  layer: ExtensionLayer;\n  name: string;\n  target_command: string;\n  flags: FlagDefinition[];\n}\n\n/**\n * Documents the registered extension command definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionCommandDefinition {\n  layer: ExtensionLayer;\n  name: string;\n  source_package?: string;\n  command: string;\n  action: string;\n  description?: string;\n  intent?: string;\n  examples: string[];\n  failure_hints: string[];\n  arguments: ExtensionCommandArgumentDefinition[];\n}\n\n/**\n * Documents the registered extension schema field definitions payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionSchemaFieldDefinitions {\n  layer: ExtensionLayer;\n  name: string;\n  fields: SchemaFieldDefinition[];\n}\n\n/**\n * Documents the registered extension schema item type definitions payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionSchemaItemTypeDefinitions {\n  layer: ExtensionLayer;\n  name: string;\n  types: SchemaItemTypeDefinition[];\n}\n\n/**\n * Documents the registered extension schema migration definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionSchemaMigrationDefinition {\n  layer: ExtensionLayer;\n  name: string;\n  definition: SchemaMigrationDefinition;\n  runtime_definition: SchemaMigrationDefinition;\n}\n\n/**\n * Documents the registered extension importer payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionImporter {\n  layer: ExtensionLayer;\n  name: string;\n  importer: string;\n}\n\n/**\n * Documents the registered extension exporter payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionExporter {\n  layer: ExtensionLayer;\n  name: string;\n  exporter: string;\n}\n\n/**\n * Documents the registered extension search provider payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionSearchProvider {\n  layer: ExtensionLayer;\n  name: string;\n  definition: SearchProviderDefinition;\n  runtime_definition: SearchProviderDefinition;\n}\n\n/**\n * Documents the registered extension vector store adapter payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionVectorStoreAdapter {\n  layer: ExtensionLayer;\n  name: string;\n  definition: VectorStoreAdapterDefinition;\n  runtime_definition: VectorStoreAdapterDefinition;\n}\n\n/**\n * Documents a project profile contributed by an extension via\n * `api.registerProfile(profile)`.\n *\n * A profile is the broadest customization primitive an extension can ship: it\n * bundles item types, custom statuses, fields, per-type workflows, config knobs,\n * create templates, and package recommendations into one declarative archetype\n * that `pm profile apply` stages idempotently — the same shape as the\n * core-baked archetypes. Registering one makes it resolvable by name through\n * `pm profile list/show/apply` for as long as the owning package is active.\n */\nexport interface RegisteredExtensionProjectProfile {\n  layer: ExtensionLayer;\n  name: string;\n  profile: ProjectProfileDefinition;\n}\n\n/**\n * Documents the extension registration registry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionRegistrationRegistry {\n  commands: RegisteredExtensionCommandDefinition[];\n  flags: RegisteredExtensionFlagDefinitions[];\n  item_fields: RegisteredExtensionSchemaFieldDefinitions[];\n  item_types: RegisteredExtensionSchemaItemTypeDefinitions[];\n  migrations: RegisteredExtensionSchemaMigrationDefinition[];\n  profiles: RegisteredExtensionProjectProfile[];\n  importers: RegisteredExtensionImporter[];\n  exporters: RegisteredExtensionExporter[];\n  search_providers: RegisteredExtensionSearchProvider[];\n  vector_store_adapters: RegisteredExtensionVectorStoreAdapter[];\n}\n\n/**\n * Documents the extension registration counts payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionRegistrationCounts {\n  commands: number;\n  flags: number;\n  item_fields: number;\n  item_types: number;\n  migrations: number;\n  profiles: number;\n  importers: number;\n  exporters: number;\n  search_providers: number;\n  vector_store_adapters: number;\n}\n\n/**\n * Read-only identity an extension's `activate(api)` receives about itself, so\n * authors can emit self-identifying logs, gate on their own version, and build\n * better error messages without re-reading the on-disk manifest or duplicating\n * metadata in-module. Exposed as `api.extension`.\n */\nexport interface ExtensionSelfIdentity {\n  readonly name: string;\n  readonly layer: ExtensionLayer;\n  readonly version: string;\n  readonly capabilities: readonly ExtensionCapability[];\n  readonly pm_min_version?: string;\n  readonly pm_max_version?: string;\n  readonly source_package?: string;\n}\n\n/**\n * Documents the extension api payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionApi {\n  /** Read-only identity of the extension this `api` was created for. */\n  readonly extension: ExtensionSelfIdentity;\n  registerCommand(command: string, override: CommandOverride): void;\n  registerCommand(definition: CommandDefinition): void;\n  registerParser(command: string, override: ParserOverride): void;\n  registerPreflight(override: PreflightOverride): void;\n  registerService(service: ExtensionServiceName, override: ServiceOverride): void;\n  registerFlags(targetCommand: string, flags: FlagDefinition[]): void;\n  registerItemFields(fields: SchemaFieldDefinition[]): void;\n  registerItemTypes(types: SchemaItemTypeDefinition[]): void;\n  registerMigration(definition: SchemaMigrationDefinition): void;\n  registerProfile(profile: ProjectProfileRegistrationInput): void;\n  registerRenderer(format: OutputRendererFormat, renderer: RendererOverride): void;\n  registerImporter(name: string, importer: Importer, options?: ImportExportRegistrationOptions): void;\n  registerExporter(name: string, exporter: Exporter, options?: ImportExportRegistrationOptions): void;\n  registerSearchProvider(provider: SearchProviderDefinition): void;\n  registerVectorStoreAdapter(adapter: VectorStoreAdapterDefinition): void;\n  hooks: {\n    beforeCommand(hook: BeforeCommandHook): void;\n    afterCommand(hook: AfterCommandHook): void;\n    onWrite(hook: OnWriteHook): void;\n    onRead(hook: OnReadHook): void;\n    onIndex(hook: OnIndexHook): void;\n  };\n}\n\n/**\n * Documents the failed extension activation payload exchanged by command, SDK, and package integrations.\n */\nexport interface FailedExtensionActivation {\n  layer: ExtensionLayer;\n  name: string;\n  entry_path: string;\n  error: string;\n  trace?: ExtensionActivationFailureTrace;\n}\n\n/**\n * Documents the extension activation failure trace payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionActivationFailureTrace {\n  method: string;\n  /** `-1` means the failure happened before a numbered registration was accepted. */\n  registration_index: number;\n  command?: string;\n  capability?: ExtensionCapability;\n  missing_capability?: ExtensionCapability;\n  expected_schema: string;\n  received?: unknown;\n  hint?: string;\n}\n\n/**\n * Documents the extension activation result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionActivationResult {\n  hooks: ExtensionHookRegistry;\n  commands: ExtensionCommandRegistry;\n  parsers: ExtensionParserRegistry;\n  preflight: ExtensionPreflightRegistry;\n  services: ExtensionServiceRegistry;\n  renderers: ExtensionRendererRegistry;\n  registrations: ExtensionRegistrationRegistry;\n  failed: FailedExtensionActivation[];\n  warnings: string[];\n  hook_counts: {\n    before_command: number;\n    after_command: number;\n    on_write: number;\n    on_read: number;\n    on_index: number;\n  };\n  command_override_count: number;\n  command_handler_count: number;\n  parser_override_count: number;\n  preflight_override_count: number;\n  service_override_count: number;\n  renderer_override_count: number;\n  registration_counts: ExtensionRegistrationCounts;\n}\n\n/**\n * Documents the extension candidate payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionCandidate {\n  layer: ExtensionLayer;\n  directory: string;\n  manifest_path: string;\n  entry_path: string;\n  manifest: ExtensionManifest;\n  source_package?: string;\n}\n\n/**\n * Documents the extension layer scan result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionLayerScanResult {\n  diagnostics: ExtensionDiagnostic[];\n  warnings: string[];\n  candidates: ExtensionCandidate[];\n}\n\n/**\n * Documents the scanned extension directory payload exchanged by command, SDK, and package integrations.\n */\nexport interface ScannedExtensionDirectory {\n  diagnostic: ExtensionDiagnostic;\n  warnings: string[];\n  candidate: ExtensionCandidate | null;\n}\n\n/**\n * Documents the legacy extension capability alias mapping payload exchanged by command, SDK, and package integrations.\n */\nexport interface LegacyExtensionCapabilityAliasMapping {\n  alias: string;\n  target: ExtensionCapability;\n}\n\n/**\n * Documents the discover extensions options payload exchanged by command, SDK, and package integrations.\n */\nexport interface DiscoverExtensionsOptions {\n  pmRoot: string;\n  settings: PmSettings;\n  cwd?: string;\n  noExtensions?: boolean;\n  reload_token?: string;\n  cache_bust?: boolean;\n}\n\n/**\n * Documents the activatable extension payload exchanged by command, SDK, and package integrations.\n */\nexport interface ActivatableExtension {\n  activate: (api: ExtensionApi) => void | Promise<void>;\n  /**\n   * Optional teardown lifecycle hook, analogous to VS Code's `deactivate`\n   * export. Invoked when the host tears the extension down — on long-running\n   * MCP-server reload between requests, or via the `deactivateExtensions`\n   * primitive — so an extension can close connections, clear timers, and\n   * release buffers it opened during `activate`.\n   */\n  deactivate?: () => void | Promise<void>;\n}\n\n/**\n * Documents the extension deactivation failure payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionDeactivationFailure {\n  layer: ExtensionLayer;\n  name: string;\n  error: string;\n}\n\n/**\n * Documents the extension deactivation options payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionDeactivationOptions {\n  /**\n   * Maximum time to wait for each extension's `deactivate` hook. Defaults to\n   * 5000ms so a hanging teardown cannot block host shutdown or reload. Set to\n   * 0 or Infinity only when the host intentionally wants to wait indefinitely.\n   */\n  deactivate_timeout_ms?: number;\n}\n\n/**\n * Documents the extension deactivation result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionDeactivationResult {\n  /** Count of loaded extensions whose `deactivate` hook ran without throwing. */\n  deactivated: number;\n  warnings: string[];\n  failed: ExtensionDeactivationFailure[];\n}\n\n/**\n * Documents the service override result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ServiceOverrideResult {\n  handled: boolean;\n  result: unknown;\n  warnings: string[];\n}\n\n/**\n * Documents the command override result payload exchanged by command, SDK, and package integrations.\n */\nexport interface CommandOverrideResult {\n  overridden: boolean;\n  result: unknown;\n  warnings: string[];\n}\n\n/**\n * Documents the command handler result payload exchanged by command, SDK, and package integrations.\n */\nexport interface CommandHandlerResult {\n  handled: boolean;\n  result: unknown;\n  warnings: string[];\n  /**\n   * Human-readable, single-line, length-bounded message describing why an\n   * extension command handler failed. Surfaced to the user/CI so the real cause\n   * (e.g. \"Changelog is out of date: CHANGELOG.md\") is visible instead of only\n   * the opaque `extension_command_handler_failed` warning code.\n   */\n  errorMessage?: string;\n}\n\n/**\n * Documents the parser override result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ParserOverrideResult {\n  overridden: boolean;\n  context: CommandHandlerContext;\n  warnings: string[];\n}\n\n/**\n * Documents the preflight override result payload exchanged by command, SDK, and package integrations.\n */\nexport interface PreflightOverrideResult {\n  overridden: boolean;\n  context: CommandHandlerContext;\n  decision: PreflightRuntimeDecision;\n  warnings: string[];\n}\n\n/**\n * Documents the renderer override result payload exchanged by command, SDK, and package integrations.\n */\nexport interface RendererOverrideResult {\n  overridden: boolean;\n  rendered: string | null;\n  warnings: string[];\n}\n\n/**\n * Documents the unknown extension capability warning details payload exchanged by command, SDK, and package integrations.\n */\nexport interface UnknownExtensionCapabilityWarningDetails {\n  layer: ExtensionLayer;\n  name: string;\n  capability: string;\n  allowed_capabilities: string[];\n  capability_contract_version: number;\n  suggested_capability?: string;\n  suggestion_source?: \"legacy_alias\" | \"nearest_match\";\n  legacy_alias_target?: string;\n}\n"],"names":[],"mappings":";;AAgBA,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,UAAU;IACV,WAAW;IACX,OAAO;IACP,QAAQ;IACR,WAAW;IACX,QAAQ;IACR,QAAQ;IACR,WAAW;IACX,UAAU;CACF,CAAC;AAKX,MAAM,CAAC,MAAM,qCAAqC,GAAG,CAAC,CAAC;AACvD,MAAM,CAAC,MAAM,mCAAmC,GAAkD,MAAM,CAAC,MAAM,CAAC;IAC9G,SAAS,EAAE,QAAQ;IACnB,UAAU,EAAE,QAAQ;CACrB,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,MAAM,CAAC,MAAM,CAAC;IACzD,OAAO,EAAE,qCAAqC;IAC9C,YAAY,EAAE,CAAC,GAAG,4BAA4B,CAAC;IAC/C,cAAc,EAAE,EAAE,GAAG,mCAAmC,EAAE;CAC3D,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAKhF,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAK/E,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,CAAU,CAAC;AAM1F,MAAM,CAAC,MAAM,mCAAmC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAU,CAAC;AAe9E,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,mBAAmB;IACnB,kBAAkB;IAClB,qBAAqB;IACrB,oBAAoB;IACpB,eAAe;IACf,cAAc;IACd,eAAe;IACf,cAAc;IACd,mBAAmB;IACnB,kBAAkB;IAClB,mBAAmB;IACnB,iBAAiB;IACjB,iBAAiB;IACjB,oBAAoB;IACpB,mBAAmB;IACnB,oBAAoB;IACpB,oBAAoB;IACpB,oBAAoB;IACpB,iBAAiB;IACjB,oBAAoB;CACZ,CAAC;AAMX,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,eAAe;IACf,cAAc;IACd,aAAa;IACb,cAAc;IACd,cAAc;IACd,gBAAgB;IAChB,kBAAkB;IAClB,mBAAmB;CACX,CAAC;AA0DX;;GAEG;AACH,MAAM,UAAU,sCAAsC;IACpD,OAAO;QACL,IAAI,EAAE,KAAK;QACX,UAAU,EAAE,KAAK;QACjB,kBAAkB,EAAE,KAAK;QACzB,kBAAkB,EAAE,EAAE;QACtB,uBAAuB,EAAE,MAAM;QAC/B,kBAAkB,EAAE,EAAE;QACtB,kBAAkB,EAAE,EAAE;QACtB,oBAAoB,EAAE,EAAE;QACxB,oBAAoB,EAAE,EAAE;QACxB,gBAAgB,EAAE,EAAE;QACpB,gBAAgB,EAAE,EAAE;QACpB,gBAAgB,EAAE,EAAE;QACpB,gBAAgB,EAAE,EAAE;QACpB,eAAe,EAAE,EAAE;QACnB,eAAe,EAAE,EAAE;QACnB,gBAAgB,EAAE,EAAE;QACpB,gBAAgB,EAAE,EAAE;QACpB,mBAAmB,EAAE,EAAE;KACxB,CAAC;AACJ,CAAC","debugId":"add4a412-10a4-5c04-b3a2-998cc74fdd38"}
+{"version":3,"file":"extension-types.js","sources":["core/extensions/extension-types.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/extension-types\n *\n * Implements extension runtime contracts and governance for Extension Types.\n */\nimport type {\n  ExtensionPolicyOverrideSettings,\n  ExtensionPolicySettings,\n  ItemDocument,\n  ItemFrontMatter,\n  ItemStatus,\n  PmSettings,\n} from \"../../types/index.js\";\nimport type { GlobalOptions } from \"../shared/command-types.js\";\nimport type { ProjectProfileDefinition, ProjectProfileRegistrationInput } from \"../profile/profile-presets.js\";\n\nexport const KNOWN_EXTENSION_CAPABILITIES = [\n  \"commands\",\n  \"renderers\",\n  \"hooks\",\n  \"schema\",\n  \"importers\",\n  \"search\",\n  \"parser\",\n  \"preflight\",\n  \"services\",\n] as const;\n/**\n * Restricts extension capability values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionCapability = (typeof KNOWN_EXTENSION_CAPABILITIES)[number];\nexport const EXTENSION_CAPABILITY_CONTRACT_VERSION = 2;\nexport const EXTENSION_CAPABILITY_LEGACY_ALIASES: Readonly<Record<string, ExtensionCapability>> = Object.freeze({\n  migration: \"schema\",\n  validation: \"schema\",\n});\nexport const EXTENSION_CAPABILITY_CONTRACT = Object.freeze({\n  version: EXTENSION_CAPABILITY_CONTRACT_VERSION,\n  capabilities: [...KNOWN_EXTENSION_CAPABILITIES],\n  legacy_aliases: { ...EXTENSION_CAPABILITY_LEGACY_ALIASES },\n});\n\nexport const KNOWN_EXTENSION_POLICY_MODES = [\"off\", \"warn\", \"enforce\"] as const;\n/**\n * Restricts extension policy mode values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionPolicyMode = (typeof KNOWN_EXTENSION_POLICY_MODES)[number];\nexport const KNOWN_EXTENSION_TRUST_MODES = [\"off\", \"warn\", \"enforce\"] as const;\n/**\n * Restricts extension trust mode values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionTrustMode = (typeof KNOWN_EXTENSION_TRUST_MODES)[number];\nexport const KNOWN_EXTENSION_SANDBOX_PROFILES = [\"none\", \"restricted\", \"strict\"] as const;\n/**\n * Restricts extension sandbox profile values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionSandboxProfile = (typeof KNOWN_EXTENSION_SANDBOX_PROFILES)[number];\n\nexport const KNOWN_PM_MAX_VERSION_EXCEEDED_MODES = [\"block\", \"warn\"] as const;\n/** How a `pm_max_version` violation is handled for an extension layer. */\nexport type PmMaxVersionExceededMode = (typeof KNOWN_PM_MAX_VERSION_EXCEEDED_MODES)[number];\n/** Optional per-layer override map for `extensions.policy.pm_max_version_exceeded_mode`. */\nexport interface PmMaxVersionExceededModeByLayer {\n  global?: PmMaxVersionExceededMode;\n  project?: PmMaxVersionExceededMode;\n}\n/**\n * Settings value for `extensions.policy.pm_max_version_exceeded_mode`: either a\n * single mode applied to both layers, or a per-layer override map. Unset (and\n * any unset layer key) defaults to `\"block\"`.\n */\nexport type PmMaxVersionExceededModeSetting = PmMaxVersionExceededMode | PmMaxVersionExceededModeByLayer;\n\nexport const KNOWN_EXTENSION_POLICY_SURFACES = [\n  \"commands.override\",\n  \"commands.handler\",\n  \"hooks.beforecommand\",\n  \"hooks.aftercommand\",\n  \"hooks.onwrite\",\n  \"hooks.onread\",\n  \"hooks.onindex\",\n  \"schema.flags\",\n  \"schema.itemfields\",\n  \"schema.itemtypes\",\n  \"schema.migrations\",\n  \"schema.profiles\",\n  \"parser.override\",\n  \"preflight.override\",\n  \"services.override\",\n  \"renderers.override\",\n  \"importers.importer\",\n  \"importers.exporter\",\n  \"search.provider\",\n  \"search.vectorstore\",\n] as const;\n/**\n * Restricts extension policy surface values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionPolicySurface = (typeof KNOWN_EXTENSION_POLICY_SURFACES)[number];\n\nexport const KNOWN_EXTENSION_SERVICE_NAMES = [\n  \"output_format\",\n  \"error_format\",\n  \"help_format\",\n  \"lock_acquire\",\n  \"lock_release\",\n  \"history_append\",\n  \"item_store_write\",\n  \"item_store_delete\",\n] as const;\n/**\n * Restricts extension service name values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionServiceName = (typeof KNOWN_EXTENSION_SERVICE_NAMES)[number];\n\n/**\n * Documents the extension provenance metadata payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionProvenanceMetadata {\n  source?: string;\n  signature?: string;\n  attestation?: string;\n  verified?: boolean;\n}\n\n/**\n * Documents the extension runtime permission declaration payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionRuntimePermissionDeclaration {\n  fs_read?: boolean;\n  fs_write?: boolean;\n  network?: boolean;\n  env_read?: boolean;\n  env_write?: boolean;\n  process_spawn?: boolean;\n}\n\n/**\n * Documents the extension activation metadata payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionActivationMetadata {\n  commands?: string[];\n}\n\n/**\n * Restricts extension policy override values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionPolicyOverride = ExtensionPolicyOverrideSettings;\n/**\n * Extension governance policy as read from / serialized to settings. Extends the\n * stored settings shape with `pm_max_version_exceeded_mode` (pm-k5e8), which\n * relaxes the default-BLOCK on `pm_max_version` violations to warn-only —\n * globally or per extension layer.\n */\nexport type ExtensionGovernancePolicy = ExtensionPolicySettings & {\n  pm_max_version_exceeded_mode?: PmMaxVersionExceededModeSetting;\n};\n\n/**\n * Documents the extension manifest engines payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionManifestEngines {\n  pm?: string;\n  node?: string;\n  [engine: string]: string | undefined;\n}\n\n/**\n * Implements create default extension governance policy for the public runtime surface of this module.\n */\nexport function createDefaultExtensionGovernancePolicy(): ExtensionGovernancePolicy {\n  return {\n    mode: \"off\",\n    trust_mode: \"off\",\n    require_provenance: false,\n    trusted_extensions: [],\n    default_sandbox_profile: \"none\",\n    allowed_extensions: [],\n    blocked_extensions: [],\n    allowed_capabilities: [],\n    blocked_capabilities: [],\n    allowed_surfaces: [],\n    blocked_surfaces: [],\n    allowed_commands: [],\n    blocked_commands: [],\n    allowed_actions: [],\n    blocked_actions: [],\n    allowed_services: [],\n    blocked_services: [],\n    extension_overrides: [],\n  };\n}\n\n/**\n * Restricts extension layer values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionLayer = \"global\" | \"project\";\n/**\n * Restricts extension status values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionStatus = \"ok\" | \"warn\";\n\n/**\n * Documents the extension manifest payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionManifest {\n  name: string;\n  version: string;\n  entry: string;\n  priority: number;\n  capabilities: string[];\n  manifest_version?: number;\n  pm_min_version?: string;\n  pm_max_version?: string;\n  engines?: ExtensionManifestEngines;\n  trusted?: boolean;\n  provenance?: ExtensionProvenanceMetadata;\n  sandbox_profile?: ExtensionSandboxProfile;\n  permissions?: ExtensionRuntimePermissionDeclaration;\n  activation?: ExtensionActivationMetadata;\n  legacy_capability_aliases?: LegacyExtensionCapabilityAliasMapping[];\n}\n\n/**\n * Documents the extension diagnostic payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionDiagnostic {\n  layer: ExtensionLayer;\n  directory: string;\n  manifest_path: string;\n  name: string | null;\n  version: string | null;\n  entry: string | null;\n  priority: number | null;\n  entry_path: string | null;\n  enabled: boolean | null;\n  status: ExtensionStatus;\n}\n\n/**\n * Documents the effective extension payload exchanged by command, SDK, and package integrations.\n */\nexport interface EffectiveExtension {\n  layer: ExtensionLayer;\n  directory: string;\n  manifest_path: string;\n  name: string;\n  source_package?: string;\n  version: string;\n  entry: string;\n  priority: number;\n  entry_path: string;\n  manifest_version?: number;\n  pm_min_version?: string;\n  pm_max_version?: string;\n  engines?: ExtensionManifestEngines;\n  trusted?: boolean;\n  provenance?: ExtensionProvenanceMetadata;\n  sandbox_profile?: ExtensionSandboxProfile;\n  permissions?: ExtensionRuntimePermissionDeclaration;\n  capabilities?: string[];\n  activation?: ExtensionActivationMetadata;\n}\n\n/**\n * Documents the extension discovery result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionDiscoveryResult {\n  disabled_by_flag: boolean;\n  roots: {\n    global: string;\n    project: string;\n  };\n  configured_enabled: string[];\n  configured_disabled: string[];\n  discovered: ExtensionDiagnostic[];\n  effective: EffectiveExtension[];\n  warnings: string[];\n  policy: ExtensionGovernancePolicy;\n}\n\n/**\n * Documents the loaded extension payload exchanged by command, SDK, and package integrations.\n */\nexport interface LoadedExtension extends EffectiveExtension {\n  module: unknown;\n}\n\n/**\n * Documents the failed extension load payload exchanged by command, SDK, and package integrations.\n */\nexport interface FailedExtensionLoad {\n  layer: ExtensionLayer;\n  name: string;\n  entry_path: string;\n  error: string;\n}\n\n/**\n * Documents the extension load result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionLoadResult extends ExtensionDiscoveryResult {\n  loaded: LoadedExtension[];\n  failed: FailedExtensionLoad[];\n}\n\n/**\n * Documents the before command hook context payload exchanged by command, SDK, and package integrations.\n */\nexport interface BeforeCommandHookContext {\n  command: string;\n  args: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n  pm_root: string;\n}\n\n/**\n * Documents the after command hook context payload exchanged by command, SDK, and package integrations.\n */\nexport interface AfterCommandHookContext extends BeforeCommandHookContext {\n  ok: boolean;\n  error?: string;\n  result?: unknown;\n  affected?: AfterCommandAffectedItem[];\n}\n\n/**\n * Documents the after command affected item payload exchanged by command, SDK, and package integrations.\n */\nexport interface AfterCommandAffectedItem {\n  id: string;\n  op?: string;\n  item_type?: string;\n  previous_status?: ItemStatus;\n  status?: ItemStatus;\n  previous?: Partial<ItemFrontMatter>;\n  current?: Partial<ItemFrontMatter>;\n  changed_fields?: string[];\n}\n\n/**\n * Documents the on write hook context payload exchanged by command, SDK, and package integrations.\n */\nexport interface OnWriteHookContext {\n  path: string;\n  scope: \"project\" | \"global\";\n  op: string;\n  item_id?: string;\n  item_type?: string;\n  before?: ItemDocument;\n  after?: ItemDocument;\n  changed_fields?: string[];\n}\n\n/**\n * Documents the on read hook context payload exchanged by command, SDK, and package integrations.\n */\nexport interface OnReadHookContext {\n  path: string;\n  scope: \"project\" | \"global\";\n}\n\n/**\n * Documents the on index hook context payload exchanged by command, SDK, and package integrations.\n */\nexport interface OnIndexHookContext {\n  mode: string;\n  total_items?: number;\n}\n\n/**\n * Restricts before command hook values accepted by command, SDK, and storage contracts.\n */\nexport type BeforeCommandHook = (context: BeforeCommandHookContext) => Promise<void> | void;\n/**\n * Restricts after command hook values accepted by command, SDK, and storage contracts.\n */\nexport type AfterCommandHook = (context: AfterCommandHookContext) => Promise<void> | void;\n/**\n * Restricts on write hook values accepted by command, SDK, and storage contracts.\n */\nexport type OnWriteHook = (context: OnWriteHookContext) => Promise<void> | void;\n/**\n * Restricts on read hook values accepted by command, SDK, and storage contracts.\n */\nexport type OnReadHook = (context: OnReadHookContext) => Promise<void> | void;\n/**\n * Restricts on index hook values accepted by command, SDK, and storage contracts.\n */\nexport type OnIndexHook = (context: OnIndexHookContext) => Promise<void> | void;\n/**\n * Restricts output renderer format values accepted by command, SDK, and storage contracts.\n */\nexport type OutputRendererFormat = \"toon\" | \"json\";\n/**\n * Restricts command override values accepted by command, SDK, and storage contracts.\n */\nexport type CommandOverride = (context: CommandOverrideContext) => unknown;\n/**\n * Restricts renderer override values accepted by command, SDK, and storage contracts.\n */\nexport type RendererOverride = (context: RendererOverrideContext) => string | null | undefined;\n/**\n * Restricts command handler values accepted by command, SDK, and storage contracts.\n */\nexport type CommandHandler = (context: CommandHandlerContext) => unknown;\n/**\n * Restricts parser override values accepted by command, SDK, and storage contracts.\n */\nexport type ParserOverride = (context: ParserOverrideContext) => ParserOverrideDelta | Promise<ParserOverrideDelta>;\n/**\n * Restricts preflight override values accepted by command, SDK, and storage contracts.\n */\nexport type PreflightOverride = (context: PreflightOverrideContext) => PreflightOverrideDelta | Promise<PreflightOverrideDelta>;\n/**\n * Restricts service override values accepted by command, SDK, and storage contracts.\n */\nexport type ServiceOverride = (context: ServiceOverrideContext) => unknown;\n\n/**\n * Documents the registered extension hook payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionHook<THook> {\n  layer: ExtensionLayer;\n  name: string;\n  run: THook;\n}\n\n/**\n * Documents the extension hook registry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionHookRegistry {\n  beforeCommand: Array<RegisteredExtensionHook<BeforeCommandHook>>;\n  afterCommand: Array<RegisteredExtensionHook<AfterCommandHook>>;\n  onWrite: Array<RegisteredExtensionHook<OnWriteHook>>;\n  onRead: Array<RegisteredExtensionHook<OnReadHook>>;\n  onIndex: Array<RegisteredExtensionHook<OnIndexHook>>;\n}\n\n/**\n * Documents the command override context payload exchanged by command, SDK, and package integrations.\n */\nexport interface CommandOverrideContext {\n  command: string;\n  args: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n  pm_root: string;\n  result: unknown;\n}\n\n/**\n * Documents the renderer override context payload exchanged by command, SDK, and package integrations.\n */\nexport interface RendererOverrideContext {\n  format: OutputRendererFormat;\n  command?: string;\n  args?: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n  pm_root?: string;\n  result: unknown;\n}\n\n/**\n * Documents the command handler context payload exchanged by command, SDK, and package integrations.\n */\nexport interface CommandHandlerContext {\n  command: string;\n  args: string[];\n  options: Record<string, unknown>;\n  global: GlobalOptions;\n  pm_root: string;\n}\n\n/**\n * Documents the parser override context payload exchanged by command, SDK, and package integrations.\n */\nexport type ParserOverrideContext = CommandHandlerContext;\n\n/**\n * Documents the parser override delta payload exchanged by command, SDK, and package integrations.\n */\nexport interface ParserOverrideDelta {\n  args?: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n}\n\n/**\n * Documents the preflight override context payload exchanged by command, SDK, and package integrations.\n */\nexport interface PreflightOverrideContext extends CommandHandlerContext {\n  decision: PreflightRuntimeDecision;\n}\n\n/**\n * Documents the preflight runtime decision payload exchanged by command, SDK, and package integrations.\n */\nexport interface PreflightRuntimeDecision {\n  enforce_item_format_gate: boolean;\n  run_preflight_item_format_sync: boolean;\n  run_extension_migrations: boolean;\n  enforce_mandatory_migration_gate: boolean;\n}\n\n/**\n * Documents the preflight override delta payload exchanged by command, SDK, and package integrations.\n */\nexport interface PreflightOverrideDelta extends ParserOverrideDelta {\n  enforce_item_format_gate?: boolean;\n  run_preflight_item_format_sync?: boolean;\n  run_extension_migrations?: boolean;\n  enforce_mandatory_migration_gate?: boolean;\n}\n\n/**\n * Documents the service override context payload exchanged by command, SDK, and package integrations.\n */\nexport interface ServiceOverrideContext {\n  service: ExtensionServiceName;\n  command?: string;\n  args?: string[];\n  options?: Record<string, unknown>;\n  global?: GlobalOptions;\n  pm_root?: string;\n  payload: unknown;\n}\n\n/**\n * Documents the extension command argument definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionCommandArgumentDefinition {\n  name: string;\n  required?: boolean;\n  variadic?: boolean;\n  description?: string;\n}\n\n/**\n * Documents the command definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface CommandDefinition {\n  name: string;\n  run?: CommandHandler;\n  /**\n   * @deprecated Use `run` instead. This alias remains for backward compatibility.\n   */\n  handler?: CommandHandler;\n  action?: string;\n  description?: string;\n  intent?: string;\n  examples?: string[];\n  failure_hints?: string[];\n  arguments?: ExtensionCommandArgumentDefinition[];\n  flags?: FlagDefinition[];\n}\n\n/**\n * Optional command-definition metadata for first-class importer/exporter\n * registration.\n *\n * `registerImporter`/`registerExporter` always create a `<name> import` /\n * `<name> export` command path. By default that path only has a handler. When\n * these options are supplied, the auto-created command also gains a full command\n * definition (description, flags, intent, examples, failure hints, positional\n * arguments) — surfaced in help and runtime contracts exactly like\n * `registerCommand`. The registration `name` and `run` handler are implicit, so\n * they are not part of this options object.\n */\nexport interface ImportExportRegistrationOptions {\n  action?: string;\n  description?: string;\n  intent?: string;\n  examples?: string[];\n  failure_hints?: string[];\n  arguments?: ExtensionCommandArgumentDefinition[];\n  flags?: FlagDefinition[];\n}\n\n/**\n * Restricts flag value type values accepted by command, SDK, and storage contracts.\n */\nexport type FlagValueType = \"string\" | \"number\" | \"boolean\";\n\n/**\n * Documents the flag definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface FlagDefinition {\n  long?: string;\n  short?: string;\n  value_name?: string;\n  description?: string;\n  required?: boolean;\n  enabled?: boolean;\n  visible?: boolean;\n  /**\n   * Canonical flag value type. Prefer this field; it is the one runtime\n   * contracts and help output read first.\n   */\n  value_type?: FlagValueType;\n  /**\n   * @deprecated Use `value_type`. Retained for backward compatibility: when\n   * both are present `value_type` wins, and `type` resolves only when\n   * `value_type` is absent (`value_type ?? type`).\n   */\n  type?: FlagValueType;\n  /**\n   * When true, a repeated comma-list flag accumulates values across repeats\n   * — parity with core list flags such as `--tags` — instead of the last\n   * value winning. Mirrors the core `CliFlagContract.list` field so\n   * extension-registered list flags coalesce through the same bootstrap path.\n   */\n  list?: boolean;\n  /**\n   * Default value applied when the flag is omitted. Surfaced to runtime\n   * contracts and help output. A `list` flag may default to an array of scalars\n   * (e.g. `[\"a\", \"b\"]`); the array is flattened/coerced like any list value.\n   */\n  default?: string | number | boolean | Array<string | number | boolean>;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the schema field definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface SchemaFieldDefinition {\n  name: string;\n  type: string;\n  optional?: boolean;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the schema item type command option policy definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface SchemaItemTypeCommandOptionPolicyDefinition {\n  command: string;\n  option: string;\n  enabled?: boolean;\n  required?: boolean;\n  visible?: boolean;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the schema item type option definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface SchemaItemTypeOptionDefinition {\n  key: string;\n  values?: string[];\n  required?: boolean;\n  aliases?: string[];\n  [key: string]: unknown;\n}\n\n/**\n * Documents the schema item type definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface SchemaItemTypeDefinition {\n  name: string;\n  folder?: string;\n  aliases?: string[];\n  required_create_fields?: string[];\n  required_create_repeatables?: string[];\n  command_option_policies?: SchemaItemTypeCommandOptionPolicyDefinition[];\n  options?: SchemaItemTypeOptionDefinition[];\n  [key: string]: unknown;\n}\n\n/**\n * Documents the schema migration run context payload exchanged by command, SDK, and package integrations.\n */\nexport interface SchemaMigrationRunContext {\n  id: string;\n  command: \"migration\";\n  layer: ExtensionLayer;\n  extension: string;\n  pm_root: string;\n  status: string;\n}\n\n/**\n * Restricts schema migration runner values accepted by command, SDK, and storage contracts.\n */\nexport type SchemaMigrationRunner = (context: SchemaMigrationRunContext) => unknown | Promise<unknown>;\n\n/**\n * Documents the schema migration definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface SchemaMigrationDefinition {\n  id?: string;\n  description?: string;\n  status?: string;\n  mandatory?: boolean;\n  run?: SchemaMigrationRunner;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the import export context payload exchanged by command, SDK, and package integrations.\n */\nexport interface ImportExportContext {\n  registration: string;\n  action: \"import\" | \"export\";\n  command: string;\n  args: string[];\n  options: Record<string, unknown>;\n  global: GlobalOptions;\n  pm_root: string;\n}\n\n/**\n * Restricts importer values accepted by command, SDK, and storage contracts.\n */\nexport type Importer = (context: ImportExportContext) => unknown | Promise<unknown>;\n/**\n * Restricts exporter values accepted by command, SDK, and storage contracts.\n */\nexport type Exporter = (context: ImportExportContext) => unknown | Promise<unknown>;\n\n/**\n * Restricts extension search mode values accepted by command, SDK, and storage contracts.\n */\nexport type ExtensionSearchMode = \"keyword\" | \"semantic\" | \"hybrid\";\n\n/**\n * Documents the search provider query context payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderQueryContext {\n  query: string;\n  mode: ExtensionSearchMode;\n  tokens: string[];\n  options: Record<string, unknown>;\n  settings: PmSettings;\n  documents: ItemDocument[];\n  [key: string]: unknown;\n}\n\n/**\n * Documents the search provider hit payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderHit {\n  id: string;\n  score: number;\n  matched_fields?: string[];\n  [key: string]: unknown;\n}\n\n/**\n * Restricts search provider query result values accepted by command, SDK, and storage contracts.\n */\nexport type SearchProviderQueryResult = SearchProviderHit[] | { hits?: SearchProviderHit[] };\n\n/**\n * Documents the search provider query expansion context payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderQueryExpansionContext {\n  query: string;\n  mode: Exclude<ExtensionSearchMode, \"keyword\">;\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/**\n * Restricts search provider query expansion result values accepted by command, SDK, and storage contracts.\n */\nexport type SearchProviderQueryExpansionResult = string[] | { queries?: string[] };\n\n/**\n * Documents the search provider rerank candidate payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderRerankCandidate {\n  id: string;\n  text: string;\n  score: number;\n}\n\n/**\n * Documents the search provider rerank hit payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderRerankHit {\n  id: string;\n  score: number;\n}\n\n/**\n * Restricts search provider rerank result values accepted by command, SDK, and storage contracts.\n */\nexport type SearchProviderRerankResult = SearchProviderRerankHit[] | { hits?: SearchProviderRerankHit[] };\n\n/**\n * Documents the search provider rerank context payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderRerankContext {\n  query: string;\n  mode: \"hybrid\";\n  model: string;\n  top_k: number;\n  settings: PmSettings;\n  candidates: SearchProviderRerankCandidate[];\n  [key: string]: unknown;\n}\n\n/**\n * Documents the search provider embed batch context payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderEmbedBatchContext {\n  inputs: string[];\n  settings: PmSettings;\n  model: string;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the search provider embed context payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderEmbedContext {\n  input: string;\n  settings: PmSettings;\n  model: string;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the search provider definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface SearchProviderDefinition {\n  name: string;\n  query?: (context: SearchProviderQueryContext) => SearchProviderQueryResult | Promise<SearchProviderQueryResult>;\n  queryExpansion?: (\n    context: SearchProviderQueryExpansionContext,\n  ) => SearchProviderQueryExpansionResult | Promise<SearchProviderQueryExpansionResult>;\n  query_expansion?: (\n    context: SearchProviderQueryExpansionContext,\n  ) => SearchProviderQueryExpansionResult | Promise<SearchProviderQueryExpansionResult>;\n  rerank?: (context: SearchProviderRerankContext) => SearchProviderRerankResult | Promise<SearchProviderRerankResult>;\n  embedBatch?: (context: SearchProviderEmbedBatchContext) => number[][] | Promise<number[][]>;\n  embed_batch?: (context: SearchProviderEmbedBatchContext) => number[][] | Promise<number[][]>;\n  embed?: (context: SearchProviderEmbedContext) => number[] | Promise<number[]>;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the vector store query hit payload exchanged by command, SDK, and package integrations.\n */\nexport interface VectorStoreQueryHit {\n  id: string;\n  score: number;\n  payload?: Record<string, unknown>;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the vector store query context payload exchanged by command, SDK, and package integrations.\n */\nexport interface VectorStoreQueryContext {\n  vector: number[];\n  limit: number;\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the vector store upsert point payload exchanged by command, SDK, and package integrations.\n */\nexport interface VectorStoreUpsertPoint {\n  id: string;\n  vector: number[];\n  payload?: Record<string, unknown>;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the vector store upsert context payload exchanged by command, SDK, and package integrations.\n */\nexport interface VectorStoreUpsertContext {\n  points: VectorStoreUpsertPoint[];\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the vector store delete context payload exchanged by command, SDK, and package integrations.\n */\nexport interface VectorStoreDeleteContext {\n  ids: string[];\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the vector store adapter definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface VectorStoreAdapterDefinition {\n  name: string;\n  query?: (context: VectorStoreQueryContext) => VectorStoreQueryHit[] | Promise<VectorStoreQueryHit[]>;\n  upsert?: (context: VectorStoreUpsertContext) => unknown | Promise<unknown>;\n  delete?: (context: VectorStoreDeleteContext) => unknown | Promise<unknown>;\n  [key: string]: unknown;\n}\n\n/**\n * Documents the registered extension command override payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionCommandOverride {\n  layer: ExtensionLayer;\n  name: string;\n  command: string;\n  run: CommandOverride;\n}\n\n/**\n * Documents the registered extension command handler payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionCommandHandler {\n  layer: ExtensionLayer;\n  name: string;\n  command: string;\n  run: CommandHandler;\n}\n\n/**\n * Documents the registered extension parser override payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionParserOverride {\n  layer: ExtensionLayer;\n  name: string;\n  command: string;\n  run: ParserOverride;\n}\n\n/**\n * Documents the registered extension preflight override payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionPreflightOverride {\n  layer: ExtensionLayer;\n  name: string;\n  run: PreflightOverride;\n}\n\n/**\n * Documents the registered extension service override payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionServiceOverride {\n  layer: ExtensionLayer;\n  name: string;\n  service: ExtensionServiceName;\n  run: ServiceOverride;\n}\n\n/**\n * Documents the registered extension renderer override payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionRendererOverride {\n  layer: ExtensionLayer;\n  name: string;\n  format: OutputRendererFormat;\n  run: RendererOverride;\n}\n\n/**\n * Documents the extension command registry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionCommandRegistry {\n  overrides: RegisteredExtensionCommandOverride[];\n  handlers: RegisteredExtensionCommandHandler[];\n}\n\n/**\n * Documents the extension parser registry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionParserRegistry {\n  overrides: RegisteredExtensionParserOverride[];\n}\n\n/**\n * Documents the extension preflight registry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionPreflightRegistry {\n  overrides: RegisteredExtensionPreflightOverride[];\n}\n\n/**\n * Documents the extension service registry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionServiceRegistry {\n  overrides: RegisteredExtensionServiceOverride[];\n}\n\n/**\n * Documents the extension renderer registry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionRendererRegistry {\n  overrides: RegisteredExtensionRendererOverride[];\n}\n\n/**\n * Documents the registered extension flag definitions payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionFlagDefinitions {\n  layer: ExtensionLayer;\n  name: string;\n  target_command: string;\n  flags: FlagDefinition[];\n}\n\n/**\n * Documents the registered extension command definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionCommandDefinition {\n  layer: ExtensionLayer;\n  name: string;\n  source_package?: string;\n  command: string;\n  action: string;\n  description?: string;\n  intent?: string;\n  examples: string[];\n  failure_hints: string[];\n  arguments: ExtensionCommandArgumentDefinition[];\n}\n\n/**\n * Documents the registered extension schema field definitions payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionSchemaFieldDefinitions {\n  layer: ExtensionLayer;\n  name: string;\n  fields: SchemaFieldDefinition[];\n}\n\n/**\n * Documents the registered extension schema item type definitions payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionSchemaItemTypeDefinitions {\n  layer: ExtensionLayer;\n  name: string;\n  types: SchemaItemTypeDefinition[];\n}\n\n/**\n * Documents the registered extension schema migration definition payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionSchemaMigrationDefinition {\n  layer: ExtensionLayer;\n  name: string;\n  definition: SchemaMigrationDefinition;\n  runtime_definition: SchemaMigrationDefinition;\n}\n\n/**\n * Documents the registered extension importer payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionImporter {\n  layer: ExtensionLayer;\n  name: string;\n  importer: string;\n}\n\n/**\n * Documents the registered extension exporter payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionExporter {\n  layer: ExtensionLayer;\n  name: string;\n  exporter: string;\n}\n\n/**\n * Documents the registered extension search provider payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionSearchProvider {\n  layer: ExtensionLayer;\n  name: string;\n  definition: SearchProviderDefinition;\n  runtime_definition: SearchProviderDefinition;\n}\n\n/**\n * Documents the registered extension vector store adapter payload exchanged by command, SDK, and package integrations.\n */\nexport interface RegisteredExtensionVectorStoreAdapter {\n  layer: ExtensionLayer;\n  name: string;\n  definition: VectorStoreAdapterDefinition;\n  runtime_definition: VectorStoreAdapterDefinition;\n}\n\n/**\n * Documents a project profile contributed by an extension via\n * `api.registerProfile(profile)`.\n *\n * A profile is the broadest customization primitive an extension can ship: it\n * bundles item types, custom statuses, fields, per-type workflows, config knobs,\n * create templates, and package recommendations into one declarative archetype\n * that `pm profile apply` stages idempotently — the same shape as the\n * core-baked archetypes. Registering one makes it resolvable by name through\n * `pm profile list/show/apply` for as long as the owning package is active.\n */\nexport interface RegisteredExtensionProjectProfile {\n  layer: ExtensionLayer;\n  name: string;\n  profile: ProjectProfileDefinition;\n}\n\n/**\n * Documents the extension registration registry payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionRegistrationRegistry {\n  commands: RegisteredExtensionCommandDefinition[];\n  flags: RegisteredExtensionFlagDefinitions[];\n  item_fields: RegisteredExtensionSchemaFieldDefinitions[];\n  item_types: RegisteredExtensionSchemaItemTypeDefinitions[];\n  migrations: RegisteredExtensionSchemaMigrationDefinition[];\n  profiles: RegisteredExtensionProjectProfile[];\n  importers: RegisteredExtensionImporter[];\n  exporters: RegisteredExtensionExporter[];\n  search_providers: RegisteredExtensionSearchProvider[];\n  vector_store_adapters: RegisteredExtensionVectorStoreAdapter[];\n}\n\n/**\n * Documents the extension registration counts payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionRegistrationCounts {\n  commands: number;\n  flags: number;\n  item_fields: number;\n  item_types: number;\n  migrations: number;\n  profiles: number;\n  importers: number;\n  exporters: number;\n  search_providers: number;\n  vector_store_adapters: number;\n}\n\n/**\n * Read-only identity an extension's `activate(api)` receives about itself, so\n * authors can emit self-identifying logs, gate on their own version, and build\n * better error messages without re-reading the on-disk manifest or duplicating\n * metadata in-module. Exposed as `api.extension`.\n */\nexport interface ExtensionSelfIdentity {\n  readonly name: string;\n  readonly layer: ExtensionLayer;\n  readonly version: string;\n  readonly capabilities: readonly ExtensionCapability[];\n  readonly pm_min_version?: string;\n  readonly pm_max_version?: string;\n  readonly source_package?: string;\n}\n\n/**\n * Documents the extension api payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionApi {\n  /** Read-only identity of the extension this `api` was created for. */\n  readonly extension: ExtensionSelfIdentity;\n  registerCommand(command: string, override: CommandOverride): void;\n  registerCommand(definition: CommandDefinition): void;\n  registerParser(command: string, override: ParserOverride): void;\n  registerPreflight(override: PreflightOverride): void;\n  registerService(service: ExtensionServiceName, override: ServiceOverride): void;\n  registerFlags(targetCommand: string, flags: FlagDefinition[]): void;\n  registerItemFields(fields: SchemaFieldDefinition[]): void;\n  registerItemTypes(types: SchemaItemTypeDefinition[]): void;\n  registerMigration(definition: SchemaMigrationDefinition): void;\n  registerProfile(profile: ProjectProfileRegistrationInput): void;\n  registerRenderer(format: OutputRendererFormat, renderer: RendererOverride): void;\n  registerImporter(name: string, importer: Importer, options?: ImportExportRegistrationOptions): void;\n  registerExporter(name: string, exporter: Exporter, options?: ImportExportRegistrationOptions): void;\n  registerSearchProvider(provider: SearchProviderDefinition): void;\n  registerVectorStoreAdapter(adapter: VectorStoreAdapterDefinition): void;\n  hooks: {\n    beforeCommand(hook: BeforeCommandHook): void;\n    afterCommand(hook: AfterCommandHook): void;\n    onWrite(hook: OnWriteHook): void;\n    onRead(hook: OnReadHook): void;\n    onIndex(hook: OnIndexHook): void;\n  };\n}\n\n/**\n * Documents the failed extension activation payload exchanged by command, SDK, and package integrations.\n */\nexport interface FailedExtensionActivation {\n  layer: ExtensionLayer;\n  name: string;\n  entry_path: string;\n  error: string;\n  trace?: ExtensionActivationFailureTrace;\n}\n\n/**\n * Documents the extension activation failure trace payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionActivationFailureTrace {\n  method: string;\n  /** `-1` means the failure happened before a numbered registration was accepted. */\n  registration_index: number;\n  command?: string;\n  capability?: ExtensionCapability;\n  missing_capability?: ExtensionCapability;\n  expected_schema: string;\n  received?: unknown;\n  hint?: string;\n}\n\n/**\n * Documents the extension activation result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionActivationResult {\n  hooks: ExtensionHookRegistry;\n  commands: ExtensionCommandRegistry;\n  parsers: ExtensionParserRegistry;\n  preflight: ExtensionPreflightRegistry;\n  services: ExtensionServiceRegistry;\n  renderers: ExtensionRendererRegistry;\n  registrations: ExtensionRegistrationRegistry;\n  failed: FailedExtensionActivation[];\n  warnings: string[];\n  hook_counts: {\n    before_command: number;\n    after_command: number;\n    on_write: number;\n    on_read: number;\n    on_index: number;\n  };\n  command_override_count: number;\n  command_handler_count: number;\n  parser_override_count: number;\n  preflight_override_count: number;\n  service_override_count: number;\n  renderer_override_count: number;\n  registration_counts: ExtensionRegistrationCounts;\n}\n\n/**\n * Documents the extension candidate payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionCandidate {\n  layer: ExtensionLayer;\n  directory: string;\n  manifest_path: string;\n  entry_path: string;\n  manifest: ExtensionManifest;\n  source_package?: string;\n}\n\n/**\n * Documents the extension layer scan result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionLayerScanResult {\n  diagnostics: ExtensionDiagnostic[];\n  warnings: string[];\n  candidates: ExtensionCandidate[];\n}\n\n/**\n * Documents the scanned extension directory payload exchanged by command, SDK, and package integrations.\n */\nexport interface ScannedExtensionDirectory {\n  diagnostic: ExtensionDiagnostic;\n  warnings: string[];\n  candidate: ExtensionCandidate | null;\n}\n\n/**\n * Documents the legacy extension capability alias mapping payload exchanged by command, SDK, and package integrations.\n */\nexport interface LegacyExtensionCapabilityAliasMapping {\n  alias: string;\n  target: ExtensionCapability;\n}\n\n/**\n * Documents the discover extensions options payload exchanged by command, SDK, and package integrations.\n */\nexport interface DiscoverExtensionsOptions {\n  pmRoot: string;\n  settings: PmSettings;\n  cwd?: string;\n  noExtensions?: boolean;\n  reload_token?: string;\n  cache_bust?: boolean;\n}\n\n/**\n * Documents the activatable extension payload exchanged by command, SDK, and package integrations.\n */\nexport interface ActivatableExtension {\n  activate: (api: ExtensionApi) => void | Promise<void>;\n  /**\n   * Optional teardown lifecycle hook, analogous to VS Code's `deactivate`\n   * export. Invoked when the host tears the extension down — on long-running\n   * MCP-server reload between requests, or via the `deactivateExtensions`\n   * primitive — so an extension can close connections, clear timers, and\n   * release buffers it opened during `activate`.\n   */\n  deactivate?: () => void | Promise<void>;\n}\n\n/**\n * Documents the extension deactivation failure payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionDeactivationFailure {\n  layer: ExtensionLayer;\n  name: string;\n  error: string;\n}\n\n/**\n * Documents the extension deactivation options payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionDeactivationOptions {\n  /**\n   * Maximum time to wait for each extension's `deactivate` hook. Defaults to\n   * 5000ms so a hanging teardown cannot block host shutdown or reload. Set to\n   * 0 or Infinity only when the host intentionally wants to wait indefinitely.\n   */\n  deactivate_timeout_ms?: number;\n}\n\n/**\n * Documents the extension deactivation result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExtensionDeactivationResult {\n  /** Count of loaded extensions whose `deactivate` hook ran without throwing. */\n  deactivated: number;\n  warnings: string[];\n  failed: ExtensionDeactivationFailure[];\n}\n\n/**\n * Documents the service override result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ServiceOverrideResult {\n  handled: boolean;\n  result: unknown;\n  warnings: string[];\n}\n\n/**\n * Documents the command override result payload exchanged by command, SDK, and package integrations.\n */\nexport interface CommandOverrideResult {\n  overridden: boolean;\n  result: unknown;\n  warnings: string[];\n}\n\n/**\n * Documents the command handler result payload exchanged by command, SDK, and package integrations.\n */\nexport interface CommandHandlerResult {\n  handled: boolean;\n  result: unknown;\n  warnings: string[];\n  /**\n   * Human-readable, single-line, length-bounded message describing why an\n   * extension command handler failed. Surfaced to the user/CI so the real cause\n   * (e.g. \"Changelog is out of date: CHANGELOG.md\") is visible instead of only\n   * the opaque `extension_command_handler_failed` warning code.\n   */\n  errorMessage?: string;\n}\n\n/**\n * Documents the parser override result payload exchanged by command, SDK, and package integrations.\n */\nexport interface ParserOverrideResult {\n  overridden: boolean;\n  context: CommandHandlerContext;\n  warnings: string[];\n}\n\n/**\n * Documents the preflight override result payload exchanged by command, SDK, and package integrations.\n */\nexport interface PreflightOverrideResult {\n  overridden: boolean;\n  context: CommandHandlerContext;\n  decision: PreflightRuntimeDecision;\n  warnings: string[];\n}\n\n/**\n * Documents the renderer override result payload exchanged by command, SDK, and package integrations.\n */\nexport interface RendererOverrideResult {\n  overridden: boolean;\n  rendered: string | null;\n  warnings: string[];\n}\n\n/**\n * Documents the unknown extension capability warning details payload exchanged by command, SDK, and package integrations.\n */\nexport interface UnknownExtensionCapabilityWarningDetails {\n  layer: ExtensionLayer;\n  name: string;\n  capability: string;\n  allowed_capabilities: string[];\n  capability_contract_version: number;\n  suggested_capability?: string;\n  suggestion_source?: \"legacy_alias\" | \"nearest_match\";\n  legacy_alias_target?: string;\n}\n"],"names":[],"mappings":";;AAgBA,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,UAAU;IACV,WAAW;IACX,OAAO;IACP,QAAQ;IACR,WAAW;IACX,QAAQ;IACR,QAAQ;IACR,WAAW;IACX,UAAU;CACF,CAAC;AAKX,MAAM,CAAC,MAAM,qCAAqC,GAAG,CAAC,CAAC;AACvD,MAAM,CAAC,MAAM,mCAAmC,GAAkD,MAAM,CAAC,MAAM,CAAC;IAC9G,SAAS,EAAE,QAAQ;IACnB,UAAU,EAAE,QAAQ;CACrB,CAAC,CAAC;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,MAAM,CAAC,MAAM,CAAC;IACzD,OAAO,EAAE,qCAAqC;IAC9C,YAAY,EAAE,CAAC,GAAG,4BAA4B,CAAC;IAC/C,cAAc,EAAE,EAAE,GAAG,mCAAmC,EAAE;CAC3D,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAKhF,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAK/E,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,CAAU,CAAC;AAM1F,MAAM,CAAC,MAAM,mCAAmC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAU,CAAC;AAe9E,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,mBAAmB;IACnB,kBAAkB;IAClB,qBAAqB;IACrB,oBAAoB;IACpB,eAAe;IACf,cAAc;IACd,eAAe;IACf,cAAc;IACd,mBAAmB;IACnB,kBAAkB;IAClB,mBAAmB;IACnB,iBAAiB;IACjB,iBAAiB;IACjB,oBAAoB;IACpB,mBAAmB;IACnB,oBAAoB;IACpB,oBAAoB;IACpB,oBAAoB;IACpB,iBAAiB;IACjB,oBAAoB;CACZ,CAAC;AAMX,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,eAAe;IACf,cAAc;IACd,aAAa;IACb,cAAc;IACd,cAAc;IACd,gBAAgB;IAChB,kBAAkB;IAClB,mBAAmB;CACX,CAAC;AA0DX;;GAEG;AACH,MAAM,UAAU,sCAAsC;IACpD,OAAO;QACL,IAAI,EAAE,KAAK;QACX,UAAU,EAAE,KAAK;QACjB,kBAAkB,EAAE,KAAK;QACzB,kBAAkB,EAAE,EAAE;QACtB,uBAAuB,EAAE,MAAM;QAC/B,kBAAkB,EAAE,EAAE;QACtB,kBAAkB,EAAE,EAAE;QACtB,oBAAoB,EAAE,EAAE;QACxB,oBAAoB,EAAE,EAAE;QACxB,gBAAgB,EAAE,EAAE;QACpB,gBAAgB,EAAE,EAAE;QACpB,gBAAgB,EAAE,EAAE;QACpB,gBAAgB,EAAE,EAAE;QACpB,eAAe,EAAE,EAAE;QACnB,eAAe,EAAE,EAAE;QACnB,gBAAgB,EAAE,EAAE;QACpB,gBAAgB,EAAE,EAAE;QACpB,mBAAmB,EAAE,EAAE;KACxB,CAAC;AACJ,CAAC","debugId":"75a0fe7b-f263-5311-acda-2a527cb2d17d"}

package/dist/core/history/history-rewrite.d.ts

@@ -2,6 +2,7 @@ import type { ItemTypeRegistry } from "../item/type-registry.js";
 import { locateItem, readLocatedItem } from "../store/item-store.js";
 import type { ItemDocument, PmSettings } from "../../types/index.js";
 type LoadedItem = Awaited<ReturnType<typeof readLocatedItem>>;
+type HistoryRawWriter = (filePath: string, content: string) => Promise<void>;
 /**
  * Documents the history rewrite subject payload exchanged by command, SDK, and package integrations.
  */
@@ -70,6 +71,15 @@ export interface ExecuteHistoryRewriteParams {
     applyRewrite: (verified: VerifiedHistoryRewriteState) => Promise<void>;
     applyPostRewrite?: (verified: VerifiedHistoryRewriteState) => Promise<string[]>;
 }
+/**
+ * Writes the rewritten history stream and restores the under-lock snapshot on failure.
+ */
+export declare function writeHistoryRawWithRollback(params: {
+    historyPath: string;
+    nextHistoryRaw: string;
+    historyRawUnderLock: string | null;
+    writeHistoryRaw?: HistoryRawWriter;
+}): Promise<void>;
 /**
  * Shared lock/verify/ownership orchestration for history-rewrite commands.
  * Callers provide the operation-specific write/rollback logic and optional

package/dist/core/history/history-rewrite.js

@@ -4,8 +4,9 @@
  * Implements append-only history and replay behavior for History Rewrite.
  */
 
-!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]="665cdb28-cf61-56a3-a037-708d2445359d")}catch(e){}}();
-import { readFileIfExists } from "../fs/fs-utils.js";
+!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]="f03392a5-662f-5a2d-97c6-7a51a575dd39")}catch(e){}}();
+import fs from "node:fs/promises";
+import { readFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
 import { acquireLock } from "../lock/lock.js";
 import { EXIT_CODE } from "../shared/constants.js";
 import { PmCliError } from "../shared/errors.js";
@@ -50,6 +51,29 @@ export async function verifyHistoryRewriteNoDrift(params) {
     }
     return { historyRawUnderLock, locatedUnderLock, loadedItemUnderLock };
 }
+/**
+ * Writes the rewritten history stream and restores the under-lock snapshot on failure.
+ */
+export async function writeHistoryRawWithRollback(params) {
+    const writeHistoryRaw = params.writeHistoryRaw ?? writeFileAtomic;
+    try {
+        await writeHistoryRaw(params.historyPath, params.nextHistoryRaw);
+    }
+    catch (error) {
+        try {
+            if (params.historyRawUnderLock === null) {
+                await fs.rm(params.historyPath, { force: true });
+            }
+            else {
+                await writeHistoryRaw(params.historyPath, params.historyRawUnderLock);
+            }
+        }
+        catch (rollbackError) {
+            throw new AggregateError([error, rollbackError], `History rewrite failed and rollback also failed: ${String(error)}`);
+        }
+        throw error;
+    }
+}
 /**
  * Shared lock/verify/ownership orchestration for history-rewrite commands.
  * Callers provide the operation-specific write/rollback logic and optional
@@ -86,4 +110,4 @@ export async function executeHistoryRewrite(params) {
     }
 }
 //# sourceMappingURL=history-rewrite.js.map
-//# debugId=665cdb28-cf61-56a3-a037-708d2445359d
+//# debugId=f03392a5-662f-5a2d-97c6-7a51a575dd39

package/dist/core/history/history-rewrite.js.map

@@ -1 +1 @@
-{"version":3,"file":"history-rewrite.js","sources":["core/history/history-rewrite.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/history/history-rewrite\n *\n * Implements append-only history and replay behavior for History Rewrite.\n */\nimport { readFileIfExists } from \"../fs/fs-utils.js\";\nimport type { ItemTypeRegistry } from \"../item/type-registry.js\";\nimport { acquireLock } from \"../lock/lock.js\";\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\nimport { locateItem, readLocatedItem } from \"../store/item-store.js\";\nimport { resolveGovernanceKnobs } from \"../store/settings.js\";\nimport type { ItemDocument, PmSettings } from \"../../types/index.js\";\n\ntype LoadedItem = Awaited<ReturnType<typeof readLocatedItem>>;\n\n/**\n * Documents the history rewrite subject payload exchanged by command, SDK, and package integrations.\n */\nexport interface HistoryRewriteSubject {\n  id: string;\n  historyPath: string;\n}\n\n/**\n * Documents the history rewrite ownership params payload exchanged by command, SDK, and package integrations.\n */\nexport interface HistoryRewriteOwnershipParams {\n  itemDocument: ItemDocument | null;\n  subjectId: string;\n  author: string;\n  force: boolean | undefined;\n  settings: PmSettings;\n}\n\n/**\n * Apply ownership_enforcement governance to a history-rewriting operation.\n * Returns the warning(s) the caller should append (empty when no conflict or strict-throws).\n * Throws PmCliError(CONFLICT) in strict mode when the assignee conflicts and --force is not set.\n */\nexport function checkHistoryRewriteOwnership(params: HistoryRewriteOwnershipParams): string[] {\n  if (!params.itemDocument) return [];\n  const assigned = params.itemDocument.metadata?.assignee?.trim();\n  if (!assigned || assigned === params.author || params.force) return [];\n\n  const governance = resolveGovernanceKnobs(params.settings);\n  if (governance.ownership_enforcement === \"strict\") {\n    throw new PmCliError(\n      `Item ${params.subjectId} is assigned to ${assigned}. Use --force to override.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  if (governance.ownership_enforcement === \"warn\") {\n    return [`ownership_warning:assignee_conflict:${params.subjectId}:${assigned}`];\n  }\n  return [];\n}\n\n/**\n * Documents the verify history rewrite drift params payload exchanged by command, SDK, and package integrations.\n */\nexport interface VerifyHistoryRewriteDriftParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in the conflict message (e.g. \"history-redact\"). */\n  operation: string;\n}\n\n/**\n * Documents the verified history rewrite state payload exchanged by command, SDK, and package integrations.\n */\nexport interface VerifiedHistoryRewriteState {\n  historyRawUnderLock: string | null;\n  locatedUnderLock: Awaited<ReturnType<typeof locateItem>>;\n  loadedItemUnderLock: LoadedItem | null;\n}\n\n/**\n * Re-read the history stream and the located item document under the acquired lock and\n * compare both with the pre-lock raw snapshots. Throws PmCliError(CONFLICT) if either\n * diverged while waiting for the lock so the caller surfaces an actionable retry.\n */\nexport async function verifyHistoryRewriteNoDrift(\n  params: VerifyHistoryRewriteDriftParams,\n): Promise<VerifiedHistoryRewriteState> {\n  const historyRawUnderLock = await readFileIfExists(params.subject.historyPath);\n  if (historyRawUnderLock !== params.historyRawBeforeLock) {\n    throw new PmCliError(\n      `History for ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  const locatedUnderLock = await locateItem(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.id_prefix,\n    params.settings.item_format,\n    params.typeRegistry.type_to_folder,\n  );\n  const loadedItemUnderLock = locatedUnderLock\n    ? await readLocatedItem(locatedUnderLock, { schema: params.settings.schema })\n    : null;\n  if ((loadedItemUnderLock?.raw ?? null) !== (params.currentItemRawBeforeLock ?? null)) {\n    throw new PmCliError(\n      `Item ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  return { historyRawUnderLock, locatedUnderLock, loadedItemUnderLock };\n}\n\n/**\n * Documents the execute history rewrite params payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExecuteHistoryRewriteParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in conflict guidance (e.g. \"history-redact\"). */\n  operation: string;\n  author: string;\n  force: boolean | undefined;\n  itemDocument: ItemDocument | null;\n  applyRewrite: (verified: VerifiedHistoryRewriteState) => Promise<void>;\n  applyPostRewrite?: (verified: VerifiedHistoryRewriteState) => Promise<string[]>;\n}\n\n/**\n * Shared lock/verify/ownership orchestration for history-rewrite commands.\n * Callers provide the operation-specific write/rollback logic and optional\n * post-write hook execution while this helper enforces the common governance +\n * lock sequencing contract.\n */\nexport async function executeHistoryRewrite(params: ExecuteHistoryRewriteParams): Promise<string[]> {\n  const warnings = [...checkHistoryRewriteOwnership({\n    itemDocument: params.itemDocument,\n    subjectId: params.subject.id,\n    author: params.author,\n    force: params.force,\n    settings: params.settings,\n  })];\n  const releaseLock = await acquireLock(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.locks.ttl_seconds,\n    params.author,\n    Boolean(params.force),\n    params.settings.governance.force_required_for_stale_lock,\n  );\n  try {\n    const verified = await verifyHistoryRewriteNoDrift({\n      pmRoot: params.pmRoot,\n      subject: params.subject,\n      settings: params.settings,\n      typeRegistry: params.typeRegistry,\n      historyRawBeforeLock: params.historyRawBeforeLock,\n      currentItemRawBeforeLock: params.currentItemRawBeforeLock,\n      operation: params.operation,\n    });\n    await params.applyRewrite(verified);\n    if (params.applyPostRewrite) {\n      warnings.push(...(await params.applyPostRewrite(verified)));\n    }\n    return warnings;\n  } finally {\n    await releaseLock();\n  }\n}\n"],"names":[],"mappings":"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","debugId":"665cdb28-cf61-56a3-a037-708d2445359d"}
+{"version":3,"file":"history-rewrite.js","sources":["core/history/history-rewrite.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/history/history-rewrite\n *\n * Implements append-only history and replay behavior for History Rewrite.\n */\nimport fs from \"node:fs/promises\";\nimport { readFileIfExists, writeFileAtomic } from \"../fs/fs-utils.js\";\nimport type { ItemTypeRegistry } from \"../item/type-registry.js\";\nimport { acquireLock } from \"../lock/lock.js\";\nimport { EXIT_CODE } from \"../shared/constants.js\";\nimport { PmCliError } from \"../shared/errors.js\";\nimport { locateItem, readLocatedItem } from \"../store/item-store.js\";\nimport { resolveGovernanceKnobs } from \"../store/settings.js\";\nimport type { ItemDocument, PmSettings } from \"../../types/index.js\";\n\ntype LoadedItem = Awaited<ReturnType<typeof readLocatedItem>>;\ntype HistoryRawWriter = (filePath: string, content: string) => Promise<void>;\n\n/**\n * Documents the history rewrite subject payload exchanged by command, SDK, and package integrations.\n */\nexport interface HistoryRewriteSubject {\n  id: string;\n  historyPath: string;\n}\n\n/**\n * Documents the history rewrite ownership params payload exchanged by command, SDK, and package integrations.\n */\nexport interface HistoryRewriteOwnershipParams {\n  itemDocument: ItemDocument | null;\n  subjectId: string;\n  author: string;\n  force: boolean | undefined;\n  settings: PmSettings;\n}\n\n/**\n * Apply ownership_enforcement governance to a history-rewriting operation.\n * Returns the warning(s) the caller should append (empty when no conflict or strict-throws).\n * Throws PmCliError(CONFLICT) in strict mode when the assignee conflicts and --force is not set.\n */\nexport function checkHistoryRewriteOwnership(params: HistoryRewriteOwnershipParams): string[] {\n  if (!params.itemDocument) return [];\n  const assigned = params.itemDocument.metadata?.assignee?.trim();\n  if (!assigned || assigned === params.author || params.force) return [];\n\n  const governance = resolveGovernanceKnobs(params.settings);\n  if (governance.ownership_enforcement === \"strict\") {\n    throw new PmCliError(\n      `Item ${params.subjectId} is assigned to ${assigned}. Use --force to override.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  if (governance.ownership_enforcement === \"warn\") {\n    return [`ownership_warning:assignee_conflict:${params.subjectId}:${assigned}`];\n  }\n  return [];\n}\n\n/**\n * Documents the verify history rewrite drift params payload exchanged by command, SDK, and package integrations.\n */\nexport interface VerifyHistoryRewriteDriftParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in the conflict message (e.g. \"history-redact\"). */\n  operation: string;\n}\n\n/**\n * Documents the verified history rewrite state payload exchanged by command, SDK, and package integrations.\n */\nexport interface VerifiedHistoryRewriteState {\n  historyRawUnderLock: string | null;\n  locatedUnderLock: Awaited<ReturnType<typeof locateItem>>;\n  loadedItemUnderLock: LoadedItem | null;\n}\n\n/**\n * Re-read the history stream and the located item document under the acquired lock and\n * compare both with the pre-lock raw snapshots. Throws PmCliError(CONFLICT) if either\n * diverged while waiting for the lock so the caller surfaces an actionable retry.\n */\nexport async function verifyHistoryRewriteNoDrift(\n  params: VerifyHistoryRewriteDriftParams,\n): Promise<VerifiedHistoryRewriteState> {\n  const historyRawUnderLock = await readFileIfExists(params.subject.historyPath);\n  if (historyRawUnderLock !== params.historyRawBeforeLock) {\n    throw new PmCliError(\n      `History for ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  const locatedUnderLock = await locateItem(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.id_prefix,\n    params.settings.item_format,\n    params.typeRegistry.type_to_folder,\n  );\n  const loadedItemUnderLock = locatedUnderLock\n    ? await readLocatedItem(locatedUnderLock, { schema: params.settings.schema })\n    : null;\n  if ((loadedItemUnderLock?.raw ?? null) !== (params.currentItemRawBeforeLock ?? null)) {\n    throw new PmCliError(\n      `Item ${params.subject.id} changed while waiting for lock; retry ${params.operation}.`,\n      EXIT_CODE.CONFLICT,\n    );\n  }\n  return { historyRawUnderLock, locatedUnderLock, loadedItemUnderLock };\n}\n\n/**\n * Documents the execute history rewrite params payload exchanged by command, SDK, and package integrations.\n */\nexport interface ExecuteHistoryRewriteParams {\n  pmRoot: string;\n  subject: HistoryRewriteSubject;\n  settings: PmSettings;\n  typeRegistry: ItemTypeRegistry;\n  historyRawBeforeLock: string | null;\n  currentItemRawBeforeLock: string | null;\n  /** Short operation name used in conflict guidance (e.g. \"history-redact\"). */\n  operation: string;\n  author: string;\n  force: boolean | undefined;\n  itemDocument: ItemDocument | null;\n  applyRewrite: (verified: VerifiedHistoryRewriteState) => Promise<void>;\n  applyPostRewrite?: (verified: VerifiedHistoryRewriteState) => Promise<string[]>;\n}\n\n/**\n * Writes the rewritten history stream and restores the under-lock snapshot on failure.\n */\nexport async function writeHistoryRawWithRollback(params: {\n  historyPath: string;\n  nextHistoryRaw: string;\n  historyRawUnderLock: string | null;\n  writeHistoryRaw?: HistoryRawWriter;\n}): Promise<void> {\n  const writeHistoryRaw = params.writeHistoryRaw ?? writeFileAtomic;\n  try {\n    await writeHistoryRaw(params.historyPath, params.nextHistoryRaw);\n  } catch (error) {\n    try {\n      if (params.historyRawUnderLock === null) {\n        await fs.rm(params.historyPath, { force: true });\n      } else {\n        await writeHistoryRaw(params.historyPath, params.historyRawUnderLock);\n      }\n    } catch (rollbackError) {\n      throw new AggregateError(\n        [error, rollbackError],\n        `History rewrite failed and rollback also failed: ${String(error)}`,\n      );\n    }\n    throw error;\n  }\n}\n\n/**\n * Shared lock/verify/ownership orchestration for history-rewrite commands.\n * Callers provide the operation-specific write/rollback logic and optional\n * post-write hook execution while this helper enforces the common governance +\n * lock sequencing contract.\n */\nexport async function executeHistoryRewrite(params: ExecuteHistoryRewriteParams): Promise<string[]> {\n  const warnings = [...checkHistoryRewriteOwnership({\n    itemDocument: params.itemDocument,\n    subjectId: params.subject.id,\n    author: params.author,\n    force: params.force,\n    settings: params.settings,\n  })];\n  const releaseLock = await acquireLock(\n    params.pmRoot,\n    params.subject.id,\n    params.settings.locks.ttl_seconds,\n    params.author,\n    Boolean(params.force),\n    params.settings.governance.force_required_for_stale_lock,\n  );\n  try {\n    const verified = await verifyHistoryRewriteNoDrift({\n      pmRoot: params.pmRoot,\n      subject: params.subject,\n      settings: params.settings,\n      typeRegistry: params.typeRegistry,\n      historyRawBeforeLock: params.historyRawBeforeLock,\n      currentItemRawBeforeLock: params.currentItemRawBeforeLock,\n      operation: params.operation,\n    });\n    await params.applyRewrite(verified);\n    if (params.applyPostRewrite) {\n      warnings.push(...(await params.applyPostRewrite(verified)));\n    }\n    return warnings;\n  } finally {\n    await releaseLock();\n  }\n}\n"],"names":[],"mappings":"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","debugId":"f03392a5-662f-5a2d-97c6-7a51a575dd39"}

package/dist/core/item/type-registry.d.ts

@@ -6,6 +6,7 @@ export declare const DEFAULT_REQUIRED_CREATE_REPEATABLES: readonly ["dep", "comm
  * Restricts command option policy command values accepted by command, SDK, and storage contracts.
  */
 export type CommandOptionPolicyCommand = "create" | "update";
+export declare const COMMON_MUTATION_COMMAND_OPTION_KEYS: readonly ["deadline", "estimatedMinutes", "acceptanceCriteria", "definitionOfReady", "order", "goal", "objective", "value", "impact", "outcome", "whyNow", "assignee", "parent", "reviewer", "risk", "confidence", "sprint", "release", "blockedBy", "blockedReason", "unblockNote", "reporter", "severity", "environment", "reproSteps", "resolution", "expectedResult", "actualResult", "affectedVersion", "fixedVersion", "component", "regression", "customerImpact"];
 /**
  * Documents the command option policy state payload exchanged by command, SDK, and package integrations.
  */