@unbrained/pm-cli 2026.6.20 → 2026.6.22

package/dist/core/extensions/index.js

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Index.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c8e3bac0-fd3d-5586-9c22-994b64c9efb3")}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]="abe62b94-a55a-5cdf-8f1a-34360ddc4c25")}catch(e){}}();
 import { runCommandHandler, runCommandOverride, runOnIndexHooks, runParserOverride, runPreflightOverride, runOnReadHooks, runRendererOverride, runServiceOverride, runServiceOverrideSync, runOnWriteHooks, } from "./loader.js";
 let activeExtensionHooks = null;
 let activeExtensionCommands = null;
@@ -330,5 +330,6 @@ export function runActiveServiceOverrideSync(service, payload) {
     return runServiceOverrideSync(activeExtensionServices, buildServiceContext(service, payload));
 }
 export * from "./loader.js";
+export { EXTENSION_CAPABILITY_REGISTRATION_SURFACES, collectUsedExtensionCapabilities, reconcileExtensionCapabilityUsage, } from "./capability-usage.js";
 //# sourceMappingURL=index.js.map
-//# debugId=c8e3bac0-fd3d-5586-9c22-994b64c9efb3
+//# debugId=abe62b94-a55a-5cdf-8f1a-34360ddc4c25

package/dist/core/extensions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["core/extensions/index.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/index\n *\n * Implements extension runtime contracts and governance for Index.\n */\nimport {\n  runCommandHandler,\n  runCommandOverride,\n  runOnIndexHooks,\n  runParserOverride,\n  runPreflightOverride,\n  runOnReadHooks,\n  runRendererOverride,\n  runServiceOverride,\n  runServiceOverrideSync,\n  runOnWriteHooks,\n  type CommandHandlerContext,\n  type CommandHandlerResult,\n  type CommandOverrideContext,\n  type CommandOverrideResult,\n  type ExtensionCommandRegistry,\n  type ExtensionHookRegistry,\n  type ExtensionParserRegistry,\n  type ExtensionPreflightRegistry,\n  type ExtensionRegistrationRegistry,\n  type ExtensionRendererRegistry,\n  type ExtensionServiceName,\n  type ExtensionServiceRegistry,\n  type AfterCommandAffectedItem,\n  type OnIndexHookContext,\n  type OnReadHookContext,\n  type OnWriteHookContext,\n  type OutputRendererFormat,\n  type ParserOverrideContext,\n  type ParserOverrideResult,\n  type PreflightOverrideContext,\n  type PreflightOverrideResult,\n  type RendererOverrideResult,\n  type ServiceOverrideResult,\n} from \"./loader.js\";\nimport type { ItemFrontMatter } from \"../../types/index.js\";\n\nlet activeExtensionHooks: ExtensionHookRegistry | null = null;\nlet activeExtensionCommands: ExtensionCommandRegistry | null = null;\nlet activeExtensionParsers: ExtensionParserRegistry | null = null;\nlet activeExtensionPreflight: ExtensionPreflightRegistry | null = null;\nlet activeExtensionServices: ExtensionServiceRegistry | null = null;\nlet activeExtensionRenderers: ExtensionRendererRegistry | null = null;\nlet activeExtensionRegistrations: ExtensionRegistrationRegistry | null = null;\nlet activeCommandContext: Omit<CommandOverrideContext, \"result\"> | null = null;\nlet activeCommandResult: unknown = undefined;\nlet activeAfterCommandAffectedItems: AfterCommandAffectedItem[] = [];\nconst AFTER_COMMAND_SNAPSHOT_OMITTED_FIELDS = new Set([\n  \"body\",\n  \"comments\",\n  \"dependencies\",\n  \"docs\",\n  \"events\",\n  \"files\",\n  \"learnings\",\n  \"notes\",\n  \"reminders\",\n  \"test_runs\",\n  \"tests\",\n]);\n\n/**\n * Implements set active extension hooks for the public runtime surface of this module.\n */\nexport function setActiveExtensionHooks(hooks: ExtensionHookRegistry | null): void {\n  activeExtensionHooks = hooks;\n}\n\n/**\n * Implements set active extension commands for the public runtime surface of this module.\n */\nexport function setActiveExtensionCommands(commands: ExtensionCommandRegistry | null): void {\n  activeExtensionCommands = commands;\n}\n\n/**\n * Implements set active extension parsers for the public runtime surface of this module.\n */\nexport function setActiveExtensionParsers(parsers: ExtensionParserRegistry | null): void {\n  activeExtensionParsers = parsers;\n}\n\n/**\n * Implements set active extension preflight for the public runtime surface of this module.\n */\nexport function setActiveExtensionPreflight(preflight: ExtensionPreflightRegistry | null): void {\n  activeExtensionPreflight = preflight;\n}\n\n/**\n * Implements set active extension services for the public runtime surface of this module.\n */\nexport function setActiveExtensionServices(services: ExtensionServiceRegistry | null): void {\n  activeExtensionServices = services;\n}\n\n/**\n * Implements set active extension renderers for the public runtime surface of this module.\n */\nexport function setActiveExtensionRenderers(renderers: ExtensionRendererRegistry | null): void {\n  activeExtensionRenderers = renderers;\n}\n\n/**\n * Implements set active extension registrations for the public runtime surface of this module.\n */\nexport function setActiveExtensionRegistrations(registrations: ExtensionRegistrationRegistry | null): void {\n  activeExtensionRegistrations = registrations;\n}\n\n/**\n * Implements get active extension registrations for the public runtime surface of this module.\n */\nexport function getActiveExtensionRegistrations(): ExtensionRegistrationRegistry | null {\n  return activeExtensionRegistrations;\n}\n\n/**\n * Implements set active command context for the public runtime surface of this module.\n */\nexport function setActiveCommandContext(context: Omit<CommandOverrideContext, \"result\"> | null): void {\n  activeCommandContext = context;\n}\n\n/**\n * Implements set active command result for the public runtime surface of this module.\n */\nexport function setActiveCommandResult(result: unknown): void {\n  activeCommandResult = result;\n}\n\n/**\n * Implements get active command result for the public runtime surface of this module.\n */\nexport function getActiveCommandResult(): unknown {\n  return activeCommandResult;\n}\n\n/**\n * Implements record after command affected item for the public runtime surface of this module.\n */\nexport function recordAfterCommandAffectedItem(item: AfterCommandAffectedItem): void {\n  if (!item || (activeExtensionHooks?.afterCommand?.length ?? 0) === 0) {\n    return;\n  }\n  activeAfterCommandAffectedItems.push(item);\n}\n\n/**\n * Implements project after command item snapshot for the public runtime surface of this module.\n */\nexport function projectAfterCommandItemSnapshot(\n  metadata: ItemFrontMatter,\n  changedFields: readonly string[],\n): Partial<ItemFrontMatter> {\n  if (!metadata || !metadata.id) {\n    return {};\n  }\n  const snapshot: Record<string, unknown> = {\n    id: metadata.id,\n    type: metadata.type,\n    status: metadata.status,\n  };\n  if (!Array.isArray(changedFields)) {\n    return snapshot as Partial<ItemFrontMatter>;\n  }\n  const source = metadata as unknown as Record<string, unknown>;\n  for (const field of changedFields) {\n    if (typeof field !== \"string\") {\n      continue;\n    }\n    const actualField = field.startsWith(\"unset:\") ? field.slice(\"unset:\".length) : field;\n    if (\n      actualField === \"id\" ||\n      actualField === \"type\" ||\n      actualField === \"status\" ||\n      AFTER_COMMAND_SNAPSHOT_OMITTED_FIELDS.has(actualField)\n    ) {\n      continue;\n    }\n    if (Object.hasOwn(source, actualField) && source[actualField] !== undefined) {\n      snapshot[actualField] = source[actualField];\n    }\n  }\n  return snapshot as Partial<ItemFrontMatter>;\n}\n\n/**\n * Implements consume after command affected items for the public runtime surface of this module.\n */\nexport function consumeAfterCommandAffectedItems(): AfterCommandAffectedItem[] | undefined {\n  if (activeAfterCommandAffectedItems.length === 0) {\n    return undefined;\n  }\n  const affected = activeAfterCommandAffectedItems;\n  activeAfterCommandAffectedItems = [];\n  return affected;\n}\n\n/**\n * Implements clear active extension hooks for the public runtime surface of this module.\n */\nexport function clearActiveExtensionHooks(): void {\n  activeExtensionHooks = null;\n  activeExtensionCommands = null;\n  activeExtensionParsers = null;\n  activeExtensionPreflight = null;\n  activeExtensionServices = null;\n  activeExtensionRenderers = null;\n  activeExtensionRegistrations = null;\n  activeCommandContext = null;\n  activeCommandResult = undefined;\n  activeAfterCommandAffectedItems = [];\n}\n\n/**\n * Implements run active on write hooks for the public runtime surface of this module.\n */\nexport async function runActiveOnWriteHooks(context: OnWriteHookContext): Promise<string[]> {\n  if (!activeExtensionHooks) {\n    return [];\n  }\n  return runOnWriteHooks(activeExtensionHooks, context);\n}\n\n/**\n * Implements run active on read hooks for the public runtime surface of this module.\n */\nexport async function runActiveOnReadHooks(context: OnReadHookContext): Promise<string[]> {\n  if (!activeExtensionHooks) {\n    return [];\n  }\n  return runOnReadHooks(activeExtensionHooks, context);\n}\n\n/**\n * Synchronous fast-path predicate: true only when at least one onRead hook is\n * registered. Bulk readers (e.g. the metadata cache scanning hundreds of files)\n * use this to skip per-file `await runActiveOnReadHooks(...)` calls entirely when\n * no extension observes reads, avoiding hundreds of needless microtasks.\n */\nexport function hasActiveOnReadHooks(): boolean {\n  return (activeExtensionHooks?.onRead?.length ?? 0) > 0;\n}\n\n/**\n * Implements run active on index hooks for the public runtime surface of this module.\n */\nexport async function runActiveOnIndexHooks(context: OnIndexHookContext): Promise<string[]> {\n  if (!activeExtensionHooks) {\n    return [];\n  }\n  return runOnIndexHooks(activeExtensionHooks, context);\n}\n\n/**\n * Implements run active command override for the public runtime surface of this module.\n */\nexport function runActiveCommandOverride(result: unknown): CommandOverrideResult {\n  if (!activeExtensionCommands || !activeCommandContext) {\n    return {\n      overridden: false,\n      result,\n      warnings: [],\n    };\n  }\n  return runCommandOverride(activeExtensionCommands, {\n    command: activeCommandContext.command,\n    args: [...activeCommandContext.args],\n    options: activeCommandContext.options ? { ...activeCommandContext.options } : {},\n    global: activeCommandContext.global ? { ...activeCommandContext.global } : undefined,\n    pm_root: activeCommandContext.pm_root,\n    result,\n  });\n}\n\n/**\n * Implements run active command handler for the public runtime surface of this module.\n */\nexport async function runActiveCommandHandler(context: CommandHandlerContext): Promise<CommandHandlerResult> {\n  if (!activeExtensionCommands) {\n    return {\n      handled: false,\n      result: null,\n      warnings: [],\n    };\n  }\n  return runCommandHandler(activeExtensionCommands, context);\n}\n\n/**\n * Implements run active parser override for the public runtime surface of this module.\n */\nexport async function runActiveParserOverride(context: ParserOverrideContext): Promise<ParserOverrideResult> {\n  if (!activeExtensionParsers) {\n    return {\n      overridden: false,\n      context: {\n        command: context.command,\n        args: [...context.args],\n        options: { ...context.options },\n        global: { ...context.global },\n        pm_root: context.pm_root,\n      },\n      warnings: [],\n    };\n  }\n  return runParserOverride(activeExtensionParsers, context);\n}\n\n/**\n * Implements run active preflight override for the public runtime surface of this module.\n */\nexport async function runActivePreflightOverride(context: PreflightOverrideContext): Promise<PreflightOverrideResult> {\n  if (!activeExtensionPreflight) {\n    return {\n      overridden: false,\n      context: {\n        command: context.command,\n        args: [...context.args],\n        options: { ...context.options },\n        global: { ...context.global },\n        pm_root: context.pm_root,\n      },\n      decision: { ...context.decision },\n      warnings: [],\n    };\n  }\n  return runPreflightOverride(activeExtensionPreflight, context);\n}\n\n/**\n * Implements run active renderer override for the public runtime surface of this module.\n */\nexport function runActiveRendererOverride(format: OutputRendererFormat, result: unknown): RendererOverrideResult {\n  if (!activeExtensionRenderers) {\n    return {\n      overridden: false,\n      rendered: null,\n      warnings: [],\n    };\n  }\n  return runRendererOverride(activeExtensionRenderers, {\n    format,\n    command: activeCommandContext?.command,\n    args: activeCommandContext ? [...activeCommandContext.args] : [],\n    options: activeCommandContext?.options ? { ...activeCommandContext.options } : {},\n    global: activeCommandContext?.global ? { ...activeCommandContext.global } : undefined,\n    pm_root: activeCommandContext?.pm_root,\n    result,\n  });\n}\n\nfunction buildServiceContext(service: ExtensionServiceName, payload: unknown) {\n  return {\n    service,\n    command: activeCommandContext?.command,\n    args: activeCommandContext ? [...activeCommandContext.args] : [],\n    options: activeCommandContext?.options ? { ...activeCommandContext.options } : {},\n    global: activeCommandContext?.global ? { ...activeCommandContext.global } : undefined,\n    pm_root: activeCommandContext?.pm_root,\n    payload,\n  };\n}\n\n/**\n * Implements run active service override for the public runtime surface of this module.\n */\nexport async function runActiveServiceOverride(\n  service: ExtensionServiceName,\n  payload: unknown,\n): Promise<ServiceOverrideResult> {\n  if (!activeExtensionServices) {\n    return {\n      handled: false,\n      result: payload,\n      warnings: [],\n    };\n  }\n  return runServiceOverride(activeExtensionServices, buildServiceContext(service, payload));\n}\n\n/**\n * Implements run active service override sync for the public runtime surface of this module.\n */\nexport function runActiveServiceOverrideSync(service: ExtensionServiceName, payload: unknown): ServiceOverrideResult {\n  if (!activeExtensionServices) {\n    return {\n      handled: false,\n      result: payload,\n      warnings: [],\n    };\n  }\n  return runServiceOverrideSync(activeExtensionServices, buildServiceContext(service, payload));\n}\n\nexport * from \"./loader.js\";\n"],"names":[],"mappings":"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","debugId":"c8e3bac0-fd3d-5586-9c22-994b64c9efb3"}
+{"version":3,"file":"index.js","sources":["core/extensions/index.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/index\n *\n * Implements extension runtime contracts and governance for Index.\n */\nimport {\n  runCommandHandler,\n  runCommandOverride,\n  runOnIndexHooks,\n  runParserOverride,\n  runPreflightOverride,\n  runOnReadHooks,\n  runRendererOverride,\n  runServiceOverride,\n  runServiceOverrideSync,\n  runOnWriteHooks,\n  type CommandHandlerContext,\n  type CommandHandlerResult,\n  type CommandOverrideContext,\n  type CommandOverrideResult,\n  type ExtensionCommandRegistry,\n  type ExtensionHookRegistry,\n  type ExtensionParserRegistry,\n  type ExtensionPreflightRegistry,\n  type ExtensionRegistrationRegistry,\n  type ExtensionRendererRegistry,\n  type ExtensionServiceName,\n  type ExtensionServiceRegistry,\n  type AfterCommandAffectedItem,\n  type OnIndexHookContext,\n  type OnReadHookContext,\n  type OnWriteHookContext,\n  type OutputRendererFormat,\n  type ParserOverrideContext,\n  type ParserOverrideResult,\n  type PreflightOverrideContext,\n  type PreflightOverrideResult,\n  type RendererOverrideResult,\n  type ServiceOverrideResult,\n} from \"./loader.js\";\nimport type { ItemFrontMatter } from \"../../types/index.js\";\n\nlet activeExtensionHooks: ExtensionHookRegistry | null = null;\nlet activeExtensionCommands: ExtensionCommandRegistry | null = null;\nlet activeExtensionParsers: ExtensionParserRegistry | null = null;\nlet activeExtensionPreflight: ExtensionPreflightRegistry | null = null;\nlet activeExtensionServices: ExtensionServiceRegistry | null = null;\nlet activeExtensionRenderers: ExtensionRendererRegistry | null = null;\nlet activeExtensionRegistrations: ExtensionRegistrationRegistry | null = null;\nlet activeCommandContext: Omit<CommandOverrideContext, \"result\"> | null = null;\nlet activeCommandResult: unknown = undefined;\nlet activeAfterCommandAffectedItems: AfterCommandAffectedItem[] = [];\nconst AFTER_COMMAND_SNAPSHOT_OMITTED_FIELDS = new Set([\n  \"body\",\n  \"comments\",\n  \"dependencies\",\n  \"docs\",\n  \"events\",\n  \"files\",\n  \"learnings\",\n  \"notes\",\n  \"reminders\",\n  \"test_runs\",\n  \"tests\",\n]);\n\n/**\n * Implements set active extension hooks for the public runtime surface of this module.\n */\nexport function setActiveExtensionHooks(hooks: ExtensionHookRegistry | null): void {\n  activeExtensionHooks = hooks;\n}\n\n/**\n * Implements set active extension commands for the public runtime surface of this module.\n */\nexport function setActiveExtensionCommands(commands: ExtensionCommandRegistry | null): void {\n  activeExtensionCommands = commands;\n}\n\n/**\n * Implements set active extension parsers for the public runtime surface of this module.\n */\nexport function setActiveExtensionParsers(parsers: ExtensionParserRegistry | null): void {\n  activeExtensionParsers = parsers;\n}\n\n/**\n * Implements set active extension preflight for the public runtime surface of this module.\n */\nexport function setActiveExtensionPreflight(preflight: ExtensionPreflightRegistry | null): void {\n  activeExtensionPreflight = preflight;\n}\n\n/**\n * Implements set active extension services for the public runtime surface of this module.\n */\nexport function setActiveExtensionServices(services: ExtensionServiceRegistry | null): void {\n  activeExtensionServices = services;\n}\n\n/**\n * Implements set active extension renderers for the public runtime surface of this module.\n */\nexport function setActiveExtensionRenderers(renderers: ExtensionRendererRegistry | null): void {\n  activeExtensionRenderers = renderers;\n}\n\n/**\n * Implements set active extension registrations for the public runtime surface of this module.\n */\nexport function setActiveExtensionRegistrations(registrations: ExtensionRegistrationRegistry | null): void {\n  activeExtensionRegistrations = registrations;\n}\n\n/**\n * Implements get active extension registrations for the public runtime surface of this module.\n */\nexport function getActiveExtensionRegistrations(): ExtensionRegistrationRegistry | null {\n  return activeExtensionRegistrations;\n}\n\n/**\n * Implements set active command context for the public runtime surface of this module.\n */\nexport function setActiveCommandContext(context: Omit<CommandOverrideContext, \"result\"> | null): void {\n  activeCommandContext = context;\n}\n\n/**\n * Implements set active command result for the public runtime surface of this module.\n */\nexport function setActiveCommandResult(result: unknown): void {\n  activeCommandResult = result;\n}\n\n/**\n * Implements get active command result for the public runtime surface of this module.\n */\nexport function getActiveCommandResult(): unknown {\n  return activeCommandResult;\n}\n\n/**\n * Implements record after command affected item for the public runtime surface of this module.\n */\nexport function recordAfterCommandAffectedItem(item: AfterCommandAffectedItem): void {\n  if (!item || (activeExtensionHooks?.afterCommand?.length ?? 0) === 0) {\n    return;\n  }\n  activeAfterCommandAffectedItems.push(item);\n}\n\n/**\n * Implements project after command item snapshot for the public runtime surface of this module.\n */\nexport function projectAfterCommandItemSnapshot(\n  metadata: ItemFrontMatter,\n  changedFields: readonly string[],\n): Partial<ItemFrontMatter> {\n  if (!metadata || !metadata.id) {\n    return {};\n  }\n  const snapshot: Record<string, unknown> = {\n    id: metadata.id,\n    type: metadata.type,\n    status: metadata.status,\n  };\n  if (!Array.isArray(changedFields)) {\n    return snapshot as Partial<ItemFrontMatter>;\n  }\n  const source = metadata as unknown as Record<string, unknown>;\n  for (const field of changedFields) {\n    if (typeof field !== \"string\") {\n      continue;\n    }\n    const actualField = field.startsWith(\"unset:\") ? field.slice(\"unset:\".length) : field;\n    if (\n      actualField === \"id\" ||\n      actualField === \"type\" ||\n      actualField === \"status\" ||\n      AFTER_COMMAND_SNAPSHOT_OMITTED_FIELDS.has(actualField)\n    ) {\n      continue;\n    }\n    if (Object.hasOwn(source, actualField) && source[actualField] !== undefined) {\n      snapshot[actualField] = source[actualField];\n    }\n  }\n  return snapshot as Partial<ItemFrontMatter>;\n}\n\n/**\n * Implements consume after command affected items for the public runtime surface of this module.\n */\nexport function consumeAfterCommandAffectedItems(): AfterCommandAffectedItem[] | undefined {\n  if (activeAfterCommandAffectedItems.length === 0) {\n    return undefined;\n  }\n  const affected = activeAfterCommandAffectedItems;\n  activeAfterCommandAffectedItems = [];\n  return affected;\n}\n\n/**\n * Implements clear active extension hooks for the public runtime surface of this module.\n */\nexport function clearActiveExtensionHooks(): void {\n  activeExtensionHooks = null;\n  activeExtensionCommands = null;\n  activeExtensionParsers = null;\n  activeExtensionPreflight = null;\n  activeExtensionServices = null;\n  activeExtensionRenderers = null;\n  activeExtensionRegistrations = null;\n  activeCommandContext = null;\n  activeCommandResult = undefined;\n  activeAfterCommandAffectedItems = [];\n}\n\n/**\n * Implements run active on write hooks for the public runtime surface of this module.\n */\nexport async function runActiveOnWriteHooks(context: OnWriteHookContext): Promise<string[]> {\n  if (!activeExtensionHooks) {\n    return [];\n  }\n  return runOnWriteHooks(activeExtensionHooks, context);\n}\n\n/**\n * Implements run active on read hooks for the public runtime surface of this module.\n */\nexport async function runActiveOnReadHooks(context: OnReadHookContext): Promise<string[]> {\n  if (!activeExtensionHooks) {\n    return [];\n  }\n  return runOnReadHooks(activeExtensionHooks, context);\n}\n\n/**\n * Synchronous fast-path predicate: true only when at least one onRead hook is\n * registered. Bulk readers (e.g. the metadata cache scanning hundreds of files)\n * use this to skip per-file `await runActiveOnReadHooks(...)` calls entirely when\n * no extension observes reads, avoiding hundreds of needless microtasks.\n */\nexport function hasActiveOnReadHooks(): boolean {\n  return (activeExtensionHooks?.onRead?.length ?? 0) > 0;\n}\n\n/**\n * Implements run active on index hooks for the public runtime surface of this module.\n */\nexport async function runActiveOnIndexHooks(context: OnIndexHookContext): Promise<string[]> {\n  if (!activeExtensionHooks) {\n    return [];\n  }\n  return runOnIndexHooks(activeExtensionHooks, context);\n}\n\n/**\n * Implements run active command override for the public runtime surface of this module.\n */\nexport function runActiveCommandOverride(result: unknown): CommandOverrideResult {\n  if (!activeExtensionCommands || !activeCommandContext) {\n    return {\n      overridden: false,\n      result,\n      warnings: [],\n    };\n  }\n  return runCommandOverride(activeExtensionCommands, {\n    command: activeCommandContext.command,\n    args: [...activeCommandContext.args],\n    options: activeCommandContext.options ? { ...activeCommandContext.options } : {},\n    global: activeCommandContext.global ? { ...activeCommandContext.global } : undefined,\n    pm_root: activeCommandContext.pm_root,\n    result,\n  });\n}\n\n/**\n * Implements run active command handler for the public runtime surface of this module.\n */\nexport async function runActiveCommandHandler(context: CommandHandlerContext): Promise<CommandHandlerResult> {\n  if (!activeExtensionCommands) {\n    return {\n      handled: false,\n      result: null,\n      warnings: [],\n    };\n  }\n  return runCommandHandler(activeExtensionCommands, context);\n}\n\n/**\n * Implements run active parser override for the public runtime surface of this module.\n */\nexport async function runActiveParserOverride(context: ParserOverrideContext): Promise<ParserOverrideResult> {\n  if (!activeExtensionParsers) {\n    return {\n      overridden: false,\n      context: {\n        command: context.command,\n        args: [...context.args],\n        options: { ...context.options },\n        global: { ...context.global },\n        pm_root: context.pm_root,\n      },\n      warnings: [],\n    };\n  }\n  return runParserOverride(activeExtensionParsers, context);\n}\n\n/**\n * Implements run active preflight override for the public runtime surface of this module.\n */\nexport async function runActivePreflightOverride(context: PreflightOverrideContext): Promise<PreflightOverrideResult> {\n  if (!activeExtensionPreflight) {\n    return {\n      overridden: false,\n      context: {\n        command: context.command,\n        args: [...context.args],\n        options: { ...context.options },\n        global: { ...context.global },\n        pm_root: context.pm_root,\n      },\n      decision: { ...context.decision },\n      warnings: [],\n    };\n  }\n  return runPreflightOverride(activeExtensionPreflight, context);\n}\n\n/**\n * Implements run active renderer override for the public runtime surface of this module.\n */\nexport function runActiveRendererOverride(format: OutputRendererFormat, result: unknown): RendererOverrideResult {\n  if (!activeExtensionRenderers) {\n    return {\n      overridden: false,\n      rendered: null,\n      warnings: [],\n    };\n  }\n  return runRendererOverride(activeExtensionRenderers, {\n    format,\n    command: activeCommandContext?.command,\n    args: activeCommandContext ? [...activeCommandContext.args] : [],\n    options: activeCommandContext?.options ? { ...activeCommandContext.options } : {},\n    global: activeCommandContext?.global ? { ...activeCommandContext.global } : undefined,\n    pm_root: activeCommandContext?.pm_root,\n    result,\n  });\n}\n\nfunction buildServiceContext(service: ExtensionServiceName, payload: unknown) {\n  return {\n    service,\n    command: activeCommandContext?.command,\n    args: activeCommandContext ? [...activeCommandContext.args] : [],\n    options: activeCommandContext?.options ? { ...activeCommandContext.options } : {},\n    global: activeCommandContext?.global ? { ...activeCommandContext.global } : undefined,\n    pm_root: activeCommandContext?.pm_root,\n    payload,\n  };\n}\n\n/**\n * Implements run active service override for the public runtime surface of this module.\n */\nexport async function runActiveServiceOverride(\n  service: ExtensionServiceName,\n  payload: unknown,\n): Promise<ServiceOverrideResult> {\n  if (!activeExtensionServices) {\n    return {\n      handled: false,\n      result: payload,\n      warnings: [],\n    };\n  }\n  return runServiceOverride(activeExtensionServices, buildServiceContext(service, payload));\n}\n\n/**\n * Implements run active service override sync for the public runtime surface of this module.\n */\nexport function runActiveServiceOverrideSync(service: ExtensionServiceName, payload: unknown): ServiceOverrideResult {\n  if (!activeExtensionServices) {\n    return {\n      handled: false,\n      result: payload,\n      warnings: [],\n    };\n  }\n  return runServiceOverrideSync(activeExtensionServices, buildServiceContext(service, payload));\n}\n\nexport * from \"./loader.js\";\nexport {\n  EXTENSION_CAPABILITY_REGISTRATION_SURFACES,\n  collectUsedExtensionCapabilities,\n  reconcileExtensionCapabilityUsage,\n  type CollectUsedExtensionCapabilitiesOptions,\n  type ExtensionCapabilityUsageReconciliation,\n} from \"./capability-usage.js\";\n"],"names":[],"mappings":"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","debugId":"abe62b94-a55a-5cdf-8f1a-34360ddc4c25"}

package/dist/core/item/item-format-version.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @module core/item/item-format-version
+ *
+ * Tracks the on-disk item front-matter format version so a future breaking
+ * storage change can tell already-current items apart from items that a staged
+ * migration must rewrite, without re-parsing and structurally guessing every
+ * file. The version is an explicit, monotonically increasing integer stamped in
+ * front-matter as `pm_format_version`.
+ *
+ * Token economy is a first-class constraint here: the baseline version (1) is
+ * the implicit default and is never serialized, so today's corpus gains zero
+ * bytes and zero churn. The field only materializes once an item reaches
+ * version 2 or higher. Absence of the field is therefore always interpreted as
+ * the baseline version, both now and after future bumps. The classification
+ * helpers below power the advisory `pm health` integrity surface and the
+ * `pm validate` format-version check.
+ */
+import type { ItemMetadata } from "../../types/index.js";
+/**
+ * The original (and implicit) item front-matter format version. Items missing a
+ * `pm_format_version` field are always treated as this version, so the baseline
+ * is never written to disk and adds no per-item token cost.
+ */
+export declare const BASELINE_ITEM_FORMAT_VERSION = 1;
+/**
+ * The format version this runtime writes and considers current. When a breaking
+ * front-matter change ships, bump this constant and add a migration that
+ * rewrites items whose {@link effectiveItemFormatVersion} is lower; items at or
+ * above it need no migration. It stays equal to
+ * {@link BASELINE_ITEM_FORMAT_VERSION} until the first such change.
+ */
+export declare const CURRENT_ITEM_FORMAT_VERSION = 1;
+/**
+ * Resolve the format version an item is effectively stored at. A present,
+ * positive-integer `pm_format_version` is taken verbatim (including versions
+ * ahead of this runtime, so they can be flagged rather than silently clamped);
+ * an absent, malformed, or sub-baseline value resolves to
+ * {@link BASELINE_ITEM_FORMAT_VERSION}.
+ */
+export declare function effectiveItemFormatVersion(metadata: Pick<ItemMetadata, "pm_format_version">): number;
+/**
+ * Reduce an item's `pm_format_version` to its persisted form: the baseline
+ * version (and any malformed or sub-baseline value) is dropped so it is never
+ * serialized, while versions at or above {@link BASELINE_ITEM_FORMAT_VERSION}
+ * plus one are preserved verbatim. This keeps the field absent for the entire
+ * current corpus and only writes it once an item genuinely advances past the
+ * implicit baseline.
+ */
+export declare function normalizeItemFormatVersion(value: unknown): number | undefined;
+/**
+ * Relationship between an item's stored format version and the runtime's
+ * current version: `outdated` (below current, a migration would rewrite it),
+ * `ahead` (above current, written by a newer pm than this one), or `current`.
+ */
+export type ItemFormatVersionStatus = "current" | "outdated" | "ahead";
+/**
+ * Classify a single stored format version against the runtime's current
+ * version. Defaults to {@link CURRENT_ITEM_FORMAT_VERSION}; the `current`
+ * parameter exists so callers (and tests) can evaluate against a hypothetical
+ * future version without mutating the module constant.
+ */
+export declare function classifyItemFormatVersion(version: number, current?: number): ItemFormatVersionStatus;
+/**
+ * One item's reference (id or relative path) paired with the format version it
+ * is stored at, used as input to {@link scanItemFormatVersions}.
+ */
+export interface ItemFormatVersionScanEntry {
+    ref: string;
+    version: number;
+}
+/**
+ * Sorted references partitioned by how their stored format version compares to
+ * the runtime's current version. References at the current version are omitted
+ * from both lists.
+ */
+export interface ItemFormatVersionScanResult {
+    outdated: string[];
+    ahead: string[];
+}
+/**
+ * Partition a set of items by format version into `outdated` (need migration)
+ * and `ahead` (written by a newer pm) reference lists, each sorted for stable
+ * diagnostics. Pushing all comparison branches into this pure, exhaustively
+ * tested helper lets `pm health` and `pm validate` emit findings by iterating
+ * the result lists, with no version-comparison branching of their own.
+ */
+export declare function scanItemFormatVersions(entries: readonly ItemFormatVersionScanEntry[], current?: number): ItemFormatVersionScanResult;

package/dist/core/item/item-format-version.js

@@ -0,0 +1,85 @@
+/**
+ * The original (and implicit) item front-matter format version. Items missing a
+ * `pm_format_version` field are always treated as this version, so the baseline
+ * is never written to disk and adds no per-item token cost.
+ */
+
+!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]="f0e67d63-2f7b-5f4a-b441-7a499c82e0a8")}catch(e){}}();
+export const BASELINE_ITEM_FORMAT_VERSION = 1;
+/**
+ * The format version this runtime writes and considers current. When a breaking
+ * front-matter change ships, bump this constant and add a migration that
+ * rewrites items whose {@link effectiveItemFormatVersion} is lower; items at or
+ * above it need no migration. It stays equal to
+ * {@link BASELINE_ITEM_FORMAT_VERSION} until the first such change.
+ */
+export const CURRENT_ITEM_FORMAT_VERSION = 1;
+/**
+ * Resolve the format version an item is effectively stored at. A present,
+ * positive-integer `pm_format_version` is taken verbatim (including versions
+ * ahead of this runtime, so they can be flagged rather than silently clamped);
+ * an absent, malformed, or sub-baseline value resolves to
+ * {@link BASELINE_ITEM_FORMAT_VERSION}.
+ */
+export function effectiveItemFormatVersion(metadata) {
+    const raw = metadata.pm_format_version;
+    if (typeof raw === "number" && Number.isInteger(raw) && raw >= BASELINE_ITEM_FORMAT_VERSION) {
+        return raw;
+    }
+    return BASELINE_ITEM_FORMAT_VERSION;
+}
+/**
+ * Reduce an item's `pm_format_version` to its persisted form: the baseline
+ * version (and any malformed or sub-baseline value) is dropped so it is never
+ * serialized, while versions at or above {@link BASELINE_ITEM_FORMAT_VERSION}
+ * plus one are preserved verbatim. This keeps the field absent for the entire
+ * current corpus and only writes it once an item genuinely advances past the
+ * implicit baseline.
+ */
+export function normalizeItemFormatVersion(value) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value <= BASELINE_ITEM_FORMAT_VERSION) {
+        return undefined;
+    }
+    return value;
+}
+/**
+ * Classify a single stored format version against the runtime's current
+ * version. Defaults to {@link CURRENT_ITEM_FORMAT_VERSION}; the `current`
+ * parameter exists so callers (and tests) can evaluate against a hypothetical
+ * future version without mutating the module constant.
+ */
+export function classifyItemFormatVersion(version, current = CURRENT_ITEM_FORMAT_VERSION) {
+    if (version < current) {
+        return "outdated";
+    }
+    if (version > current) {
+        return "ahead";
+    }
+    return "current";
+}
+/**
+ * Partition a set of items by format version into `outdated` (need migration)
+ * and `ahead` (written by a newer pm) reference lists, each sorted for stable
+ * diagnostics. Pushing all comparison branches into this pure, exhaustively
+ * tested helper lets `pm health` and `pm validate` emit findings by iterating
+ * the result lists, with no version-comparison branching of their own.
+ */
+export function scanItemFormatVersions(entries, current = CURRENT_ITEM_FORMAT_VERSION) {
+    const outdated = [];
+    const ahead = [];
+    for (const entry of entries) {
+        const status = classifyItemFormatVersion(entry.version, current);
+        if (status === "outdated") {
+            outdated.push(entry.ref);
+        }
+        else if (status === "ahead") {
+            ahead.push(entry.ref);
+        }
+    }
+    return {
+        outdated: outdated.sort((left, right) => left.localeCompare(right)),
+        ahead: ahead.sort((left, right) => left.localeCompare(right)),
+    };
+}
+//# sourceMappingURL=item-format-version.js.map
+//# debugId=f0e67d63-2f7b-5f4a-b441-7a499c82e0a8

package/dist/core/item/item-format-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-format-version.js","sources":["core/item/item-format-version.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/item/item-format-version\n *\n * Tracks the on-disk item front-matter format version so a future breaking\n * storage change can tell already-current items apart from items that a staged\n * migration must rewrite, without re-parsing and structurally guessing every\n * file. The version is an explicit, monotonically increasing integer stamped in\n * front-matter as `pm_format_version`.\n *\n * Token economy is a first-class constraint here: the baseline version (1) is\n * the implicit default and is never serialized, so today's corpus gains zero\n * bytes and zero churn. The field only materializes once an item reaches\n * version 2 or higher. Absence of the field is therefore always interpreted as\n * the baseline version, both now and after future bumps. The classification\n * helpers below power the advisory `pm health` integrity surface and the\n * `pm validate` format-version check.\n */\nimport type { ItemMetadata } from \"../../types/index.js\";\n\n/**\n * The original (and implicit) item front-matter format version. Items missing a\n * `pm_format_version` field are always treated as this version, so the baseline\n * is never written to disk and adds no per-item token cost.\n */\nexport const BASELINE_ITEM_FORMAT_VERSION = 1;\n\n/**\n * The format version this runtime writes and considers current. When a breaking\n * front-matter change ships, bump this constant and add a migration that\n * rewrites items whose {@link effectiveItemFormatVersion} is lower; items at or\n * above it need no migration. It stays equal to\n * {@link BASELINE_ITEM_FORMAT_VERSION} until the first such change.\n */\nexport const CURRENT_ITEM_FORMAT_VERSION = 1;\n\n/**\n * Resolve the format version an item is effectively stored at. A present,\n * positive-integer `pm_format_version` is taken verbatim (including versions\n * ahead of this runtime, so they can be flagged rather than silently clamped);\n * an absent, malformed, or sub-baseline value resolves to\n * {@link BASELINE_ITEM_FORMAT_VERSION}.\n */\nexport function effectiveItemFormatVersion(metadata: Pick<ItemMetadata, \"pm_format_version\">): number {\n  const raw = metadata.pm_format_version;\n  if (typeof raw === \"number\" && Number.isInteger(raw) && raw >= BASELINE_ITEM_FORMAT_VERSION) {\n    return raw;\n  }\n  return BASELINE_ITEM_FORMAT_VERSION;\n}\n\n/**\n * Reduce an item's `pm_format_version` to its persisted form: the baseline\n * version (and any malformed or sub-baseline value) is dropped so it is never\n * serialized, while versions at or above {@link BASELINE_ITEM_FORMAT_VERSION}\n * plus one are preserved verbatim. This keeps the field absent for the entire\n * current corpus and only writes it once an item genuinely advances past the\n * implicit baseline.\n */\nexport function normalizeItemFormatVersion(value: unknown): number | undefined {\n  if (typeof value !== \"number\" || !Number.isInteger(value) || value <= BASELINE_ITEM_FORMAT_VERSION) {\n    return undefined;\n  }\n  return value;\n}\n\n/**\n * Relationship between an item's stored format version and the runtime's\n * current version: `outdated` (below current, a migration would rewrite it),\n * `ahead` (above current, written by a newer pm than this one), or `current`.\n */\nexport type ItemFormatVersionStatus = \"current\" | \"outdated\" | \"ahead\";\n\n/**\n * Classify a single stored format version against the runtime's current\n * version. Defaults to {@link CURRENT_ITEM_FORMAT_VERSION}; the `current`\n * parameter exists so callers (and tests) can evaluate against a hypothetical\n * future version without mutating the module constant.\n */\nexport function classifyItemFormatVersion(\n  version: number,\n  current: number = CURRENT_ITEM_FORMAT_VERSION,\n): ItemFormatVersionStatus {\n  if (version < current) {\n    return \"outdated\";\n  }\n  if (version > current) {\n    return \"ahead\";\n  }\n  return \"current\";\n}\n\n/**\n * One item's reference (id or relative path) paired with the format version it\n * is stored at, used as input to {@link scanItemFormatVersions}.\n */\nexport interface ItemFormatVersionScanEntry {\n  ref: string;\n  version: number;\n}\n\n/**\n * Sorted references partitioned by how their stored format version compares to\n * the runtime's current version. References at the current version are omitted\n * from both lists.\n */\nexport interface ItemFormatVersionScanResult {\n  outdated: string[];\n  ahead: string[];\n}\n\n/**\n * Partition a set of items by format version into `outdated` (need migration)\n * and `ahead` (written by a newer pm) reference lists, each sorted for stable\n * diagnostics. Pushing all comparison branches into this pure, exhaustively\n * tested helper lets `pm health` and `pm validate` emit findings by iterating\n * the result lists, with no version-comparison branching of their own.\n */\nexport function scanItemFormatVersions(\n  entries: readonly ItemFormatVersionScanEntry[],\n  current: number = CURRENT_ITEM_FORMAT_VERSION,\n): ItemFormatVersionScanResult {\n  const outdated: string[] = [];\n  const ahead: string[] = [];\n  for (const entry of entries) {\n    const status = classifyItemFormatVersion(entry.version, current);\n    if (status === \"outdated\") {\n      outdated.push(entry.ref);\n    } else if (status === \"ahead\") {\n      ahead.push(entry.ref);\n    }\n  }\n  return {\n    outdated: outdated.sort((left, right) => left.localeCompare(right)),\n    ahead: ahead.sort((left, right) => left.localeCompare(right)),\n  };\n}\n"],"names":[],"mappings":"AAmBA;;;;GAIG;;;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CAAC,QAAiD;IAC1F,MAAM,GAAG,GAAG,QAAQ,CAAC,iBAAiB,CAAC;IACvC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,4BAA4B,EAAE,CAAC;QAC5F,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,4BAA4B,CAAC;AACtC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAc;IACvD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,4BAA4B,EAAE,CAAC;QACnG,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAe,EACf,UAAkB,2BAA2B;IAE7C,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC;QACtB,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,OAAO,GAAG,OAAO,EAAE,CAAC;QACtB,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAqBD;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAA8C,EAC9C,UAAkB,2BAA2B;IAE7C,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,MAAM,GAAG,yBAAyB,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjE,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;YAC1B,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;aAAM,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YAC9B,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO;QACL,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QACnE,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;KAC9D,CAAC;AACJ,CAAC","debugId":"f0e67d63-2f7b-5f4a-b441-7a499c82e0a8"}

package/dist/core/item/item-format.js

@@ -4,11 +4,12 @@
  * Defines item parsing, formatting, and lifecycle helpers for Item Format.
  */
 
-!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]="c295802c-f55f-56e8-afdc-257cdef6a4cb")}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]="777ea2a9-5aa6-5a90-abb5-a0b6052645f2")}catch(e){}}();
 import { encode as encodeToon } from "@toon-format/toon";
 import { CONFIDENCE_TEXT_VALUES, ISSUE_SEVERITY_VALUES, RECURRENCE_FREQUENCY_VALUES, RECURRENCE_WEEKDAY_VALUES, STATUS_VALUES, weekdayOrderIndex, } from "../../types/index.js";
 import { coerceRuntimeFieldValue } from "../schema/runtime-field-values.js";
 import { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../schema/runtime-schema.js";
+import { BASELINE_ITEM_FORMAT_VERSION, normalizeItemFormatVersion } from "./item-format-version.js";
 import { normalizeStatusInput } from "./status.js";
 import { decodeToonItemContent } from "./toon-decode.js";
 import { EXIT_CODE, FRONT_MATTER_KEY_ORDER } from "../shared/constants.js";
@@ -129,6 +130,10 @@ function assertValidFrontMatter(frontMatter, runtimeContext) {
     }
     const itemType = record.type;
     assertFrontMatterCondition(typeof itemType === "string" && itemType.trim().length > 0, "type must be a non-empty string");
+    const formatVersion = record.pm_format_version;
+    if (formatVersion !== undefined) {
+        assertFrontMatterCondition(typeof formatVersion === "number" && Number.isInteger(formatVersion) && formatVersion >= BASELINE_ITEM_FORMAT_VERSION, `pm_format_version must be an integer >= ${BASELINE_ITEM_FORMAT_VERSION}`);
+    }
     const status = record.status;
     assertFrontMatterCondition(typeof status === "string" && status.trim().length > 0, "status must be a non-empty string");
     const statusRegistry = runtimeContext?.statusRegistry;
@@ -849,6 +854,7 @@ export function normalizeFrontMatter(frontMatter, options = {}) {
         title: frontMatter.title,
         description: frontMatter.description,
         type: frontMatter.type,
+        pm_format_version: normalizeItemFormatVersion(frontMatter.pm_format_version),
         source_type: frontMatter.source_type?.trim() || undefined,
         type_options: normalizeTypeOptions(frontMatter.type_options),
         status: normalizedStatus,
@@ -1149,4 +1155,4 @@ export const _testOnlyItemFormat = {
     sortTests,
 };
 //# sourceMappingURL=item-format.js.map
-//# debugId=c295802c-f55f-56e8-afdc-257cdef6a4cb
+//# debugId=777ea2a9-5aa6-5a90-abb5-a0b6052645f2