@unbrained/pm-cli 2026.7.19 → 2026.7.20

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  ItemMetadata,\n  ItemStatus,\n  PmSettings,\n} from \"../../types/index.js\";\nimport type { GlobalOptions } from \"../shared/command-types.js\";\nimport type {\n  ProjectProfileDefinition,\n  ProjectProfileRegistrationInput,\n} from \"../profile/profile-presets.js\";\nimport type { RelationshipKindDefinition } from \"../../sdk/relationships.js\";\nimport type { PmClient } from \"../../sdk/runtime.js\";\nimport type {\n  GetItemAtResult,\n} from \"../../sdk/history-read.js\";\nimport type {\n  RelationshipEventStore,\n} from \"../../sdk/relationship-history.js\";\nimport type {\n  CommitWorkspaceTransactionOptions,\n  WorkspaceTransactionCommitResult,\n} from \"../../sdk/workspace-transaction.js\";\n\n/** Public contract for known extension capabilities, shared by SDK and presentation-layer consumers. */\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/** Restricts extension capability values accepted by command, SDK, and storage contracts. */\nexport type ExtensionCapability = (typeof KNOWN_EXTENSION_CAPABILITIES)[number];\n/** Public contract for extension capability contract version, shared by SDK and presentation-layer consumers. */\nexport const EXTENSION_CAPABILITY_CONTRACT_VERSION = 2;\n/** Public contract for extension capability legacy aliases, shared by SDK and presentation-layer consumers. */\nexport const EXTENSION_CAPABILITY_LEGACY_ALIASES: Readonly<\n  Record<string, ExtensionCapability>\n> = Object.freeze({\n  migration: \"schema\",\n  validation: \"schema\",\n});\n/** Public contract for extension capability contract, shared by SDK and presentation-layer consumers. */\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\n/** Public contract for known extension policy modes, shared by SDK and presentation-layer consumers. */\nexport const KNOWN_EXTENSION_POLICY_MODES = [\"off\", \"warn\", \"enforce\"] as const;\n/** Restricts extension policy mode values accepted by command, SDK, and storage contracts. */\nexport type ExtensionPolicyMode = (typeof KNOWN_EXTENSION_POLICY_MODES)[number];\n/** Public contract for known extension trust modes, shared by SDK and presentation-layer consumers. */\nexport const KNOWN_EXTENSION_TRUST_MODES = [\"off\", \"warn\", \"enforce\"] as const;\n/** Restricts extension trust mode values accepted by command, SDK, and storage contracts. */\nexport type ExtensionTrustMode = (typeof KNOWN_EXTENSION_TRUST_MODES)[number];\n/** Public contract for known extension sandbox profiles, shared by SDK and presentation-layer consumers. */\nexport const KNOWN_EXTENSION_SANDBOX_PROFILES = [\n  \"none\",\n  \"restricted\",\n  \"strict\",\n] as const;\n/** Restricts extension sandbox profile values accepted by command, SDK, and storage contracts. */\nexport type ExtensionSandboxProfile =\n  (typeof KNOWN_EXTENSION_SANDBOX_PROFILES)[number];\n\n/** Public contract for known pm max version exceeded modes, shared by SDK and presentation-layer consumers. */\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 =\n  (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  /** Value that configures or reports global for this contract. */\n  global?: PmMaxVersionExceededMode;\n  /** Value that configures or reports project for this contract. */\n  project?: PmMaxVersionExceededMode;\n}\n/** Settings value for `extensions.policy.pm_max_version_exceeded_mode`: either a single mode applied to both layers, or a per-layer override map. Unset (and any unset layer key) defaults to `\"block\"`. */\nexport type PmMaxVersionExceededModeSetting =\n  | PmMaxVersionExceededMode\n  | PmMaxVersionExceededModeByLayer;\n\n/** Public contract for known extension policy surfaces, shared by SDK and presentation-layer consumers. */\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.relationshipkinds\",\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/** Restricts extension policy surface values accepted by command, SDK, and storage contracts. */\nexport type ExtensionPolicySurface =\n  (typeof KNOWN_EXTENSION_POLICY_SURFACES)[number];\n\n/** Public contract for known extension service names, shared by SDK and presentation-layer consumers. */\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  \"context_relevance\",\n  \"command_result\",\n] as const;\n/** Restricts extension service name values accepted by command, SDK, and storage contracts. */\nexport type ExtensionServiceName =\n  (typeof KNOWN_EXTENSION_SERVICE_NAMES)[number];\n\n/** Documents the extension provenance metadata payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionProvenanceMetadata {\n  /** Value that configures or reports source for this contract. */\n  source?: string;\n  /** Value that configures or reports signature for this contract. */\n  signature?: string;\n  /** Value that configures or reports attestation for this contract. */\n  attestation?: string;\n  /** Value that configures or reports verified for this contract. */\n  verified?: boolean;\n}\n\n/** Documents the extension runtime permission declaration payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionRuntimePermissionDeclaration {\n  /** Value that configures or reports fs read for this contract. */\n  fs_read?: boolean;\n  /** Value that configures or reports fs write for this contract. */\n  fs_write?: boolean;\n  /** Value that configures or reports network for this contract. */\n  network?: boolean;\n  /** Value that configures or reports env read for this contract. */\n  env_read?: boolean;\n  /** Value that configures or reports env write for this contract. */\n  env_write?: boolean;\n  /** Value that configures or reports process spawn for this contract. */\n  process_spawn?: boolean;\n}\n\n/** Documents the extension activation metadata payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionActivationMetadata {\n  /** Value that configures or reports commands for this contract. */\n  commands?: string[];\n}\n\n/** Restricts extension policy override values accepted by command, SDK, and storage contracts. */\nexport type ExtensionPolicyOverride = ExtensionPolicyOverrideSettings;\n/** Extension governance policy as read from / serialized to settings. Extends the stored settings shape with `pm_max_version_exceeded_mode` (pm-k5e8), which relaxes the default-BLOCK on `pm_max_version` violations to warn-only — globally or per extension layer. */\nexport type ExtensionGovernancePolicy = ExtensionPolicySettings & {\n  pm_max_version_exceeded_mode?: PmMaxVersionExceededModeSetting;\n};\n\n/** Documents the extension manifest engines payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionManifestEngines {\n  /** Value that configures or reports pm for this contract. */\n  pm?: string;\n  /** Value that configures or reports node for this contract. */\n  node?: string;\n  [engine: string]: string | undefined;\n}\n\n/** Implements create default extension governance policy for the public runtime surface of this module. */\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/** Restricts extension layer values accepted by command, SDK, and storage contracts. */\nexport type ExtensionLayer = \"global\" | \"project\";\n/** Restricts extension status values accepted by command, SDK, and storage contracts. */\nexport type ExtensionStatus = \"ok\" | \"warn\";\n\n/** Documents the extension manifest payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionManifest {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports version for this contract. */\n  version: string;\n  /** Value that configures or reports entry for this contract. */\n  entry: string;\n  /** Value that configures or reports priority for this contract. */\n  priority: number;\n  /** Value that configures or reports capabilities for this contract. */\n  capabilities: string[];\n  /** Value that configures or reports manifest version for this contract. */\n  manifest_version?: number;\n  /** Value that configures or reports pm min version for this contract. */\n  pm_min_version?: string;\n  /** Value that configures or reports pm max version for this contract. */\n  pm_max_version?: string;\n  /** Value that configures or reports engines for this contract. */\n  engines?: ExtensionManifestEngines;\n  /** Value that configures or reports trusted for this contract. */\n  trusted?: boolean;\n  /** Value that configures or reports provenance for this contract. */\n  provenance?: ExtensionProvenanceMetadata;\n  /** Value that configures or reports sandbox profile for this contract. */\n  sandbox_profile?: ExtensionSandboxProfile;\n  /** Value that configures or reports permissions for this contract. */\n  permissions?: ExtensionRuntimePermissionDeclaration;\n  /** Value that configures or reports activation for this contract. */\n  activation?: ExtensionActivationMetadata;\n  /** Value that configures or reports legacy capability aliases for this contract. */\n  legacy_capability_aliases?: LegacyExtensionCapabilityAliasMapping[];\n}\n\n/** Documents the extension diagnostic payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionDiagnostic {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports directory for this contract. */\n  directory: string;\n  /** Filesystem path used for manifest resolution. */\n  manifest_path: string;\n  /** Value that configures or reports name for this contract. */\n  name: string | null;\n  /** Value that configures or reports version for this contract. */\n  version: string | null;\n  /** Value that configures or reports entry for this contract. */\n  entry: string | null;\n  /** Value that configures or reports priority for this contract. */\n  priority: number | null;\n  /** Filesystem path used for entry resolution. */\n  entry_path: string | null;\n  /** Whether enabled applies to this operation. */\n  enabled: boolean | null;\n  /** Lifecycle state reported for status. */\n  status: ExtensionStatus;\n}\n\n/** Documents the effective extension payload exchanged by command, SDK, and package integrations. */\nexport interface EffectiveExtension {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports directory for this contract. */\n  directory: string;\n  /** Filesystem path used for manifest resolution. */\n  manifest_path: string;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports source package for this contract. */\n  source_package?: string;\n  /** Value that configures or reports version for this contract. */\n  version: string;\n  /** Value that configures or reports entry for this contract. */\n  entry: string;\n  /** Value that configures or reports priority for this contract. */\n  priority: number;\n  /** Filesystem path used for entry resolution. */\n  entry_path: string;\n  /** Value that configures or reports manifest version for this contract. */\n  manifest_version?: number;\n  /** Value that configures or reports pm min version for this contract. */\n  pm_min_version?: string;\n  /** Value that configures or reports pm max version for this contract. */\n  pm_max_version?: string;\n  /** Value that configures or reports engines for this contract. */\n  engines?: ExtensionManifestEngines;\n  /** Value that configures or reports trusted for this contract. */\n  trusted?: boolean;\n  /** Value that configures or reports provenance for this contract. */\n  provenance?: ExtensionProvenanceMetadata;\n  /** Value that configures or reports sandbox profile for this contract. */\n  sandbox_profile?: ExtensionSandboxProfile;\n  /** Value that configures or reports permissions for this contract. */\n  permissions?: ExtensionRuntimePermissionDeclaration;\n  /** Value that configures or reports capabilities for this contract. */\n  capabilities?: string[];\n  /** Value that configures or reports activation for this contract. */\n  activation?: ExtensionActivationMetadata;\n}\n\n/** Documents the extension discovery result payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionDiscoveryResult {\n  /** Value that configures or reports disabled by flag for this contract. */\n  disabled_by_flag: boolean;\n  /** Value that configures or reports roots for this contract. */\n  roots: {\n    global: string;\n    project: string;\n  };\n  /** Value that configures or reports configured enabled for this contract. */\n  configured_enabled: string[];\n  /** Value that configures or reports configured disabled for this contract. */\n  configured_disabled: string[];\n  /** Value that configures or reports discovered for this contract. */\n  discovered: ExtensionDiagnostic[];\n  /** Value that configures or reports effective for this contract. */\n  effective: EffectiveExtension[];\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n  /** Value that configures or reports policy for this contract. */\n  policy: ExtensionGovernancePolicy;\n}\n\n/** Documents the loaded extension payload exchanged by command, SDK, and package integrations. */\nexport interface LoadedExtension extends EffectiveExtension {\n  /** Value that configures or reports module for this contract. */\n  module: unknown;\n}\n\n/** Documents the failed extension load payload exchanged by command, SDK, and package integrations. */\nexport interface FailedExtensionLoad {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Filesystem path used for entry resolution. */\n  entry_path: string;\n  /** Value that configures or reports error for this contract. */\n  error: string;\n}\n\n/** Documents the extension load result payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionLoadResult extends ExtensionDiscoveryResult {\n  /** Value that configures or reports loaded for this contract. */\n  loaded: LoadedExtension[];\n  /** Value that configures or reports failed for this contract. */\n  failed: FailedExtensionLoad[];\n}\n\n/** Documents the before command hook context payload exchanged by command, SDK, and package integrations. */\nexport interface BeforeCommandHookContext {\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports args for this contract. */\n  args: string[];\n  /** Value that configures or reports options for this contract. */\n  options?: Record<string, unknown>;\n  /** Value that configures or reports global for this contract. */\n  global?: GlobalOptions;\n  /** Value that configures or reports pm root for this contract. */\n  pm_root: string;\n}\n\n/** Documents the after command hook context payload exchanged by command, SDK, and package integrations. */\nexport interface AfterCommandHookContext extends BeforeCommandHookContext {\n  /** Whether the operation completed without a blocking failure. */\n  ok: boolean;\n  /** Value that configures or reports error for this contract. */\n  error?: string;\n  /** Value that configures or reports result for this contract. */\n  result?: unknown;\n  /** Value that configures or reports affected for this contract. */\n  affected?: AfterCommandAffectedItem[];\n}\n\n/** Documents the after command affected item payload exchanged by command, SDK, and package integrations. */\nexport interface AfterCommandAffectedItem {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports op for this contract. */\n  op?: string;\n  /** Schema type that determines the shape and validation rules for this value. */\n  item_type?: string;\n  /** Lifecycle state reported for previousthe record. */\n  previous_status?: ItemStatus;\n  /** Lifecycle state reported for status. */\n  status?: ItemStatus;\n  /** Value that configures or reports previous for this contract. */\n  previous?: Partial<ItemMetadata>;\n  /** Value that configures or reports current for this contract. */\n  current?: Partial<ItemMetadata>;\n  /** Value that configures or reports changed fields for this contract. */\n  changed_fields?: string[];\n}\n\n/** Documents the on write hook context payload exchanged by command, SDK, and package integrations. */\nexport interface OnWriteHookContext {\n  /** Filesystem path used for path resolution. */\n  path: string;\n  /** Value that configures or reports scope for this contract. */\n  scope: \"project\" | \"global\";\n  /** Value that configures or reports op for this contract. */\n  op: string;\n  /** Value that configures or reports item id for this contract. */\n  item_id?: string;\n  /** Schema type that determines the shape and validation rules for this value. */\n  item_type?: string;\n  /** Value that configures or reports before for this contract. */\n  before?: ItemDocument;\n  /** Value that configures or reports after for this contract. */\n  after?: ItemDocument;\n  /** Value that configures or reports changed fields for this contract. */\n  changed_fields?: string[];\n}\n\n/** Documents the on read hook context payload exchanged by command, SDK, and package integrations. */\nexport interface OnReadHookContext {\n  /** Filesystem path used for path resolution. */\n  path: string;\n  /** Value that configures or reports scope for this contract. */\n  scope: \"project\" | \"global\";\n}\n\n/** Documents the on index hook context payload exchanged by command, SDK, and package integrations. */\nexport interface OnIndexHookContext {\n  /** Value that configures or reports mode for this contract. */\n  mode: string;\n  /** Value that configures or reports total items for this contract. */\n  total_items?: number;\n}\n\n/** Restricts before command hook values accepted by command, SDK, and storage contracts. */\nexport type BeforeCommandHook = (\n  context: BeforeCommandHookContext,\n) => Promise<void> | void;\n/** Restricts after command hook values accepted by command, SDK, and storage contracts. */\nexport type AfterCommandHook = (\n  context: AfterCommandHookContext,\n) => Promise<void> | void;\n/** Restricts on write hook values accepted by command, SDK, and storage contracts. */\nexport type OnWriteHook = (context: OnWriteHookContext) => Promise<void> | void;\n/** Restricts on read hook values accepted by command, SDK, and storage contracts. */\nexport type OnReadHook = (context: OnReadHookContext) => Promise<void> | void;\n/** Restricts on index hook values accepted by command, SDK, and storage contracts. */\nexport type OnIndexHook = (context: OnIndexHookContext) => Promise<void> | void;\n/** Restricts output renderer format values accepted by command, SDK, and storage contracts. */\nexport type OutputRendererFormat = \"toon\" | \"json\";\n/** Restricts command override values accepted by command, SDK, and storage contracts. */\nexport type CommandOverride = (context: CommandOverrideContext) => unknown;\n/** Restricts renderer override values accepted by command, SDK, and storage contracts. */\nexport type RendererOverride = (\n  context: RendererOverrideContext,\n) => string | null | undefined;\n/** Restricts command handler values accepted by command, SDK, and storage contracts. */\nexport type CommandHandler = (context: CommandHandlerContext) => unknown;\n/** Restricts parser override values accepted by command, SDK, and storage contracts. */\nexport type ParserOverride = (\n  context: ParserOverrideContext,\n) => ParserOverrideDelta | Promise<ParserOverrideDelta>;\n/** Restricts preflight override values accepted by command, SDK, and storage contracts. */\nexport type PreflightOverride = (\n  context: PreflightOverrideContext,\n) => PreflightOverrideDelta | Promise<PreflightOverrideDelta>;\n/** Restricts service override values accepted by command, SDK, and storage contracts. */\nexport type ServiceOverride = (context: ServiceOverrideContext) => unknown;\n\n/** Documents the registered extension hook payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionHook<THook> {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports run for this contract. */\n  run: THook;\n}\n\n/** Documents the extension hook registry payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionHookRegistry {\n  /** Value that configures or reports before command for this contract. */\n  beforeCommand: Array<RegisteredExtensionHook<BeforeCommandHook>>;\n  /** Value that configures or reports after command for this contract. */\n  afterCommand: Array<RegisteredExtensionHook<AfterCommandHook>>;\n  /** Value that configures or reports on write for this contract. */\n  onWrite: Array<RegisteredExtensionHook<OnWriteHook>>;\n  /** Value that configures or reports on read for this contract. */\n  onRead: Array<RegisteredExtensionHook<OnReadHook>>;\n  /** Value that configures or reports on index for this contract. */\n  onIndex: Array<RegisteredExtensionHook<OnIndexHook>>;\n}\n\n/** Documents the command override context payload exchanged by command, SDK, and package integrations. */\nexport interface CommandOverrideContext {\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports args for this contract. */\n  args: string[];\n  /** Value that configures or reports options for this contract. */\n  options?: Record<string, unknown>;\n  /** Value that configures or reports global for this contract. */\n  global?: GlobalOptions;\n  /** Value that configures or reports pm root for this contract. */\n  pm_root: string;\n  /** Value that configures or reports result for this contract. */\n  result: unknown;\n}\n\n/** Documents the renderer override context payload exchanged by command, SDK, and package integrations. */\nexport interface RendererOverrideContext {\n  /** Value that configures or reports format for this contract. */\n  format: OutputRendererFormat;\n  /** Value that configures or reports command for this contract. */\n  command?: string;\n  /** Value that configures or reports args for this contract. */\n  args?: string[];\n  /** Value that configures or reports options for this contract. */\n  options?: Record<string, unknown>;\n  /** Value that configures or reports global for this contract. */\n  global?: GlobalOptions;\n  /** Value that configures or reports pm root for this contract. */\n  pm_root?: string;\n  /** Value that configures or reports result for this contract. */\n  result: unknown;\n}\n\n/** Documents the command handler context payload exchanged by command, SDK, and package integrations. */\nexport interface CommandHandlerContext {\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports args for this contract. */\n  args: string[];\n  /** Value that configures or reports options for this contract. */\n  options: Record<string, unknown>;\n  /** Value that configures or reports global for this contract. */\n  global: GlobalOptions;\n  /** Value that configures or reports pm root for this contract. */\n  pm_root: string;\n  /** Host-bound SDK runtime that avoids package-resolution and private-import coupling. */\n  sdk?: ExtensionCommandSdk;\n}\n\n/** Runtime SDK services injected into every extension command invocation. */\nexport interface ExtensionCommandSdk {\n  /** Tracker-bound client using the invocation author and workspace. */\n  client: PmClient;\n  /** Reconstruct one item at a history version or timestamp. */\n  getItemAt(id: string, target: string): Promise<GetItemAtResult>;\n  /** Open a durable event store with package-contributed relationship semantics. */\n  openRelationshipEventStore(options: {\n    nodes: Iterable<string>;\n    definitions: readonly RelationshipKindDefinition[];\n    relativePath?: string;\n  }): Promise<RelationshipEventStore>;\n  /** Commit idempotent item and relationship mutations under one durable journal. */\n  commitWorkspaceTransaction(\n    options: Omit<CommitWorkspaceTransactionOptions, \"pmRoot\">,\n  ): Promise<WorkspaceTransactionCommitResult>;\n}\n\n/** Documents the parser override context payload exchanged by command, SDK, and package integrations. */\nexport type ParserOverrideContext = CommandHandlerContext;\n\n/** Documents the parser override delta payload exchanged by command, SDK, and package integrations. */\nexport interface ParserOverrideDelta {\n  /** Value that configures or reports args for this contract. */\n  args?: string[];\n  /** Value that configures or reports options for this contract. */\n  options?: Record<string, unknown>;\n  /** Value that configures or reports global for this contract. */\n  global?: GlobalOptions;\n}\n\n/** Documents the preflight override context payload exchanged by command, SDK, and package integrations. */\nexport interface PreflightOverrideContext extends CommandHandlerContext {\n  /** Value that configures or reports decision for this contract. */\n  decision: PreflightRuntimeDecision;\n}\n\n/** Documents the preflight runtime decision payload exchanged by command, SDK, and package integrations. */\nexport interface PreflightRuntimeDecision {\n  /** Value that configures or reports enforce item format gate for this contract. */\n  enforce_item_format_gate: boolean;\n  /** Executes the preflight item format sync operation through the package runtime. */\n  run_preflight_item_format_sync: boolean;\n  /** Executes the extension migrations operation through the package runtime. */\n  run_extension_migrations: boolean;\n  /** Value that configures or reports enforce mandatory migration gate for this contract. */\n  enforce_mandatory_migration_gate: boolean;\n}\n\n/** Documents the preflight override delta payload exchanged by command, SDK, and package integrations. */\nexport interface PreflightOverrideDelta extends ParserOverrideDelta {\n  /** Value that configures or reports enforce item format gate for this contract. */\n  enforce_item_format_gate?: boolean;\n  /** Executes the preflight item format sync operation through the package runtime. */\n  run_preflight_item_format_sync?: boolean;\n  /** Executes the extension migrations operation through the package runtime. */\n  run_extension_migrations?: boolean;\n  /** Value that configures or reports enforce mandatory migration gate for this contract. */\n  enforce_mandatory_migration_gate?: boolean;\n}\n\n/** Documents the service override context payload exchanged by command, SDK, and package integrations. */\nexport interface ServiceOverrideContext {\n  /** Value that configures or reports service for this contract. */\n  service: ExtensionServiceName;\n  /** Value that configures or reports command for this contract. */\n  command?: string;\n  /** Value that configures or reports args for this contract. */\n  args?: string[];\n  /** Value that configures or reports options for this contract. */\n  options?: Record<string, unknown>;\n  /** Value that configures or reports global for this contract. */\n  global?: GlobalOptions;\n  /** Value that configures or reports pm root for this contract. */\n  pm_root?: string;\n  /** Value that configures or reports payload for this contract. */\n  payload: unknown;\n}\n\n/** Documents the extension command argument definition payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionCommandArgumentDefinition {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports required for this contract. */\n  required?: boolean;\n  /** Value that configures or reports variadic for this contract. */\n  variadic?: boolean;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n}\n\n/** Documents the command definition payload exchanged by command, SDK, and package integrations. */\nexport interface CommandDefinition {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports run for this contract. */\n  run?: CommandHandler;\n  /**\n   * @deprecated Use `run` instead. This alias remains for backward compatibility.\n   */\n  handler?: CommandHandler;\n  /** Value that configures or reports action for this contract. */\n  action?: string;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Value that configures or reports intent for this contract. */\n  intent?: string;\n  /** Value that configures or reports examples for this contract. */\n  examples?: string[];\n  /** Value that configures or reports failure hints for this contract. */\n  failure_hints?: string[];\n  /** Value that configures or reports arguments for this contract. */\n  arguments?: ExtensionCommandArgumentDefinition[];\n  /** Value that configures or reports flags for this contract. */\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  /** Value that configures or reports action for this contract. */\n  action?: string;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Value that configures or reports intent for this contract. */\n  intent?: string;\n  /** Value that configures or reports examples for this contract. */\n  examples?: string[];\n  /** Value that configures or reports failure hints for this contract. */\n  failure_hints?: string[];\n  /** Value that configures or reports arguments for this contract. */\n  arguments?: ExtensionCommandArgumentDefinition[];\n  /** Value that configures or reports flags for this contract. */\n  flags?: FlagDefinition[];\n}\n\n/** Restricts flag value type values accepted by command, SDK, and storage contracts. */\nexport type FlagValueType = \"string\" | \"number\" | \"boolean\";\n\n/** Documents the flag definition payload exchanged by command, SDK, and package integrations. */\nexport interface FlagDefinition {\n  /** Value that configures or reports long for this contract. */\n  long?: string;\n  /** Value that configures or reports short for this contract. */\n  short?: string;\n  /** Value that configures or reports value name for this contract. */\n  value_name?: string;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Value that configures or reports required for this contract. */\n  required?: boolean;\n  /** Whether enabled applies to this operation. */\n  enabled?: boolean;\n  /** Value that configures or reports visible for this contract. */\n  visible?: boolean;\n  /** Canonical flag value type. Prefer this field; it is the one runtime contracts and help output read first. */\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  /** When true, a repeated comma-list flag accumulates values across repeats — parity with core list flags such as `--tags` — instead of the last value winning. Mirrors the core `CliFlagContract.list` field so extension-registered list flags coalesce through the same bootstrap path. */\n  list?: boolean;\n  /** Default value applied when the flag is omitted. Surfaced to runtime contracts and help output. A `list` flag may default to an array of scalars (e.g. `[\"a\", \"b\"]`); the array is flattened/coerced like any list value. */\n  default?: string | number | boolean | Array<string | number | boolean>;\n  [key: string]: unknown;\n}\n\n/** Documents the schema field definition payload exchanged by command, SDK, and package integrations. */\nexport interface SchemaFieldDefinition {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Schema type that determines the shape and validation rules for this value. */\n  type: string;\n  /** Value that configures or reports optional for this contract. */\n  optional?: boolean;\n  [key: string]: unknown;\n}\n\n/** Documents the schema item type command option policy definition payload exchanged by command, SDK, and package integrations. */\nexport interface SchemaItemTypeCommandOptionPolicyDefinition {\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports option for this contract. */\n  option: string;\n  /** Whether enabled applies to this operation. */\n  enabled?: boolean;\n  /** Value that configures or reports required for this contract. */\n  required?: boolean;\n  /** Value that configures or reports visible for this contract. */\n  visible?: boolean;\n  [key: string]: unknown;\n}\n\n/** Documents the schema item type option definition payload exchanged by command, SDK, and package integrations. */\nexport interface SchemaItemTypeOptionDefinition {\n  /** Value that configures or reports key for this contract. */\n  key: string;\n  /** Value that configures or reports values for this contract. */\n  values?: string[];\n  /** Value that configures or reports required for this contract. */\n  required?: boolean;\n  /** Value that configures or reports aliases for this contract. */\n  aliases?: string[];\n  [key: string]: unknown;\n}\n\n/** Documents the schema item type definition payload exchanged by command, SDK, and package integrations. */\nexport interface SchemaItemTypeDefinition {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports folder for this contract. */\n  folder?: string;\n  /** Value that configures or reports aliases for this contract. */\n  aliases?: string[];\n  /** Value that configures or reports required create fields for this contract. */\n  required_create_fields?: string[];\n  /** Value that configures or reports required create repeatables for this contract. */\n  required_create_repeatables?: string[];\n  /** Value that configures or reports command option policies for this contract. */\n  command_option_policies?: SchemaItemTypeCommandOptionPolicyDefinition[];\n  /** Value that configures or reports options for this contract. */\n  options?: SchemaItemTypeOptionDefinition[];\n  [key: string]: unknown;\n}\n\n/** Documents the schema migration run context payload exchanged by command, SDK, and package integrations. */\nexport interface SchemaMigrationRunContext {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports command for this contract. */\n  command: \"migration\";\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports extension for this contract. */\n  extension: string;\n  /** Value that configures or reports pm root for this contract. */\n  pm_root: string;\n  /** Lifecycle state reported for status. */\n  status: string;\n}\n\n/** Restricts schema migration runner values accepted by command, SDK, and storage contracts. */\nexport type SchemaMigrationRunner = (\n  context: SchemaMigrationRunContext,\n) => unknown | Promise<unknown>;\n\n/** Documents the schema migration definition payload exchanged by command, SDK, and package integrations. */\nexport interface SchemaMigrationDefinition {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id?: string;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Lifecycle state reported for status. */\n  status?: string;\n  /** Value that configures or reports mandatory for this contract. */\n  mandatory?: boolean;\n  /** Value that configures or reports run for this contract. */\n  run?: SchemaMigrationRunner;\n  [key: string]: unknown;\n}\n\n/** Documents the import export context payload exchanged by command, SDK, and package integrations. */\nexport interface ImportExportContext {\n  /** Value that configures or reports registration for this contract. */\n  registration: string;\n  /** Value that configures or reports action for this contract. */\n  action: \"import\" | \"export\";\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports args for this contract. */\n  args: string[];\n  /** Value that configures or reports options for this contract. */\n  options: Record<string, unknown>;\n  /** Value that configures or reports global for this contract. */\n  global: GlobalOptions;\n  /** Value that configures or reports pm root for this contract. */\n  pm_root: string;\n}\n\n/** Restricts importer values accepted by command, SDK, and storage contracts. */\nexport type Importer = (\n  context: ImportExportContext,\n) => unknown | Promise<unknown>;\n/** Restricts exporter values accepted by command, SDK, and storage contracts. */\nexport type Exporter = (\n  context: ImportExportContext,\n) => unknown | Promise<unknown>;\n\n/** Restricts extension search mode values accepted by command, SDK, and storage contracts. */\nexport type ExtensionSearchMode = \"keyword\" | \"semantic\" | \"hybrid\";\n\n/** Documents the search provider query context payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderQueryContext {\n  /** Value that configures or reports query for this contract. */\n  query: string;\n  /** Value that configures or reports mode for this contract. */\n  mode: ExtensionSearchMode;\n  /** Value that configures or reports tokens for this contract. */\n  tokens: string[];\n  /** Value that configures or reports options for this contract. */\n  options: Record<string, unknown>;\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  /** Value that configures or reports documents for this contract. */\n  documents: ItemDocument[];\n  [key: string]: unknown;\n}\n\n/** Documents the search provider hit payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderHit {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports score for this contract. */\n  score: number;\n  /** Value that configures or reports matched fields for this contract. */\n  matched_fields?: string[];\n  [key: string]: unknown;\n}\n\n/** Restricts search provider query result values accepted by command, SDK, and storage contracts. */\nexport type SearchProviderQueryResult =\n  | SearchProviderHit[]\n  | { hits?: SearchProviderHit[] };\n\n/** Documents the search provider query expansion context payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderQueryExpansionContext {\n  /** Value that configures or reports query for this contract. */\n  query: string;\n  /** Value that configures or reports mode for this contract. */\n  mode: Exclude<ExtensionSearchMode, \"keyword\">;\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/** Restricts search provider query expansion result values accepted by command, SDK, and storage contracts. */\nexport type SearchProviderQueryExpansionResult =\n  | string[]\n  | { queries?: string[] };\n\n/** Documents the search provider rerank candidate payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderRerankCandidate {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports text for this contract. */\n  text: string;\n  /** Value that configures or reports score for this contract. */\n  score: number;\n}\n\n/** Documents the search provider rerank hit payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderRerankHit {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports score for this contract. */\n  score: number;\n}\n\n/** Restricts search provider rerank result values accepted by command, SDK, and storage contracts. */\nexport type SearchProviderRerankResult =\n  | SearchProviderRerankHit[]\n  | { hits?: SearchProviderRerankHit[] };\n\n/** Documents the search provider rerank context payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderRerankContext {\n  /** Value that configures or reports query for this contract. */\n  query: string;\n  /** Value that configures or reports mode for this contract. */\n  mode: \"hybrid\";\n  /** Value that configures or reports model for this contract. */\n  model: string;\n  /** Value that configures or reports top k for this contract. */\n  top_k: number;\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  /** Value that configures or reports candidates for this contract. */\n  candidates: SearchProviderRerankCandidate[];\n  [key: string]: unknown;\n}\n\n/** Documents the search provider embed batch context payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderEmbedBatchContext {\n  /** Value that configures or reports inputs for this contract. */\n  inputs: string[];\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  /** Value that configures or reports model for this contract. */\n  model: string;\n  [key: string]: unknown;\n}\n\n/** Documents the search provider embed context payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderEmbedContext {\n  /** Value that configures or reports input for this contract. */\n  input: string;\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  /** Value that configures or reports model for this contract. */\n  model: string;\n  [key: string]: unknown;\n}\n\n/** Documents the search provider definition payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderDefinition {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports query for this contract. */\n  query?: (\n    context: SearchProviderQueryContext,\n  ) => SearchProviderQueryResult | Promise<SearchProviderQueryResult>;\n  /** Value that configures or reports query expansion for this contract. */\n  queryExpansion?: (\n    context: SearchProviderQueryExpansionContext,\n  ) =>\n    | SearchProviderQueryExpansionResult\n    | Promise<SearchProviderQueryExpansionResult>;\n  /** Value that configures or reports query expansion for this contract. */\n  query_expansion?: (\n    context: SearchProviderQueryExpansionContext,\n  ) =>\n    | SearchProviderQueryExpansionResult\n    | Promise<SearchProviderQueryExpansionResult>;\n  /** Value that configures or reports rerank for this contract. */\n  rerank?: (\n    context: SearchProviderRerankContext,\n  ) => SearchProviderRerankResult | Promise<SearchProviderRerankResult>;\n  /** Value that configures or reports embed batch for this contract. */\n  embedBatch?: (\n    context: SearchProviderEmbedBatchContext,\n  ) => number[][] | Promise<number[][]>;\n  /** Value that configures or reports embed batch for this contract. */\n  embed_batch?: (\n    context: SearchProviderEmbedBatchContext,\n  ) => number[][] | Promise<number[][]>;\n  /** Value that configures or reports embed for this contract. */\n  embed?: (context: SearchProviderEmbedContext) => number[] | Promise<number[]>;\n  [key: string]: unknown;\n}\n\n/** Documents the vector store query hit payload exchanged by command, SDK, and package integrations. */\nexport interface VectorStoreQueryHit {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports score for this contract. */\n  score: number;\n  /** Value that configures or reports payload for this contract. */\n  payload?: Record<string, unknown>;\n  [key: string]: unknown;\n}\n\n/** Documents the vector store query context payload exchanged by command, SDK, and package integrations. */\nexport interface VectorStoreQueryContext {\n  /** Value that configures or reports vector for this contract. */\n  vector: number[];\n  /** Value that configures or reports limit for this contract. */\n  limit: number;\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/** Documents the vector store upsert point payload exchanged by command, SDK, and package integrations. */\nexport interface VectorStoreUpsertPoint {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports vector for this contract. */\n  vector: number[];\n  /** Value that configures or reports payload for this contract. */\n  payload?: Record<string, unknown>;\n  [key: string]: unknown;\n}\n\n/** Documents the vector store upsert context payload exchanged by command, SDK, and package integrations. */\nexport interface VectorStoreUpsertContext {\n  /** Value that configures or reports points for this contract. */\n  points: VectorStoreUpsertPoint[];\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/** Documents the vector store delete context payload exchanged by command, SDK, and package integrations. */\nexport interface VectorStoreDeleteContext {\n  /** Value that configures or reports ids for this contract. */\n  ids: string[];\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/** Documents the vector store adapter definition payload exchanged by command, SDK, and package integrations. */\nexport interface VectorStoreAdapterDefinition {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports query for this contract. */\n  query?: (\n    context: VectorStoreQueryContext,\n  ) => VectorStoreQueryHit[] | Promise<VectorStoreQueryHit[]>;\n  /** Value that configures or reports upsert for this contract. */\n  upsert?: (context: VectorStoreUpsertContext) => unknown | Promise<unknown>;\n  /** Value that configures or reports delete for this contract. */\n  delete?: (context: VectorStoreDeleteContext) => unknown | Promise<unknown>;\n  [key: string]: unknown;\n}\n\n/** Documents the registered extension command override payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionCommandOverride {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports run for this contract. */\n  run: CommandOverride;\n}\n\n/** Documents the registered extension command handler payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionCommandHandler {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports run for this contract. */\n  run: CommandHandler;\n}\n\n/** Documents the registered extension parser override payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionParserOverride {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports run for this contract. */\n  run: ParserOverride;\n}\n\n/** Documents the registered extension preflight override payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionPreflightOverride {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports run for this contract. */\n  run: PreflightOverride;\n}\n\n/** Documents the registered extension service override payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionServiceOverride {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports service for this contract. */\n  service: ExtensionServiceName;\n  /** Value that configures or reports run for this contract. */\n  run: ServiceOverride;\n}\n\n/** Documents the registered extension renderer override payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionRendererOverride {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports format for this contract. */\n  format: OutputRendererFormat;\n  /** Value that configures or reports run for this contract. */\n  run: RendererOverride;\n}\n\n/** Documents the extension command registry payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionCommandRegistry {\n  /** Value that configures or reports overrides for this contract. */\n  overrides: RegisteredExtensionCommandOverride[];\n  /** Value that configures or reports handlers for this contract. */\n  handlers: RegisteredExtensionCommandHandler[];\n}\n\n/** Documents the extension parser registry payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionParserRegistry {\n  /** Value that configures or reports overrides for this contract. */\n  overrides: RegisteredExtensionParserOverride[];\n}\n\n/** Documents the extension preflight registry payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionPreflightRegistry {\n  /** Value that configures or reports overrides for this contract. */\n  overrides: RegisteredExtensionPreflightOverride[];\n}\n\n/** Documents the extension service registry payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionServiceRegistry {\n  /** Value that configures or reports overrides for this contract. */\n  overrides: RegisteredExtensionServiceOverride[];\n}\n\n/** Documents the extension renderer registry payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionRendererRegistry {\n  /** Value that configures or reports overrides for this contract. */\n  overrides: RegisteredExtensionRendererOverride[];\n}\n\n/** Documents the registered extension flag definitions payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionFlagDefinitions {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports target command for this contract. */\n  target_command: string;\n  /** Value that configures or reports flags for this contract. */\n  flags: FlagDefinition[];\n}\n\n/** Documents the registered extension command definition payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionCommandDefinition {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports source package for this contract. */\n  source_package?: string;\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports action for this contract. */\n  action: string;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Value that configures or reports intent for this contract. */\n  intent?: string;\n  /** Value that configures or reports examples for this contract. */\n  examples: string[];\n  /** Value that configures or reports failure hints for this contract. */\n  failure_hints: string[];\n  /** Value that configures or reports arguments for this contract. */\n  arguments: ExtensionCommandArgumentDefinition[];\n}\n\n/** Documents the registered extension schema field definitions payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionSchemaFieldDefinitions {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports fields for this contract. */\n  fields: SchemaFieldDefinition[];\n}\n\n/** Documents the registered extension schema item type definitions payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionSchemaItemTypeDefinitions {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports types for this contract. */\n  types: SchemaItemTypeDefinition[];\n}\n\n/** Relationship ontology definitions contributed by one active extension. */\nexport interface RegisteredExtensionRelationshipKindDefinitions {\n  /** Extension layer that owns these definitions. */\n  layer: ExtensionLayer;\n  /** Extension name that owns these definitions. */\n  name: string;\n  /** Validated immutable relationship-kind definitions. */\n  definitions: RelationshipKindDefinition[];\n}\n\n/** Documents the registered extension schema migration definition payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionSchemaMigrationDefinition {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports definition for this contract. */\n  definition: SchemaMigrationDefinition;\n  /** Value that configures or reports runtime definition for this contract. */\n  runtime_definition: SchemaMigrationDefinition;\n}\n\n/** Documents the registered extension importer payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionImporter {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports importer for this contract. */\n  importer: string;\n}\n\n/** Documents the registered extension exporter payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionExporter {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports exporter for this contract. */\n  exporter: string;\n}\n\n/** Documents the registered extension search provider payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionSearchProvider {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports definition for this contract. */\n  definition: SearchProviderDefinition;\n  /** Value that configures or reports runtime definition for this contract. */\n  runtime_definition: SearchProviderDefinition;\n}\n\n/** Documents the registered extension vector store adapter payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionVectorStoreAdapter {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports definition for this contract. */\n  definition: VectorStoreAdapterDefinition;\n  /** Value that configures or reports runtime definition for this contract. */\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  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports profile for this contract. */\n  profile: ProjectProfileDefinition;\n}\n\n/** Documents the extension registration registry payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionRegistrationRegistry {\n  /** Value that configures or reports commands for this contract. */\n  commands: RegisteredExtensionCommandDefinition[];\n  /** Value that configures or reports flags for this contract. */\n  flags: RegisteredExtensionFlagDefinitions[];\n  /** Value that configures or reports item fields for this contract. */\n  item_fields: RegisteredExtensionSchemaFieldDefinitions[];\n  /** Value that configures or reports item types for this contract. */\n  item_types: RegisteredExtensionSchemaItemTypeDefinitions[];\n  /** Value that configures application-defined relationship semantics. */\n  relationship_kinds: RegisteredExtensionRelationshipKindDefinitions[];\n  /** Value that configures or reports migrations for this contract. */\n  migrations: RegisteredExtensionSchemaMigrationDefinition[];\n  /** Value that configures or reports profiles for this contract. */\n  profiles: RegisteredExtensionProjectProfile[];\n  /** Value that configures or reports importers for this contract. */\n  importers: RegisteredExtensionImporter[];\n  /** Value that configures or reports exporters for this contract. */\n  exporters: RegisteredExtensionExporter[];\n  /** Value that configures or reports search providers for this contract. */\n  search_providers: RegisteredExtensionSearchProvider[];\n  /** Value that configures or reports vector store adapters for this contract. */\n  vector_store_adapters: RegisteredExtensionVectorStoreAdapter[];\n}\n\n/** Documents the extension registration counts payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionRegistrationCounts {\n  /** Value that configures or reports commands for this contract. */\n  commands: number;\n  /** Value that configures or reports flags for this contract. */\n  flags: number;\n  /** Value that configures or reports item fields for this contract. */\n  item_fields: number;\n  /** Value that configures or reports item types for this contract. */\n  item_types: number;\n  /** Number of application-defined relationship kinds. */\n  relationship_kinds?: number;\n  /** Value that configures or reports migrations for this contract. */\n  migrations: number;\n  /** Value that configures or reports profiles for this contract. */\n  profiles: number;\n  /** Value that configures or reports importers for this contract. */\n  importers: number;\n  /** Value that configures or reports exporters for this contract. */\n  exporters: number;\n  /** Value that configures or reports search providers for this contract. */\n  search_providers: number;\n  /** Value that configures or reports vector store adapters for this contract. */\n  vector_store_adapters: number;\n}\n\n/** Read-only identity an extension's `activate(api)` receives about itself, so authors can emit self-identifying logs, gate on their own version, and build better error messages without re-reading the on-disk manifest or duplicating metadata in-module. Exposed as `api.extension`. */\nexport interface ExtensionSelfIdentity {\n  /** Value that configures or reports name for this contract. */\n  readonly name: string;\n  /** Value that configures or reports layer for this contract. */\n  readonly layer: ExtensionLayer;\n  /** Value that configures or reports version for this contract. */\n  readonly version: string;\n  /** Value that configures or reports capabilities for this contract. */\n  readonly capabilities: readonly ExtensionCapability[];\n  /** Value that configures or reports pm min version for this contract. */\n  readonly pm_min_version?: string;\n  /** Value that configures or reports pm max version for this contract. */\n  readonly pm_max_version?: string;\n  /** Value that configures or reports source package for this contract. */\n  readonly source_package?: string;\n}\n\n/** Documents the extension api payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionApi {\n  /** Read-only identity of the extension this `api` was created for. */\n  readonly extension: ExtensionSelfIdentity;\n  /** Value that configures or reports register command for this contract. */\n  registerCommand(command: string, override: CommandOverride): void;\n  /** Value that configures or reports register command for this contract. */\n  registerCommand(definition: CommandDefinition): void;\n  /** Value that configures or reports register parser for this contract. */\n  registerParser(command: string, override: ParserOverride): void;\n  /** Value that configures or reports register preflight for this contract. */\n  registerPreflight(override: PreflightOverride): void;\n  /** Value that configures or reports register service for this contract. */\n  registerService(\n    service: ExtensionServiceName,\n    override: ServiceOverride,\n  ): void;\n  /** Value that configures or reports register flags for this contract. */\n  registerFlags(targetCommand: string, flags: FlagDefinition[]): void;\n  /** Value that configures or reports register item fields for this contract. */\n  registerItemFields(fields: SchemaFieldDefinition[]): void;\n  /** Value that configures or reports register item types for this contract. */\n  registerItemTypes(types: SchemaItemTypeDefinition[]): void;\n  /** Register versioned relationship semantics consumed by every graph surface. */\n  registerRelationshipKinds(definitions: RelationshipKindDefinition[]): void;\n  /** Value that configures or reports register migration for this contract. */\n  registerMigration(definition: SchemaMigrationDefinition): void;\n  /** Value that configures or reports register profile for this contract. */\n  registerProfile(profile: ProjectProfileRegistrationInput): void;\n  /** Value that configures or reports register renderer for this contract. */\n  registerRenderer(\n    format: OutputRendererFormat,\n    renderer: RendererOverride,\n  ): void;\n  /** Value that configures or reports register importer for this contract. */\n  registerImporter(\n    name: string,\n    importer: Importer,\n    options?: ImportExportRegistrationOptions,\n  ): void;\n  /** Value that configures or reports register exporter for this contract. */\n  registerExporter(\n    name: string,\n    exporter: Exporter,\n    options?: ImportExportRegistrationOptions,\n  ): void;\n  /** Value that configures or reports register search provider for this contract. */\n  registerSearchProvider(provider: SearchProviderDefinition): void;\n  /** Value that configures or reports register vector store adapter for this contract. */\n  registerVectorStoreAdapter(adapter: VectorStoreAdapterDefinition): void;\n  /** Value that configures or reports hooks for this contract. */\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/** Documents the failed extension activation payload exchanged by command, SDK, and package integrations. */\nexport interface FailedExtensionActivation {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Filesystem path used for entry resolution. */\n  entry_path: string;\n  /** Value that configures or reports error for this contract. */\n  error: string;\n  /** Value that configures or reports trace for this contract. */\n  trace?: ExtensionActivationFailureTrace;\n}\n\n/** Documents the extension activation failure trace payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionActivationFailureTrace {\n  /** Value that configures or reports method for this contract. */\n  method: string;\n  /** `-1` means the failure happened before a numbered registration was accepted. */\n  registration_index: number;\n  /** Value that configures or reports command for this contract. */\n  command?: string;\n  /** Value that configures or reports capability for this contract. */\n  capability?: ExtensionCapability;\n  /** Value that configures or reports missing capability for this contract. */\n  missing_capability?: ExtensionCapability;\n  /** Value that configures or reports expected schema for this contract. */\n  expected_schema: string;\n  /** Value that configures or reports received for this contract. */\n  received?: unknown;\n  /** Value that configures or reports hint for this contract. */\n  hint?: string;\n}\n\n/** Documents the extension activation result payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionActivationResult {\n  /** Value that configures or reports hooks for this contract. */\n  hooks: ExtensionHookRegistry;\n  /** Value that configures or reports commands for this contract. */\n  commands: ExtensionCommandRegistry;\n  /** Value that configures or reports parsers for this contract. */\n  parsers: ExtensionParserRegistry;\n  /** Value that configures or reports preflight for this contract. */\n  preflight: ExtensionPreflightRegistry;\n  /** Value that configures or reports services for this contract. */\n  services: ExtensionServiceRegistry;\n  /** Value that configures or reports renderers for this contract. */\n  renderers: ExtensionRendererRegistry;\n  /** Value that configures or reports registrations for this contract. */\n  registrations: ExtensionRegistrationRegistry;\n  /** Value that configures or reports failed for this contract. */\n  failed: FailedExtensionActivation[];\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n  /** Value that configures or reports hook counts for this contract. */\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  /** Number of command override entries represented by this result. */\n  command_override_count: number;\n  /** Number of command handler entries represented by this result. */\n  command_handler_count: number;\n  /** Number of parser override entries represented by this result. */\n  parser_override_count: number;\n  /** Number of preflight override entries represented by this result. */\n  preflight_override_count: number;\n  /** Number of service override entries represented by this result. */\n  service_override_count: number;\n  /** Number of renderer override entries represented by this result. */\n  renderer_override_count: number;\n  /** Value that configures or reports registration counts for this contract. */\n  registration_counts: ExtensionRegistrationCounts;\n}\n\n/** Documents the extension candidate payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionCandidate {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports directory for this contract. */\n  directory: string;\n  /** Filesystem path used for manifest resolution. */\n  manifest_path: string;\n  /** Filesystem path used for entry resolution. */\n  entry_path: string;\n  /** Declarative package manifest consumed by the extension loader. */\n  manifest: ExtensionManifest;\n  /** Value that configures or reports source package for this contract. */\n  source_package?: string;\n}\n\n/** Documents the extension layer scan result payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionLayerScanResult {\n  /** Value that configures or reports diagnostics for this contract. */\n  diagnostics: ExtensionDiagnostic[];\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n  /** Value that configures or reports candidates for this contract. */\n  candidates: ExtensionCandidate[];\n}\n\n/** Documents the scanned extension directory payload exchanged by command, SDK, and package integrations. */\nexport interface ScannedExtensionDirectory {\n  /** Value that configures or reports diagnostic for this contract. */\n  diagnostic: ExtensionDiagnostic;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n  /** Value that configures or reports candidate for this contract. */\n  candidate: ExtensionCandidate | null;\n}\n\n/** Documents the legacy extension capability alias mapping payload exchanged by command, SDK, and package integrations. */\nexport interface LegacyExtensionCapabilityAliasMapping {\n  /** Value that configures or reports alias for this contract. */\n  alias: string;\n  /** Value that configures or reports target for this contract. */\n  target: ExtensionCapability;\n}\n\n/** Documents the discover extensions options payload exchanged by command, SDK, and package integrations. */\nexport interface DiscoverExtensionsOptions {\n  /** Value that configures or reports pm root for this contract. */\n  pmRoot: string;\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  /** Value that configures or reports cwd for this contract. */\n  cwd?: string;\n  /** Value that configures or reports no extensions for this contract. */\n  noExtensions?: boolean;\n  /** Value that configures or reports ignore global extensions for this contract. */\n  ignoreGlobalExtensions?: boolean;\n  /** Value that configures or reports reload token for this contract. */\n  reload_token?: string;\n  /** Value that configures or reports cache bust for this contract. */\n  cache_bust?: boolean;\n  /** Optional import-stage filter. Discovery still reports the full effective set, but `loadExtensions` imports only entries accepted by this predicate. */\n  extensionFilter?: (extension: EffectiveExtension) => boolean;\n}\n\n/** Documents the activatable extension payload exchanged by command, SDK, and package integrations. */\nexport interface ActivatableExtension {\n  /** Registers this package's commands, actions, and runtime hooks with the host. */\n  activate: (api: ExtensionApi) => void | Promise<void>;\n  /** Optional teardown lifecycle hook, analogous to VS Code's `deactivate` export. Invoked when the host tears the extension down — on long-running MCP-server reload between requests, or via the `deactivateExtensions` primitive — so an extension can close connections, clear timers, and release buffers it opened during `activate`. */\n  deactivate?: () => void | Promise<void>;\n}\n\n/** Documents the extension deactivation failure payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionDeactivationFailure {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports error for this contract. */\n  error: string;\n}\n\n/** Documents the extension deactivation options payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionDeactivationOptions {\n  /** Maximum time to wait for each extension's `deactivate` hook. Defaults to 5000ms so a hanging teardown cannot block host shutdown or reload. Set to 0 or Infinity only when the host intentionally wants to wait indefinitely. */\n  deactivate_timeout_ms?: number;\n}\n\n/** Documents the extension deactivation result payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionDeactivationResult {\n  /** Count of loaded extensions whose `deactivate` hook ran without throwing. */\n  deactivated: number;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n  /** Value that configures or reports failed for this contract. */\n  failed: ExtensionDeactivationFailure[];\n}\n\n/** Documents the service override result payload exchanged by command, SDK, and package integrations. */\nexport interface ServiceOverrideResult {\n  /** Value that configures or reports handled for this contract. */\n  handled: boolean;\n  /** Value that configures or reports result for this contract. */\n  result: unknown;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n}\n\n/** Documents the command override result payload exchanged by command, SDK, and package integrations. */\nexport interface CommandOverrideResult {\n  /** Value that configures or reports overridden for this contract. */\n  overridden: boolean;\n  /** Value that configures or reports result for this contract. */\n  result: unknown;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n}\n\n/** Documents the command handler result payload exchanged by command, SDK, and package integrations. */\nexport interface CommandHandlerResult {\n  /** Value that configures or reports handled for this contract. */\n  handled: boolean;\n  /** Value that configures or reports result for this contract. */\n  result: unknown;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n  /** Human-readable, single-line, length-bounded message describing why an extension command handler failed. Surfaced to the user/CI so the real cause (e.g. \"Changelog is out of date: CHANGELOG.md\") is visible instead of only the opaque `extension_command_handler_failed` warning code. */\n  errorMessage?: string;\n}\n\n/** Documents the parser override result payload exchanged by command, SDK, and package integrations. */\nexport interface ParserOverrideResult {\n  /** Value that configures or reports overridden for this contract. */\n  overridden: boolean;\n  /** Value that configures or reports context for this contract. */\n  context: CommandHandlerContext;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n}\n\n/** Documents the preflight override result payload exchanged by command, SDK, and package integrations. */\nexport interface PreflightOverrideResult {\n  /** Value that configures or reports overridden for this contract. */\n  overridden: boolean;\n  /** Value that configures or reports context for this contract. */\n  context: CommandHandlerContext;\n  /** Value that configures or reports decision for this contract. */\n  decision: PreflightRuntimeDecision;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n}\n\n/** Documents the renderer override result payload exchanged by command, SDK, and package integrations. */\nexport interface RendererOverrideResult {\n  /** Value that configures or reports overridden for this contract. */\n  overridden: boolean;\n  /** Value that configures or reports rendered for this contract. */\n  rendered: string | null;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n}\n\n/** Documents the unknown extension capability warning details payload exchanged by command, SDK, and package integrations. */\nexport interface UnknownExtensionCapabilityWarningDetails {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports capability for this contract. */\n  capability: string;\n  /** Value that configures or reports allowed capabilities for this contract. */\n  allowed_capabilities: string[];\n  /** Value that configures or reports capability contract version for this contract. */\n  capability_contract_version: number;\n  /** Value that configures or reports suggested capability for this contract. */\n  suggested_capability?: string;\n  /** Value that configures or reports suggestion source for this contract. */\n  suggestion_source?: \"legacy_alias\" | \"nearest_match\";\n  /** Value that configures or reports legacy alias target for this contract. */\n  legacy_alias_target?: string;\n}\n"],"names":[],"mappings":"AA+BA,wGAAwG;;;AACxG,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;AAGX,iHAAiH;AACjH,MAAM,CAAC,MAAM,qCAAqC,GAAG,CAAC,CAAC;AACvD,+GAA+G;AAC/G,MAAM,CAAC,MAAM,mCAAmC,GAE5C,MAAM,CAAC,MAAM,CAAC;IAChB,SAAS,EAAE,QAAQ;IACnB,UAAU,EAAE,QAAQ;CACrB,CAAC,CAAC;AACH,yGAAyG;AACzG,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,wGAAwG;AACxG,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAGhF,uGAAuG;AACvG,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAG/E,4GAA4G;AAC5G,MAAM,CAAC,MAAM,gCAAgC,GAAG;IAC9C,MAAM;IACN,YAAY;IACZ,QAAQ;CACA,CAAC;AAKX,+GAA+G;AAC/G,MAAM,CAAC,MAAM,mCAAmC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAU,CAAC;AAgB9E,2GAA2G;AAC3G,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,0BAA0B;IAC1B,mBAAmB;IACnB,iBAAiB;IACjB,iBAAiB;IACjB,oBAAoB;IACpB,mBAAmB;IACnB,oBAAoB;IACpB,oBAAoB;IACpB,oBAAoB;IACpB,iBAAiB;IACjB,oBAAoB;CACZ,CAAC;AAKX,yGAAyG;AACzG,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,eAAe;IACf,cAAc;IACd,aAAa;IACb,cAAc;IACd,cAAc;IACd,gBAAgB;IAChB,kBAAkB;IAClB,mBAAmB;IACnB,mBAAmB;IACnB,gBAAgB;CACR,CAAC;AAuDX,2GAA2G;AAC3G,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":"765cc85b-c5c2-5021-8237-60235d3726df"}
+{"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  ItemMetadata,\n  ItemStatus,\n  PmSettings,\n} from \"../../types/index.js\";\nimport type { GlobalOptions } from \"../shared/command-types.js\";\nimport type {\n  ProjectProfileDefinition,\n  ProjectProfileRegistrationInput,\n} from \"../profile/profile-presets.js\";\nimport type { RelationshipKindDefinition } from \"../../sdk/relationships.js\";\nimport type { PmClient } from \"../../sdk/runtime.js\";\nimport type {\n  GetItemAtResult,\n} from \"../../sdk/history-read.js\";\nimport type {\n  RelationshipEventStore,\n} from \"../../sdk/relationship-history.js\";\nimport type {\n  CommitWorkspaceTransactionOptions,\n  WorkspaceTransactionCommitResult,\n} from \"../../sdk/workspace-transaction.js\";\n\n/** Public contract for known extension capabilities, shared by SDK and presentation-layer consumers. */\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/** Restricts extension capability values accepted by command, SDK, and storage contracts. */\nexport type ExtensionCapability = (typeof KNOWN_EXTENSION_CAPABILITIES)[number];\n/** Public contract for extension capability contract version, shared by SDK and presentation-layer consumers. */\nexport const EXTENSION_CAPABILITY_CONTRACT_VERSION = 2;\n/** Public contract for extension capability legacy aliases, shared by SDK and presentation-layer consumers. */\nexport const EXTENSION_CAPABILITY_LEGACY_ALIASES: Readonly<\n  Record<string, ExtensionCapability>\n> = Object.freeze({\n  migration: \"schema\",\n  validation: \"schema\",\n});\n/** Public contract for extension capability contract, shared by SDK and presentation-layer consumers. */\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\n/** Public contract for known extension policy modes, shared by SDK and presentation-layer consumers. */\nexport const KNOWN_EXTENSION_POLICY_MODES = [\"off\", \"warn\", \"enforce\"] as const;\n/** Restricts extension policy mode values accepted by command, SDK, and storage contracts. */\nexport type ExtensionPolicyMode = (typeof KNOWN_EXTENSION_POLICY_MODES)[number];\n/** Public contract for known extension trust modes, shared by SDK and presentation-layer consumers. */\nexport const KNOWN_EXTENSION_TRUST_MODES = [\"off\", \"warn\", \"enforce\"] as const;\n/** Restricts extension trust mode values accepted by command, SDK, and storage contracts. */\nexport type ExtensionTrustMode = (typeof KNOWN_EXTENSION_TRUST_MODES)[number];\n/** Public contract for known extension sandbox profiles, shared by SDK and presentation-layer consumers. */\nexport const KNOWN_EXTENSION_SANDBOX_PROFILES = [\n  \"none\",\n  \"restricted\",\n  \"strict\",\n] as const;\n/** Restricts extension sandbox profile values accepted by command, SDK, and storage contracts. */\nexport type ExtensionSandboxProfile =\n  (typeof KNOWN_EXTENSION_SANDBOX_PROFILES)[number];\n\n/** Public contract for known pm max version exceeded modes, shared by SDK and presentation-layer consumers. */\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 =\n  (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  /** Value that configures or reports global for this contract. */\n  global?: PmMaxVersionExceededMode;\n  /** Value that configures or reports project for this contract. */\n  project?: PmMaxVersionExceededMode;\n}\n/** Settings value for `extensions.policy.pm_max_version_exceeded_mode`: either a single mode applied to both layers, or a per-layer override map. Unset (and any unset layer key) defaults to `\"block\"`. */\nexport type PmMaxVersionExceededModeSetting =\n  | PmMaxVersionExceededMode\n  | PmMaxVersionExceededModeByLayer;\n\n/** Public contract for known extension policy surfaces, shared by SDK and presentation-layer consumers. */\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.relationshipkinds\",\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/** Restricts extension policy surface values accepted by command, SDK, and storage contracts. */\nexport type ExtensionPolicySurface =\n  (typeof KNOWN_EXTENSION_POLICY_SURFACES)[number];\n\n/** Public contract for known extension service names, shared by SDK and presentation-layer consumers. */\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  \"context_relevance\",\n  \"command_result\",\n] as const;\n/** Restricts extension service name values accepted by command, SDK, and storage contracts. */\nexport type ExtensionServiceName =\n  (typeof KNOWN_EXTENSION_SERVICE_NAMES)[number];\n\n/** Documents the extension provenance metadata payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionProvenanceMetadata {\n  /** Value that configures or reports source for this contract. */\n  source?: string;\n  /** Value that configures or reports signature for this contract. */\n  signature?: string;\n  /** Value that configures or reports attestation for this contract. */\n  attestation?: string;\n  /** Value that configures or reports verified for this contract. */\n  verified?: boolean;\n}\n\n/** Documents the extension runtime permission declaration payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionRuntimePermissionDeclaration {\n  /** Value that configures or reports fs read for this contract. */\n  fs_read?: boolean;\n  /** Value that configures or reports fs write for this contract. */\n  fs_write?: boolean;\n  /** Value that configures or reports network for this contract. */\n  network?: boolean;\n  /** Value that configures or reports env read for this contract. */\n  env_read?: boolean;\n  /** Value that configures or reports env write for this contract. */\n  env_write?: boolean;\n  /** Value that configures or reports process spawn for this contract. */\n  process_spawn?: boolean;\n}\n\n/** Documents the extension activation metadata payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionActivationMetadata {\n  /** Value that configures or reports commands for this contract. */\n  commands?: string[];\n}\n\n/** Restricts extension policy override values accepted by command, SDK, and storage contracts. */\nexport type ExtensionPolicyOverride = ExtensionPolicyOverrideSettings;\n/** Extension governance policy as read from / serialized to settings. Extends the stored settings shape with `pm_max_version_exceeded_mode` (pm-k5e8), which relaxes the default-BLOCK on `pm_max_version` violations to warn-only — globally or per extension layer. */\nexport type ExtensionGovernancePolicy = ExtensionPolicySettings & {\n  pm_max_version_exceeded_mode?: PmMaxVersionExceededModeSetting;\n};\n\n/** Documents the extension manifest engines payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionManifestEngines {\n  /** Value that configures or reports pm for this contract. */\n  pm?: string;\n  /** Value that configures or reports node for this contract. */\n  node?: string;\n  [engine: string]: string | undefined;\n}\n\n/** Implements create default extension governance policy for the public runtime surface of this module. */\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/** Restricts extension layer values accepted by command, SDK, and storage contracts. */\nexport type ExtensionLayer = \"global\" | \"project\";\n/** Restricts extension status values accepted by command, SDK, and storage contracts. */\nexport type ExtensionStatus = \"ok\" | \"warn\";\n\n/** Documents the extension manifest payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionManifest {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports version for this contract. */\n  version: string;\n  /** Value that configures or reports entry for this contract. */\n  entry: string;\n  /** Value that configures or reports priority for this contract. */\n  priority: number;\n  /** Value that configures or reports capabilities for this contract. */\n  capabilities: string[];\n  /** Value that configures or reports manifest version for this contract. */\n  manifest_version?: number;\n  /** Value that configures or reports pm min version for this contract. */\n  pm_min_version?: string;\n  /** Value that configures or reports pm max version for this contract. */\n  pm_max_version?: string;\n  /** Value that configures or reports engines for this contract. */\n  engines?: ExtensionManifestEngines;\n  /** Value that configures or reports trusted for this contract. */\n  trusted?: boolean;\n  /** Value that configures or reports provenance for this contract. */\n  provenance?: ExtensionProvenanceMetadata;\n  /** Value that configures or reports sandbox profile for this contract. */\n  sandbox_profile?: ExtensionSandboxProfile;\n  /** Value that configures or reports permissions for this contract. */\n  permissions?: ExtensionRuntimePermissionDeclaration;\n  /** Value that configures or reports activation for this contract. */\n  activation?: ExtensionActivationMetadata;\n  /** Value that configures or reports legacy capability aliases for this contract. */\n  legacy_capability_aliases?: LegacyExtensionCapabilityAliasMapping[];\n}\n\n/** Documents the extension diagnostic payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionDiagnostic {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports directory for this contract. */\n  directory: string;\n  /** Filesystem path used for manifest resolution. */\n  manifest_path: string;\n  /** Value that configures or reports name for this contract. */\n  name: string | null;\n  /** Value that configures or reports version for this contract. */\n  version: string | null;\n  /** Value that configures or reports entry for this contract. */\n  entry: string | null;\n  /** Value that configures or reports priority for this contract. */\n  priority: number | null;\n  /** Filesystem path used for entry resolution. */\n  entry_path: string | null;\n  /** Whether enabled applies to this operation. */\n  enabled: boolean | null;\n  /** Lifecycle state reported for status. */\n  status: ExtensionStatus;\n}\n\n/** Documents the effective extension payload exchanged by command, SDK, and package integrations. */\nexport interface EffectiveExtension {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports directory for this contract. */\n  directory: string;\n  /** Filesystem path used for manifest resolution. */\n  manifest_path: string;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports source package for this contract. */\n  source_package?: string;\n  /** Value that configures or reports version for this contract. */\n  version: string;\n  /** Value that configures or reports entry for this contract. */\n  entry: string;\n  /** Value that configures or reports priority for this contract. */\n  priority: number;\n  /** Filesystem path used for entry resolution. */\n  entry_path: string;\n  /** Value that configures or reports manifest version for this contract. */\n  manifest_version?: number;\n  /** Value that configures or reports pm min version for this contract. */\n  pm_min_version?: string;\n  /** Value that configures or reports pm max version for this contract. */\n  pm_max_version?: string;\n  /** Value that configures or reports engines for this contract. */\n  engines?: ExtensionManifestEngines;\n  /** Value that configures or reports trusted for this contract. */\n  trusted?: boolean;\n  /** Value that configures or reports provenance for this contract. */\n  provenance?: ExtensionProvenanceMetadata;\n  /** Value that configures or reports sandbox profile for this contract. */\n  sandbox_profile?: ExtensionSandboxProfile;\n  /** Value that configures or reports permissions for this contract. */\n  permissions?: ExtensionRuntimePermissionDeclaration;\n  /** Value that configures or reports capabilities for this contract. */\n  capabilities?: string[];\n  /** Value that configures or reports activation for this contract. */\n  activation?: ExtensionActivationMetadata;\n}\n\n/** Documents the extension discovery result payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionDiscoveryResult {\n  /** Value that configures or reports disabled by flag for this contract. */\n  disabled_by_flag: boolean;\n  /** Value that configures or reports roots for this contract. */\n  roots: {\n    global: string;\n    project: string;\n  };\n  /** Value that configures or reports configured enabled for this contract. */\n  configured_enabled: string[];\n  /** Value that configures or reports configured disabled for this contract. */\n  configured_disabled: string[];\n  /** Value that configures or reports discovered for this contract. */\n  discovered: ExtensionDiagnostic[];\n  /** Value that configures or reports effective for this contract. */\n  effective: EffectiveExtension[];\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n  /** Value that configures or reports policy for this contract. */\n  policy: ExtensionGovernancePolicy;\n}\n\n/** Documents the loaded extension payload exchanged by command, SDK, and package integrations. */\nexport interface LoadedExtension extends EffectiveExtension {\n  /** Value that configures or reports module for this contract. */\n  module: unknown;\n}\n\n/** Documents the failed extension load payload exchanged by command, SDK, and package integrations. */\nexport interface FailedExtensionLoad {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Filesystem path used for entry resolution. */\n  entry_path: string;\n  /** Value that configures or reports error for this contract. */\n  error: string;\n}\n\n/** Documents the extension load result payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionLoadResult extends ExtensionDiscoveryResult {\n  /** Value that configures or reports loaded for this contract. */\n  loaded: LoadedExtension[];\n  /** Value that configures or reports failed for this contract. */\n  failed: FailedExtensionLoad[];\n}\n\n/** Documents the before command hook context payload exchanged by command, SDK, and package integrations. */\nexport interface BeforeCommandHookContext {\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports args for this contract. */\n  args: string[];\n  /** Value that configures or reports options for this contract. */\n  options?: Record<string, unknown>;\n  /** Value that configures or reports global for this contract. */\n  global?: GlobalOptions;\n  /** Value that configures or reports pm root for this contract. */\n  pm_root: string;\n}\n\n/** Documents the after command hook context payload exchanged by command, SDK, and package integrations. */\nexport interface AfterCommandHookContext extends BeforeCommandHookContext {\n  /** Whether the operation completed without a blocking failure. */\n  ok: boolean;\n  /** Value that configures or reports error for this contract. */\n  error?: string;\n  /** Value that configures or reports result for this contract. */\n  result?: unknown;\n  /** Value that configures or reports affected for this contract. */\n  affected?: AfterCommandAffectedItem[];\n}\n\n/** Documents the after command affected item payload exchanged by command, SDK, and package integrations. */\nexport interface AfterCommandAffectedItem {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports op for this contract. */\n  op?: string;\n  /** Schema type that determines the shape and validation rules for this value. */\n  item_type?: string;\n  /** Status id the item held before this mutation. */\n  previous_status?: ItemStatus;\n  /** Lifecycle state reported for status. */\n  status?: ItemStatus;\n  /** Value that configures or reports previous for this contract. */\n  previous?: Partial<ItemMetadata>;\n  /** Value that configures or reports current for this contract. */\n  current?: Partial<ItemMetadata>;\n  /** Value that configures or reports changed fields for this contract. */\n  changed_fields?: string[];\n}\n\n/** Documents the on write hook context payload exchanged by command, SDK, and package integrations. */\nexport interface OnWriteHookContext {\n  /** Filesystem path used for path resolution. */\n  path: string;\n  /** Value that configures or reports scope for this contract. */\n  scope: \"project\" | \"global\";\n  /** Value that configures or reports op for this contract. */\n  op: string;\n  /** Value that configures or reports item id for this contract. */\n  item_id?: string;\n  /** Schema type that determines the shape and validation rules for this value. */\n  item_type?: string;\n  /** Value that configures or reports before for this contract. */\n  before?: ItemDocument;\n  /** Value that configures or reports after for this contract. */\n  after?: ItemDocument;\n  /** Value that configures or reports changed fields for this contract. */\n  changed_fields?: string[];\n}\n\n/** Documents the on read hook context payload exchanged by command, SDK, and package integrations. */\nexport interface OnReadHookContext {\n  /** Filesystem path used for path resolution. */\n  path: string;\n  /** Value that configures or reports scope for this contract. */\n  scope: \"project\" | \"global\";\n}\n\n/** Documents the on index hook context payload exchanged by command, SDK, and package integrations. */\nexport interface OnIndexHookContext {\n  /** Value that configures or reports mode for this contract. */\n  mode: string;\n  /** Value that configures or reports total items for this contract. */\n  total_items?: number;\n}\n\n/** Restricts before command hook values accepted by command, SDK, and storage contracts. */\nexport type BeforeCommandHook = (\n  context: BeforeCommandHookContext,\n) => Promise<void> | void;\n/** Restricts after command hook values accepted by command, SDK, and storage contracts. */\nexport type AfterCommandHook = (\n  context: AfterCommandHookContext,\n) => Promise<void> | void;\n/** Restricts on write hook values accepted by command, SDK, and storage contracts. */\nexport type OnWriteHook = (context: OnWriteHookContext) => Promise<void> | void;\n/** Restricts on read hook values accepted by command, SDK, and storage contracts. */\nexport type OnReadHook = (context: OnReadHookContext) => Promise<void> | void;\n/** Restricts on index hook values accepted by command, SDK, and storage contracts. */\nexport type OnIndexHook = (context: OnIndexHookContext) => Promise<void> | void;\n/** Restricts output renderer format values accepted by command, SDK, and storage contracts. */\nexport type OutputRendererFormat = \"toon\" | \"json\";\n/** Restricts command override values accepted by command, SDK, and storage contracts. */\nexport type CommandOverride = (context: CommandOverrideContext) => unknown;\n/** Restricts renderer override values accepted by command, SDK, and storage contracts. */\nexport type RendererOverride = (\n  context: RendererOverrideContext,\n) => string | null | undefined;\n/** Restricts command handler values accepted by command, SDK, and storage contracts. */\nexport type CommandHandler = (context: CommandHandlerContext) => unknown;\n/** Restricts parser override values accepted by command, SDK, and storage contracts. */\nexport type ParserOverride = (\n  context: ParserOverrideContext,\n) => ParserOverrideDelta | Promise<ParserOverrideDelta>;\n/** Restricts preflight override values accepted by command, SDK, and storage contracts. */\nexport type PreflightOverride = (\n  context: PreflightOverrideContext,\n) => PreflightOverrideDelta | Promise<PreflightOverrideDelta>;\n/** Restricts service override values accepted by command, SDK, and storage contracts. */\nexport type ServiceOverride = (context: ServiceOverrideContext) => unknown;\n\n/** Documents the registered extension hook payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionHook<THook> {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports run for this contract. */\n  run: THook;\n}\n\n/** Documents the extension hook registry payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionHookRegistry {\n  /** Value that configures or reports before command for this contract. */\n  beforeCommand: Array<RegisteredExtensionHook<BeforeCommandHook>>;\n  /** Value that configures or reports after command for this contract. */\n  afterCommand: Array<RegisteredExtensionHook<AfterCommandHook>>;\n  /** Value that configures or reports on write for this contract. */\n  onWrite: Array<RegisteredExtensionHook<OnWriteHook>>;\n  /** Value that configures or reports on read for this contract. */\n  onRead: Array<RegisteredExtensionHook<OnReadHook>>;\n  /** Value that configures or reports on index for this contract. */\n  onIndex: Array<RegisteredExtensionHook<OnIndexHook>>;\n}\n\n/** Documents the command override context payload exchanged by command, SDK, and package integrations. */\nexport interface CommandOverrideContext {\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports args for this contract. */\n  args: string[];\n  /** Value that configures or reports options for this contract. */\n  options?: Record<string, unknown>;\n  /** Value that configures or reports global for this contract. */\n  global?: GlobalOptions;\n  /** Value that configures or reports pm root for this contract. */\n  pm_root: string;\n  /** Value that configures or reports result for this contract. */\n  result: unknown;\n}\n\n/** Documents the renderer override context payload exchanged by command, SDK, and package integrations. */\nexport interface RendererOverrideContext {\n  /** Value that configures or reports format for this contract. */\n  format: OutputRendererFormat;\n  /** Value that configures or reports command for this contract. */\n  command?: string;\n  /** Value that configures or reports args for this contract. */\n  args?: string[];\n  /** Value that configures or reports options for this contract. */\n  options?: Record<string, unknown>;\n  /** Value that configures or reports global for this contract. */\n  global?: GlobalOptions;\n  /** Value that configures or reports pm root for this contract. */\n  pm_root?: string;\n  /** Value that configures or reports result for this contract. */\n  result: unknown;\n}\n\n/** Documents the command handler context payload exchanged by command, SDK, and package integrations. */\nexport interface CommandHandlerContext {\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports args for this contract. */\n  args: string[];\n  /** Value that configures or reports options for this contract. */\n  options: Record<string, unknown>;\n  /** Value that configures or reports global for this contract. */\n  global: GlobalOptions;\n  /** Value that configures or reports pm root for this contract. */\n  pm_root: string;\n  /** Host-bound SDK runtime that avoids package-resolution and private-import coupling. */\n  sdk?: ExtensionCommandSdk;\n}\n\n/** Runtime SDK services injected into every extension command invocation. */\nexport interface ExtensionCommandSdk {\n  /** Tracker-bound client using the invocation author and workspace. */\n  client: PmClient;\n  /** Reconstruct one item at a history version or timestamp. */\n  getItemAt(id: string, target: string): Promise<GetItemAtResult>;\n  /** Open a durable event store with package-contributed relationship semantics. */\n  openRelationshipEventStore(options: {\n    nodes: Iterable<string>;\n    definitions: readonly RelationshipKindDefinition[];\n    relativePath?: string;\n  }): Promise<RelationshipEventStore>;\n  /** Commit idempotent item and relationship mutations under one durable journal. */\n  commitWorkspaceTransaction(\n    options: Omit<CommitWorkspaceTransactionOptions, \"pmRoot\">,\n  ): Promise<WorkspaceTransactionCommitResult>;\n}\n\n/** Documents the parser override context payload exchanged by command, SDK, and package integrations. */\nexport type ParserOverrideContext = CommandHandlerContext;\n\n/** Documents the parser override delta payload exchanged by command, SDK, and package integrations. */\nexport interface ParserOverrideDelta {\n  /** Value that configures or reports args for this contract. */\n  args?: string[];\n  /** Value that configures or reports options for this contract. */\n  options?: Record<string, unknown>;\n  /** Value that configures or reports global for this contract. */\n  global?: GlobalOptions;\n}\n\n/** Documents the preflight override context payload exchanged by command, SDK, and package integrations. */\nexport interface PreflightOverrideContext extends CommandHandlerContext {\n  /** Value that configures or reports decision for this contract. */\n  decision: PreflightRuntimeDecision;\n}\n\n/** Documents the preflight runtime decision payload exchanged by command, SDK, and package integrations. */\nexport interface PreflightRuntimeDecision {\n  /** Value that configures or reports enforce item format gate for this contract. */\n  enforce_item_format_gate: boolean;\n  /** Executes the preflight item format sync operation through the package runtime. */\n  run_preflight_item_format_sync: boolean;\n  /** Executes the extension migrations operation through the package runtime. */\n  run_extension_migrations: boolean;\n  /** Value that configures or reports enforce mandatory migration gate for this contract. */\n  enforce_mandatory_migration_gate: boolean;\n}\n\n/** Documents the preflight override delta payload exchanged by command, SDK, and package integrations. */\nexport interface PreflightOverrideDelta extends ParserOverrideDelta {\n  /** Value that configures or reports enforce item format gate for this contract. */\n  enforce_item_format_gate?: boolean;\n  /** Executes the preflight item format sync operation through the package runtime. */\n  run_preflight_item_format_sync?: boolean;\n  /** Executes the extension migrations operation through the package runtime. */\n  run_extension_migrations?: boolean;\n  /** Value that configures or reports enforce mandatory migration gate for this contract. */\n  enforce_mandatory_migration_gate?: boolean;\n}\n\n/** Documents the service override context payload exchanged by command, SDK, and package integrations. */\nexport interface ServiceOverrideContext {\n  /** Value that configures or reports service for this contract. */\n  service: ExtensionServiceName;\n  /** Value that configures or reports command for this contract. */\n  command?: string;\n  /** Value that configures or reports args for this contract. */\n  args?: string[];\n  /** Value that configures or reports options for this contract. */\n  options?: Record<string, unknown>;\n  /** Value that configures or reports global for this contract. */\n  global?: GlobalOptions;\n  /** Value that configures or reports pm root for this contract. */\n  pm_root?: string;\n  /** Value that configures or reports payload for this contract. */\n  payload: unknown;\n}\n\n/** Documents the extension command argument definition payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionCommandArgumentDefinition {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports required for this contract. */\n  required?: boolean;\n  /** Value that configures or reports variadic for this contract. */\n  variadic?: boolean;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n}\n\n/** Documents the command definition payload exchanged by command, SDK, and package integrations. */\nexport interface CommandDefinition {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports run for this contract. */\n  run?: CommandHandler;\n  /**\n   * @deprecated Use `run` instead. This alias remains for backward compatibility.\n   */\n  handler?: CommandHandler;\n  /** Value that configures or reports action for this contract. */\n  action?: string;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Value that configures or reports intent for this contract. */\n  intent?: string;\n  /** Value that configures or reports examples for this contract. */\n  examples?: string[];\n  /** Value that configures or reports failure hints for this contract. */\n  failure_hints?: string[];\n  /** Value that configures or reports arguments for this contract. */\n  arguments?: ExtensionCommandArgumentDefinition[];\n  /** Value that configures or reports flags for this contract. */\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  /** Value that configures or reports action for this contract. */\n  action?: string;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Value that configures or reports intent for this contract. */\n  intent?: string;\n  /** Value that configures or reports examples for this contract. */\n  examples?: string[];\n  /** Value that configures or reports failure hints for this contract. */\n  failure_hints?: string[];\n  /** Value that configures or reports arguments for this contract. */\n  arguments?: ExtensionCommandArgumentDefinition[];\n  /** Value that configures or reports flags for this contract. */\n  flags?: FlagDefinition[];\n}\n\n/** Restricts flag value type values accepted by command, SDK, and storage contracts. */\nexport type FlagValueType = \"string\" | \"number\" | \"boolean\";\n\n/** Documents the flag definition payload exchanged by command, SDK, and package integrations. */\nexport interface FlagDefinition {\n  /** Value that configures or reports long for this contract. */\n  long?: string;\n  /** Value that configures or reports short for this contract. */\n  short?: string;\n  /** Value that configures or reports value name for this contract. */\n  value_name?: string;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Value that configures or reports required for this contract. */\n  required?: boolean;\n  /** Whether enabled applies to this operation. */\n  enabled?: boolean;\n  /** Value that configures or reports visible for this contract. */\n  visible?: boolean;\n  /** Canonical flag value type. Prefer this field; it is the one runtime contracts and help output read first. */\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  /** When true, a repeated comma-list flag accumulates values across repeats — parity with core list flags such as `--tags` — instead of the last value winning. Mirrors the core `CliFlagContract.list` field so extension-registered list flags coalesce through the same bootstrap path. */\n  list?: boolean;\n  /** Default value applied when the flag is omitted. Surfaced to runtime contracts and help output. A `list` flag may default to an array of scalars (e.g. `[\"a\", \"b\"]`); the array is flattened/coerced like any list value. */\n  default?: string | number | boolean | Array<string | number | boolean>;\n  [key: string]: unknown;\n}\n\n/** Documents the schema field definition payload exchanged by command, SDK, and package integrations. */\nexport interface SchemaFieldDefinition {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Schema type that determines the shape and validation rules for this value. */\n  type: string;\n  /** Value that configures or reports optional for this contract. */\n  optional?: boolean;\n  [key: string]: unknown;\n}\n\n/** Documents the schema item type command option policy definition payload exchanged by command, SDK, and package integrations. */\nexport interface SchemaItemTypeCommandOptionPolicyDefinition {\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports option for this contract. */\n  option: string;\n  /** Whether enabled applies to this operation. */\n  enabled?: boolean;\n  /** Value that configures or reports required for this contract. */\n  required?: boolean;\n  /** Value that configures or reports visible for this contract. */\n  visible?: boolean;\n  [key: string]: unknown;\n}\n\n/** Documents the schema item type option definition payload exchanged by command, SDK, and package integrations. */\nexport interface SchemaItemTypeOptionDefinition {\n  /** Value that configures or reports key for this contract. */\n  key: string;\n  /** Value that configures or reports values for this contract. */\n  values?: string[];\n  /** Value that configures or reports required for this contract. */\n  required?: boolean;\n  /** Value that configures or reports aliases for this contract. */\n  aliases?: string[];\n  [key: string]: unknown;\n}\n\n/** Documents the schema item type definition payload exchanged by command, SDK, and package integrations. */\nexport interface SchemaItemTypeDefinition {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports folder for this contract. */\n  folder?: string;\n  /** Value that configures or reports aliases for this contract. */\n  aliases?: string[];\n  /** Value that configures or reports required create fields for this contract. */\n  required_create_fields?: string[];\n  /** Value that configures or reports required create repeatables for this contract. */\n  required_create_repeatables?: string[];\n  /** Value that configures or reports command option policies for this contract. */\n  command_option_policies?: SchemaItemTypeCommandOptionPolicyDefinition[];\n  /** Value that configures or reports options for this contract. */\n  options?: SchemaItemTypeOptionDefinition[];\n  [key: string]: unknown;\n}\n\n/** Documents the schema migration run context payload exchanged by command, SDK, and package integrations. */\nexport interface SchemaMigrationRunContext {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports command for this contract. */\n  command: \"migration\";\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports extension for this contract. */\n  extension: string;\n  /** Value that configures or reports pm root for this contract. */\n  pm_root: string;\n  /** Lifecycle state reported for status. */\n  status: string;\n}\n\n/** Restricts schema migration runner values accepted by command, SDK, and storage contracts. */\nexport type SchemaMigrationRunner = (\n  context: SchemaMigrationRunContext,\n) => unknown | Promise<unknown>;\n\n/** Documents the schema migration definition payload exchanged by command, SDK, and package integrations. */\nexport interface SchemaMigrationDefinition {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id?: string;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Lifecycle state reported for status. */\n  status?: string;\n  /** Value that configures or reports mandatory for this contract. */\n  mandatory?: boolean;\n  /** Value that configures or reports run for this contract. */\n  run?: SchemaMigrationRunner;\n  [key: string]: unknown;\n}\n\n/** Documents the import export context payload exchanged by command, SDK, and package integrations. */\nexport interface ImportExportContext {\n  /** Value that configures or reports registration for this contract. */\n  registration: string;\n  /** Value that configures or reports action for this contract. */\n  action: \"import\" | \"export\";\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports args for this contract. */\n  args: string[];\n  /** Value that configures or reports options for this contract. */\n  options: Record<string, unknown>;\n  /** Value that configures or reports global for this contract. */\n  global: GlobalOptions;\n  /** Value that configures or reports pm root for this contract. */\n  pm_root: string;\n}\n\n/** Restricts importer values accepted by command, SDK, and storage contracts. */\nexport type Importer = (\n  context: ImportExportContext,\n) => unknown | Promise<unknown>;\n/** Restricts exporter values accepted by command, SDK, and storage contracts. */\nexport type Exporter = (\n  context: ImportExportContext,\n) => unknown | Promise<unknown>;\n\n/** Restricts extension search mode values accepted by command, SDK, and storage contracts. */\nexport type ExtensionSearchMode = \"keyword\" | \"semantic\" | \"hybrid\";\n\n/** Documents the search provider query context payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderQueryContext {\n  /** Value that configures or reports query for this contract. */\n  query: string;\n  /** Value that configures or reports mode for this contract. */\n  mode: ExtensionSearchMode;\n  /** Value that configures or reports tokens for this contract. */\n  tokens: string[];\n  /** Value that configures or reports options for this contract. */\n  options: Record<string, unknown>;\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  /** Value that configures or reports documents for this contract. */\n  documents: ItemDocument[];\n  [key: string]: unknown;\n}\n\n/** Documents the search provider hit payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderHit {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports score for this contract. */\n  score: number;\n  /** Value that configures or reports matched fields for this contract. */\n  matched_fields?: string[];\n  [key: string]: unknown;\n}\n\n/** Restricts search provider query result values accepted by command, SDK, and storage contracts. */\nexport type SearchProviderQueryResult =\n  | SearchProviderHit[]\n  | { hits?: SearchProviderHit[] };\n\n/** Documents the search provider query expansion context payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderQueryExpansionContext {\n  /** Value that configures or reports query for this contract. */\n  query: string;\n  /** Value that configures or reports mode for this contract. */\n  mode: Exclude<ExtensionSearchMode, \"keyword\">;\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/** Restricts search provider query expansion result values accepted by command, SDK, and storage contracts. */\nexport type SearchProviderQueryExpansionResult =\n  | string[]\n  | { queries?: string[] };\n\n/** Documents the search provider rerank candidate payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderRerankCandidate {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports text for this contract. */\n  text: string;\n  /** Value that configures or reports score for this contract. */\n  score: number;\n}\n\n/** Documents the search provider rerank hit payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderRerankHit {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports score for this contract. */\n  score: number;\n}\n\n/** Restricts search provider rerank result values accepted by command, SDK, and storage contracts. */\nexport type SearchProviderRerankResult =\n  | SearchProviderRerankHit[]\n  | { hits?: SearchProviderRerankHit[] };\n\n/** Documents the search provider rerank context payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderRerankContext {\n  /** Value that configures or reports query for this contract. */\n  query: string;\n  /** Value that configures or reports mode for this contract. */\n  mode: \"hybrid\";\n  /** Value that configures or reports model for this contract. */\n  model: string;\n  /** Value that configures or reports top k for this contract. */\n  top_k: number;\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  /** Value that configures or reports candidates for this contract. */\n  candidates: SearchProviderRerankCandidate[];\n  [key: string]: unknown;\n}\n\n/** Documents the search provider embed batch context payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderEmbedBatchContext {\n  /** Value that configures or reports inputs for this contract. */\n  inputs: string[];\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  /** Value that configures or reports model for this contract. */\n  model: string;\n  [key: string]: unknown;\n}\n\n/** Documents the search provider embed context payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderEmbedContext {\n  /** Value that configures or reports input for this contract. */\n  input: string;\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  /** Value that configures or reports model for this contract. */\n  model: string;\n  [key: string]: unknown;\n}\n\n/** Documents the search provider definition payload exchanged by command, SDK, and package integrations. */\nexport interface SearchProviderDefinition {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports query for this contract. */\n  query?: (\n    context: SearchProviderQueryContext,\n  ) => SearchProviderQueryResult | Promise<SearchProviderQueryResult>;\n  /** Value that configures or reports query expansion for this contract. */\n  queryExpansion?: (\n    context: SearchProviderQueryExpansionContext,\n  ) =>\n    | SearchProviderQueryExpansionResult\n    | Promise<SearchProviderQueryExpansionResult>;\n  /** Value that configures or reports query expansion for this contract. */\n  query_expansion?: (\n    context: SearchProviderQueryExpansionContext,\n  ) =>\n    | SearchProviderQueryExpansionResult\n    | Promise<SearchProviderQueryExpansionResult>;\n  /** Value that configures or reports rerank for this contract. */\n  rerank?: (\n    context: SearchProviderRerankContext,\n  ) => SearchProviderRerankResult | Promise<SearchProviderRerankResult>;\n  /** Value that configures or reports embed batch for this contract. */\n  embedBatch?: (\n    context: SearchProviderEmbedBatchContext,\n  ) => number[][] | Promise<number[][]>;\n  /** Value that configures or reports embed batch for this contract. */\n  embed_batch?: (\n    context: SearchProviderEmbedBatchContext,\n  ) => number[][] | Promise<number[][]>;\n  /** Value that configures or reports embed for this contract. */\n  embed?: (context: SearchProviderEmbedContext) => number[] | Promise<number[]>;\n  [key: string]: unknown;\n}\n\n/** Documents the vector store query hit payload exchanged by command, SDK, and package integrations. */\nexport interface VectorStoreQueryHit {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports score for this contract. */\n  score: number;\n  /** Value that configures or reports payload for this contract. */\n  payload?: Record<string, unknown>;\n  [key: string]: unknown;\n}\n\n/** Documents the vector store query context payload exchanged by command, SDK, and package integrations. */\nexport interface VectorStoreQueryContext {\n  /** Value that configures or reports vector for this contract. */\n  vector: number[];\n  /** Value that configures or reports limit for this contract. */\n  limit: number;\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/** Documents the vector store upsert point payload exchanged by command, SDK, and package integrations. */\nexport interface VectorStoreUpsertPoint {\n  /** Stable identifier used to reference this record across commands and storage. */\n  id: string;\n  /** Value that configures or reports vector for this contract. */\n  vector: number[];\n  /** Value that configures or reports payload for this contract. */\n  payload?: Record<string, unknown>;\n  [key: string]: unknown;\n}\n\n/** Documents the vector store upsert context payload exchanged by command, SDK, and package integrations. */\nexport interface VectorStoreUpsertContext {\n  /** Value that configures or reports points for this contract. */\n  points: VectorStoreUpsertPoint[];\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/** Documents the vector store delete context payload exchanged by command, SDK, and package integrations. */\nexport interface VectorStoreDeleteContext {\n  /** Value that configures or reports ids for this contract. */\n  ids: string[];\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  [key: string]: unknown;\n}\n\n/** Documents the vector store adapter definition payload exchanged by command, SDK, and package integrations. */\nexport interface VectorStoreAdapterDefinition {\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports query for this contract. */\n  query?: (\n    context: VectorStoreQueryContext,\n  ) => VectorStoreQueryHit[] | Promise<VectorStoreQueryHit[]>;\n  /** Value that configures or reports upsert for this contract. */\n  upsert?: (context: VectorStoreUpsertContext) => unknown | Promise<unknown>;\n  /** Value that configures or reports delete for this contract. */\n  delete?: (context: VectorStoreDeleteContext) => unknown | Promise<unknown>;\n  [key: string]: unknown;\n}\n\n/** Documents the registered extension command override payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionCommandOverride {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports run for this contract. */\n  run: CommandOverride;\n}\n\n/** Documents the registered extension command handler payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionCommandHandler {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports run for this contract. */\n  run: CommandHandler;\n}\n\n/** Documents the registered extension parser override payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionParserOverride {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports run for this contract. */\n  run: ParserOverride;\n}\n\n/** Documents the registered extension preflight override payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionPreflightOverride {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports run for this contract. */\n  run: PreflightOverride;\n}\n\n/** Documents the registered extension service override payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionServiceOverride {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports service for this contract. */\n  service: ExtensionServiceName;\n  /** Value that configures or reports run for this contract. */\n  run: ServiceOverride;\n}\n\n/** Documents the registered extension renderer override payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionRendererOverride {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports format for this contract. */\n  format: OutputRendererFormat;\n  /** Value that configures or reports run for this contract. */\n  run: RendererOverride;\n}\n\n/** Documents the extension command registry payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionCommandRegistry {\n  /** Value that configures or reports overrides for this contract. */\n  overrides: RegisteredExtensionCommandOverride[];\n  /** Value that configures or reports handlers for this contract. */\n  handlers: RegisteredExtensionCommandHandler[];\n}\n\n/** Documents the extension parser registry payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionParserRegistry {\n  /** Value that configures or reports overrides for this contract. */\n  overrides: RegisteredExtensionParserOverride[];\n}\n\n/** Documents the extension preflight registry payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionPreflightRegistry {\n  /** Value that configures or reports overrides for this contract. */\n  overrides: RegisteredExtensionPreflightOverride[];\n}\n\n/** Documents the extension service registry payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionServiceRegistry {\n  /** Value that configures or reports overrides for this contract. */\n  overrides: RegisteredExtensionServiceOverride[];\n}\n\n/** Documents the extension renderer registry payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionRendererRegistry {\n  /** Value that configures or reports overrides for this contract. */\n  overrides: RegisteredExtensionRendererOverride[];\n}\n\n/** Documents the registered extension flag definitions payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionFlagDefinitions {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports target command for this contract. */\n  target_command: string;\n  /** Value that configures or reports flags for this contract. */\n  flags: FlagDefinition[];\n}\n\n/** Documents the registered extension command definition payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionCommandDefinition {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports source package for this contract. */\n  source_package?: string;\n  /** Value that configures or reports command for this contract. */\n  command: string;\n  /** Value that configures or reports action for this contract. */\n  action: string;\n  /** Value that configures or reports description for this contract. */\n  description?: string;\n  /** Value that configures or reports intent for this contract. */\n  intent?: string;\n  /** Value that configures or reports examples for this contract. */\n  examples: string[];\n  /** Value that configures or reports failure hints for this contract. */\n  failure_hints: string[];\n  /** Value that configures or reports arguments for this contract. */\n  arguments: ExtensionCommandArgumentDefinition[];\n}\n\n/** Documents the registered extension schema field definitions payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionSchemaFieldDefinitions {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports fields for this contract. */\n  fields: SchemaFieldDefinition[];\n}\n\n/** Documents the registered extension schema item type definitions payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionSchemaItemTypeDefinitions {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports types for this contract. */\n  types: SchemaItemTypeDefinition[];\n}\n\n/** Relationship ontology definitions contributed by one active extension. */\nexport interface RegisteredExtensionRelationshipKindDefinitions {\n  /** Extension layer that owns these definitions. */\n  layer: ExtensionLayer;\n  /** Extension name that owns these definitions. */\n  name: string;\n  /** Validated immutable relationship-kind definitions. */\n  definitions: RelationshipKindDefinition[];\n}\n\n/** Documents the registered extension schema migration definition payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionSchemaMigrationDefinition {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports definition for this contract. */\n  definition: SchemaMigrationDefinition;\n  /** Value that configures or reports runtime definition for this contract. */\n  runtime_definition: SchemaMigrationDefinition;\n}\n\n/** Documents the registered extension importer payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionImporter {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports importer for this contract. */\n  importer: string;\n}\n\n/** Documents the registered extension exporter payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionExporter {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports exporter for this contract. */\n  exporter: string;\n}\n\n/** Documents the registered extension search provider payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionSearchProvider {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports definition for this contract. */\n  definition: SearchProviderDefinition;\n  /** Value that configures or reports runtime definition for this contract. */\n  runtime_definition: SearchProviderDefinition;\n}\n\n/** Documents the registered extension vector store adapter payload exchanged by command, SDK, and package integrations. */\nexport interface RegisteredExtensionVectorStoreAdapter {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports definition for this contract. */\n  definition: VectorStoreAdapterDefinition;\n  /** Value that configures or reports runtime definition for this contract. */\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  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports profile for this contract. */\n  profile: ProjectProfileDefinition;\n}\n\n/** Documents the extension registration registry payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionRegistrationRegistry {\n  /** Value that configures or reports commands for this contract. */\n  commands: RegisteredExtensionCommandDefinition[];\n  /** Value that configures or reports flags for this contract. */\n  flags: RegisteredExtensionFlagDefinitions[];\n  /** Value that configures or reports item fields for this contract. */\n  item_fields: RegisteredExtensionSchemaFieldDefinitions[];\n  /** Value that configures or reports item types for this contract. */\n  item_types: RegisteredExtensionSchemaItemTypeDefinitions[];\n  /** Value that configures application-defined relationship semantics. */\n  relationship_kinds: RegisteredExtensionRelationshipKindDefinitions[];\n  /** Value that configures or reports migrations for this contract. */\n  migrations: RegisteredExtensionSchemaMigrationDefinition[];\n  /** Value that configures or reports profiles for this contract. */\n  profiles: RegisteredExtensionProjectProfile[];\n  /** Value that configures or reports importers for this contract. */\n  importers: RegisteredExtensionImporter[];\n  /** Value that configures or reports exporters for this contract. */\n  exporters: RegisteredExtensionExporter[];\n  /** Value that configures or reports search providers for this contract. */\n  search_providers: RegisteredExtensionSearchProvider[];\n  /** Value that configures or reports vector store adapters for this contract. */\n  vector_store_adapters: RegisteredExtensionVectorStoreAdapter[];\n}\n\n/** Documents the extension registration counts payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionRegistrationCounts {\n  /** Value that configures or reports commands for this contract. */\n  commands: number;\n  /** Value that configures or reports flags for this contract. */\n  flags: number;\n  /** Value that configures or reports item fields for this contract. */\n  item_fields: number;\n  /** Value that configures or reports item types for this contract. */\n  item_types: number;\n  /** Number of application-defined relationship kinds. */\n  relationship_kinds?: number;\n  /** Value that configures or reports migrations for this contract. */\n  migrations: number;\n  /** Value that configures or reports profiles for this contract. */\n  profiles: number;\n  /** Value that configures or reports importers for this contract. */\n  importers: number;\n  /** Value that configures or reports exporters for this contract. */\n  exporters: number;\n  /** Value that configures or reports search providers for this contract. */\n  search_providers: number;\n  /** Value that configures or reports vector store adapters for this contract. */\n  vector_store_adapters: number;\n}\n\n/** Read-only identity an extension's `activate(api)` receives about itself, so authors can emit self-identifying logs, gate on their own version, and build better error messages without re-reading the on-disk manifest or duplicating metadata in-module. Exposed as `api.extension`. */\nexport interface ExtensionSelfIdentity {\n  /** Value that configures or reports name for this contract. */\n  readonly name: string;\n  /** Value that configures or reports layer for this contract. */\n  readonly layer: ExtensionLayer;\n  /** Value that configures or reports version for this contract. */\n  readonly version: string;\n  /** Value that configures or reports capabilities for this contract. */\n  readonly capabilities: readonly ExtensionCapability[];\n  /** Value that configures or reports pm min version for this contract. */\n  readonly pm_min_version?: string;\n  /** Value that configures or reports pm max version for this contract. */\n  readonly pm_max_version?: string;\n  /** Value that configures or reports source package for this contract. */\n  readonly source_package?: string;\n}\n\n/** Documents the extension api payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionApi {\n  /** Read-only identity of the extension this `api` was created for. */\n  readonly extension: ExtensionSelfIdentity;\n  /** Value that configures or reports register command for this contract. */\n  registerCommand(command: string, override: CommandOverride): void;\n  /** Value that configures or reports register command for this contract. */\n  registerCommand(definition: CommandDefinition): void;\n  /** Value that configures or reports register parser for this contract. */\n  registerParser(command: string, override: ParserOverride): void;\n  /** Value that configures or reports register preflight for this contract. */\n  registerPreflight(override: PreflightOverride): void;\n  /** Value that configures or reports register service for this contract. */\n  registerService(\n    service: ExtensionServiceName,\n    override: ServiceOverride,\n  ): void;\n  /** Value that configures or reports register flags for this contract. */\n  registerFlags(targetCommand: string, flags: FlagDefinition[]): void;\n  /** Value that configures or reports register item fields for this contract. */\n  registerItemFields(fields: SchemaFieldDefinition[]): void;\n  /** Value that configures or reports register item types for this contract. */\n  registerItemTypes(types: SchemaItemTypeDefinition[]): void;\n  /** Register versioned relationship semantics consumed by every graph surface. */\n  registerRelationshipKinds(definitions: RelationshipKindDefinition[]): void;\n  /** Value that configures or reports register migration for this contract. */\n  registerMigration(definition: SchemaMigrationDefinition): void;\n  /** Value that configures or reports register profile for this contract. */\n  registerProfile(profile: ProjectProfileRegistrationInput): void;\n  /** Value that configures or reports register renderer for this contract. */\n  registerRenderer(\n    format: OutputRendererFormat,\n    renderer: RendererOverride,\n  ): void;\n  /** Value that configures or reports register importer for this contract. */\n  registerImporter(\n    name: string,\n    importer: Importer,\n    options?: ImportExportRegistrationOptions,\n  ): void;\n  /** Value that configures or reports register exporter for this contract. */\n  registerExporter(\n    name: string,\n    exporter: Exporter,\n    options?: ImportExportRegistrationOptions,\n  ): void;\n  /** Value that configures or reports register search provider for this contract. */\n  registerSearchProvider(provider: SearchProviderDefinition): void;\n  /** Value that configures or reports register vector store adapter for this contract. */\n  registerVectorStoreAdapter(adapter: VectorStoreAdapterDefinition): void;\n  /** Value that configures or reports hooks for this contract. */\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/** Documents the failed extension activation payload exchanged by command, SDK, and package integrations. */\nexport interface FailedExtensionActivation {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Filesystem path used for entry resolution. */\n  entry_path: string;\n  /** Value that configures or reports error for this contract. */\n  error: string;\n  /** Value that configures or reports trace for this contract. */\n  trace?: ExtensionActivationFailureTrace;\n}\n\n/** Documents the extension activation failure trace payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionActivationFailureTrace {\n  /** Value that configures or reports method for this contract. */\n  method: string;\n  /** `-1` means the failure happened before a numbered registration was accepted. */\n  registration_index: number;\n  /** Value that configures or reports command for this contract. */\n  command?: string;\n  /** Value that configures or reports capability for this contract. */\n  capability?: ExtensionCapability;\n  /** Value that configures or reports missing capability for this contract. */\n  missing_capability?: ExtensionCapability;\n  /** Value that configures or reports expected schema for this contract. */\n  expected_schema: string;\n  /** Value that configures or reports received for this contract. */\n  received?: unknown;\n  /** Value that configures or reports hint for this contract. */\n  hint?: string;\n}\n\n/** Documents the extension activation result payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionActivationResult {\n  /** Value that configures or reports hooks for this contract. */\n  hooks: ExtensionHookRegistry;\n  /** Value that configures or reports commands for this contract. */\n  commands: ExtensionCommandRegistry;\n  /** Value that configures or reports parsers for this contract. */\n  parsers: ExtensionParserRegistry;\n  /** Value that configures or reports preflight for this contract. */\n  preflight: ExtensionPreflightRegistry;\n  /** Value that configures or reports services for this contract. */\n  services: ExtensionServiceRegistry;\n  /** Value that configures or reports renderers for this contract. */\n  renderers: ExtensionRendererRegistry;\n  /** Value that configures or reports registrations for this contract. */\n  registrations: ExtensionRegistrationRegistry;\n  /** Value that configures or reports failed for this contract. */\n  failed: FailedExtensionActivation[];\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n  /** Value that configures or reports hook counts for this contract. */\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  /** Number of command override entries represented by this result. */\n  command_override_count: number;\n  /** Number of command handler entries represented by this result. */\n  command_handler_count: number;\n  /** Number of parser override entries represented by this result. */\n  parser_override_count: number;\n  /** Number of preflight override entries represented by this result. */\n  preflight_override_count: number;\n  /** Number of service override entries represented by this result. */\n  service_override_count: number;\n  /** Number of renderer override entries represented by this result. */\n  renderer_override_count: number;\n  /** Value that configures or reports registration counts for this contract. */\n  registration_counts: ExtensionRegistrationCounts;\n}\n\n/** Documents the extension candidate payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionCandidate {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports directory for this contract. */\n  directory: string;\n  /** Filesystem path used for manifest resolution. */\n  manifest_path: string;\n  /** Filesystem path used for entry resolution. */\n  entry_path: string;\n  /** Declarative package manifest consumed by the extension loader. */\n  manifest: ExtensionManifest;\n  /** Value that configures or reports source package for this contract. */\n  source_package?: string;\n}\n\n/** Documents the extension layer scan result payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionLayerScanResult {\n  /** Value that configures or reports diagnostics for this contract. */\n  diagnostics: ExtensionDiagnostic[];\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n  /** Value that configures or reports candidates for this contract. */\n  candidates: ExtensionCandidate[];\n}\n\n/** Documents the scanned extension directory payload exchanged by command, SDK, and package integrations. */\nexport interface ScannedExtensionDirectory {\n  /** Value that configures or reports diagnostic for this contract. */\n  diagnostic: ExtensionDiagnostic;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n  /** Value that configures or reports candidate for this contract. */\n  candidate: ExtensionCandidate | null;\n}\n\n/** Documents the legacy extension capability alias mapping payload exchanged by command, SDK, and package integrations. */\nexport interface LegacyExtensionCapabilityAliasMapping {\n  /** Value that configures or reports alias for this contract. */\n  alias: string;\n  /** Value that configures or reports target for this contract. */\n  target: ExtensionCapability;\n}\n\n/** Documents the discover extensions options payload exchanged by command, SDK, and package integrations. */\nexport interface DiscoverExtensionsOptions {\n  /** Value that configures or reports pm root for this contract. */\n  pmRoot: string;\n  /** Value that configures or reports settings for this contract. */\n  settings: PmSettings;\n  /** Value that configures or reports cwd for this contract. */\n  cwd?: string;\n  /** Value that configures or reports no extensions for this contract. */\n  noExtensions?: boolean;\n  /** Value that configures or reports ignore global extensions for this contract. */\n  ignoreGlobalExtensions?: boolean;\n  /** Value that configures or reports reload token for this contract. */\n  reload_token?: string;\n  /** Value that configures or reports cache bust for this contract. */\n  cache_bust?: boolean;\n  /** Optional import-stage filter. Discovery still reports the full effective set, but `loadExtensions` imports only entries accepted by this predicate. */\n  extensionFilter?: (extension: EffectiveExtension) => boolean;\n}\n\n/** Documents the activatable extension payload exchanged by command, SDK, and package integrations. */\nexport interface ActivatableExtension {\n  /** Registers this package's commands, actions, and runtime hooks with the host. */\n  activate: (api: ExtensionApi) => void | Promise<void>;\n  /** Optional teardown lifecycle hook, analogous to VS Code's `deactivate` export. Invoked when the host tears the extension down — on long-running MCP-server reload between requests, or via the `deactivateExtensions` primitive — so an extension can close connections, clear timers, and release buffers it opened during `activate`. */\n  deactivate?: () => void | Promise<void>;\n}\n\n/** Documents the extension deactivation failure payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionDeactivationFailure {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports error for this contract. */\n  error: string;\n}\n\n/** Documents the extension deactivation options payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionDeactivationOptions {\n  /** Maximum time to wait for each extension's `deactivate` hook. Defaults to 5000ms so a hanging teardown cannot block host shutdown or reload. Set to 0 or Infinity only when the host intentionally wants to wait indefinitely. */\n  deactivate_timeout_ms?: number;\n}\n\n/** Documents the extension deactivation result payload exchanged by command, SDK, and package integrations. */\nexport interface ExtensionDeactivationResult {\n  /** Count of loaded extensions whose `deactivate` hook ran without throwing. */\n  deactivated: number;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n  /** Value that configures or reports failed for this contract. */\n  failed: ExtensionDeactivationFailure[];\n}\n\n/** Documents the service override result payload exchanged by command, SDK, and package integrations. */\nexport interface ServiceOverrideResult {\n  /** Value that configures or reports handled for this contract. */\n  handled: boolean;\n  /** Value that configures or reports result for this contract. */\n  result: unknown;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n}\n\n/** Documents the command override result payload exchanged by command, SDK, and package integrations. */\nexport interface CommandOverrideResult {\n  /** Value that configures or reports overridden for this contract. */\n  overridden: boolean;\n  /** Value that configures or reports result for this contract. */\n  result: unknown;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n}\n\n/** Documents the command handler result payload exchanged by command, SDK, and package integrations. */\nexport interface CommandHandlerResult {\n  /** Value that configures or reports handled for this contract. */\n  handled: boolean;\n  /** Value that configures or reports result for this contract. */\n  result: unknown;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n  /** Human-readable, single-line, length-bounded message describing why an extension command handler failed. Surfaced to the user/CI so the real cause (e.g. \"Changelog is out of date: CHANGELOG.md\") is visible instead of only the opaque `extension_command_handler_failed` warning code. */\n  errorMessage?: string;\n}\n\n/** Documents the parser override result payload exchanged by command, SDK, and package integrations. */\nexport interface ParserOverrideResult {\n  /** Value that configures or reports overridden for this contract. */\n  overridden: boolean;\n  /** Value that configures or reports context for this contract. */\n  context: CommandHandlerContext;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n}\n\n/** Documents the preflight override result payload exchanged by command, SDK, and package integrations. */\nexport interface PreflightOverrideResult {\n  /** Value that configures or reports overridden for this contract. */\n  overridden: boolean;\n  /** Value that configures or reports context for this contract. */\n  context: CommandHandlerContext;\n  /** Value that configures or reports decision for this contract. */\n  decision: PreflightRuntimeDecision;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n}\n\n/** Documents the renderer override result payload exchanged by command, SDK, and package integrations. */\nexport interface RendererOverrideResult {\n  /** Value that configures or reports overridden for this contract. */\n  overridden: boolean;\n  /** Value that configures or reports rendered for this contract. */\n  rendered: string | null;\n  /** Value that configures or reports warnings for this contract. */\n  warnings: string[];\n}\n\n/** Documents the unknown extension capability warning details payload exchanged by command, SDK, and package integrations. */\nexport interface UnknownExtensionCapabilityWarningDetails {\n  /** Value that configures or reports layer for this contract. */\n  layer: ExtensionLayer;\n  /** Value that configures or reports name for this contract. */\n  name: string;\n  /** Value that configures or reports capability for this contract. */\n  capability: string;\n  /** Value that configures or reports allowed capabilities for this contract. */\n  allowed_capabilities: string[];\n  /** Value that configures or reports capability contract version for this contract. */\n  capability_contract_version: number;\n  /** Value that configures or reports suggested capability for this contract. */\n  suggested_capability?: string;\n  /** Value that configures or reports suggestion source for this contract. */\n  suggestion_source?: \"legacy_alias\" | \"nearest_match\";\n  /** Value that configures or reports legacy alias target for this contract. */\n  legacy_alias_target?: string;\n}\n"],"names":[],"mappings":"AA+BA,wGAAwG;;;AACxG,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;AAGX,iHAAiH;AACjH,MAAM,CAAC,MAAM,qCAAqC,GAAG,CAAC,CAAC;AACvD,+GAA+G;AAC/G,MAAM,CAAC,MAAM,mCAAmC,GAE5C,MAAM,CAAC,MAAM,CAAC;IAChB,SAAS,EAAE,QAAQ;IACnB,UAAU,EAAE,QAAQ;CACrB,CAAC,CAAC;AACH,yGAAyG;AACzG,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,wGAAwG;AACxG,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAGhF,uGAAuG;AACvG,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAU,CAAC;AAG/E,4GAA4G;AAC5G,MAAM,CAAC,MAAM,gCAAgC,GAAG;IAC9C,MAAM;IACN,YAAY;IACZ,QAAQ;CACA,CAAC;AAKX,+GAA+G;AAC/G,MAAM,CAAC,MAAM,mCAAmC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAU,CAAC;AAgB9E,2GAA2G;AAC3G,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,0BAA0B;IAC1B,mBAAmB;IACnB,iBAAiB;IACjB,iBAAiB;IACjB,oBAAoB;IACpB,mBAAmB;IACnB,oBAAoB;IACpB,oBAAoB;IACpB,oBAAoB;IACpB,iBAAiB;IACjB,oBAAoB;CACZ,CAAC;AAKX,yGAAyG;AACzG,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,eAAe;IACf,cAAc;IACd,aAAa;IACb,cAAc;IACd,cAAc;IACd,gBAAgB;IAChB,kBAAkB;IAClB,mBAAmB;IACnB,mBAAmB;IACnB,gBAAgB;CACR,CAAC;AAuDX,2GAA2G;AAC3G,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":"15bbc696-5001-58e2-8b5c-dd09860d5a29"}

package/dist/core/item/id.d.ts

@@ -4,5 +4,22 @@ export declare function normalizePrefix(input: string | undefined): string;
 export declare function normalizeRawItemId(input: string): string;
 /** Implements normalize item id for the public runtime surface of this module. */
 export declare function normalizeItemId(input: string, prefix: string): string;
-/** Implements generate item id for the public runtime surface of this module. */
-export declare function generateItemId(pmRoot: string, prefix: string): Promise<string>;
+/** Bounds accepted for the configurable random id token length (`ids.token_length`). */
+export declare const ID_TOKEN_LENGTH_MIN = 4;
+/** Upper bound for `ids.token_length`; longer tokens stop improving ergonomics without meaningfully improving uniqueness. */
+export declare const ID_TOKEN_LENGTH_MAX = 12;
+/** Clamp a configured id token length into the supported bounds, falling back to the 4-character default for non-finite input. */
+export declare function clampIdTokenLength(value: number | undefined): number;
+/**
+ * Mint a new item id as `<prefix><random base36 token>`. The starting token
+ * length comes from the workspace `ids.token_length` setting (default 4) and
+ * escalates automatically when the local uniqueness probe keeps colliding.
+ * Uniqueness is only verifiable against the local working tree: concurrent
+ * branches can still mint the same id independently, which is why longer
+ * configured tokens matter for multi-agent workflows and why
+ * `pm validate --check-storage-integrity` detects post-merge duplicate-id
+ * collisions (GH-600).
+ */
+export declare function generateItemId(pmRoot: string, prefix: string, options?: {
+    tokenLength?: number;
+}): Promise<string>;

package/dist/core/item/id.js

@@ -4,7 +4,7 @@
  * Defines item parsing, formatting, and lifecycle helpers for Id.
  */
 
-!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]="900d99bf-095b-5dcf-9a33-b04c9b440969")}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]="ee13ce1e-8508-5eb1-be0b-6e49f4280e87")}catch(e){}}();
 import crypto from "node:crypto";
 import path from "node:path";
 import { TYPE_TO_FOLDER } from "../shared/constants.js";
@@ -52,11 +52,32 @@ async function idExists(pmRoot, id) {
     }
     return false;
 }
-/** Implements generate item id for the public runtime surface of this module. */
-export async function generateItemId(pmRoot, prefix) {
-    let tokenLength = 4;
+/** Bounds accepted for the configurable random id token length (`ids.token_length`). */
+export const ID_TOKEN_LENGTH_MIN = 4;
+/** Upper bound for `ids.token_length`; longer tokens stop improving ergonomics without meaningfully improving uniqueness. */
+export const ID_TOKEN_LENGTH_MAX = 12;
+/** Clamp a configured id token length into the supported bounds, falling back to the 4-character default for non-finite input. */
+export function clampIdTokenLength(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return ID_TOKEN_LENGTH_MIN;
+    }
+    return Math.min(ID_TOKEN_LENGTH_MAX, Math.max(ID_TOKEN_LENGTH_MIN, Math.trunc(value)));
+}
+/**
+ * Mint a new item id as `<prefix><random base36 token>`. The starting token
+ * length comes from the workspace `ids.token_length` setting (default 4) and
+ * escalates automatically when the local uniqueness probe keeps colliding.
+ * Uniqueness is only verifiable against the local working tree: concurrent
+ * branches can still mint the same id independently, which is why longer
+ * configured tokens matter for multi-agent workflows and why
+ * `pm validate --check-storage-integrity` detects post-merge duplicate-id
+ * collisions (GH-600).
+ */
+export async function generateItemId(pmRoot, prefix, options = {}) {
+    let tokenLength = clampIdTokenLength(options.tokenLength);
+    const maxTokenLength = Math.min(tokenLength + 6, ID_TOKEN_LENGTH_MAX);
     let attempts = 0;
-    while (tokenLength <= 10) {
+    while (tokenLength <= maxTokenLength) {
         for (let i = 0; i < 32; i += 1) {
             const id = `${normalizePrefix(prefix)}${randomToken(tokenLength)}`;
             if (!(await idExists(pmRoot, id))) {
@@ -69,4 +90,4 @@ export async function generateItemId(pmRoot, prefix) {
     throw new Error(`Unable to generate unique id after ${attempts} attempts`);
 }
 //# sourceMappingURL=id.js.map
-//# debugId=900d99bf-095b-5dcf-9a33-b04c9b440969
+//# debugId=ee13ce1e-8508-5eb1-be0b-6e49f4280e87

package/dist/core/item/id.js.map

@@ -1 +1 @@
-{"version":3,"file":"id.js","sources":["core/item/id.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/item/id\n *\n * Defines item parsing, formatting, and lifecycle helpers for Id.\n */\nimport crypto from \"node:crypto\";\nimport path from \"node:path\";\nimport { TYPE_TO_FOLDER } from \"../shared/constants.js\";\nimport { pathExists } from \"../fs/fs-utils.js\";\n\n/** Implements normalize prefix for the public runtime surface of this module. */\nexport function normalizePrefix(input: string | undefined): string {\n  const normalized = (input ?? \"\").trim().toLowerCase();\n  if (!normalized) return \"pm-\";\n  return normalized.endsWith(\"-\") ? normalized : `${normalized}-`;\n}\n\n/** Implements normalize raw item id for the public runtime surface of this module. */\nexport function normalizeRawItemId(input: string): string {\n  let normalized = input.trim().toLowerCase();\n  if (normalized.startsWith(\"#\")) {\n    normalized = normalized.slice(1);\n  }\n  return normalized;\n}\n\n/** Implements normalize item id for the public runtime surface of this module. */\nexport function normalizeItemId(input: string, prefix: string): string {\n  const canonicalPrefix = normalizePrefix(prefix);\n  const normalized = normalizeRawItemId(input);\n  if (normalized.startsWith(canonicalPrefix)) {\n    return normalized;\n  }\n  return `${canonicalPrefix}${normalized}`;\n}\n\nfunction randomToken(length: number): string {\n  let token = \"\";\n  for (let index = 0; index < length; index += 1) {\n    token += crypto.randomInt(0, 36).toString(36);\n  }\n  return token;\n}\n\nasync function idExists(pmRoot: string, id: string): Promise<boolean> {\n  const checks = Object.values(TYPE_TO_FOLDER).flatMap((folder) => [\n    path.join(pmRoot, folder, `${id}.md`),\n    path.join(pmRoot, folder, `${id}.toon`),\n  ]);\n  for (const target of checks) {\n    if (await pathExists(target)) {\n      return true;\n    }\n  }\n  return false;\n}\n\n/** Implements generate item id for the public runtime surface of this module. */\nexport async function generateItemId(\n  pmRoot: string,\n  prefix: string,\n): Promise<string> {\n  let tokenLength = 4;\n  let attempts = 0;\n\n  while (tokenLength <= 10) {\n    for (let i = 0; i < 32; i += 1) {\n      const id = `${normalizePrefix(prefix)}${randomToken(tokenLength)}`;\n      if (!(await idExists(pmRoot, id))) {\n        return id;\n      }\n      attempts += 1;\n    }\n    tokenLength += 1;\n  }\n\n  throw new Error(`Unable to generate unique id after ${attempts} attempts`);\n}\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,iFAAiF;AACjF,MAAM,UAAU,eAAe,CAAC,KAAyB;IACvD,MAAM,UAAU,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACtD,IAAI,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC;IAC9B,OAAO,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,GAAG,CAAC;AAClE,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,IAAI,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,MAAc;IAC3D,MAAM,eAAe,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC7C,IAAI,UAAU,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QAC3C,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,OAAO,GAAG,eAAe,GAAG,UAAU,EAAE,CAAC;AAC3C,CAAC;AAED,SAAS,WAAW,CAAC,MAAc;IACjC,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/C,KAAK,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,MAAc,EAAE,EAAU;IAChD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;QAC/D,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC;QACrC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC;KACxC,CAAC,CAAC;IACH,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,MAAM,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,MAAc;IAEd,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,OAAO,WAAW,IAAI,EAAE,EAAE,CAAC;QACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,MAAM,EAAE,GAAG,GAAG,eAAe,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;YACnE,IAAI,CAAC,CAAC,MAAM,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC;gBAClC,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,QAAQ,IAAI,CAAC,CAAC;QAChB,CAAC;QACD,WAAW,IAAI,CAAC,CAAC;IACnB,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,sCAAsC,QAAQ,WAAW,CAAC,CAAC;AAC7E,CAAC","debugId":"900d99bf-095b-5dcf-9a33-b04c9b440969"}
+{"version":3,"file":"id.js","sources":["core/item/id.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/item/id\n *\n * Defines item parsing, formatting, and lifecycle helpers for Id.\n */\nimport crypto from \"node:crypto\";\nimport path from \"node:path\";\nimport { TYPE_TO_FOLDER } from \"../shared/constants.js\";\nimport { pathExists } from \"../fs/fs-utils.js\";\n\n/** Implements normalize prefix for the public runtime surface of this module. */\nexport function normalizePrefix(input: string | undefined): string {\n  const normalized = (input ?? \"\").trim().toLowerCase();\n  if (!normalized) return \"pm-\";\n  return normalized.endsWith(\"-\") ? normalized : `${normalized}-`;\n}\n\n/** Implements normalize raw item id for the public runtime surface of this module. */\nexport function normalizeRawItemId(input: string): string {\n  let normalized = input.trim().toLowerCase();\n  if (normalized.startsWith(\"#\")) {\n    normalized = normalized.slice(1);\n  }\n  return normalized;\n}\n\n/** Implements normalize item id for the public runtime surface of this module. */\nexport function normalizeItemId(input: string, prefix: string): string {\n  const canonicalPrefix = normalizePrefix(prefix);\n  const normalized = normalizeRawItemId(input);\n  if (normalized.startsWith(canonicalPrefix)) {\n    return normalized;\n  }\n  return `${canonicalPrefix}${normalized}`;\n}\n\nfunction randomToken(length: number): string {\n  let token = \"\";\n  for (let index = 0; index < length; index += 1) {\n    token += crypto.randomInt(0, 36).toString(36);\n  }\n  return token;\n}\n\nasync function idExists(pmRoot: string, id: string): Promise<boolean> {\n  const checks = Object.values(TYPE_TO_FOLDER).flatMap((folder) => [\n    path.join(pmRoot, folder, `${id}.md`),\n    path.join(pmRoot, folder, `${id}.toon`),\n  ]);\n  for (const target of checks) {\n    if (await pathExists(target)) {\n      return true;\n    }\n  }\n  return false;\n}\n\n/** Bounds accepted for the configurable random id token length (`ids.token_length`). */\nexport const ID_TOKEN_LENGTH_MIN = 4;\n/** Upper bound for `ids.token_length`; longer tokens stop improving ergonomics without meaningfully improving uniqueness. */\nexport const ID_TOKEN_LENGTH_MAX = 12;\n\n/** Clamp a configured id token length into the supported bounds, falling back to the 4-character default for non-finite input. */\nexport function clampIdTokenLength(value: number | undefined): number {\n  if (typeof value !== \"number\" || !Number.isFinite(value)) {\n    return ID_TOKEN_LENGTH_MIN;\n  }\n  return Math.min(\n    ID_TOKEN_LENGTH_MAX,\n    Math.max(ID_TOKEN_LENGTH_MIN, Math.trunc(value)),\n  );\n}\n\n/**\n * Mint a new item id as `<prefix><random base36 token>`. The starting token\n * length comes from the workspace `ids.token_length` setting (default 4) and\n * escalates automatically when the local uniqueness probe keeps colliding.\n * Uniqueness is only verifiable against the local working tree: concurrent\n * branches can still mint the same id independently, which is why longer\n * configured tokens matter for multi-agent workflows and why\n * `pm validate --check-storage-integrity` detects post-merge duplicate-id\n * collisions (GH-600).\n */\nexport async function generateItemId(\n  pmRoot: string,\n  prefix: string,\n  options: { tokenLength?: number } = {},\n): Promise<string> {\n  let tokenLength = clampIdTokenLength(options.tokenLength);\n  const maxTokenLength = Math.min(\n    tokenLength + 6,\n    ID_TOKEN_LENGTH_MAX,\n  );\n  let attempts = 0;\n\n  while (tokenLength <= maxTokenLength) {\n    for (let i = 0; i < 32; i += 1) {\n      const id = `${normalizePrefix(prefix)}${randomToken(tokenLength)}`;\n      if (!(await idExists(pmRoot, id))) {\n        return id;\n      }\n      attempts += 1;\n    }\n    tokenLength += 1;\n  }\n\n  throw new Error(`Unable to generate unique id after ${attempts} attempts`);\n}\n"],"names":[],"mappings":"AAAA;;;;GAIG;;;AACH,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,iFAAiF;AACjF,MAAM,UAAU,eAAe,CAAC,KAAyB;IACvD,MAAM,UAAU,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACtD,IAAI,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC;IAC9B,OAAO,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,GAAG,CAAC;AAClE,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,IAAI,UAAU,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC5C,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,UAAU,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,eAAe,CAAC,KAAa,EAAE,MAAc;IAC3D,MAAM,eAAe,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAC7C,IAAI,UAAU,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QAC3C,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,OAAO,GAAG,eAAe,GAAG,UAAU,EAAE,CAAC;AAC3C,CAAC;AAED,SAAS,WAAW,CAAC,MAAc;IACjC,IAAI,KAAK,GAAG,EAAE,CAAC;IACf,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/C,KAAK,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,MAAc,EAAE,EAAU;IAChD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;QAC/D,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC;QACrC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC;KACxC,CAAC,CAAC;IACH,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,MAAM,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YAC7B,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC;AACrC,6HAA6H;AAC7H,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAEtC,kIAAkI;AAClI,MAAM,UAAU,kBAAkB,CAAC,KAAyB;IAC1D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzD,OAAO,mBAAmB,CAAC;IAC7B,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CACb,mBAAmB,EACnB,IAAI,CAAC,GAAG,CAAC,mBAAmB,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CACjD,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,MAAc,EACd,UAAoC,EAAE;IAEtC,IAAI,WAAW,GAAG,kBAAkB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC1D,MAAM,cAAc,GAAG,IAAI,CAAC,GAAG,CAC7B,WAAW,GAAG,CAAC,EACf,mBAAmB,CACpB,CAAC;IACF,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,OAAO,WAAW,IAAI,cAAc,EAAE,CAAC;QACrC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,MAAM,EAAE,GAAG,GAAG,eAAe,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;YACnE,IAAI,CAAC,CAAC,MAAM,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC;gBAClC,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,QAAQ,IAAI,CAAC,CAAC;QAChB,CAAC;QACD,WAAW,IAAI,CAAC,CAAC;IACnB,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,sCAAsC,QAAQ,WAAW,CAAC,CAAC;AAC7E,CAAC","debugId":"ee13ce1e-8508-5eb1-be0b-6e49f4280e87"}

package/dist/core/item/parse.d.ts

@@ -2,6 +2,13 @@
 export declare function parseTags(raw: string): string[];
 /** Merge repeated `--add-tags` / `--remove-tags` values into a single normalized tag list. Each entry can itself be CSV or a JSON array, mirroring the format accepted by `--tags`. Returns a deterministically sorted, deduped list. */
 export declare function collectTagFlagValues(values: readonly string[] | undefined): string[];
+/** Split a stored `acceptance_criteria` value into its individual criteria. Criteria are stored as one string joined with `"; "` (repeated `--ac` values accumulate that way), so the semicolon is the criterion boundary and cannot appear inside one criterion; entries are trimmed and blanks dropped. Non-string/absent values yield an empty list. */
+export declare function splitAcceptanceCriteria(value: unknown): string[];
+/** Apply additive/subtractive acceptance-criteria mutations to a base criteria list. Used by `pm update --add-ac/--remove-ac` so individual semicolon-free criteria can be edited without replacing the whole `acceptance_criteria` value (tag-API parity; disjoint additions merge cleanly across branches). Additions append in argv order and dedupe on exact trimmed text; removals match exact trimmed text and report unmatched selectors so a typo never becomes a silent no-op. */
+export declare function applyAcceptanceCriteriaMutations(baseCriteria: readonly string[], add: readonly string[] | undefined, remove: readonly string[] | undefined): {
+    criteria: string[];
+    unmatchedRemovals: string[];
+};
 /** Apply an additive tag mutation to a base tag list. Used by `pm create` and `pm update` so `--add-tags` extends `--tags` (or the existing tags) without replacing them. Output is sorted + deduped lowercase, matching `parseTags`. */
 export declare function mergeAdditiveTags(baseTags: readonly string[], add: readonly string[] | undefined): string[];
 /** Apply a subtractive tag mutation to a base tag list. Used by `pm update` so `--remove-tags x,y` prunes those entries without rewriting the full set. Removal is case-insensitive: both the base list and the removal selectors are normalized to canonical lowercase before matching. */