@unbrained/pm-cli 2026.6.30 → 2026.7.2

package/dist/core/config/nested-settings.js

@@ -27,7 +27,7 @@
  * `pm config list` and in error hints.
  */
 
-!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]="439e5c08-5cff-56f0-a21d-15ffdb7afe94")}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]="b0ddd8ee-f289-5872-bce9-00b573abca7e")}catch(e){}}();
 export const NESTED_SETTING_DESCRIPTORS = [
     {
         key: "search_provider",
@@ -278,51 +278,39 @@ export function resolveNestedSettingDescriptor(raw) {
     }
     return DESCRIPTOR_BY_KEY.get(normalized);
 }
-/**
- * Validate and coerce a raw string value for a nested-leaf setting. The
- * returned value is the typed leaf that should be written into PmSettings.
- *
- * Empty strings are allowed for "string" leaves unless `non_empty` is set.
- */
-export function parseNestedSettingValue(descriptor, rawValue) {
-    if (typeof rawValue !== "string") {
-        return { ok: false, error: { message: `Config set ${descriptor.key} requires a string value` } };
+function parseNestedBooleanValue(descriptor, rawValue) {
+    const normalized = rawValue.trim().toLowerCase();
+    if (normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on") {
+        return { ok: true, parsed: { descriptor, value: true } };
     }
-    const trimmed = rawValue.trim();
-    if (descriptor.kind === "boolean") {
-        const normalized = trimmed.toLowerCase();
-        if (normalized === "true" || normalized === "1" || normalized === "yes" || normalized === "on") {
-            return { ok: true, parsed: { descriptor, value: true } };
-        }
-        if (normalized === "false" || normalized === "0" || normalized === "no" || normalized === "off") {
-            return { ok: true, parsed: { descriptor, value: false } };
-        }
+    if (normalized === "false" || normalized === "0" || normalized === "no" || normalized === "off") {
+        return { ok: true, parsed: { descriptor, value: false } };
+    }
+    return {
+        ok: false,
+        error: {
+            message: `Config set ${descriptor.key} requires a boolean value (true|false), got "${rawValue}"`,
+        },
+    };
+}
+function parseNestedStringValue(descriptor, rawValue, trimmed) {
+    if (descriptor.non_empty === true && trimmed.length === 0) {
+        return {
+            ok: false,
+            error: { message: `Config set ${descriptor.key} requires a non-empty value` },
+        };
+    }
+    if (descriptor.choices && !descriptor.choices.includes(trimmed)) {
         return {
             ok: false,
             error: {
-                message: `Config set ${descriptor.key} requires a boolean value (true|false), got "${rawValue}"`,
+                message: `Config set ${descriptor.key} must be one of ${descriptor.choices.join("|")}, got "${rawValue}"`,
             },
         };
     }
-    if (descriptor.kind === "string") {
-        if (descriptor.non_empty === true && trimmed.length === 0) {
-            return {
-                ok: false,
-                error: { message: `Config set ${descriptor.key} requires a non-empty value` },
-            };
-        }
-        if (descriptor.choices && !descriptor.choices.includes(trimmed)) {
-            return {
-                ok: false,
-                error: {
-                    message: `Config set ${descriptor.key} must be one of ${descriptor.choices.join("|")}, got "${rawValue}"`,
-                },
-            };
-        }
-        return { ok: true, parsed: { descriptor, value: trimmed } };
-    }
-    // Number("") === 0, which would silently accept empty / whitespace-only input
-    // as a valid zero. Reject explicitly so misconfigurations don't slip through.
+    return { ok: true, parsed: { descriptor, value: trimmed } };
+}
+function parseFiniteNestedNumber(descriptor, rawValue, trimmed) {
     if (trimmed.length === 0) {
         return {
             ok: false,
@@ -336,40 +324,74 @@ export function parseNestedSettingValue(descriptor, rawValue) {
             error: { message: `Config set ${descriptor.key} requires a finite number, got "${rawValue}"` },
         };
     }
-    if (descriptor.kind === "integer") {
-        if (!Number.isInteger(parsed) || parsed < 0) {
-            return {
-                ok: false,
-                error: { message: `Config set ${descriptor.key} requires a non-negative integer, got "${rawValue}"` },
-            };
-        }
-        if (descriptor.min !== undefined && parsed < descriptor.min) {
-            return {
-                ok: false,
-                error: {
-                    message: `Config set ${descriptor.key} requires an integer >= ${descriptor.min}, got "${rawValue}" (the runtime silently ignores 0 here and falls back to the default)`,
-                },
-            };
-        }
-        return { ok: true, parsed: { descriptor, value: parsed } };
+    return { ok: true, value: parsed };
+}
+function parseNestedIntegerValue(descriptor, rawValue, value) {
+    if (!Number.isInteger(value) || value < 0) {
+        return {
+            ok: false,
+            error: { message: `Config set ${descriptor.key} requires a non-negative integer, got "${rawValue}"` },
+        };
     }
-    if (descriptor.kind === "ratio") {
-        if (parsed < 0 || parsed > 1) {
-            return {
-                ok: false,
-                error: { message: `Config set ${descriptor.key} requires a number in [0, 1], got "${rawValue}"` },
-            };
-        }
-        return { ok: true, parsed: { descriptor, value: parsed } };
+    if (descriptor.min !== undefined && value < descriptor.min) {
+        return {
+            ok: false,
+            error: {
+                message: `Config set ${descriptor.key} requires an integer >= ${descriptor.min}, got "${rawValue}" (the runtime silently ignores 0 here and falls back to the default)`,
+            },
+        };
     }
-    // kind === "number" — negatives are allowed; only apply an explicit `min`.
-    if (descriptor.min !== undefined && parsed < descriptor.min) {
+    return { ok: true, parsed: { descriptor, value } };
+}
+function parseNestedRatioValue(descriptor, rawValue, value) {
+    if (value < 0 || value > 1) {
+        return {
+            ok: false,
+            error: { message: `Config set ${descriptor.key} requires a number in [0, 1], got "${rawValue}"` },
+        };
+    }
+    return { ok: true, parsed: { descriptor, value } };
+}
+function parseNestedNumberValue(descriptor, rawValue, value) {
+    if (descriptor.min !== undefined && value < descriptor.min) {
         return {
             ok: false,
             error: { message: `Config set ${descriptor.key} requires a number >= ${descriptor.min}, got "${rawValue}"` },
         };
     }
-    return { ok: true, parsed: { descriptor, value: parsed } };
+    return { ok: true, parsed: { descriptor, value } };
+}
+/**
+ * Validate and coerce a raw string value for a nested-leaf setting. The
+ * returned value is the typed leaf that should be written into PmSettings.
+ *
+ * Empty strings are allowed for "string" leaves unless `non_empty` is set.
+ */
+export function parseNestedSettingValue(descriptor, rawValue) {
+    if (typeof rawValue !== "string") {
+        return { ok: false, error: { message: `Config set ${descriptor.key} requires a string value` } };
+    }
+    const trimmed = rawValue.trim();
+    if (descriptor.kind === "boolean") {
+        return parseNestedBooleanValue(descriptor, rawValue);
+    }
+    if (descriptor.kind === "string") {
+        return parseNestedStringValue(descriptor, rawValue, trimmed);
+    }
+    // Number("") === 0, which would silently accept empty / whitespace-only input
+    // as a valid zero. Reject explicitly so misconfigurations don't slip through.
+    const parsed = parseFiniteNestedNumber(descriptor, rawValue, trimmed);
+    if (!parsed.ok) {
+        return { ok: false, error: parsed.error };
+    }
+    if (descriptor.kind === "integer") {
+        return parseNestedIntegerValue(descriptor, rawValue, parsed.value);
+    }
+    if (descriptor.kind === "ratio") {
+        return parseNestedRatioValue(descriptor, rawValue, parsed.value);
+    }
+    // kind === "number" — negatives are allowed; only apply an explicit `min`.
+    return parseNestedNumberValue(descriptor, rawValue, parsed.value);
 }
 /** Walk a dotted path on an arbitrary record (best-effort, returns null on miss). */
 export function readNestedSettingValue(settings, descriptor) {
@@ -415,4 +437,4 @@ export function writeNestedSettingValue(settings, descriptor, value) {
     return true;
 }
 //# sourceMappingURL=nested-settings.js.map
-//# debugId=439e5c08-5cff-56f0-a21d-15ffdb7afe94
+//# debugId=b0ddd8ee-f289-5872-bce9-00b573abca7e

package/dist/core/config/nested-settings.js.map

@@ -1 +1 @@
-{"version":3,"file":"nested-settings.js","sources":["core/config/nested-settings.ts"],"sourceRoot":"/","sourcesContent":["/**\n * Nested leaf settings exposed via `pm config <scope> set/get <key> <value>`.\n *\n * These are simple string/number leaves of {@link PmSettings} (provider URLs,\n * vector-store adapter, search tuning) that previously required hand-editing\n * `.agents/pm/settings.json`. They live here so the same dotted path is\n * documented in one place and surfaced both to the config dispatcher and to\n * `pm config list` (so `pm config list --json` is discoverable).\n *\n * Shape conventions:\n * - `path` is the dotted JSON path in {@link PmSettings} (e.g. `search.provider`).\n * - `kind` is the value shape: \"string\" | \"boolean\" | \"integer\" | \"number\" | \"ratio\"\n *   - \"ratio\" must be a finite number in [0, 1].\n *   - \"integer\" must be a finite non-negative integer. Set `min: 1` for keys\n *     where the runtime silently falls back when 0 is supplied (e.g. batch\n *     size, timeout, max-results limits).\n *   - \"number\" must be a finite number — negatives ARE allowed (e.g. score\n *     thresholds may legitimately be negative when a provider normalizes\n *     scores into a signed range).\n *\n * Adding a key here makes it acceptable to `pm config <scope> set <key> <value>`\n * with no other code changes — the dispatcher walks the dotted path on the\n * already-validated PmSettings shape.\n */\n\n/** Supported coercion shapes for nested settings exposed through `pm config`. */\nexport type NestedSettingKind = \"string\" | \"boolean\" | \"integer\" | \"number\" | \"ratio\";\n\n/**\n * Documents the nested setting descriptor payload exchanged by command, SDK, and package integrations.\n */\nexport interface NestedSettingDescriptor {\n  /** CLI key (snake_case). Kebab-case form is accepted by normalizing `-` → `_`. */\n  key: string;\n  /** Dotted JSON path in PmSettings. */\n  path: string;\n  /** Value shape. */\n  kind: NestedSettingKind;\n  /** Short human-facing summary for `pm config list`. */\n  summary: string;\n  /** Optional accepted values for string settings. */\n  choices?: readonly string[];\n  /** Require a non-empty trimmed string value for string settings. */\n  non_empty?: boolean;\n  /**\n   * Optional minimum value for `integer` / `number` kinds. When set,\n   * `parseNestedSettingValue` rejects values strictly below `min`. Useful for\n   * settings where 0 would be silently ignored by the runtime (batch sizes,\n   * timeouts, max-results limits).\n   */\n  min?: number;\n}\n\n/**\n * Search/provider/vector-store leaves. Order is the display order in\n * `pm config list` and in error hints.\n */\nexport const NESTED_SETTING_DESCRIPTORS: readonly NestedSettingDescriptor[] = [\n  {\n    key: \"search_provider\",\n    path: \"search.provider\",\n    kind: \"string\",\n    summary: \"Search embedding provider name (e.g. openai, ollama, or an extension provider).\",\n  },\n  {\n    key: \"search_mutation_refresh_policy\",\n    path: \"search.mutation_refresh_policy\",\n    kind: \"string\",\n    choices: [\"cache_only\", \"semantic_configured\", \"semantic_auto\"],\n    summary: \"Mutation-time search refresh policy: cache_only, semantic_configured, or semantic_auto.\",\n  },\n  {\n    key: \"search_query_expansion_enabled\",\n    path: \"search.query_expansion.enabled\",\n    kind: \"boolean\",\n    summary: \"Enable or disable query expansion for semantic/hybrid search.\",\n  },\n  {\n    key: \"search_query_expansion_provider\",\n    path: \"search.query_expansion.provider\",\n    kind: \"string\",\n    summary: \"Query expansion provider name (built-in openai/ollama or extension provider).\",\n  },\n  {\n    key: \"search_rerank_enabled\",\n    path: \"search.rerank.enabled\",\n    kind: \"boolean\",\n    summary: \"Enable or disable post-retrieval reranking for hybrid search.\",\n  },\n  {\n    key: \"search_rerank_model\",\n    path: \"search.rerank.model\",\n    kind: \"string\",\n    summary: \"Rerank model name override used by built-in providers.\",\n  },\n  {\n    key: \"search_rerank_top_k\",\n    path: \"search.rerank.top_k\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Number of top hybrid candidates to rerank when rerank is enabled.\",\n  },\n  {\n    key: \"search_embedding_model\",\n    path: \"search.embedding_model\",\n    kind: \"string\",\n    summary: \"Default embedding model name (overrides provider-specific model when set).\",\n  },\n  {\n    key: \"search_embedding_corpus_max_characters\",\n    path: \"search.embedding_corpus_max_characters\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Maximum semantic corpus characters per item before truncation.\",\n  },\n  {\n    key: \"search_embedding_batch_size\",\n    path: \"search.embedding_batch_size\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Number of items embedded per request batch.\",\n  },\n  {\n    key: \"search_embedding_timeout_ms\",\n    path: \"search.embedding_timeout_ms\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Per-request embedding timeout in milliseconds.\",\n  },\n  {\n    key: \"search_score_threshold\",\n    path: \"search.score_threshold\",\n    kind: \"number\",\n    summary: \"Minimum score for a hit to be returned (0 keeps all matches).\",\n  },\n  {\n    key: \"search_hybrid_semantic_weight\",\n    path: \"search.hybrid_semantic_weight\",\n    kind: \"ratio\",\n    summary: \"Hybrid mode semantic weight in [0, 1] (1-weight goes to keyword).\",\n  },\n  {\n    key: \"search_max_results\",\n    path: \"search.max_results\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Default upper bound on search hits when --limit is not supplied.\",\n  },\n  {\n    key: \"search_bm25_k1\",\n    path: \"search.bm25.k1\",\n    kind: \"number\",\n    min: 0,\n    summary: \"Offline BM25 term-frequency saturation (k1); higher saturates repeated terms slower (default 1.2).\",\n  },\n  {\n    key: \"search_bm25_b\",\n    path: \"search.bm25.b\",\n    kind: \"ratio\",\n    summary: \"Offline BM25 document-length normalization (b) in [0, 1]; 0 disables, 1 fully normalizes (default 0.75).\",\n  },\n  {\n    key: \"openai_base_url\",\n    path: \"providers.openai.base_url\",\n    kind: \"string\",\n    summary: \"OpenAI-compatible API base URL (LM Studio/vLLM also use this).\",\n  },\n  {\n    key: \"openai_api_key\",\n    path: \"providers.openai.api_key\",\n    kind: \"string\",\n    summary: \"OpenAI-compatible API key.\",\n  },\n  {\n    key: \"openai_model\",\n    path: \"providers.openai.model\",\n    kind: \"string\",\n    summary: \"OpenAI-compatible embedding model name.\",\n  },\n  {\n    key: \"ollama_base_url\",\n    path: \"providers.ollama.base_url\",\n    kind: \"string\",\n    summary: \"Ollama API base URL (typically http://localhost:11434).\",\n  },\n  {\n    key: \"ollama_model\",\n    path: \"providers.ollama.model\",\n    kind: \"string\",\n    summary: \"Ollama embedding model name (e.g. nomic-embed-text).\",\n  },\n  {\n    key: \"vector_store_adapter\",\n    path: \"vector_store.adapter\",\n    kind: \"string\",\n    summary: \"Vector store adapter name (lancedb, qdrant, or an extension adapter).\",\n  },\n  {\n    key: \"vector_store_collection_name\",\n    path: \"vector_store.collection_name\",\n    kind: \"string\",\n    non_empty: true,\n    summary: \"Vector collection/table name shared by Qdrant and LanceDB adapters.\",\n  },\n  {\n    key: \"qdrant_url\",\n    path: \"vector_store.qdrant.url\",\n    kind: \"string\",\n    summary: \"Qdrant HTTP API URL.\",\n  },\n  {\n    key: \"qdrant_api_key\",\n    path: \"vector_store.qdrant.api_key\",\n    kind: \"string\",\n    summary: \"Qdrant API key (empty if running unauthenticated).\",\n  },\n  {\n    key: \"lancedb_path\",\n    path: \"vector_store.lancedb.path\",\n    kind: \"string\",\n    summary: \"LanceDB storage path (relative to pm root or absolute).\",\n  },\n  // General workspace leaves (id/author/output/locks/schema governance). These\n  // are documented user-facing settings in CONFIGURATION.md that previously\n  // required hand-editing settings.json.\n  {\n    key: \"id_prefix\",\n    path: \"id_prefix\",\n    kind: \"string\",\n    non_empty: true,\n    summary: \"Prefix for generated item IDs (e.g. \\\"pm\\\" produces pm-xxxx).\",\n  },\n  {\n    key: \"author_default\",\n    path: \"author_default\",\n    kind: \"string\",\n    non_empty: true,\n    summary: \"Default author recorded on mutations when --author is not supplied.\",\n  },\n  {\n    key: \"output_default_format\",\n    path: \"output.default_format\",\n    kind: \"string\",\n    choices: [\"toon\", \"json\"],\n    summary: \"Default output format for commands that support it: toon or json.\",\n  },\n  {\n    key: \"locks_ttl_seconds\",\n    path: \"locks.ttl_seconds\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Claim/lock time-to-live in seconds before a stale lock can be reclaimed.\",\n  },\n  {\n    key: \"checkpoints_retention_days\",\n    path: \"checkpoints.retention_days\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Age in days above which pm gc --scope checkpoints prunes bulk-mutation rollback checkpoints.\",\n  },\n  {\n    key: \"schema_unknown_field_policy\",\n    path: \"schema.unknown_field_policy\",\n    kind: \"string\",\n    choices: [\"allow\", \"warn\", \"reject\"],\n    summary: \"How item I/O handles metadata keys not in the field registry: allow, warn, or reject.\",\n  },\n  // History compaction policy leaves (pm health advisory + pm history-compact\n  // bulk-sweep default threshold). Disabled by default; enabling makes large\n  // streams discoverable without a manual stats pass.\n  {\n    key: \"history_compact_policy_enabled\",\n    path: \"history.compact_policy.enabled\",\n    kind: \"boolean\",\n    summary: \"Enable the history-compaction advisory: pm health warns on over-threshold streams.\",\n  },\n  {\n    key: \"history_compact_policy_max_entries\",\n    path: \"history.compact_policy.max_entries\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Entry count above which a history stream is flagged (and the default pm history-compact --all-over threshold).\",\n  },\n  {\n    key: \"history_compact_policy_trigger\",\n    path: \"history.compact_policy.trigger\",\n    kind: \"string\",\n    choices: [\"health_warn\", \"auto\"],\n    summary: \"History-compaction policy intent: health_warn (advisory only) or auto (scheduled sweeps expected).\",\n  },\n];\n\nconst DESCRIPTOR_BY_KEY: ReadonlyMap<string, NestedSettingDescriptor> = new Map(\n  NESTED_SETTING_DESCRIPTORS.map((descriptor) => [descriptor.key, descriptor]),\n);\n\n/**\n * Map a raw user-supplied key (kebab or snake case, any casing) onto a known\n * nested-leaf descriptor. Returns `undefined` when the key is not a nested\n * leaf (callers can then fall back to the regular ConfigKey path).\n */\nexport function resolveNestedSettingDescriptor(raw: string | undefined): NestedSettingDescriptor | undefined {\n  if (typeof raw !== \"string\") {\n    return undefined;\n  }\n  const normalized = raw.trim().toLowerCase().replaceAll(\"-\", \"_\");\n  if (normalized.length === 0) {\n    return undefined;\n  }\n  return DESCRIPTOR_BY_KEY.get(normalized);\n}\n\n/** Recoverable parsed value with the descriptor it satisfied. */\nexport interface NestedSettingParsedValue {\n  descriptor: NestedSettingDescriptor;\n  value: string | number | boolean;\n}\n\n/** Throwable validation error returned as a structured result. */\nexport interface NestedSettingParseError {\n  message: string;\n}\n\n/**\n * Restricts nested setting parse result values accepted by command, SDK, and storage contracts.\n */\nexport type NestedSettingParseResult =\n  | { ok: true; parsed: NestedSettingParsedValue }\n  | { ok: false; error: NestedSettingParseError };\n\n/**\n * Validate and coerce a raw string value for a nested-leaf setting. The\n * returned value is the typed leaf that should be written into PmSettings.\n *\n * Empty strings are allowed for \"string\" leaves unless `non_empty` is set.\n */\nexport function parseNestedSettingValue(\n  descriptor: NestedSettingDescriptor,\n  rawValue: string,\n): NestedSettingParseResult {\n  if (typeof rawValue !== \"string\") {\n    return { ok: false, error: { message: `Config set ${descriptor.key} requires a string value` } };\n  }\n  const trimmed = rawValue.trim();\n  if (descriptor.kind === \"boolean\") {\n    const normalized = trimmed.toLowerCase();\n    if (normalized === \"true\" || normalized === \"1\" || normalized === \"yes\" || normalized === \"on\") {\n      return { ok: true, parsed: { descriptor, value: true } };\n    }\n    if (normalized === \"false\" || normalized === \"0\" || normalized === \"no\" || normalized === \"off\") {\n      return { ok: true, parsed: { descriptor, value: false } };\n    }\n    return {\n      ok: false,\n      error: {\n        message: `Config set ${descriptor.key} requires a boolean value (true|false), got \"${rawValue}\"`,\n      },\n    };\n  }\n  if (descriptor.kind === \"string\") {\n    if (descriptor.non_empty === true && trimmed.length === 0) {\n      return {\n        ok: false,\n        error: { message: `Config set ${descriptor.key} requires a non-empty value` },\n      };\n    }\n    if (descriptor.choices && !descriptor.choices.includes(trimmed)) {\n      return {\n        ok: false,\n        error: {\n          message: `Config set ${descriptor.key} must be one of ${descriptor.choices.join(\"|\")}, got \"${rawValue}\"`,\n        },\n      };\n    }\n    return { ok: true, parsed: { descriptor, value: trimmed } };\n  }\n\n  // Number(\"\") === 0, which would silently accept empty / whitespace-only input\n  // as a valid zero. Reject explicitly so misconfigurations don't slip through.\n  if (trimmed.length === 0) {\n    return {\n      ok: false,\n      error: { message: `Config set ${descriptor.key} requires a non-empty value` },\n    };\n  }\n\n  const parsed = Number(trimmed);\n  if (!Number.isFinite(parsed)) {\n    return {\n      ok: false,\n      error: { message: `Config set ${descriptor.key} requires a finite number, got \"${rawValue}\"` },\n    };\n  }\n  if (descriptor.kind === \"integer\") {\n    if (!Number.isInteger(parsed) || parsed < 0) {\n      return {\n        ok: false,\n        error: { message: `Config set ${descriptor.key} requires a non-negative integer, got \"${rawValue}\"` },\n      };\n    }\n    if (descriptor.min !== undefined && parsed < descriptor.min) {\n      return {\n        ok: false,\n        error: {\n          message: `Config set ${descriptor.key} requires an integer >= ${descriptor.min}, got \"${rawValue}\" (the runtime silently ignores 0 here and falls back to the default)`,\n        },\n      };\n    }\n    return { ok: true, parsed: { descriptor, value: parsed } };\n  }\n  if (descriptor.kind === \"ratio\") {\n    if (parsed < 0 || parsed > 1) {\n      return {\n        ok: false,\n        error: { message: `Config set ${descriptor.key} requires a number in [0, 1], got \"${rawValue}\"` },\n      };\n    }\n    return { ok: true, parsed: { descriptor, value: parsed } };\n  }\n  // kind === \"number\" — negatives are allowed; only apply an explicit `min`.\n  if (descriptor.min !== undefined && parsed < descriptor.min) {\n    return {\n      ok: false,\n      error: { message: `Config set ${descriptor.key} requires a number >= ${descriptor.min}, got \"${rawValue}\"` },\n    };\n  }\n  return { ok: true, parsed: { descriptor, value: parsed } };\n}\n\n/** Walk a dotted path on an arbitrary record (best-effort, returns null on miss). */\nexport function readNestedSettingValue(\n  settings: unknown,\n  descriptor: NestedSettingDescriptor,\n): string | number | boolean | null {\n  const segments = descriptor.path.split(\".\");\n  let cursor: unknown = settings;\n  for (const segment of segments) {\n    if (typeof cursor !== \"object\" || cursor === null) {\n      return null;\n    }\n    cursor = (cursor as Record<string, unknown>)[segment];\n  }\n  if (typeof cursor === \"string\" || typeof cursor === \"number\" || typeof cursor === \"boolean\") {\n    return cursor;\n  }\n  return null;\n}\n\n/**\n * Set a leaf value on a settings object by walking the descriptor's dotted\n * path. Missing intermediate objects are created. Returns `true` when the\n * value actually changed.\n */\nexport function writeNestedSettingValue(\n  settings: Record<string, unknown>,\n  descriptor: NestedSettingDescriptor,\n  value: string | number | boolean,\n): boolean {\n  const segments = descriptor.path.split(\".\");\n  let cursor: Record<string, unknown> = settings;\n  for (let index = 0; index < segments.length - 1; index += 1) {\n    const segment = segments[index];\n    const existing = cursor[segment];\n    if (typeof existing !== \"object\" || existing === null || Array.isArray(existing)) {\n      const next: Record<string, unknown> = {};\n      cursor[segment] = next;\n      cursor = next;\n    } else {\n      cursor = existing as Record<string, unknown>;\n    }\n  }\n  const leafKey = segments[segments.length - 1];\n  const previous = cursor[leafKey];\n  if (previous === value) {\n    return false;\n  }\n  cursor[leafKey] = value;\n  return true;\n}\n"],"names":[],"mappings":"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","debugId":"439e5c08-5cff-56f0-a21d-15ffdb7afe94"}
+{"version":3,"file":"nested-settings.js","sources":["core/config/nested-settings.ts"],"sourceRoot":"/","sourcesContent":["/**\n * Nested leaf settings exposed via `pm config <scope> set/get <key> <value>`.\n *\n * These are simple string/number leaves of {@link PmSettings} (provider URLs,\n * vector-store adapter, search tuning) that previously required hand-editing\n * `.agents/pm/settings.json`. They live here so the same dotted path is\n * documented in one place and surfaced both to the config dispatcher and to\n * `pm config list` (so `pm config list --json` is discoverable).\n *\n * Shape conventions:\n * - `path` is the dotted JSON path in {@link PmSettings} (e.g. `search.provider`).\n * - `kind` is the value shape: \"string\" | \"boolean\" | \"integer\" | \"number\" | \"ratio\"\n *   - \"ratio\" must be a finite number in [0, 1].\n *   - \"integer\" must be a finite non-negative integer. Set `min: 1` for keys\n *     where the runtime silently falls back when 0 is supplied (e.g. batch\n *     size, timeout, max-results limits).\n *   - \"number\" must be a finite number — negatives ARE allowed (e.g. score\n *     thresholds may legitimately be negative when a provider normalizes\n *     scores into a signed range).\n *\n * Adding a key here makes it acceptable to `pm config <scope> set <key> <value>`\n * with no other code changes — the dispatcher walks the dotted path on the\n * already-validated PmSettings shape.\n */\n\n/** Supported coercion shapes for nested settings exposed through `pm config`. */\nexport type NestedSettingKind = \"string\" | \"boolean\" | \"integer\" | \"number\" | \"ratio\";\n\n/**\n * Documents the nested setting descriptor payload exchanged by command, SDK, and package integrations.\n */\nexport interface NestedSettingDescriptor {\n  /** CLI key (snake_case). Kebab-case form is accepted by normalizing `-` → `_`. */\n  key: string;\n  /** Dotted JSON path in PmSettings. */\n  path: string;\n  /** Value shape. */\n  kind: NestedSettingKind;\n  /** Short human-facing summary for `pm config list`. */\n  summary: string;\n  /** Optional accepted values for string settings. */\n  choices?: readonly string[];\n  /** Require a non-empty trimmed string value for string settings. */\n  non_empty?: boolean;\n  /**\n   * Optional minimum value for `integer` / `number` kinds. When set,\n   * `parseNestedSettingValue` rejects values strictly below `min`. Useful for\n   * settings where 0 would be silently ignored by the runtime (batch sizes,\n   * timeouts, max-results limits).\n   */\n  min?: number;\n}\n\n/**\n * Search/provider/vector-store leaves. Order is the display order in\n * `pm config list` and in error hints.\n */\nexport const NESTED_SETTING_DESCRIPTORS: readonly NestedSettingDescriptor[] = [\n  {\n    key: \"search_provider\",\n    path: \"search.provider\",\n    kind: \"string\",\n    summary: \"Search embedding provider name (e.g. openai, ollama, or an extension provider).\",\n  },\n  {\n    key: \"search_mutation_refresh_policy\",\n    path: \"search.mutation_refresh_policy\",\n    kind: \"string\",\n    choices: [\"cache_only\", \"semantic_configured\", \"semantic_auto\"],\n    summary: \"Mutation-time search refresh policy: cache_only, semantic_configured, or semantic_auto.\",\n  },\n  {\n    key: \"search_query_expansion_enabled\",\n    path: \"search.query_expansion.enabled\",\n    kind: \"boolean\",\n    summary: \"Enable or disable query expansion for semantic/hybrid search.\",\n  },\n  {\n    key: \"search_query_expansion_provider\",\n    path: \"search.query_expansion.provider\",\n    kind: \"string\",\n    summary: \"Query expansion provider name (built-in openai/ollama or extension provider).\",\n  },\n  {\n    key: \"search_rerank_enabled\",\n    path: \"search.rerank.enabled\",\n    kind: \"boolean\",\n    summary: \"Enable or disable post-retrieval reranking for hybrid search.\",\n  },\n  {\n    key: \"search_rerank_model\",\n    path: \"search.rerank.model\",\n    kind: \"string\",\n    summary: \"Rerank model name override used by built-in providers.\",\n  },\n  {\n    key: \"search_rerank_top_k\",\n    path: \"search.rerank.top_k\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Number of top hybrid candidates to rerank when rerank is enabled.\",\n  },\n  {\n    key: \"search_embedding_model\",\n    path: \"search.embedding_model\",\n    kind: \"string\",\n    summary: \"Default embedding model name (overrides provider-specific model when set).\",\n  },\n  {\n    key: \"search_embedding_corpus_max_characters\",\n    path: \"search.embedding_corpus_max_characters\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Maximum semantic corpus characters per item before truncation.\",\n  },\n  {\n    key: \"search_embedding_batch_size\",\n    path: \"search.embedding_batch_size\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Number of items embedded per request batch.\",\n  },\n  {\n    key: \"search_embedding_timeout_ms\",\n    path: \"search.embedding_timeout_ms\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Per-request embedding timeout in milliseconds.\",\n  },\n  {\n    key: \"search_score_threshold\",\n    path: \"search.score_threshold\",\n    kind: \"number\",\n    summary: \"Minimum score for a hit to be returned (0 keeps all matches).\",\n  },\n  {\n    key: \"search_hybrid_semantic_weight\",\n    path: \"search.hybrid_semantic_weight\",\n    kind: \"ratio\",\n    summary: \"Hybrid mode semantic weight in [0, 1] (1-weight goes to keyword).\",\n  },\n  {\n    key: \"search_max_results\",\n    path: \"search.max_results\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Default upper bound on search hits when --limit is not supplied.\",\n  },\n  {\n    key: \"search_bm25_k1\",\n    path: \"search.bm25.k1\",\n    kind: \"number\",\n    min: 0,\n    summary: \"Offline BM25 term-frequency saturation (k1); higher saturates repeated terms slower (default 1.2).\",\n  },\n  {\n    key: \"search_bm25_b\",\n    path: \"search.bm25.b\",\n    kind: \"ratio\",\n    summary: \"Offline BM25 document-length normalization (b) in [0, 1]; 0 disables, 1 fully normalizes (default 0.75).\",\n  },\n  {\n    key: \"openai_base_url\",\n    path: \"providers.openai.base_url\",\n    kind: \"string\",\n    summary: \"OpenAI-compatible API base URL (LM Studio/vLLM also use this).\",\n  },\n  {\n    key: \"openai_api_key\",\n    path: \"providers.openai.api_key\",\n    kind: \"string\",\n    summary: \"OpenAI-compatible API key.\",\n  },\n  {\n    key: \"openai_model\",\n    path: \"providers.openai.model\",\n    kind: \"string\",\n    summary: \"OpenAI-compatible embedding model name.\",\n  },\n  {\n    key: \"ollama_base_url\",\n    path: \"providers.ollama.base_url\",\n    kind: \"string\",\n    summary: \"Ollama API base URL (typically http://localhost:11434).\",\n  },\n  {\n    key: \"ollama_model\",\n    path: \"providers.ollama.model\",\n    kind: \"string\",\n    summary: \"Ollama embedding model name (e.g. nomic-embed-text).\",\n  },\n  {\n    key: \"vector_store_adapter\",\n    path: \"vector_store.adapter\",\n    kind: \"string\",\n    summary: \"Vector store adapter name (lancedb, qdrant, or an extension adapter).\",\n  },\n  {\n    key: \"vector_store_collection_name\",\n    path: \"vector_store.collection_name\",\n    kind: \"string\",\n    non_empty: true,\n    summary: \"Vector collection/table name shared by Qdrant and LanceDB adapters.\",\n  },\n  {\n    key: \"qdrant_url\",\n    path: \"vector_store.qdrant.url\",\n    kind: \"string\",\n    summary: \"Qdrant HTTP API URL.\",\n  },\n  {\n    key: \"qdrant_api_key\",\n    path: \"vector_store.qdrant.api_key\",\n    kind: \"string\",\n    summary: \"Qdrant API key (empty if running unauthenticated).\",\n  },\n  {\n    key: \"lancedb_path\",\n    path: \"vector_store.lancedb.path\",\n    kind: \"string\",\n    summary: \"LanceDB storage path (relative to pm root or absolute).\",\n  },\n  // General workspace leaves (id/author/output/locks/schema governance). These\n  // are documented user-facing settings in CONFIGURATION.md that previously\n  // required hand-editing settings.json.\n  {\n    key: \"id_prefix\",\n    path: \"id_prefix\",\n    kind: \"string\",\n    non_empty: true,\n    summary: \"Prefix for generated item IDs (e.g. \\\"pm\\\" produces pm-xxxx).\",\n  },\n  {\n    key: \"author_default\",\n    path: \"author_default\",\n    kind: \"string\",\n    non_empty: true,\n    summary: \"Default author recorded on mutations when --author is not supplied.\",\n  },\n  {\n    key: \"output_default_format\",\n    path: \"output.default_format\",\n    kind: \"string\",\n    choices: [\"toon\", \"json\"],\n    summary: \"Default output format for commands that support it: toon or json.\",\n  },\n  {\n    key: \"locks_ttl_seconds\",\n    path: \"locks.ttl_seconds\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Claim/lock time-to-live in seconds before a stale lock can be reclaimed.\",\n  },\n  {\n    key: \"checkpoints_retention_days\",\n    path: \"checkpoints.retention_days\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Age in days above which pm gc --scope checkpoints prunes bulk-mutation rollback checkpoints.\",\n  },\n  {\n    key: \"schema_unknown_field_policy\",\n    path: \"schema.unknown_field_policy\",\n    kind: \"string\",\n    choices: [\"allow\", \"warn\", \"reject\"],\n    summary: \"How item I/O handles metadata keys not in the field registry: allow, warn, or reject.\",\n  },\n  // History compaction policy leaves (pm health advisory + pm history-compact\n  // bulk-sweep default threshold). Disabled by default; enabling makes large\n  // streams discoverable without a manual stats pass.\n  {\n    key: \"history_compact_policy_enabled\",\n    path: \"history.compact_policy.enabled\",\n    kind: \"boolean\",\n    summary: \"Enable the history-compaction advisory: pm health warns on over-threshold streams.\",\n  },\n  {\n    key: \"history_compact_policy_max_entries\",\n    path: \"history.compact_policy.max_entries\",\n    kind: \"integer\",\n    min: 1,\n    summary: \"Entry count above which a history stream is flagged (and the default pm history-compact --all-over threshold).\",\n  },\n  {\n    key: \"history_compact_policy_trigger\",\n    path: \"history.compact_policy.trigger\",\n    kind: \"string\",\n    choices: [\"health_warn\", \"auto\"],\n    summary: \"History-compaction policy intent: health_warn (advisory only) or auto (scheduled sweeps expected).\",\n  },\n];\n\nconst DESCRIPTOR_BY_KEY: ReadonlyMap<string, NestedSettingDescriptor> = new Map(\n  NESTED_SETTING_DESCRIPTORS.map((descriptor) => [descriptor.key, descriptor]),\n);\n\n/**\n * Map a raw user-supplied key (kebab or snake case, any casing) onto a known\n * nested-leaf descriptor. Returns `undefined` when the key is not a nested\n * leaf (callers can then fall back to the regular ConfigKey path).\n */\nexport function resolveNestedSettingDescriptor(raw: string | undefined): NestedSettingDescriptor | undefined {\n  if (typeof raw !== \"string\") {\n    return undefined;\n  }\n  const normalized = raw.trim().toLowerCase().replaceAll(\"-\", \"_\");\n  if (normalized.length === 0) {\n    return undefined;\n  }\n  return DESCRIPTOR_BY_KEY.get(normalized);\n}\n\n/** Recoverable parsed value with the descriptor it satisfied. */\nexport interface NestedSettingParsedValue {\n  descriptor: NestedSettingDescriptor;\n  value: string | number | boolean;\n}\n\n/** Throwable validation error returned as a structured result. */\nexport interface NestedSettingParseError {\n  message: string;\n}\n\n/**\n * Restricts nested setting parse result values accepted by command, SDK, and storage contracts.\n */\nexport type NestedSettingParseResult =\n  | { ok: true; parsed: NestedSettingParsedValue }\n  | { ok: false; error: NestedSettingParseError };\n\nfunction parseNestedBooleanValue(descriptor: NestedSettingDescriptor, rawValue: string): NestedSettingParseResult {\n  const normalized = rawValue.trim().toLowerCase();\n  if (normalized === \"true\" || normalized === \"1\" || normalized === \"yes\" || normalized === \"on\") {\n    return { ok: true, parsed: { descriptor, value: true } };\n  }\n  if (normalized === \"false\" || normalized === \"0\" || normalized === \"no\" || normalized === \"off\") {\n    return { ok: true, parsed: { descriptor, value: false } };\n  }\n  return {\n    ok: false,\n    error: {\n      message: `Config set ${descriptor.key} requires a boolean value (true|false), got \"${rawValue}\"`,\n    },\n  };\n}\n\nfunction parseNestedStringValue(\n  descriptor: NestedSettingDescriptor,\n  rawValue: string,\n  trimmed: string,\n): NestedSettingParseResult {\n  if (descriptor.non_empty === true && trimmed.length === 0) {\n    return {\n      ok: false,\n      error: { message: `Config set ${descriptor.key} requires a non-empty value` },\n    };\n  }\n  if (descriptor.choices && !descriptor.choices.includes(trimmed)) {\n    return {\n      ok: false,\n      error: {\n        message: `Config set ${descriptor.key} must be one of ${descriptor.choices.join(\"|\")}, got \"${rawValue}\"`,\n      },\n    };\n  }\n  return { ok: true, parsed: { descriptor, value: trimmed } };\n}\n\nfunction parseFiniteNestedNumber(\n  descriptor: NestedSettingDescriptor,\n  rawValue: string,\n  trimmed: string,\n): { ok: true; value: number } | { ok: false; error: NestedSettingParseError } {\n  if (trimmed.length === 0) {\n    return {\n      ok: false,\n      error: { message: `Config set ${descriptor.key} requires a non-empty value` },\n    };\n  }\n  const parsed = Number(trimmed);\n  if (!Number.isFinite(parsed)) {\n    return {\n      ok: false,\n      error: { message: `Config set ${descriptor.key} requires a finite number, got \"${rawValue}\"` },\n    };\n  }\n  return { ok: true, value: parsed };\n}\n\nfunction parseNestedIntegerValue(\n  descriptor: NestedSettingDescriptor,\n  rawValue: string,\n  value: number,\n): NestedSettingParseResult {\n  if (!Number.isInteger(value) || value < 0) {\n    return {\n      ok: false,\n      error: { message: `Config set ${descriptor.key} requires a non-negative integer, got \"${rawValue}\"` },\n    };\n  }\n  if (descriptor.min !== undefined && value < descriptor.min) {\n    return {\n      ok: false,\n      error: {\n        message: `Config set ${descriptor.key} requires an integer >= ${descriptor.min}, got \"${rawValue}\" (the runtime silently ignores 0 here and falls back to the default)`,\n      },\n    };\n  }\n  return { ok: true, parsed: { descriptor, value } };\n}\n\nfunction parseNestedRatioValue(\n  descriptor: NestedSettingDescriptor,\n  rawValue: string,\n  value: number,\n): NestedSettingParseResult {\n  if (value < 0 || value > 1) {\n    return {\n      ok: false,\n      error: { message: `Config set ${descriptor.key} requires a number in [0, 1], got \"${rawValue}\"` },\n    };\n  }\n  return { ok: true, parsed: { descriptor, value } };\n}\n\nfunction parseNestedNumberValue(\n  descriptor: NestedSettingDescriptor,\n  rawValue: string,\n  value: number,\n): NestedSettingParseResult {\n  if (descriptor.min !== undefined && value < descriptor.min) {\n    return {\n      ok: false,\n      error: { message: `Config set ${descriptor.key} requires a number >= ${descriptor.min}, got \"${rawValue}\"` },\n    };\n  }\n  return { ok: true, parsed: { descriptor, value } };\n}\n\n/**\n * Validate and coerce a raw string value for a nested-leaf setting. The\n * returned value is the typed leaf that should be written into PmSettings.\n *\n * Empty strings are allowed for \"string\" leaves unless `non_empty` is set.\n */\nexport function parseNestedSettingValue(\n  descriptor: NestedSettingDescriptor,\n  rawValue: string,\n): NestedSettingParseResult {\n  if (typeof rawValue !== \"string\") {\n    return { ok: false, error: { message: `Config set ${descriptor.key} requires a string value` } };\n  }\n  const trimmed = rawValue.trim();\n  if (descriptor.kind === \"boolean\") {\n    return parseNestedBooleanValue(descriptor, rawValue);\n  }\n  if (descriptor.kind === \"string\") {\n    return parseNestedStringValue(descriptor, rawValue, trimmed);\n  }\n\n  // Number(\"\") === 0, which would silently accept empty / whitespace-only input\n  // as a valid zero. Reject explicitly so misconfigurations don't slip through.\n  const parsed = parseFiniteNestedNumber(descriptor, rawValue, trimmed);\n  if (!parsed.ok) {\n    return { ok: false, error: parsed.error };\n  }\n  if (descriptor.kind === \"integer\") {\n    return parseNestedIntegerValue(descriptor, rawValue, parsed.value);\n  }\n  if (descriptor.kind === \"ratio\") {\n    return parseNestedRatioValue(descriptor, rawValue, parsed.value);\n  }\n  // kind === \"number\" — negatives are allowed; only apply an explicit `min`.\n  return parseNestedNumberValue(descriptor, rawValue, parsed.value);\n}\n\n/** Walk a dotted path on an arbitrary record (best-effort, returns null on miss). */\nexport function readNestedSettingValue(\n  settings: unknown,\n  descriptor: NestedSettingDescriptor,\n): string | number | boolean | null {\n  const segments = descriptor.path.split(\".\");\n  let cursor: unknown = settings;\n  for (const segment of segments) {\n    if (typeof cursor !== \"object\" || cursor === null) {\n      return null;\n    }\n    cursor = (cursor as Record<string, unknown>)[segment];\n  }\n  if (typeof cursor === \"string\" || typeof cursor === \"number\" || typeof cursor === \"boolean\") {\n    return cursor;\n  }\n  return null;\n}\n\n/**\n * Set a leaf value on a settings object by walking the descriptor's dotted\n * path. Missing intermediate objects are created. Returns `true` when the\n * value actually changed.\n */\nexport function writeNestedSettingValue(\n  settings: Record<string, unknown>,\n  descriptor: NestedSettingDescriptor,\n  value: string | number | boolean,\n): boolean {\n  const segments = descriptor.path.split(\".\");\n  let cursor: Record<string, unknown> = settings;\n  for (let index = 0; index < segments.length - 1; index += 1) {\n    const segment = segments[index];\n    const existing = cursor[segment];\n    if (typeof existing !== \"object\" || existing === null || Array.isArray(existing)) {\n      const next: Record<string, unknown> = {};\n      cursor[segment] = next;\n      cursor = next;\n    } else {\n      cursor = existing as Record<string, unknown>;\n    }\n  }\n  const leafKey = segments[segments.length - 1];\n  const previous = cursor[leafKey];\n  if (previous === value) {\n    return false;\n  }\n  cursor[leafKey] = value;\n  return true;\n}\n"],"names":[],"mappings":"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","debugId":"b0ddd8ee-f289-5872-bce9-00b573abca7e"}

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;