@unbrained/pm-cli 2026.6.30 → 2026.7.1

package/dist/core/extensions/activation-summary-markdown.js

@@ -4,7 +4,7 @@
  * section headings so a deep title never emits an invalid `#######` run.
  */
 
-!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]="916c708e-0da8-5408-8d50-ce702f482e94")}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]="b179b4ec-bec8-5761-b7d2-db8f7c8ed54a")}catch(e){}}();
 const MIN_HEADING_LEVEL = 1;
 const MAX_HEADING_LEVEL = 6;
 /**
@@ -84,6 +84,24 @@ function renderSection(heading, level, entries) {
     lines.push(...entries.map((entry) => `- ${code(entry)}`), "");
     return lines;
 }
+/**
+ * Render the preflight-overrides section: a count line when any are registered,
+ * `_None._` when {@link ExtensionSurfaceMarkdownOptions.includeEmpty} forces the
+ * empty section, or no lines at all otherwise. Preflight overrides carry no
+ * per-entry identifier, so they have a bespoke renderer rather than reusing
+ * {@link renderSection}.
+ */
+function renderPreflightSection(count, level, includeEmpty) {
+    if (count === 0 && !includeEmpty) {
+        return [];
+    }
+    return [
+        `${headingPrefix(level)} Preflight overrides`,
+        "",
+        count > 0 ? `- ${count} registered (this surface carries no per-entry identifier)` : "_None._",
+        "",
+    ];
+}
 /**
  * Render an {@link ExtensionActivationSummary} as a deterministic Markdown
  * reference document.
@@ -115,26 +133,19 @@ export function renderExtensionSurfaceMarkdown(summary, options = {}) {
     if (includeEmpty || summary.capabilities.length > 0) {
         lines.push(renderCapabilitiesLine(summary.capabilities), "");
     }
-    let renderedSurface = false;
     for (const [field, heading] of SURFACE_SECTIONS) {
         const entries = summary[field];
         if (entries.length === 0 && !includeEmpty) {
             continue;
         }
-        renderedSurface = renderedSurface || entries.length > 0;
         lines.push(...renderSection(heading, sectionLevel, entries));
     }
-    if (summary.preflight_overrides > 0 || includeEmpty) {
-        renderedSurface = renderedSurface || summary.preflight_overrides > 0;
-        lines.push(`${headingPrefix(sectionLevel)} Preflight overrides`, "");
-        lines.push(summary.preflight_overrides > 0
-            ? `- ${summary.preflight_overrides} registered (this surface carries no per-entry identifier)`
-            : "_None._", "");
-    }
-    if (!renderedSurface && !includeEmpty) {
+    lines.push(...renderPreflightSection(summary.preflight_overrides, sectionLevel, includeEmpty));
+    const hasAnySurface = summary.preflight_overrides > 0 || SURFACE_SECTIONS.some(([field]) => summary[field].length > 0);
+    if (!hasAnySurface && !includeEmpty) {
         lines.push("_This extension registers no surfaces._", "");
     }
     return `${lines.join("\n").trimEnd()}\n`;
 }
 //# sourceMappingURL=activation-summary-markdown.js.map
-//# debugId=916c708e-0da8-5408-8d50-ce702f482e94
+//# debugId=b179b4ec-bec8-5761-b7d2-db8f7c8ed54a

package/dist/core/extensions/activation-summary-markdown.js.map

@@ -1 +1 @@
-{"version":3,"file":"activation-summary-markdown.js","sources":["core/extensions/activation-summary-markdown.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/activation-summary-markdown\n *\n * Renders an {@link ExtensionActivationSummary} to a deterministic Markdown\n * reference document — the *render* leg that completes the `describe`\n * (enumerate-all) verb.\n *\n * {@link ./activation-summary.js#describeExtensionActivation | `describeExtensionActivation`}\n * (and its author-time twin\n * {@link ../../sdk/compose.js#describeExtensionBlueprint | `describeExtensionBlueprint`})\n * already answer \"what does this package register?\" as a structured summary, and\n * the `assert*`/`run*` testing helpers verify and invoke each surface. What was\n * missing is a way to turn that summary into human-readable docs: package\n * authors hand-wrote the README \"commands & capabilities\" reference, which\n * silently drifted from the surface the loader actually registers.\n *\n * {@link renderExtensionSurfaceMarkdown} closes that gap. It is a pure,\n * dependency-free projection of the summary, so an author can pipe\n * `describeExtensionBlueprint(blueprint)` straight into it during their build or\n * test step and embed the result in their README — a reference that can never\n * drift from the registered surface (\"project management = context management\").\n * The CLI's `pm extension|package describe --markdown` composes the same\n * primitive across every loaded extension.\n */\nimport type { ExtensionActivationSummary } from \"./activation-summary.js\";\n\n/**\n * The lowest and highest ATX heading levels Markdown supports, used to validate\n * {@link ExtensionSurfaceMarkdownOptions.headingLevel} and to clamp nested\n * section headings so a deep title never emits an invalid `#######` run.\n */\nconst MIN_HEADING_LEVEL = 1;\nconst MAX_HEADING_LEVEL = 6;\n\n/**\n * Options for {@link renderExtensionSurfaceMarkdown}.\n */\nexport interface ExtensionSurfaceMarkdownOptions {\n  /**\n   * Heading text for the document title. Defaults to `\"Extension surfaces\"`.\n   * The title always renders as an ATX heading at\n   * {@link ExtensionSurfaceMarkdownOptions.headingLevel}; per-surface sections\n   * render one level deeper.\n   */\n  title?: string;\n  /**\n   * ATX heading level for the title, an integer in `[1, 6]` (default `2`, i.e.\n   * `##`, so the document embeds cleanly under a `# Package` README heading).\n   * Section headings render at `headingLevel + 1`, clamped to `6`. Values\n   * outside `[1, 6]` throw a {@link RangeError}.\n   */\n  headingLevel?: number;\n  /**\n   * When `true`, render every surface section even when it has no entries\n   * (emitting `_None._` under the heading) and always emit the capabilities\n   * line. Defaults to `false`, which omits empty sections so the reference lists\n   * only what the package actually contributes.\n   */\n  includeEmpty?: boolean;\n}\n\n/**\n * A surface section paired with the {@link ExtensionActivationSummary} field\n * whose identifiers populate it. Ordered for an author-facing reference:\n * commands first, then schema, then importers/exporters, retrieval, lifecycle\n * hooks, and finally the override surfaces. {@link ExtensionActivationSummary.command_handlers}\n * is intentionally omitted — it is a documented superset of `commands` plus the\n * synthesized `<name> import`/`<name> export` paths already covered by the\n * Importers and Exporters sections, so rendering it would duplicate information.\n */\nconst SURFACE_SECTIONS = [\n  [\"commands\", \"Commands\"],\n  [\"command_overrides\", \"Command overrides\"],\n  [\"flag_commands\", \"Flag commands\"],\n  [\"item_types\", \"Item types\"],\n  [\"item_fields\", \"Item fields\"],\n  [\"migrations\", \"Migrations\"],\n  [\"profiles\", \"Profiles\"],\n  [\"importers\", \"Importers\"],\n  [\"exporters\", \"Exporters\"],\n  [\"search_providers\", \"Search providers\"],\n  [\"vector_store_adapters\", \"Vector store adapters\"],\n  [\"hooks\", \"Lifecycle hooks\"],\n  [\"parser_overrides\", \"Parser overrides\"],\n  [\"service_overrides\", \"Service overrides\"],\n  [\"renderer_overrides\", \"Renderer overrides\"],\n] as const satisfies ReadonlyArray<\n  readonly [\n    {\n      [K in keyof ExtensionActivationSummary]: ExtensionActivationSummary[K] extends readonly string[] ? K : never;\n    }[keyof ExtensionActivationSummary],\n    string,\n  ]\n>;\n\n/**\n * Repeat `#` `level` times to form an ATX heading prefix.\n */\nfunction headingPrefix(level: number): string {\n  return \"#\".repeat(level);\n}\n\n/**\n * Render `value` as an inline Markdown code span. Backslash escapes do not work\n * inside CommonMark code spans, so when `value` contains backticks the span is\n * delimited by a run of backticks one longer than the longest internal run, and\n * padded with a space when the value borders a backtick — the CommonMark rule\n * for embedding literal backticks in a code span.\n */\nfunction code(value: string): string {\n  if (!value.includes(\"`\")) {\n    return `\\`${value}\\``;\n  }\n  let longestRun = 0;\n  let currentRun = 0;\n  for (const char of value) {\n    currentRun = char === \"`\" ? currentRun + 1 : 0;\n    longestRun = Math.max(longestRun, currentRun);\n  }\n  const fence = \"`\".repeat(longestRun + 1);\n  const pad = value.startsWith(\"`\") || value.endsWith(\"`\") ? \" \" : \"\";\n  return `${fence}${pad}${value}${pad}${fence}`;\n}\n\n/**\n * Render the comma-separated capabilities summary line (or `_none registered_`\n * when the activation exercised no known capability).\n */\nfunction renderCapabilitiesLine(capabilities: readonly string[]): string {\n  if (capabilities.length === 0) {\n    return \"Capabilities: _none registered_\";\n  }\n  return `Capabilities: ${capabilities.map(code).join(\", \")}`;\n}\n\n/**\n * Render one surface section as `heading` + a bullet per identifier, or, when\n * `entries` is empty, `heading` + `_None._`. Callers decide whether an empty\n * section is rendered at all via {@link ExtensionSurfaceMarkdownOptions.includeEmpty}.\n */\nfunction renderSection(heading: string, level: number, entries: readonly string[]): string[] {\n  const lines = [`${headingPrefix(level)} ${heading}`, \"\"];\n  if (entries.length === 0) {\n    lines.push(\"_None._\", \"\");\n    return lines;\n  }\n  lines.push(...entries.map((entry) => `- ${code(entry)}`), \"\");\n  return lines;\n}\n\n/**\n * Render an {@link ExtensionActivationSummary} as a deterministic Markdown\n * reference document.\n *\n * The output is a title heading, a one-line capabilities summary, and a section\n * per registered surface (commands, overrides, flags, item types/fields,\n * migrations, importers/exporters, search providers, vector adapters, lifecycle\n * hooks, and the parser/service/renderer override surfaces), followed by a\n * preflight-override count line when any are registered. Section order and\n * within-section identifier order both come straight from the summary, so the\n * same summary always renders byte-for-byte the same document.\n *\n * By default empty sections are omitted so the reference lists only what the\n * package contributes; set {@link ExtensionSurfaceMarkdownOptions.includeEmpty}\n * to render every section. A summary with no surfaces at all renders the title,\n * the capabilities line, and a `_This extension registers no surfaces._` note.\n *\n * @throws {RangeError} when `options.headingLevel` is not an integer in `[1, 6]`.\n */\nexport function renderExtensionSurfaceMarkdown(\n  summary: ExtensionActivationSummary,\n  options: ExtensionSurfaceMarkdownOptions = {},\n): string {\n  const titleLevel = options.headingLevel ?? 2;\n  if (!Number.isInteger(titleLevel) || titleLevel < MIN_HEADING_LEVEL || titleLevel > MAX_HEADING_LEVEL) {\n    throw new RangeError(\n      `headingLevel must be an integer in [${MIN_HEADING_LEVEL}, ${MAX_HEADING_LEVEL}], received ${String(options.headingLevel)}`,\n    );\n  }\n  const sectionLevel = Math.min(titleLevel + 1, MAX_HEADING_LEVEL);\n  const includeEmpty = options.includeEmpty === true;\n  const title = options.title ?? \"Extension surfaces\";\n\n  const lines = [`${headingPrefix(titleLevel)} ${title}`, \"\"];\n  if (includeEmpty || summary.capabilities.length > 0) {\n    lines.push(renderCapabilitiesLine(summary.capabilities), \"\");\n  }\n\n  let renderedSurface = false;\n  for (const [field, heading] of SURFACE_SECTIONS) {\n    const entries = summary[field];\n    if (entries.length === 0 && !includeEmpty) {\n      continue;\n    }\n    renderedSurface = renderedSurface || entries.length > 0;\n    lines.push(...renderSection(heading, sectionLevel, entries));\n  }\n\n  if (summary.preflight_overrides > 0 || includeEmpty) {\n    renderedSurface = renderedSurface || summary.preflight_overrides > 0;\n    lines.push(`${headingPrefix(sectionLevel)} Preflight overrides`, \"\");\n    lines.push(\n      summary.preflight_overrides > 0\n        ? `- ${summary.preflight_overrides} registered (this surface carries no per-entry identifier)`\n        : \"_None._\",\n      \"\",\n    );\n  }\n\n  if (!renderedSurface && !includeEmpty) {\n    lines.push(\"_This extension registers no surfaces._\", \"\");\n  }\n\n  return `${lines.join(\"\\n\").trimEnd()}\\n`;\n}\n"],"names":[],"mappings":"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","debugId":"916c708e-0da8-5408-8d50-ce702f482e94"}
+{"version":3,"file":"activation-summary-markdown.js","sources":["core/extensions/activation-summary-markdown.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/extensions/activation-summary-markdown\n *\n * Renders an {@link ExtensionActivationSummary} to a deterministic Markdown\n * reference document — the *render* leg that completes the `describe`\n * (enumerate-all) verb.\n *\n * {@link ./activation-summary.js#describeExtensionActivation | `describeExtensionActivation`}\n * (and its author-time twin\n * {@link ../../sdk/compose.js#describeExtensionBlueprint | `describeExtensionBlueprint`})\n * already answer \"what does this package register?\" as a structured summary, and\n * the `assert*`/`run*` testing helpers verify and invoke each surface. What was\n * missing is a way to turn that summary into human-readable docs: package\n * authors hand-wrote the README \"commands & capabilities\" reference, which\n * silently drifted from the surface the loader actually registers.\n *\n * {@link renderExtensionSurfaceMarkdown} closes that gap. It is a pure,\n * dependency-free projection of the summary, so an author can pipe\n * `describeExtensionBlueprint(blueprint)` straight into it during their build or\n * test step and embed the result in their README — a reference that can never\n * drift from the registered surface (\"project management = context management\").\n * The CLI's `pm extension|package describe --markdown` composes the same\n * primitive across every loaded extension.\n */\nimport type { ExtensionActivationSummary } from \"./activation-summary.js\";\n\n/**\n * The lowest and highest ATX heading levels Markdown supports, used to validate\n * {@link ExtensionSurfaceMarkdownOptions.headingLevel} and to clamp nested\n * section headings so a deep title never emits an invalid `#######` run.\n */\nconst MIN_HEADING_LEVEL = 1;\nconst MAX_HEADING_LEVEL = 6;\n\n/**\n * Options for {@link renderExtensionSurfaceMarkdown}.\n */\nexport interface ExtensionSurfaceMarkdownOptions {\n  /**\n   * Heading text for the document title. Defaults to `\"Extension surfaces\"`.\n   * The title always renders as an ATX heading at\n   * {@link ExtensionSurfaceMarkdownOptions.headingLevel}; per-surface sections\n   * render one level deeper.\n   */\n  title?: string;\n  /**\n   * ATX heading level for the title, an integer in `[1, 6]` (default `2`, i.e.\n   * `##`, so the document embeds cleanly under a `# Package` README heading).\n   * Section headings render at `headingLevel + 1`, clamped to `6`. Values\n   * outside `[1, 6]` throw a {@link RangeError}.\n   */\n  headingLevel?: number;\n  /**\n   * When `true`, render every surface section even when it has no entries\n   * (emitting `_None._` under the heading) and always emit the capabilities\n   * line. Defaults to `false`, which omits empty sections so the reference lists\n   * only what the package actually contributes.\n   */\n  includeEmpty?: boolean;\n}\n\n/**\n * A surface section paired with the {@link ExtensionActivationSummary} field\n * whose identifiers populate it. Ordered for an author-facing reference:\n * commands first, then schema, then importers/exporters, retrieval, lifecycle\n * hooks, and finally the override surfaces. {@link ExtensionActivationSummary.command_handlers}\n * is intentionally omitted — it is a documented superset of `commands` plus the\n * synthesized `<name> import`/`<name> export` paths already covered by the\n * Importers and Exporters sections, so rendering it would duplicate information.\n */\nconst SURFACE_SECTIONS = [\n  [\"commands\", \"Commands\"],\n  [\"command_overrides\", \"Command overrides\"],\n  [\"flag_commands\", \"Flag commands\"],\n  [\"item_types\", \"Item types\"],\n  [\"item_fields\", \"Item fields\"],\n  [\"migrations\", \"Migrations\"],\n  [\"profiles\", \"Profiles\"],\n  [\"importers\", \"Importers\"],\n  [\"exporters\", \"Exporters\"],\n  [\"search_providers\", \"Search providers\"],\n  [\"vector_store_adapters\", \"Vector store adapters\"],\n  [\"hooks\", \"Lifecycle hooks\"],\n  [\"parser_overrides\", \"Parser overrides\"],\n  [\"service_overrides\", \"Service overrides\"],\n  [\"renderer_overrides\", \"Renderer overrides\"],\n] as const satisfies ReadonlyArray<\n  readonly [\n    {\n      [K in keyof ExtensionActivationSummary]: ExtensionActivationSummary[K] extends readonly string[] ? K : never;\n    }[keyof ExtensionActivationSummary],\n    string,\n  ]\n>;\n\n/**\n * Repeat `#` `level` times to form an ATX heading prefix.\n */\nfunction headingPrefix(level: number): string {\n  return \"#\".repeat(level);\n}\n\n/**\n * Render `value` as an inline Markdown code span. Backslash escapes do not work\n * inside CommonMark code spans, so when `value` contains backticks the span is\n * delimited by a run of backticks one longer than the longest internal run, and\n * padded with a space when the value borders a backtick — the CommonMark rule\n * for embedding literal backticks in a code span.\n */\nfunction code(value: string): string {\n  if (!value.includes(\"`\")) {\n    return `\\`${value}\\``;\n  }\n  let longestRun = 0;\n  let currentRun = 0;\n  for (const char of value) {\n    currentRun = char === \"`\" ? currentRun + 1 : 0;\n    longestRun = Math.max(longestRun, currentRun);\n  }\n  const fence = \"`\".repeat(longestRun + 1);\n  const pad = value.startsWith(\"`\") || value.endsWith(\"`\") ? \" \" : \"\";\n  return `${fence}${pad}${value}${pad}${fence}`;\n}\n\n/**\n * Render the comma-separated capabilities summary line (or `_none registered_`\n * when the activation exercised no known capability).\n */\nfunction renderCapabilitiesLine(capabilities: readonly string[]): string {\n  if (capabilities.length === 0) {\n    return \"Capabilities: _none registered_\";\n  }\n  return `Capabilities: ${capabilities.map(code).join(\", \")}`;\n}\n\n/**\n * Render one surface section as `heading` + a bullet per identifier, or, when\n * `entries` is empty, `heading` + `_None._`. Callers decide whether an empty\n * section is rendered at all via {@link ExtensionSurfaceMarkdownOptions.includeEmpty}.\n */\nfunction renderSection(heading: string, level: number, entries: readonly string[]): string[] {\n  const lines = [`${headingPrefix(level)} ${heading}`, \"\"];\n  if (entries.length === 0) {\n    lines.push(\"_None._\", \"\");\n    return lines;\n  }\n  lines.push(...entries.map((entry) => `- ${code(entry)}`), \"\");\n  return lines;\n}\n\n/**\n * Render the preflight-overrides section: a count line when any are registered,\n * `_None._` when {@link ExtensionSurfaceMarkdownOptions.includeEmpty} forces the\n * empty section, or no lines at all otherwise. Preflight overrides carry no\n * per-entry identifier, so they have a bespoke renderer rather than reusing\n * {@link renderSection}.\n */\nfunction renderPreflightSection(count: number, level: number, includeEmpty: boolean): string[] {\n  if (count === 0 && !includeEmpty) {\n    return [];\n  }\n  return [\n    `${headingPrefix(level)} Preflight overrides`,\n    \"\",\n    count > 0 ? `- ${count} registered (this surface carries no per-entry identifier)` : \"_None._\",\n    \"\",\n  ];\n}\n\n/**\n * Render an {@link ExtensionActivationSummary} as a deterministic Markdown\n * reference document.\n *\n * The output is a title heading, a one-line capabilities summary, and a section\n * per registered surface (commands, overrides, flags, item types/fields,\n * migrations, importers/exporters, search providers, vector adapters, lifecycle\n * hooks, and the parser/service/renderer override surfaces), followed by a\n * preflight-override count line when any are registered. Section order and\n * within-section identifier order both come straight from the summary, so the\n * same summary always renders byte-for-byte the same document.\n *\n * By default empty sections are omitted so the reference lists only what the\n * package contributes; set {@link ExtensionSurfaceMarkdownOptions.includeEmpty}\n * to render every section. A summary with no surfaces at all renders the title,\n * the capabilities line, and a `_This extension registers no surfaces._` note.\n *\n * @throws {RangeError} when `options.headingLevel` is not an integer in `[1, 6]`.\n */\nexport function renderExtensionSurfaceMarkdown(\n  summary: ExtensionActivationSummary,\n  options: ExtensionSurfaceMarkdownOptions = {},\n): string {\n  const titleLevel = options.headingLevel ?? 2;\n  if (!Number.isInteger(titleLevel) || titleLevel < MIN_HEADING_LEVEL || titleLevel > MAX_HEADING_LEVEL) {\n    throw new RangeError(\n      `headingLevel must be an integer in [${MIN_HEADING_LEVEL}, ${MAX_HEADING_LEVEL}], received ${String(options.headingLevel)}`,\n    );\n  }\n  const sectionLevel = Math.min(titleLevel + 1, MAX_HEADING_LEVEL);\n  const includeEmpty = options.includeEmpty === true;\n  const title = options.title ?? \"Extension surfaces\";\n\n  const lines = [`${headingPrefix(titleLevel)} ${title}`, \"\"];\n  if (includeEmpty || summary.capabilities.length > 0) {\n    lines.push(renderCapabilitiesLine(summary.capabilities), \"\");\n  }\n\n  for (const [field, heading] of SURFACE_SECTIONS) {\n    const entries = summary[field];\n    if (entries.length === 0 && !includeEmpty) {\n      continue;\n    }\n    lines.push(...renderSection(heading, sectionLevel, entries));\n  }\n\n  lines.push(...renderPreflightSection(summary.preflight_overrides, sectionLevel, includeEmpty));\n\n  const hasAnySurface =\n    summary.preflight_overrides > 0 || SURFACE_SECTIONS.some(([field]) => summary[field].length > 0);\n  if (!hasAnySurface && !includeEmpty) {\n    lines.push(\"_This extension registers no surfaces._\", \"\");\n  }\n\n  return `${lines.join(\"\\n\").trimEnd()}\\n`;\n}\n"],"names":[],"mappings":"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","debugId":"b179b4ec-bec8-5761-b7d2-db8f7c8ed54a"}

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

@@ -75,7 +75,12 @@ export declare function normalizePolicySandboxProfile(value: string | undefined)
  */
 export declare function normalizePmMaxVersionExceededMode(value: PmMaxVersionExceededModeSetting | undefined): NormalizedPmMaxVersionExceededMode;
 /**
- * Implements normalize extension policy for the public runtime surface of this module.
+ * Normalize the raw `extensions.policy` settings block into the canonical
+ * {@link NormalizedExtensionPolicy} used across loading, registration, and the
+ * doctor surface: modes/trust/sandbox coerced to known values, every allow/block
+ * list lower-cased and de-duplicated into a set, per-extension overrides indexed by
+ * name, and unknown-capability/surface tokens surfaced as warnings. A missing
+ * policy block resolves to the all-defaults policy (mode/trust `off`).
  */
 export declare function normalizeExtensionPolicy(settings: PmSettings): NormalizedExtensionPolicy;
 /**
@@ -87,7 +92,13 @@ export declare function serializeExtensionPolicy(policy: NormalizedExtensionPoli
  */
 export declare function hydrateExtensionPolicy(policy: ExtensionGovernancePolicy): NormalizedExtensionPolicy;
 /**
- * Implements evaluate extension policy for extension for the public runtime surface of this module.
+ * Evaluate the layer-level governance policy for one extension by combining the
+ * extension allow/block decision, the trust-mode decision, and the sandbox-profile
+ * decision. Reasons are weighed in extension → trust → sandbox order: the first
+ * reason whose governing mode is `enforce` blocks the extension; otherwise the
+ * first whose mode is `warn` surfaces a non-blocking violation warning; otherwise
+ * the extension is allowed. The all-`off` short-circuit skips reason resolution
+ * entirely.
  */
 export declare function evaluateExtensionPolicyForExtension(policy: NormalizedExtensionPolicy, extension: PolicyExtensionRef): {
     allowed: boolean;
@@ -101,7 +112,11 @@ export declare function evaluateExtensionPolicyForCapability(policy: NormalizedE
     warning: string | null;
 };
 /**
- * Implements evaluate extension policy for registration for the public runtime surface of this module.
+ * Evaluate the governance policy for a single capability/surface registration an
+ * extension performs during activation. When `mode` is `off` the registration is
+ * always allowed; otherwise the first allow/block reason (capability → surface →
+ * command → action → service) blocks the registration under `enforce` or surfaces
+ * a non-blocking violation warning under `warn`.
  */
 export declare function evaluateExtensionPolicyForRegistration(policy: NormalizedExtensionPolicy, extension: PolicyExtensionRef, surface: ExtensionPolicySurface, method: string, capability?: ExtensionCapability, details?: {
     command?: string;

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

@@ -4,7 +4,7 @@
  * Implements extension runtime contracts and governance for Extension Policy.
  */
 
-!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]="34b7e8e0-c42f-50c2-9ee5-093565566cd7")}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]="dbc43b74-6872-52c3-859a-64fe84c02b5b")}catch(e){}}();
 import { KNOWN_EXTENSION_POLICY_MODES, KNOWN_EXTENSION_POLICY_SURFACES, KNOWN_EXTENSION_SANDBOX_PROFILES, KNOWN_EXTENSION_TRUST_MODES, KNOWN_PM_MAX_VERSION_EXCEEDED_MODES, } from "./extension-types.js";
 import { isKnownExtensionCapability } from "./extension-capability-aliases.js";
 import { normalizeCommandName } from "./extension-runtime-helpers.js";
@@ -138,36 +138,22 @@ function collectExtensionPolicyOverrides(rawOverrides) {
     return overridesByName;
 }
 /**
- * Implements normalize extension policy for the public runtime surface of this module.
+ * Collect the deduplicated, alphabetically-sorted `extension_policy_unknown_*`
+ * warnings for a normalized policy: every allow/block capability and surface
+ * token — at the top level and inside each per-extension override — that is not a
+ * recognized {@link ExtensionCapability} or known policy surface. Overrides are
+ * walked in name order and the final list is re-sorted, so the result is stable
+ * regardless of insertion order.
  */
-export function normalizeExtensionPolicy(settings) {
-    const policy = settings.extensions.policy;
-    const mode = normalizePolicyMode(policy?.mode);
-    const trustMode = normalizePolicyTrustMode(policy?.trust_mode);
-    const pmMaxVersionExceededMode = normalizePmMaxVersionExceededMode(policy?.pm_max_version_exceeded_mode);
-    const requireProvenance = policy?.require_provenance === true;
-    const trustedExtensions = normalizePolicyStringSet(policy?.trusted_extensions);
-    const defaultSandboxProfile = normalizePolicySandboxProfile(policy?.default_sandbox_profile);
-    const allowedExtensions = normalizePolicyStringSet(policy?.allowed_extensions);
-    const blockedExtensions = normalizePolicyStringSet(policy?.blocked_extensions);
-    const allowedCapabilities = normalizePolicyStringSet(policy?.allowed_capabilities);
-    const blockedCapabilities = normalizePolicyStringSet(policy?.blocked_capabilities);
-    const allowedSurfaces = normalizePolicySurfaceSet(policy?.allowed_surfaces);
-    const blockedSurfaces = normalizePolicySurfaceSet(policy?.blocked_surfaces);
-    const allowedCommands = normalizePolicyStringSet(policy?.allowed_commands);
-    const blockedCommands = normalizePolicyStringSet(policy?.blocked_commands);
-    const allowedActions = normalizePolicyStringSet(policy?.allowed_actions);
-    const blockedActions = normalizePolicyStringSet(policy?.blocked_actions);
-    const allowedServices = normalizePolicyStringSet(policy?.allowed_services);
-    const blockedServices = normalizePolicyStringSet(policy?.blocked_services);
-    const overridesByName = collectExtensionPolicyOverrides(policy?.extension_overrides);
+function collectExtensionPolicyWarnings(normalized) {
     const warnings = [];
-    for (const capability of toSortedList([...allowedCapabilities, ...blockedCapabilities])) {
+    const sortedOverrides = [...normalized.overridesByName.values()].sort((left, right) => left.name.localeCompare(right.name));
+    for (const capability of toSortedList([...normalized.allowedCapabilities, ...normalized.blockedCapabilities])) {
         if (!isKnownExtensionCapability(capability)) {
             warnings.push(`extension_policy_unknown_capability:${capability}`);
         }
     }
-    for (const override of [...overridesByName.values()].sort((left, right) => left.name.localeCompare(right.name))) {
+    for (const override of sortedOverrides) {
         for (const capability of toSortedList([...override.allowedCapabilities, ...override.blockedCapabilities])) {
             if (!isKnownExtensionCapability(capability)) {
                 warnings.push(`extension_policy_unknown_capability:${override.name}:${capability}`);
@@ -175,39 +161,62 @@ export function normalizeExtensionPolicy(settings) {
         }
     }
     const knownSurfaces = new Set(KNOWN_EXTENSION_POLICY_SURFACES);
-    for (const surface of toSortedList([...allowedSurfaces, ...blockedSurfaces])) {
+    for (const surface of toSortedList([...normalized.allowedSurfaces, ...normalized.blockedSurfaces])) {
         if (!knownSurfaces.has(surface)) {
             warnings.push(`extension_policy_unknown_surface:${surface}`);
         }
     }
-    for (const override of [...overridesByName.values()].sort((left, right) => left.name.localeCompare(right.name))) {
+    for (const override of sortedOverrides) {
         for (const surface of toSortedList([...override.allowedSurfaces, ...override.blockedSurfaces])) {
             if (!knownSurfaces.has(surface)) {
                 warnings.push(`extension_policy_unknown_surface:${override.name}:${surface}`);
             }
         }
     }
+    return [...new Set(warnings)].sort((left, right) => left.localeCompare(right));
+}
+/**
+ * Normalize the raw `extensions.policy` settings block into the canonical
+ * {@link NormalizedExtensionPolicy} used across loading, registration, and the
+ * doctor surface: modes/trust/sandbox coerced to known values, every allow/block
+ * list lower-cased and de-duplicated into a set, per-extension overrides indexed by
+ * name, and unknown-capability/surface tokens surfaced as warnings. A missing
+ * policy block resolves to the all-defaults policy (mode/trust `off`).
+ */
+export function normalizeExtensionPolicy(settings) {
+    const policy = settings.extensions?.policy ?? {};
+    const allowedCapabilities = normalizePolicyStringSet(policy.allowed_capabilities);
+    const blockedCapabilities = normalizePolicyStringSet(policy.blocked_capabilities);
+    const allowedSurfaces = normalizePolicySurfaceSet(policy.allowed_surfaces);
+    const blockedSurfaces = normalizePolicySurfaceSet(policy.blocked_surfaces);
+    const overridesByName = collectExtensionPolicyOverrides(policy.extension_overrides);
     return {
-        mode,
-        trustMode,
-        pmMaxVersionExceededMode,
-        requireProvenance,
-        trustedExtensions,
-        defaultSandboxProfile,
-        allowedExtensions,
-        blockedExtensions,
+        mode: normalizePolicyMode(policy.mode),
+        trustMode: normalizePolicyTrustMode(policy.trust_mode),
+        pmMaxVersionExceededMode: normalizePmMaxVersionExceededMode(policy.pm_max_version_exceeded_mode),
+        requireProvenance: policy.require_provenance === true,
+        trustedExtensions: normalizePolicyStringSet(policy.trusted_extensions),
+        defaultSandboxProfile: normalizePolicySandboxProfile(policy.default_sandbox_profile),
+        allowedExtensions: normalizePolicyStringSet(policy.allowed_extensions),
+        blockedExtensions: normalizePolicyStringSet(policy.blocked_extensions),
         allowedCapabilities,
         blockedCapabilities,
         allowedSurfaces,
         blockedSurfaces,
-        allowedCommands,
-        blockedCommands,
-        allowedActions,
-        blockedActions,
-        allowedServices,
-        blockedServices,
+        allowedCommands: normalizePolicyStringSet(policy.allowed_commands),
+        blockedCommands: normalizePolicyStringSet(policy.blocked_commands),
+        allowedActions: normalizePolicyStringSet(policy.allowed_actions),
+        blockedActions: normalizePolicyStringSet(policy.blocked_actions),
+        allowedServices: normalizePolicyStringSet(policy.allowed_services),
+        blockedServices: normalizePolicyStringSet(policy.blocked_services),
         overridesByName,
-        warnings: [...new Set(warnings)].sort((left, right) => left.localeCompare(right)),
+        warnings: collectExtensionPolicyWarnings({
+            allowedCapabilities,
+            blockedCapabilities,
+            allowedSurfaces,
+            blockedSurfaces,
+            overridesByName,
+        }),
     };
 }
 /**
@@ -427,61 +436,40 @@ function buildPolicyWarning(mode, scope, extension, reason, details = {}) {
     return `extension_policy_${mode}_${scope}:${extension.layer}:${extension.name}:reason=${reason}${suffix}`;
 }
 /**
- * Implements evaluate extension policy for extension for the public runtime surface of this module.
+ * Evaluate the layer-level governance policy for one extension by combining the
+ * extension allow/block decision, the trust-mode decision, and the sandbox-profile
+ * decision. Reasons are weighed in extension → trust → sandbox order: the first
+ * reason whose governing mode is `enforce` blocks the extension; otherwise the
+ * first whose mode is `warn` surfaces a non-blocking violation warning; otherwise
+ * the extension is allowed. The all-`off` short-circuit skips reason resolution
+ * entirely.
  */
 export function evaluateExtensionPolicyForExtension(policy, extension) {
     if (policy.mode === "off" && policy.trustMode === "off") {
         return { allowed: true, warning: null };
     }
+    const violations = [];
     const reason = resolvePolicyExtensionReason(policy, extension);
-    const trustReason = resolvePolicyTrustReason(policy, extension);
-    const sandboxReason = resolvePolicySandboxReason(policy, extension);
-    const extensionEnforced = reason && policy.mode === "enforce";
-    const trustEnforced = trustReason && policy.trustMode === "enforce";
-    const sandboxEnforced = sandboxReason && policy.mode === "enforce";
-    if (!reason && !trustReason && !sandboxReason) {
-        return { allowed: true, warning: null };
+    if (reason) {
+        violations.push({ reason, scope: "extension", mode: policy.mode });
     }
-    if (extensionEnforced) {
-        return {
-            allowed: false,
-            warning: buildPolicyWarning("blocked", "extension", extension, reason),
-        };
-    }
-    if (trustEnforced) {
-        return {
-            allowed: false,
-            warning: buildPolicyWarning("blocked", "trust", extension, trustReason),
-        };
-    }
-    if (sandboxEnforced) {
-        return {
-            allowed: false,
-            warning: buildPolicyWarning("blocked", "extension", extension, sandboxReason),
-        };
+    const trustReason = resolvePolicyTrustReason(policy, extension);
+    if (trustReason) {
+        violations.push({ reason: trustReason, scope: "trust", mode: policy.trustMode });
     }
-    if (reason && policy.mode === "warn") {
-        return {
-            allowed: true,
-            warning: buildPolicyWarning("violation", "extension", extension, reason),
-        };
+    const sandboxReason = resolvePolicySandboxReason(policy, extension);
+    if (sandboxReason) {
+        violations.push({ reason: sandboxReason, scope: "extension", mode: policy.mode });
     }
-    if (trustReason && policy.trustMode === "warn") {
-        return {
-            allowed: true,
-            warning: buildPolicyWarning("violation", "trust", extension, trustReason),
-        };
+    const enforced = violations.find((violation) => violation.mode === "enforce");
+    if (enforced) {
+        return { allowed: false, warning: buildPolicyWarning("blocked", enforced.scope, extension, enforced.reason) };
     }
-    if (sandboxReason && policy.mode === "warn") {
-        return {
-            allowed: true,
-            warning: buildPolicyWarning("violation", "extension", extension, sandboxReason),
-        };
+    const warned = violations.find((violation) => violation.mode === "warn");
+    if (warned) {
+        return { allowed: true, warning: buildPolicyWarning("violation", warned.scope, extension, warned.reason) };
     }
-    return {
-        allowed: true,
-        warning: null,
-    };
+    return { allowed: true, warning: null };
 }
 /**
  * Implements evaluate extension policy for capability for the public runtime surface of this module.
@@ -500,21 +488,25 @@ export function evaluateExtensionPolicyForCapability(policy, extension, capabili
     };
 }
 /**
- * Implements evaluate extension policy for registration for the public runtime surface of this module.
+ * Resolve the first applicable registration-policy reason for a surface
+ * registration, weighed in capability → surface → command → action → service
+ * precedence. Returns `null` when the registration violates no allow/block rule.
  */
-export function evaluateExtensionPolicyForRegistration(policy, extension, surface, method, capability, details) {
-    if (policy.mode === "off") {
-        return { allowed: true, warning: null };
-    }
+function resolveRegistrationPolicyReason(policy, extension, surface, capability, detail) {
     const capabilityReason = typeof capability === "string" ? resolvePolicyCapabilityReason(policy, extension, capability) : null;
     const surfaceReason = resolvePolicySurfaceReason(policy, extension, surface);
-    const commandReason = details?.command ? resolvePolicyCommandReason(policy, extension, details.command) : null;
-    const actionReason = details?.action ? resolvePolicyActionReason(policy, extension, details.action) : null;
-    const serviceReason = details?.service ? resolvePolicyServiceReason(policy, extension, details.service) : null;
-    const reason = capabilityReason ?? surfaceReason ?? commandReason ?? actionReason ?? serviceReason;
-    if (!reason) {
-        return { allowed: true, warning: null };
-    }
+    const commandReason = detail.command ? resolvePolicyCommandReason(policy, extension, detail.command) : null;
+    const actionReason = detail.action ? resolvePolicyActionReason(policy, extension, detail.action) : null;
+    const serviceReason = detail.service ? resolvePolicyServiceReason(policy, extension, detail.service) : null;
+    return capabilityReason ?? surfaceReason ?? commandReason ?? actionReason ?? serviceReason;
+}
+/**
+ * Build the detail token map attached to a registration-policy warning: the
+ * normalized method and surface plus whichever of capability/command/action/service
+ * the registration carries. {@link buildPolicyWarning} sorts and joins these into
+ * the warning's `key=value` suffix.
+ */
+function buildRegistrationPolicyWarningDetails(method, surface, capability, detail) {
     const warningDetails = {
         method: normalizePolicyName(method).replace(/\s+/g, "_"),
         surface,
@@ -522,20 +514,38 @@ export function evaluateExtensionPolicyForRegistration(policy, extension, surfac
     if (capability) {
         warningDetails.capability = capability;
     }
-    if (details?.command) {
-        warningDetails.command = normalizeCommandName(details.command);
+    if (detail.command) {
+        warningDetails.command = normalizeCommandName(detail.command);
+    }
+    if (detail.action) {
+        warningDetails.action = normalizePolicyName(detail.action).replace(/\s+/g, "-");
     }
-    if (details?.action) {
-        warningDetails.action = normalizePolicyName(details.action).replace(/\s+/g, "-");
+    if (detail.service) {
+        warningDetails.service = normalizePolicyName(detail.service);
     }
-    if (details?.service) {
-        warningDetails.service = normalizePolicyName(details.service);
+    return warningDetails;
+}
+/**
+ * Evaluate the governance policy for a single capability/surface registration an
+ * extension performs during activation. When `mode` is `off` the registration is
+ * always allowed; otherwise the first allow/block reason (capability → surface →
+ * command → action → service) blocks the registration under `enforce` or surfaces
+ * a non-blocking violation warning under `warn`.
+ */
+export function evaluateExtensionPolicyForRegistration(policy, extension, surface, method, capability, details) {
+    if (policy.mode === "off") {
+        return { allowed: true, warning: null };
+    }
+    const detail = details ?? {};
+    const reason = resolveRegistrationPolicyReason(policy, extension, surface, capability, detail);
+    if (!reason) {
+        return { allowed: true, warning: null };
     }
-    const warning = buildPolicyWarning(policy.mode === "warn" ? "violation" : "blocked", "registration", extension, reason, warningDetails);
+    const warning = buildPolicyWarning(policy.mode === "warn" ? "violation" : "blocked", "registration", extension, reason, buildRegistrationPolicyWarningDetails(method, surface, capability, detail));
     return {
         allowed: policy.mode === "warn",
         warning,
     };
 }
 //# sourceMappingURL=extension-policy.js.map
-//# debugId=34b7e8e0-c42f-50c2-9ee5-093565566cd7
+//# debugId=dbc43b74-6872-52c3-859a-64fe84c02b5b