@unbrained/pm-cli 2026.6.19 → 2026.6.20

package/dist/core/checkpoint/checkpoint-gc.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @module core/checkpoint/checkpoint-gc
+ *
+ * Age-based garbage collector for bulk-mutation rollback checkpoints written by
+ * `update-many`/`close-many` under `checkpoints/<subdir>/<id>.json`.
+ *
+ * Safety-first policy (mirroring the stale-lock sweep in `lock/lock-gc.ts`): a
+ * checkpoint whose JSON cannot be read or whose `created_at` cannot be parsed is
+ * RETAINED rather than deleted. We only prune checkpoints whose age can be
+ * conclusively determined from their own `created_at` field and that exceed the
+ * configured `checkpoints.retention_days` policy.
+ *
+ * Staleness formula: (now_ms - Date.parse(created_at)) > retention_days * 86_400_000.
+ * A zero/negative age (a future `created_at`) is always treated as active.
+ */
+/**
+ * Documents the checkpoint gc scan entry payload exchanged by command, SDK, and package integrations.
+ */
+export interface CheckpointGcEntry {
+    /** Relative path like "checkpoints/update-many/update-many-20260619-abc123.json". */
+    file: string;
+    /** Parsed `created_at`, or null when missing/unparseable. */
+    created_at: string | null;
+    /** floor((now - created_at)/1000), null when unparseable. */
+    age_seconds: number | null;
+    /** True only when classified as expired (older than the retention window). */
+    stale: boolean;
+    reason: "expired" | "active" | "unparseable";
+}
+/**
+ * Documents the checkpoint gc hooks payload exchanged by command, SDK, and package integrations.
+ */
+export interface CheckpointGcHooks {
+    onRead?: (checkpointPath: string) => Promise<string[]> | string[];
+    onWrite?: (checkpointPath: string) => Promise<string[]> | string[];
+}
+/**
+ * Documents the checkpoint gc options payload exchanged by command, SDK, and package integrations.
+ */
+export interface CheckpointGcOptions {
+    dryRun: boolean;
+    /**
+     * Prune checkpoints older than this many days. Negative values are clamped to
+     * zero (prune everything aged); a non-finite value (NaN/Infinity) disables
+     * pruning entirely so bad input never deletes recoverable checkpoints.
+     */
+    retentionDays: number;
+    /** Epoch ms; defaults to Date.now() — injectable for deterministic tests. */
+    now?: number;
+    hooks?: CheckpointGcHooks;
+}
+/**
+ * Documents the checkpoint gc result payload exchanged by command, SDK, and package integrations.
+ */
+export interface CheckpointGcResult {
+    /** Number of *.json checkpoint files examined. */
+    scanned: number;
+    /** Relative paths removed (or would-remove under dryRun), sorted by file name asc. */
+    removed: string[];
+    /** Relative paths retained (active OR unparseable — never delete what we can't reason about). */
+    retained: string[];
+    warnings: string[];
+    /** One per scanned checkpoint file, sorted by file name asc. */
+    entries: CheckpointGcEntry[];
+}
+/**
+ * Implements run checkpoint gc for the public runtime surface of this module.
+ */
+export declare function runCheckpointGc(pmRoot: string, options: CheckpointGcOptions): Promise<CheckpointGcResult>;

package/dist/core/checkpoint/checkpoint-gc.js

@@ -0,0 +1,175 @@
+/**
+ * @module core/checkpoint/checkpoint-gc
+ *
+ * Age-based garbage collector for bulk-mutation rollback checkpoints written by
+ * `update-many`/`close-many` under `checkpoints/<subdir>/<id>.json`.
+ *
+ * Safety-first policy (mirroring the stale-lock sweep in `lock/lock-gc.ts`): a
+ * checkpoint whose JSON cannot be read or whose `created_at` cannot be parsed is
+ * RETAINED rather than deleted. We only prune checkpoints whose age can be
+ * conclusively determined from their own `created_at` field and that exceed the
+ * configured `checkpoints.retention_days` policy.
+ *
+ * Staleness formula: (now_ms - Date.parse(created_at)) > retention_days * 86_400_000.
+ * A zero/negative age (a future `created_at`) is always treated as active.
+ */
+
+!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]="83dc8421-d6b4-5ef6-ac77-bfca9e10ffb1")}catch(e){}}();
+import fs from "node:fs/promises";
+import path from "node:path";
+const MILLISECONDS_PER_DAY = 86_400_000;
+function isErrno(error, code) {
+    return (typeof error === "object" && error !== null && "code" in error && error.code === code);
+}
+/** Extract a parseable `created_at` from a checkpoint's raw JSON, or null. */
+function readCheckpointCreatedAt(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    const createdAt = parsed.created_at;
+    return typeof createdAt === "string" ? createdAt : null;
+}
+/**
+ * Collect relative `checkpoints/<subdir>/<file>.json` (and top-level `<file>.json`)
+ * paths under the checkpoints root. Subdirectory reads are resilient to
+ * concurrent races: a subdir that vanishes between the parent `readdir` and its
+ * own `readdir` (ENOENT) is skipped quietly, and any other read failure (e.g. a
+ * permission error) is surfaced as a `checkpoint_subdir_unreadable:<name>`
+ * warning rather than aborting the whole sweep.
+ */
+async function collectCheckpointFiles(checkpointsDir, warnings) {
+    let dirEntries;
+    try {
+        dirEntries = await fs.readdir(checkpointsDir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            return [];
+        }
+        throw error;
+    }
+    const files = [];
+    for (const entry of dirEntries) {
+        if (entry.isDirectory()) {
+            const subdir = path.join(checkpointsDir, entry.name);
+            let nested;
+            try {
+                nested = await fs.readdir(subdir);
+            }
+            catch (error) {
+                if (!isErrno(error, "ENOENT")) {
+                    warnings.push(`checkpoint_subdir_unreadable:${entry.name}`);
+                }
+                continue;
+            }
+            for (const file of nested) {
+                if (file.endsWith(".json")) {
+                    files.push(`${entry.name}/${file}`);
+                }
+            }
+        }
+        else if (entry.name.endsWith(".json")) {
+            files.push(entry.name);
+        }
+    }
+    return files.sort();
+}
+/**
+ * Implements run checkpoint gc for the public runtime surface of this module.
+ */
+export async function runCheckpointGc(pmRoot, options) {
+    const { dryRun, hooks } = options;
+    const nowMs = options.now ?? Date.now();
+    const retentionMs = Math.max(0, options.retentionDays) * MILLISECONDS_PER_DAY;
+    const checkpointsDir = path.join(pmRoot, "checkpoints");
+    // A non-finite retentionMs (NaN/Infinity from a non-finite retentionDays)
+    // makes every `ageMs > retentionMs` comparison false, so nothing is pruned —
+    // pruning is disabled rather than risking deletion under bad input.
+    const result = {
+        scanned: 0,
+        removed: [],
+        retained: [],
+        warnings: [],
+        entries: [],
+    };
+    const files = await collectCheckpointFiles(checkpointsDir, result.warnings);
+    for (const relName of files) {
+        const absPath = path.join(checkpointsDir, relName);
+        const relPath = `checkpoints/${relName}`;
+        result.scanned += 1;
+        if (hooks?.onRead) {
+            result.warnings.push(...(await hooks.onRead(absPath)));
+        }
+        let raw;
+        try {
+            raw = await fs.readFile(absPath, "utf8");
+        }
+        catch (readError) {
+            if (isErrno(readError, "ENOENT")) {
+                // Disappeared between readdir and readFile — treat as a ghost; skip quietly.
+                result.scanned -= 1;
+                continue;
+            }
+            result.warnings.push(`checkpoint_unreadable:${relName}`);
+            result.retained.push(relPath);
+            result.entries.push({ file: relPath, created_at: null, age_seconds: null, stale: false, reason: "unparseable" });
+            continue;
+        }
+        const createdAt = readCheckpointCreatedAt(raw);
+        const createdAtMs = createdAt === null ? Number.NaN : Date.parse(createdAt);
+        if (!Number.isFinite(createdAtMs)) {
+            result.warnings.push(`checkpoint_unparseable:${relName}`);
+            result.retained.push(relPath);
+            result.entries.push({
+                file: relPath,
+                created_at: createdAt,
+                age_seconds: null,
+                stale: false,
+                reason: "unparseable",
+            });
+            continue;
+        }
+        const ageMs = nowMs - createdAtMs;
+        const entry = {
+            file: relPath,
+            created_at: createdAt,
+            age_seconds: Math.floor(ageMs / 1000),
+            stale: ageMs > retentionMs,
+            reason: ageMs > retentionMs ? "expired" : "active",
+        };
+        if (!entry.stale) {
+            result.retained.push(relPath);
+            result.entries.push(entry);
+            continue;
+        }
+        if (!dryRun) {
+            try {
+                await fs.unlink(absPath);
+            }
+            catch (unlinkError) {
+                if (!isErrno(unlinkError, "ENOENT")) {
+                    result.warnings.push(`checkpoint_remove_failed:${relName}`);
+                    result.retained.push(relPath);
+                    result.entries.push(entry);
+                    continue;
+                }
+                // ENOENT on unlink = already gone (race); treat as removed.
+            }
+            if (hooks?.onWrite) {
+                result.warnings.push(...(await hooks.onWrite(absPath)));
+            }
+        }
+        result.removed.push(relPath);
+        result.entries.push(entry);
+    }
+    return result;
+}
+//# sourceMappingURL=checkpoint-gc.js.map
+//# debugId=83dc8421-d6b4-5ef6-ac77-bfca9e10ffb1

package/dist/core/checkpoint/checkpoint-gc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-gc.js","sources":["core/checkpoint/checkpoint-gc.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/checkpoint/checkpoint-gc\n *\n * Age-based garbage collector for bulk-mutation rollback checkpoints written by\n * `update-many`/`close-many` under `checkpoints/<subdir>/<id>.json`.\n *\n * Safety-first policy (mirroring the stale-lock sweep in `lock/lock-gc.ts`): a\n * checkpoint whose JSON cannot be read or whose `created_at` cannot be parsed is\n * RETAINED rather than deleted. We only prune checkpoints whose age can be\n * conclusively determined from their own `created_at` field and that exceed the\n * configured `checkpoints.retention_days` policy.\n *\n * Staleness formula: (now_ms - Date.parse(created_at)) > retention_days * 86_400_000.\n * A zero/negative age (a future `created_at`) is always treated as active.\n */\n\nimport type { Dirent } from \"node:fs\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\n\nconst MILLISECONDS_PER_DAY = 86_400_000;\n\n/**\n * Documents the checkpoint gc scan entry payload exchanged by command, SDK, and package integrations.\n */\nexport interface CheckpointGcEntry {\n  /** Relative path like \"checkpoints/update-many/update-many-20260619-abc123.json\". */\n  file: string;\n  /** Parsed `created_at`, or null when missing/unparseable. */\n  created_at: string | null;\n  /** floor((now - created_at)/1000), null when unparseable. */\n  age_seconds: number | null;\n  /** True only when classified as expired (older than the retention window). */\n  stale: boolean;\n  reason: \"expired\" | \"active\" | \"unparseable\";\n}\n\n/**\n * Documents the checkpoint gc hooks payload exchanged by command, SDK, and package integrations.\n */\nexport interface CheckpointGcHooks {\n  onRead?: (checkpointPath: string) => Promise<string[]> | string[];\n  onWrite?: (checkpointPath: string) => Promise<string[]> | string[];\n}\n\n/**\n * Documents the checkpoint gc options payload exchanged by command, SDK, and package integrations.\n */\nexport interface CheckpointGcOptions {\n  dryRun: boolean;\n  /**\n   * Prune checkpoints older than this many days. Negative values are clamped to\n   * zero (prune everything aged); a non-finite value (NaN/Infinity) disables\n   * pruning entirely so bad input never deletes recoverable checkpoints.\n   */\n  retentionDays: number;\n  /** Epoch ms; defaults to Date.now() — injectable for deterministic tests. */\n  now?: number;\n  hooks?: CheckpointGcHooks;\n}\n\n/**\n * Documents the checkpoint gc result payload exchanged by command, SDK, and package integrations.\n */\nexport interface CheckpointGcResult {\n  /** Number of *.json checkpoint files examined. */\n  scanned: number;\n  /** Relative paths removed (or would-remove under dryRun), sorted by file name asc. */\n  removed: string[];\n  /** Relative paths retained (active OR unparseable — never delete what we can't reason about). */\n  retained: string[];\n  warnings: string[];\n  /** One per scanned checkpoint file, sorted by file name asc. */\n  entries: CheckpointGcEntry[];\n}\n\nfunction isErrno(error: unknown, code: string): boolean {\n  return (\n    typeof error === \"object\" && error !== null && \"code\" in error && (error as { code?: string }).code === code\n  );\n}\n\n/** Extract a parseable `created_at` from a checkpoint's raw JSON, or null. */\nfunction readCheckpointCreatedAt(raw: string): string | null {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw) as unknown;\n  } catch {\n    return null;\n  }\n  if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n    return null;\n  }\n  const createdAt = (parsed as Record<string, unknown>).created_at;\n  return typeof createdAt === \"string\" ? createdAt : null;\n}\n\n/**\n * Collect relative `checkpoints/<subdir>/<file>.json` (and top-level `<file>.json`)\n * paths under the checkpoints root. Subdirectory reads are resilient to\n * concurrent races: a subdir that vanishes between the parent `readdir` and its\n * own `readdir` (ENOENT) is skipped quietly, and any other read failure (e.g. a\n * permission error) is surfaced as a `checkpoint_subdir_unreadable:<name>`\n * warning rather than aborting the whole sweep.\n */\nasync function collectCheckpointFiles(checkpointsDir: string, warnings: string[]): Promise<string[]> {\n  let dirEntries: Dirent[];\n  try {\n    dirEntries = await fs.readdir(checkpointsDir, { withFileTypes: true });\n  } catch (error: unknown) {\n    if (isErrno(error, \"ENOENT\")) {\n      return [];\n    }\n    throw error;\n  }\n  const files: string[] = [];\n  for (const entry of dirEntries) {\n    if (entry.isDirectory()) {\n      const subdir = path.join(checkpointsDir, entry.name);\n      let nested: string[];\n      try {\n        nested = await fs.readdir(subdir);\n      } catch (error: unknown) {\n        if (!isErrno(error, \"ENOENT\")) {\n          warnings.push(`checkpoint_subdir_unreadable:${entry.name}`);\n        }\n        continue;\n      }\n      for (const file of nested) {\n        if (file.endsWith(\".json\")) {\n          files.push(`${entry.name}/${file}`);\n        }\n      }\n    } else if (entry.name.endsWith(\".json\")) {\n      files.push(entry.name);\n    }\n  }\n  return files.sort();\n}\n\n/**\n * Implements run checkpoint gc for the public runtime surface of this module.\n */\nexport async function runCheckpointGc(pmRoot: string, options: CheckpointGcOptions): Promise<CheckpointGcResult> {\n  const { dryRun, hooks } = options;\n  const nowMs = options.now ?? Date.now();\n  const retentionMs = Math.max(0, options.retentionDays) * MILLISECONDS_PER_DAY;\n  const checkpointsDir = path.join(pmRoot, \"checkpoints\");\n  // A non-finite retentionMs (NaN/Infinity from a non-finite retentionDays)\n  // makes every `ageMs > retentionMs` comparison false, so nothing is pruned —\n  // pruning is disabled rather than risking deletion under bad input.\n\n  const result: CheckpointGcResult = {\n    scanned: 0,\n    removed: [],\n    retained: [],\n    warnings: [],\n    entries: [],\n  };\n\n  const files = await collectCheckpointFiles(checkpointsDir, result.warnings);\n  for (const relName of files) {\n    const absPath = path.join(checkpointsDir, relName);\n    const relPath = `checkpoints/${relName}`;\n    result.scanned += 1;\n\n    if (hooks?.onRead) {\n      result.warnings.push(...(await hooks.onRead(absPath)));\n    }\n\n    let raw: string;\n    try {\n      raw = await fs.readFile(absPath, \"utf8\");\n    } catch (readError: unknown) {\n      if (isErrno(readError, \"ENOENT\")) {\n        // Disappeared between readdir and readFile — treat as a ghost; skip quietly.\n        result.scanned -= 1;\n        continue;\n      }\n      result.warnings.push(`checkpoint_unreadable:${relName}`);\n      result.retained.push(relPath);\n      result.entries.push({ file: relPath, created_at: null, age_seconds: null, stale: false, reason: \"unparseable\" });\n      continue;\n    }\n\n    const createdAt = readCheckpointCreatedAt(raw);\n    const createdAtMs = createdAt === null ? Number.NaN : Date.parse(createdAt);\n    if (!Number.isFinite(createdAtMs)) {\n      result.warnings.push(`checkpoint_unparseable:${relName}`);\n      result.retained.push(relPath);\n      result.entries.push({\n        file: relPath,\n        created_at: createdAt,\n        age_seconds: null,\n        stale: false,\n        reason: \"unparseable\",\n      });\n      continue;\n    }\n\n    const ageMs = nowMs - createdAtMs;\n    const entry: CheckpointGcEntry = {\n      file: relPath,\n      created_at: createdAt,\n      age_seconds: Math.floor(ageMs / 1000),\n      stale: ageMs > retentionMs,\n      reason: ageMs > retentionMs ? \"expired\" : \"active\",\n    };\n    if (!entry.stale) {\n      result.retained.push(relPath);\n      result.entries.push(entry);\n      continue;\n    }\n\n    if (!dryRun) {\n      try {\n        await fs.unlink(absPath);\n      } catch (unlinkError: unknown) {\n        if (!isErrno(unlinkError, \"ENOENT\")) {\n          result.warnings.push(`checkpoint_remove_failed:${relName}`);\n          result.retained.push(relPath);\n          result.entries.push(entry);\n          continue;\n        }\n        // ENOENT on unlink = already gone (race); treat as removed.\n      }\n      if (hooks?.onWrite) {\n        result.warnings.push(...(await hooks.onWrite(absPath)));\n      }\n    }\n    result.removed.push(relPath);\n    result.entries.push(entry);\n  }\n\n  return result;\n}\n"],"names":[],"mappings":"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","debugId":"83dc8421-d6b4-5ef6-ac77-bfca9e10ffb1"}

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]="bb104779-cecf-5986-9ed2-59ba1a157f22")}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]="439e5c08-5cff-56f0-a21d-15ffdb7afe94")}catch(e){}}();
 export const NESTED_SETTING_DESCRIPTORS = [
     {
         key: "search_provider",
@@ -119,6 +119,19 @@ export const NESTED_SETTING_DESCRIPTORS = [
         min: 1,
         summary: "Default upper bound on search hits when --limit is not supplied.",
     },
+    {
+        key: "search_bm25_k1",
+        path: "search.bm25.k1",
+        kind: "number",
+        min: 0,
+        summary: "Offline BM25 term-frequency saturation (k1); higher saturates repeated terms slower (default 1.2).",
+    },
+    {
+        key: "search_bm25_b",
+        path: "search.bm25.b",
+        kind: "ratio",
+        summary: "Offline BM25 document-length normalization (b) in [0, 1]; 0 disables, 1 fully normalizes (default 0.75).",
+    },
     {
         key: "openai_base_url",
         path: "providers.openai.base_url",
@@ -211,6 +224,13 @@ export const NESTED_SETTING_DESCRIPTORS = [
         min: 1,
         summary: "Claim/lock time-to-live in seconds before a stale lock can be reclaimed.",
     },
+    {
+        key: "checkpoints_retention_days",
+        path: "checkpoints.retention_days",
+        kind: "integer",
+        min: 1,
+        summary: "Age in days above which pm gc --scope checkpoints prunes bulk-mutation rollback checkpoints.",
+    },
     {
         key: "schema_unknown_field_policy",
         path: "schema.unknown_field_policy",
@@ -395,4 +415,4 @@ export function writeNestedSettingValue(settings, descriptor, value) {
     return true;
 }
 //# sourceMappingURL=nested-settings.js.map
-//# debugId=bb104779-cecf-5986-9ed2-59ba1a157f22
+//# debugId=439e5c08-5cff-56f0-a21d-15ffdb7afe94

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: \"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: \"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":"bb104779-cecf-5986-9ed2-59ba1a157f22"}
+{"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"}

package/dist/core/diagnostics/remediation.js

@@ -24,7 +24,7 @@
  * intentionally excluded here (see pm-0hnu: "all non-extension checks").
  */
 
-!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]="b4fea4d7-ec26-5176-a1ee-77473d6a5d9b")}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]="18ec090a-cfc4-5acf-90b6-7e6fade40d8d")}catch(e){}}();
 export const REMEDIATION_REGISTRY = Object.freeze([
     // --- pm health: directories ---
     {
@@ -171,6 +171,18 @@ export const REMEDIATION_REGISTRY = Object.freeze([
         command: "pm gc --scope locks --dry-run",
         summary: "Some lock files could not be read; preview the sweep and inspect the unreadable files manually — gc never deletes what it cannot read.",
     },
+    // --- pm health: extensions ---
+    // Most extension findings keep their richer, contextual
+    // `details.triage.remediation` and are intentionally absent here. The
+    // partial-coverage code is the exception: it is not a per-extension triage
+    // result but a system-wide adoption gap (unmanaged installs the update-health
+    // scan had to skip), so it has a single deterministic fix and belongs in the
+    // shared registry like any other health finding (pm-bdvm).
+    {
+        code: "extension_update_health_partial_coverage",
+        command: "pm extension --adopt-all --project",
+        summary: "Update-health coverage is partial because unmanaged extensions were skipped; adopt the existing installs into managed metadata so the update scan covers them (use --global for global-scope extensions, or pm package --adopt-all when working with packages).",
+    },
     // --- pm health: vectorization ---
     {
         code: "vectorization_stale_items_remaining",
@@ -233,6 +245,11 @@ export const REMEDIATION_REGISTRY = Object.freeze([
         command: 'pm config set metadata-required-fields --criterion "<field>"',
         summary: "Config-driven finding: the custom metadata profile has no required fields configured and falls back to core, so configure the fields rather than mutating items.",
     },
+    {
+        code: "validate_metadata_duplicate_issue_codes",
+        command: 'pm update <id> --title "<distinct title>"',
+        summary: "Two or more items share one logical issue code (GH-235); give each a distinct title so the derived code is unique, or close the redundant item with pm close <id> --duplicate-of <canonical-id> (closed-as-duplicate items are excluded from the check).",
+    },
     // --- pm validate: resolution ---
     {
         code: "validate_resolution_missing_fields",
@@ -374,4 +391,4 @@ export function buildRemediationCommands(warnings) {
     return Object.values(buildRemediationMap(warnings));
 }
 //# sourceMappingURL=remediation.js.map
-//# debugId=b4fea4d7-ec26-5176-a1ee-77473d6a5d9b
+//# debugId=18ec090a-cfc4-5acf-90b6-7e6fade40d8d