@unbrained/pm-cli 2026.7.21 → 2026.7.22

package/dist/core/shared/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sources":["core/shared/constants.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/shared/constants\n *\n * Provides shared primitives and utilities for Constants.\n */\nimport type {\n  BuiltinItemType,\n  GovernancePreset,\n  GovernanceSettings,\n  ItemMetadata,\n  PmSettings,\n  RuntimeStatusDefinition,\n  RuntimeWorkflowDefinition,\n} from \"../../types/index.js\";\nimport { createDefaultExtensionGovernancePolicy } from \"../extensions/extension-types.js\";\n\n/**\n * Canonical default lifecycle status model and workflow role mapping.\n *\n * Single source of truth: `SETTINGS_DEFAULTS.schema` references these, and\n * `src/core/schema/runtime-schema.ts` re-exports them as\n * `DEFAULT_RUNTIME_STATUS_DEFINITIONS` / `DEFAULT_RUNTIME_WORKFLOW`.\n */\nexport const DEFAULT_STATUS_DEFINITIONS: ReadonlyArray<RuntimeStatusDefinition> =\n  Object.freeze([\n    {\n      id: \"draft\",\n      roles: [\"draft\"],\n    },\n    {\n      id: \"open\",\n      roles: [\"active\", \"default_open\"],\n    },\n    {\n      id: \"in_progress\",\n      aliases: [\"in-progress\"],\n      roles: [\"active\"],\n    },\n    {\n      id: \"blocked\",\n      roles: [\"blocked\"],\n    },\n    {\n      id: \"closed\",\n      roles: [\"terminal\", \"terminal_done\", \"default_close\"],\n    },\n    {\n      id: \"canceled\",\n      aliases: [\"cancelled\"],\n      roles: [\"terminal\", \"terminal_canceled\", \"default_cancel\"],\n    },\n  ]);\n\n/** Fallback workflow definition used when callers do not provide an override. */\nexport const DEFAULT_WORKFLOW_DEFINITION: RuntimeWorkflowDefinition =\n  Object.freeze({\n    draft_status: \"draft\",\n    open_status: \"open\",\n    in_progress_status: \"in_progress\",\n    blocked_status: \"blocked\",\n    close_status: \"closed\",\n    canceled_status: \"canceled\",\n  });\n\n/** Public contract for pm dirname, shared by SDK and presentation-layer consumers. */\nexport const PM_DIRNAME = \".agents/pm\";\n/** Public contract for settings filename, shared by SDK and presentation-layer consumers. */\nexport const SETTINGS_FILENAME = \"settings.json\";\n\n/** GH-249: placeholder close reason recorded when `pm create --status closed` lands an item directly in the close status under `governance.require_close_reason` and no --message/--resolution text is available. Mirrors `pm update --status closed`'s \"Closed via pm update\" default so all three closure paths record a reason. */\nexport const CREATE_DIRECT_CLOSE_REASON_DEFAULT =\n  \"Closed at creation via pm create\";\n\n/** Public contract for pm core required subdirs, shared by SDK and presentation-layer consumers. */\nexport const PM_CORE_REQUIRED_SUBDIRS = [\n  \"\",\n  \"epics\",\n  \"features\",\n  \"tasks\",\n  \"chores\",\n  \"issues\",\n  \"schema\",\n  \"history\",\n  \"search\",\n  \"extensions\",\n  \"locks\",\n] as const;\n\n/** Public contract for pm optional type subdirs, shared by SDK and presentation-layer consumers. */\nexport const PM_OPTIONAL_TYPE_SUBDIRS = [\n  \"decisions\",\n  \"events\",\n  \"reminders\",\n  \"milestones\",\n  \"meetings\",\n  \"plans\",\n] as const;\n\n/** Public contract for pm required subdirs, shared by SDK and presentation-layer consumers. */\nexport const PM_REQUIRED_SUBDIRS = [\n  ...PM_CORE_REQUIRED_SUBDIRS,\n  ...PM_OPTIONAL_TYPE_SUBDIRS,\n] as const;\n\n/** Public contract for type to folder, shared by SDK and presentation-layer consumers. */\nexport const TYPE_TO_FOLDER: Record<BuiltinItemType, string> = {\n  Epic: \"epics\",\n  Feature: \"features\",\n  Task: \"tasks\",\n  Chore: \"chores\",\n  Issue: \"issues\",\n  Decision: \"decisions\",\n  Event: \"events\",\n  Reminder: \"reminders\",\n  Milestone: \"milestones\",\n  Meeting: \"meetings\",\n  Plan: \"plans\",\n};\n\n/** Public contract for item metadata key order, shared by SDK and presentation-layer consumers. */\nexport const ITEM_METADATA_KEY_ORDER: ReadonlyArray<string> = [\n  \"id\",\n  \"title\",\n  \"description\",\n  \"type\",\n  \"pm_format_version\",\n  \"source_type\",\n  \"type_options\",\n  \"status\",\n  \"priority\",\n  \"tags\",\n  \"created_at\",\n  \"updated_at\",\n  \"deadline\",\n  \"reminders\",\n  \"events\",\n  \"closed_at\",\n  \"assignee\",\n  \"source_owner\",\n  \"author\",\n  \"estimated_minutes\",\n  \"acceptance_criteria\",\n  \"design\",\n  \"external_ref\",\n  \"definition_of_ready\",\n  \"order\",\n  \"goal\",\n  \"objective\",\n  \"value\",\n  \"impact\",\n  \"outcome\",\n  \"why_now\",\n  \"parent\",\n  \"reviewer\",\n  \"risk\",\n  \"confidence\",\n  \"sprint\",\n  \"release\",\n  \"blocked_by\",\n  \"blocked_reason\",\n  \"unblock_note\",\n  \"reporter\",\n  \"severity\",\n  \"environment\",\n  \"repro_steps\",\n  \"resolution\",\n  \"expected_result\",\n  \"actual_result\",\n  \"affected_version\",\n  \"fixed_version\",\n  \"component\",\n  \"regression\",\n  \"customer_impact\",\n  \"dependencies\",\n  \"comments\",\n  \"notes\",\n  \"learnings\",\n  \"files\",\n  \"tests\",\n  \"test_runs\",\n  \"docs\",\n  \"close_reason\",\n  \"duplicate_of\",\n  \"plan_mode\",\n  \"plan_scope\",\n  \"plan_harness\",\n  \"plan_resume_context\",\n  \"plan_validation\",\n  \"plan_decisions\",\n  \"plan_discoveries\",\n  \"plan_steps\",\n];\n\ntype BuiltinGovernancePreset = Exclude<GovernancePreset, \"custom\">;\n\n/** Public contract for governance preset defaults, shared by SDK and presentation-layer consumers. */\nexport const GOVERNANCE_PRESET_DEFAULTS: Record<\n  BuiltinGovernancePreset,\n  Omit<GovernanceSettings, \"preset\">\n> = {\n  minimal: {\n    ownership_enforcement: \"none\",\n    create_mode_default: \"progressive\",\n    close_validation_default: \"off\",\n    require_close_reason: true,\n    parent_reference: \"strict_error\",\n    metadata_profile: \"core\",\n    force_required_for_stale_lock: false,\n  },\n  default: {\n    ownership_enforcement: \"warn\",\n    create_mode_default: \"progressive\",\n    close_validation_default: \"warn\",\n    require_close_reason: true,\n    parent_reference: \"strict_error\",\n    metadata_profile: \"core\",\n    force_required_for_stale_lock: true,\n  },\n  strict: {\n    ownership_enforcement: \"strict\",\n    create_mode_default: \"strict\",\n    close_validation_default: \"strict\",\n    require_close_reason: true,\n    parent_reference: \"strict_error\",\n    metadata_profile: \"strict\",\n    force_required_for_stale_lock: true,\n  },\n};\n\n/** Fallback validate stale blocker reason patterns used when callers do not provide an override. */\nexport const DEFAULT_VALIDATE_STALE_BLOCKER_REASON_PATTERNS = [\n  \"no active blocker\",\n  \"ready for planned execution sequencing\",\n  \"work completed\",\n  \"work is closed\",\n] as const;\n\n/** Fallback validate closure like metadata field patterns used when callers do not provide an override. */\nexport const DEFAULT_VALIDATE_CLOSURE_LIKE_METADATA_FIELD_PATTERNS = {\n  blocked_reason: [\n    \"no active blocker because work is closed\",\n    \"work is closed\",\n  ],\n  resolution: [\n    \"closed with implementation evidence\",\n    \"closed with verification evidence\",\n    \"work completed and recorded\",\n    \"work is closed\",\n  ],\n  actual_result: [\n    \"closed and recorded\",\n    \"work completed\",\n    \"work completed and recorded\",\n  ],\n} as const;\n\nfunction cloneOptionalArray<T>(\n  values: readonly T[] | undefined,\n): T[] | undefined {\n  return values ? [...values] : undefined;\n}\n\n/** Public contract for settings defaults, shared by SDK and presentation-layer consumers. */\nexport const SETTINGS_DEFAULTS: PmSettings = {\n  version: 1,\n  id_prefix: \"pm-\",\n  ids: {\n    token_length: 4,\n  },\n  author_default: \"\",\n  item_format: \"toon\",\n  locks: {\n    ttl_seconds: 1800,\n    wait_ms: 3000,\n  },\n  checkpoints: {\n    retention_days: 14,\n  },\n  output: {\n    default_format: \"toon\",\n  },\n  history: {\n    missing_stream: \"auto_create\",\n    compact_policy: {\n      enabled: false,\n      max_entries: 500,\n      trigger: \"health_warn\",\n    },\n  },\n  validation: {\n    sprint_release_format: \"warn\",\n    parent_reference: \"warn\",\n    metadata_profile: \"core\",\n    metadata_required_fields: [],\n    lifecycle_stale_blocker_reason_patterns: [\n      ...DEFAULT_VALIDATE_STALE_BLOCKER_REASON_PATTERNS,\n    ],\n    lifecycle_closure_like_blocked_reason_patterns: [\n      ...DEFAULT_VALIDATE_CLOSURE_LIKE_METADATA_FIELD_PATTERNS.blocked_reason,\n    ],\n    lifecycle_closure_like_resolution_patterns: [\n      ...DEFAULT_VALIDATE_CLOSURE_LIKE_METADATA_FIELD_PATTERNS.resolution,\n    ],\n    lifecycle_closure_like_actual_result_patterns: [\n      ...DEFAULT_VALIDATE_CLOSURE_LIKE_METADATA_FIELD_PATTERNS.actual_result,\n    ],\n    estimate_defaults_by_type: {},\n  },\n  governance: {\n    preset: \"minimal\",\n    ...GOVERNANCE_PRESET_DEFAULTS.minimal,\n  },\n  workflow: {\n    definition_of_done: [],\n  },\n  testing: {\n    record_results_to_items: false,\n  },\n  telemetry: {\n    enabled: true,\n    first_run_prompt_completed: false,\n    capture_level: \"redacted\",\n    endpoint: \"https://pm-cli.unbrained.dev/v1/events\",\n    installation_id: \"\",\n    retention_days: 365,\n  },\n  agent_guidance: {\n    prompt_completed: false,\n    declined: false,\n    declined_at: \"\",\n    template_version: 1,\n    last_checked_files: [],\n  },\n  item_types: {\n    definitions: [],\n  },\n  schema: {\n    version: 1,\n    files: {\n      types: \"schema/types.json\",\n      statuses: \"schema/statuses.json\",\n      fields: \"schema/fields.json\",\n      workflows: \"schema/workflows.json\",\n    },\n    statuses: DEFAULT_STATUS_DEFINITIONS.map((definition) => ({\n      ...definition,\n      aliases: cloneOptionalArray(definition.aliases),\n      roles: cloneOptionalArray(definition.roles),\n    })),\n    fields: [],\n    workflow: { ...DEFAULT_WORKFLOW_DEFINITION },\n    unknown_field_policy: \"allow\",\n  },\n  extensions: {\n    enabled: [],\n    disabled: [],\n    policy: createDefaultExtensionGovernancePolicy(),\n  },\n  search: {\n    score_threshold: 0,\n    hybrid_semantic_weight: 0.7,\n    max_results: 50,\n    embedding_model: \"\",\n    embedding_batch_size: 32,\n    embedding_timeout_ms: 30_000,\n    scanner_max_batch_retries: 3,\n    provider: \"\",\n    mutation_refresh_policy: \"semantic_configured\",\n    query_expansion: {\n      enabled: false,\n      provider: \"\",\n    },\n    rerank: {\n      enabled: false,\n      model: \"\",\n      top_k: 20,\n    },\n  },\n  providers: {\n    openai: {\n      base_url: \"\",\n      api_key: \"\",\n      model: \"\",\n    },\n    ollama: {\n      base_url: \"\",\n      model: \"\",\n    },\n  },\n  context: {\n    default_depth: \"brief\",\n    activity_limit: 10,\n    stale_threshold_days: 7,\n    sections: {\n      hierarchy: true,\n      activity: true,\n      progress: true,\n      recently_created: true,\n      unparented: true,\n      blockers: true,\n      files: true,\n      workload: true,\n      staleness: true,\n      tests: true,\n    },\n  },\n  vector_store: {\n    adapter: \"\",\n    collection_name: \"pm_items\",\n    qdrant: {\n      url: \"\",\n      api_key: \"\",\n    },\n    lancedb: {\n      path: \"\",\n    },\n  },\n};\n\n/** Public contract for empty canonical document, shared by SDK and presentation-layer consumers. */\nexport const EMPTY_CANONICAL_DOCUMENT = {\n  metadata: {},\n  body: \"\",\n};\n\n/** Public contract for exit code, shared by SDK and presentation-layer consumers. */\nexport const EXIT_CODE = {\n  SUCCESS: 0,\n  GENERIC_FAILURE: 1,\n  USAGE: 2,\n  NOT_FOUND: 3,\n  CONFLICT: 4,\n  DEPENDENCY_FAILED: 5,\n} as const;\n\n/** Restricts telemetry error category values accepted by command, SDK, and storage contracts. */\nexport type TelemetryErrorCategory =\n  | \"usage\"\n  | \"validation\"\n  | \"conflict\"\n  | \"runtime\"\n  | \"unknown\";\n\n/** Public contract for telemetry error category by code, shared by SDK and presentation-layer consumers. */\nexport const TELEMETRY_ERROR_CATEGORY_BY_CODE: Readonly<\n  Record<string, TelemetryErrorCategory>\n> = Object.freeze({\n  unknown_command: \"usage\",\n  unknown_option: \"usage\",\n  missing_required_option: \"usage\",\n  missing_required_argument: \"usage\",\n  invalid_command_usage: \"usage\",\n  linked_test_value_not_quoted: \"usage\",\n  invalid_argument_value: \"validation\",\n  health_findings: \"validation\",\n  validation_findings: \"validation\",\n  close_through_update: \"validation\",\n  no_update_fields: \"validation\",\n  unsupported_update_option: \"validation\",\n  tracker_not_initialized: \"validation\",\n  item_not_found: \"validation\",\n  ownership_conflict: \"conflict\",\n  lock_conflict: \"conflict\",\n  terminal_state_conflict: \"conflict\",\n  dependency_failed: \"runtime\",\n  command_failed: \"runtime\",\n  unknown_error: \"runtime\",\n});\n\n/** Implements resolve telemetry error category for the public runtime surface of this module. */\nexport function resolveTelemetryErrorCategory(\n  errorCode: string | undefined,\n): TelemetryErrorCategory {\n  const normalized = (errorCode ?? \"\").trim().toLowerCase();\n  if (normalized.length === 0) {\n    return \"unknown\";\n  }\n  const explicit = TELEMETRY_ERROR_CATEGORY_BY_CODE[normalized];\n  if (typeof explicit === \"string\") {\n    return explicit;\n  }\n  if (normalized.includes(\"conflict\") || normalized.includes(\"locked\")) {\n    return \"conflict\";\n  }\n  if (\n    normalized.startsWith(\"unknown_\") ||\n    normalized.startsWith(\"missing_required_\")\n  ) {\n    return \"usage\";\n  }\n  if (\n    normalized.startsWith(\"invalid_\") ||\n    normalized.endsWith(\"_not_found\") ||\n    normalized.includes(\"validation\")\n  ) {\n    return \"validation\";\n  }\n  if (normalized.endsWith(\"_error\") || normalized.endsWith(\"_failed\")) {\n    return \"runtime\";\n  }\n  return \"unknown\";\n}\n"],"names":[],"mappings":"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","debugId":"54677a0e-1944-5c10-bfa9-2840cb3630cd"}
+{"version":3,"file":"constants.js","sources":["core/shared/constants.ts"],"sourceRoot":"/","sourcesContent":["/**\n * @module core/shared/constants\n *\n * Provides shared primitives and utilities for Constants.\n */\nimport type {\n  BuiltinItemType,\n  GovernancePreset,\n  GovernanceSettings,\n  ItemMetadata,\n  PmSettings,\n  RuntimeStatusDefinition,\n  RuntimeWorkflowDefinition,\n} from \"../../types/index.js\";\nimport { createDefaultExtensionGovernancePolicy } from \"../extensions/extension-types.js\";\n\n/**\n * Canonical default lifecycle status model and workflow role mapping.\n *\n * Single source of truth: `SETTINGS_DEFAULTS.schema` references these, and\n * `src/core/schema/runtime-schema.ts` re-exports them as\n * `DEFAULT_RUNTIME_STATUS_DEFINITIONS` / `DEFAULT_RUNTIME_WORKFLOW`.\n */\nexport const DEFAULT_STATUS_DEFINITIONS: ReadonlyArray<RuntimeStatusDefinition> =\n  Object.freeze([\n    {\n      id: \"draft\",\n      roles: [\"draft\"],\n    },\n    {\n      id: \"open\",\n      roles: [\"active\", \"default_open\"],\n    },\n    {\n      id: \"in_progress\",\n      aliases: [\"in-progress\"],\n      roles: [\"active\"],\n    },\n    {\n      id: \"blocked\",\n      roles: [\"blocked\"],\n    },\n    {\n      id: \"closed\",\n      roles: [\"terminal\", \"terminal_done\", \"default_close\"],\n    },\n    {\n      id: \"canceled\",\n      aliases: [\"cancelled\"],\n      roles: [\"terminal\", \"terminal_canceled\", \"default_cancel\"],\n    },\n  ]);\n\n/** Fallback workflow definition used when callers do not provide an override. */\nexport const DEFAULT_WORKFLOW_DEFINITION: RuntimeWorkflowDefinition =\n  Object.freeze({\n    draft_status: \"draft\",\n    open_status: \"open\",\n    in_progress_status: \"in_progress\",\n    blocked_status: \"blocked\",\n    close_status: \"closed\",\n    canceled_status: \"canceled\",\n  });\n\n/** Public contract for pm dirname, shared by SDK and presentation-layer consumers. */\nexport const PM_DIRNAME = \".agents/pm\";\n/** Public contract for settings filename, shared by SDK and presentation-layer consumers. */\nexport const SETTINGS_FILENAME = \"settings.json\";\n\n/** GH-249: placeholder close reason recorded when `pm create --status closed` lands an item directly in the close status under `governance.require_close_reason` and no --message/--resolution text is available. Mirrors `pm update --status closed`'s \"Closed via pm update\" default so all three closure paths record a reason. */\nexport const CREATE_DIRECT_CLOSE_REASON_DEFAULT =\n  \"Closed at creation via pm create\";\n\n/** Public contract for pm core required subdirs, shared by SDK and presentation-layer consumers. */\nexport const PM_CORE_REQUIRED_SUBDIRS = [\n  \"\",\n  \"epics\",\n  \"features\",\n  \"tasks\",\n  \"chores\",\n  \"issues\",\n  \"schema\",\n  \"history\",\n  \"search\",\n  \"extensions\",\n  \"locks\",\n] as const;\n\n/** Public contract for pm optional type subdirs, shared by SDK and presentation-layer consumers. */\nexport const PM_OPTIONAL_TYPE_SUBDIRS = [\n  \"decisions\",\n  \"events\",\n  \"reminders\",\n  \"milestones\",\n  \"meetings\",\n  \"plans\",\n] as const;\n\n/** Public contract for pm required subdirs, shared by SDK and presentation-layer consumers. */\nexport const PM_REQUIRED_SUBDIRS = [\n  ...PM_CORE_REQUIRED_SUBDIRS,\n  ...PM_OPTIONAL_TYPE_SUBDIRS,\n] as const;\n\n/** Public contract for type to folder, shared by SDK and presentation-layer consumers. */\nexport const TYPE_TO_FOLDER: Record<BuiltinItemType, string> = {\n  Epic: \"epics\",\n  Feature: \"features\",\n  Task: \"tasks\",\n  Chore: \"chores\",\n  Issue: \"issues\",\n  Decision: \"decisions\",\n  Event: \"events\",\n  Reminder: \"reminders\",\n  Milestone: \"milestones\",\n  Meeting: \"meetings\",\n  Plan: \"plans\",\n};\n\n/** Portable project-context fields shared by storage order and structured mutation IO. */\nexport const ITEM_PROJECT_CONTEXT_KEYS = [\n  \"goal\",\n  \"objective\",\n  \"value\",\n  \"impact\",\n  \"outcome\",\n  \"why_now\",\n  \"parent\",\n  \"reviewer\",\n  \"risk\",\n  \"confidence\",\n  \"sprint\",\n  \"release\",\n  \"blocked_by\",\n  \"blocked_reason\",\n  \"unblock_note\",\n  \"reporter\",\n  \"severity\",\n  \"environment\",\n  \"repro_steps\",\n  \"resolution\",\n  \"expected_result\",\n  \"actual_result\",\n] as const;\n\n/** Public contract for item metadata key order, shared by SDK and presentation-layer consumers. */\nexport const ITEM_METADATA_KEY_ORDER: ReadonlyArray<string> = [\n  \"id\",\n  \"title\",\n  \"description\",\n  \"type\",\n  \"pm_format_version\",\n  \"source_type\",\n  \"type_options\",\n  \"status\",\n  \"priority\",\n  \"tags\",\n  \"created_at\",\n  \"updated_at\",\n  \"deadline\",\n  \"reminders\",\n  \"events\",\n  \"closed_at\",\n  \"assignee\",\n  \"source_owner\",\n  \"author\",\n  \"estimated_minutes\",\n  \"acceptance_criteria\",\n  \"design\",\n  \"external_ref\",\n  \"definition_of_ready\",\n  \"order\",\n  ...ITEM_PROJECT_CONTEXT_KEYS,\n  \"affected_version\",\n  \"fixed_version\",\n  \"component\",\n  \"regression\",\n  \"customer_impact\",\n  \"dependencies\",\n  \"comments\",\n  \"notes\",\n  \"learnings\",\n  \"files\",\n  \"tests\",\n  \"test_runs\",\n  \"docs\",\n  \"close_reason\",\n  \"duplicate_of\",\n  \"plan_mode\",\n  \"plan_scope\",\n  \"plan_harness\",\n  \"plan_resume_context\",\n  \"plan_validation\",\n  \"plan_decisions\",\n  \"plan_discoveries\",\n  \"plan_steps\",\n];\n\ntype BuiltinGovernancePreset = Exclude<GovernancePreset, \"custom\">;\n\n/** Public contract for governance preset defaults, shared by SDK and presentation-layer consumers. */\nexport const GOVERNANCE_PRESET_DEFAULTS: Record<\n  BuiltinGovernancePreset,\n  Omit<GovernanceSettings, \"preset\">\n> = {\n  minimal: {\n    ownership_enforcement: \"none\",\n    create_mode_default: \"progressive\",\n    close_validation_default: \"off\",\n    require_close_reason: true,\n    parent_reference: \"strict_error\",\n    metadata_profile: \"core\",\n    force_required_for_stale_lock: false,\n  },\n  default: {\n    ownership_enforcement: \"warn\",\n    create_mode_default: \"progressive\",\n    close_validation_default: \"warn\",\n    require_close_reason: true,\n    parent_reference: \"strict_error\",\n    metadata_profile: \"core\",\n    force_required_for_stale_lock: true,\n  },\n  strict: {\n    ownership_enforcement: \"strict\",\n    create_mode_default: \"strict\",\n    close_validation_default: \"strict\",\n    require_close_reason: true,\n    parent_reference: \"strict_error\",\n    metadata_profile: \"strict\",\n    force_required_for_stale_lock: true,\n  },\n};\n\n/** Fallback validate stale blocker reason patterns used when callers do not provide an override. */\nexport const DEFAULT_VALIDATE_STALE_BLOCKER_REASON_PATTERNS = [\n  \"no active blocker\",\n  \"ready for planned execution sequencing\",\n  \"work completed\",\n  \"work is closed\",\n] as const;\n\n/** Fallback validate closure like metadata field patterns used when callers do not provide an override. */\nexport const DEFAULT_VALIDATE_CLOSURE_LIKE_METADATA_FIELD_PATTERNS = {\n  blocked_reason: [\n    \"no active blocker because work is closed\",\n    \"work is closed\",\n  ],\n  resolution: [\n    \"closed with implementation evidence\",\n    \"closed with verification evidence\",\n    \"work completed and recorded\",\n    \"work is closed\",\n  ],\n  actual_result: [\n    \"closed and recorded\",\n    \"work completed\",\n    \"work completed and recorded\",\n  ],\n} as const;\n\nfunction cloneOptionalArray<T>(\n  values: readonly T[] | undefined,\n): T[] | undefined {\n  return values ? [...values] : undefined;\n}\n\n/** Public contract for settings defaults, shared by SDK and presentation-layer consumers. */\nexport const SETTINGS_DEFAULTS: PmSettings = {\n  version: 1,\n  id_prefix: \"pm-\",\n  ids: {\n    token_length: 4,\n  },\n  author_default: \"\",\n  item_format: \"toon\",\n  locks: {\n    ttl_seconds: 1800,\n    wait_ms: 3000,\n  },\n  checkpoints: {\n    retention_days: 14,\n  },\n  output: {\n    default_format: \"toon\",\n  },\n  history: {\n    missing_stream: \"auto_create\",\n    compact_policy: {\n      enabled: false,\n      max_entries: 500,\n      trigger: \"health_warn\",\n    },\n  },\n  validation: {\n    sprint_release_format: \"warn\",\n    parent_reference: \"warn\",\n    metadata_profile: \"core\",\n    metadata_required_fields: [],\n    lifecycle_stale_blocker_reason_patterns: [\n      ...DEFAULT_VALIDATE_STALE_BLOCKER_REASON_PATTERNS,\n    ],\n    lifecycle_closure_like_blocked_reason_patterns: [\n      ...DEFAULT_VALIDATE_CLOSURE_LIKE_METADATA_FIELD_PATTERNS.blocked_reason,\n    ],\n    lifecycle_closure_like_resolution_patterns: [\n      ...DEFAULT_VALIDATE_CLOSURE_LIKE_METADATA_FIELD_PATTERNS.resolution,\n    ],\n    lifecycle_closure_like_actual_result_patterns: [\n      ...DEFAULT_VALIDATE_CLOSURE_LIKE_METADATA_FIELD_PATTERNS.actual_result,\n    ],\n    estimate_defaults_by_type: {},\n  },\n  governance: {\n    preset: \"minimal\",\n    ...GOVERNANCE_PRESET_DEFAULTS.minimal,\n  },\n  workflow: {\n    definition_of_done: [],\n  },\n  testing: {\n    record_results_to_items: false,\n  },\n  telemetry: {\n    enabled: true,\n    first_run_prompt_completed: false,\n    capture_level: \"redacted\",\n    endpoint: \"https://pm-cli.unbrained.dev/v1/events\",\n    installation_id: \"\",\n    retention_days: 365,\n  },\n  agent_guidance: {\n    prompt_completed: false,\n    declined: false,\n    declined_at: \"\",\n    template_version: 1,\n    last_checked_files: [],\n  },\n  item_types: {\n    definitions: [],\n  },\n  schema: {\n    version: 1,\n    files: {\n      types: \"schema/types.json\",\n      statuses: \"schema/statuses.json\",\n      fields: \"schema/fields.json\",\n      workflows: \"schema/workflows.json\",\n    },\n    statuses: DEFAULT_STATUS_DEFINITIONS.map((definition) => ({\n      ...definition,\n      aliases: cloneOptionalArray(definition.aliases),\n      roles: cloneOptionalArray(definition.roles),\n    })),\n    fields: [],\n    workflow: { ...DEFAULT_WORKFLOW_DEFINITION },\n    unknown_field_policy: \"allow\",\n  },\n  extensions: {\n    enabled: [],\n    disabled: [],\n    policy: createDefaultExtensionGovernancePolicy(),\n  },\n  search: {\n    score_threshold: 0,\n    hybrid_semantic_weight: 0.7,\n    max_results: 50,\n    embedding_model: \"\",\n    embedding_batch_size: 32,\n    embedding_timeout_ms: 30_000,\n    scanner_max_batch_retries: 3,\n    provider: \"\",\n    mutation_refresh_policy: \"semantic_configured\",\n    query_expansion: {\n      enabled: false,\n      provider: \"\",\n    },\n    rerank: {\n      enabled: false,\n      model: \"\",\n      top_k: 20,\n    },\n  },\n  providers: {\n    openai: {\n      base_url: \"\",\n      api_key: \"\",\n      model: \"\",\n    },\n    ollama: {\n      base_url: \"\",\n      model: \"\",\n    },\n  },\n  context: {\n    default_depth: \"brief\",\n    activity_limit: 10,\n    stale_threshold_days: 7,\n    sections: {\n      hierarchy: true,\n      activity: true,\n      progress: true,\n      recently_created: true,\n      unparented: true,\n      blockers: true,\n      files: true,\n      workload: true,\n      staleness: true,\n      tests: true,\n    },\n  },\n  vector_store: {\n    adapter: \"\",\n    collection_name: \"pm_items\",\n    qdrant: {\n      url: \"\",\n      api_key: \"\",\n    },\n    lancedb: {\n      path: \"\",\n    },\n  },\n};\n\n/** Public contract for empty canonical document, shared by SDK and presentation-layer consumers. */\nexport const EMPTY_CANONICAL_DOCUMENT = {\n  metadata: {},\n  body: \"\",\n};\n\n/** Public contract for exit code, shared by SDK and presentation-layer consumers. */\nexport const EXIT_CODE = {\n  SUCCESS: 0,\n  GENERIC_FAILURE: 1,\n  USAGE: 2,\n  NOT_FOUND: 3,\n  CONFLICT: 4,\n  DEPENDENCY_FAILED: 5,\n} as const;\n\n/** Restricts telemetry error category values accepted by command, SDK, and storage contracts. */\nexport type TelemetryErrorCategory =\n  | \"usage\"\n  | \"validation\"\n  | \"conflict\"\n  | \"runtime\"\n  | \"unknown\";\n\n/** Public contract for telemetry error category by code, shared by SDK and presentation-layer consumers. */\nexport const TELEMETRY_ERROR_CATEGORY_BY_CODE: Readonly<\n  Record<string, TelemetryErrorCategory>\n> = Object.freeze({\n  unknown_command: \"usage\",\n  unknown_option: \"usage\",\n  missing_required_option: \"usage\",\n  missing_required_argument: \"usage\",\n  invalid_command_usage: \"usage\",\n  linked_test_value_not_quoted: \"usage\",\n  invalid_argument_value: \"validation\",\n  health_findings: \"validation\",\n  validation_findings: \"validation\",\n  close_through_update: \"validation\",\n  no_update_fields: \"validation\",\n  unsupported_update_option: \"validation\",\n  tracker_not_initialized: \"validation\",\n  item_not_found: \"validation\",\n  ownership_conflict: \"conflict\",\n  lock_conflict: \"conflict\",\n  terminal_state_conflict: \"conflict\",\n  dependency_failed: \"runtime\",\n  merge_git_config_unwritable: \"runtime\",\n  command_failed: \"runtime\",\n  unknown_error: \"runtime\",\n});\n\n/** Implements resolve telemetry error category for the public runtime surface of this module. */\nexport function resolveTelemetryErrorCategory(\n  errorCode: string | undefined,\n): TelemetryErrorCategory {\n  const normalized = (errorCode ?? \"\").trim().toLowerCase();\n  if (normalized.length === 0) {\n    return \"unknown\";\n  }\n  const explicit = TELEMETRY_ERROR_CATEGORY_BY_CODE[normalized];\n  if (typeof explicit === \"string\") {\n    return explicit;\n  }\n  if (normalized.includes(\"conflict\") || normalized.includes(\"locked\")) {\n    return \"conflict\";\n  }\n  if (\n    normalized.startsWith(\"unknown_\") ||\n    normalized.startsWith(\"missing_required_\")\n  ) {\n    return \"usage\";\n  }\n  if (\n    normalized.startsWith(\"invalid_\") ||\n    normalized.endsWith(\"_not_found\") ||\n    normalized.includes(\"validation\")\n  ) {\n    return \"validation\";\n  }\n  if (normalized.endsWith(\"_error\") || normalized.endsWith(\"_failed\")) {\n    return \"runtime\";\n  }\n  return \"unknown\";\n}\n"],"names":[],"mappings":"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","debugId":"3f35f57d-c4cd-5508-8860-c6bcd0d56eeb"}

package/dist/core/store/item-metadata-cache.d.ts

@@ -1,4 +1,6 @@
 import type { ItemDocument, ItemFormat, ItemMetadata, RuntimeSchemaSettings } from "../../types/index.js";
+/** Minimum item count at which derived-index mutations use cross-process locking. */
+export declare const DEFAULT_DERIVED_INDEX_MINIMUM_ITEMS = 500;
 /** Heavy "collection" item-metadata fields. These arrays dominate the on-disk cache (e.g. a single item's comment thread can be hundreds of KB) yet the hot list path (`pm list`, stats, deps, activity, calendar, close) never reads them. They are stored in a separate collections cache that is parsed only when a caller opts in (`includeCollections`), keeping the always-loaded light cache an order of magnitude smaller and its JSON.parse correspondingly cheaper. */
 export declare const HEAVY_METADATA_KEYS: readonly ["comments", "notes", "learnings", "files", "tests", "test_runs", "docs"];
 /** Documents the cached document candidate payload exchanged by command, SDK, and package integrations. */
@@ -32,6 +34,35 @@ export declare function clearItemMetadataEnvelopeMemo(): void;
 export declare function shouldReplaceCachedDocumentCandidate(existingFormat: ItemFormat, candidateFormat: ItemFormat, preferredFormat: ItemFormat | undefined): boolean;
 /** Decide whether a scanned candidate should be recorded for its item id. An unseen id is always recorded; duplicate ids delegate to the deterministic cross-format preference rule. Keeping the short-circuit in this pure helper makes both outcomes testable without relying on filesystem enumeration or concurrent read completion order. */
 export declare function shouldRecordCachedDocumentCandidate(existingFormat: ItemFormat | undefined, candidateFormat: ItemFormat, preferredFormat: ItemFormat | undefined): boolean;
+/** Acquire the cross-process derived-index writer lock when an index exists. */
+export declare function acquireItemMetadataDerivedIndexLock(pmRoot: string, author: string): Promise<() => Promise<void>>;
+/** One authoritative item commit projected into the rebuildable index. */
+export interface ItemMetadataDerivedIndexMutation {
+    /** Tracker root containing the derived cache. */
+    pmRoot: string;
+    /** Preferred item format folded into the cache schema fingerprint. */
+    preferredFormat: ItemFormat | undefined;
+    /** Runtime item-type folder mapping. */
+    typeToFolder: Record<string, string>;
+    /** Runtime schema folded into the cache schema fingerprint. */
+    schema: RuntimeSchemaSettings | undefined;
+    /** Committed item path, or deleted item path when document is null. */
+    itemPath: string;
+    /** Previous path removed by a format or type migration. */
+    previousItemPath?: string;
+    /** Committed document, or null for deletion. */
+    document: ItemDocument | null;
+}
+/**
+ * Project one already-committed authoritative item write into every compatible
+ * derived-index tier. Callers hold {@link acquireItemMetadataDerivedIndexLock}
+ * from before the item write until this function finishes, so independent pm
+ * mutations cannot publish a cursor that omits a concurrent write. One small
+ * atomic delta carries the shared source cursor and all tier projections, so
+ * mutation cost is bounded by changed items instead of total workspace size.
+ * Any refresh failure deletes the rebuildable cache so the next read scans.
+ */
+export declare function refreshItemMetadataDerivedIndex(mutation: ItemMetadataDerivedIndexMutation): Promise<string[]>;
 /** Documents the list cache options payload exchanged by command, SDK, and package integrations. */
 export interface ListCacheOptions {
     /** When false, item bodies are neither loaded from nor written to the separate body cache. Metadata-only callers (`pm list`, stats, deps, activity, …) skip the large body cache entirely; only body consumers (search/reindex) pay for it. */
@@ -40,7 +71,7 @@ export interface ListCacheOptions {
     includeCollections?: boolean;
     /** Force canonical item enumeration and stat validation even when a fresh derived index is available. Validation, repair, migration, and equivalence tests use this correctness path. */
     forceSourceScan?: boolean;
-    /** Minimum item count required before the directory-signature derived-index fast path is used. Defaults to 10,000 so small workspaces preserve per-file external-edit detection; tests and specialized SDK hosts may lower it explicitly. */
+    /** Minimum item count required before the directory-signature derived-index fast path is used. Defaults to 500 so small workspaces preserve per-file external-edit detection; tests and specialized SDK hosts may lower it explicitly. */
     derivedIndexMinimumItems?: number;
 }
 /**

package/dist/core/store/item-metadata-cache.js

@@ -4,21 +4,26 @@
  * Reads and writes tracker storage with format-aware helpers for the item metadata cache.
  */
 
-!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]="9af59769-ef30-5386-a290-593fe42d119f")}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]="b956bd21-1ad5-5d38-a03c-fe613b5a8aab")}catch(e){}}();
 import fs from "node:fs/promises";
 import path from "node:path";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { getActiveExtensionRegistrations, hasActiveOnReadHooks, runActiveOnReadHooks, } from "../extensions/index.js";
 import { collectRegisteredItemFieldNames } from "../extensions/item-fields.js";
 import { parseItemDocument } from "../item/item-format.js";
 import { evictOldestMemoEntries } from "../shared/memo.js";
 import { writeFileAtomic } from "../fs/fs-utils.js";
+import { acquireLock } from "../lock/lock.js";
 import { ITEM_FILE_EXTENSIONS, getItemFormatFromPath } from "./paths.js";
-const CACHE_VERSION = 7;
-const DEFAULT_DERIVED_INDEX_MINIMUM_ITEMS = 10_000;
+const CACHE_VERSION = 8;
+/** Minimum item count at which derived-index mutations use cross-process locking. */
+export const DEFAULT_DERIVED_INDEX_MINIMUM_ITEMS = 500;
+const DERIVED_INDEX_LOCK_ID = "metadata-derived-index";
 const CACHE_FILENAME = "metadata-cache.json";
 const BODY_CACHE_FILENAME = "metadata-cache-bodies.json";
 const COLLECTIONS_CACHE_FILENAME = "metadata-cache-collections.json";
+const DELTA_CACHE_FILENAME = "metadata-cache-delta.json";
+const MANIFEST_CACHE_FILENAME = "metadata-cache-manifest.json";
 /** Heavy "collection" item-metadata fields. These arrays dominate the on-disk cache (e.g. a single item's comment thread can be hundreds of KB) yet the hot list path (`pm list`, stats, deps, activity, calendar, close) never reads them. They are stored in a separate collections cache that is parsed only when a caller opts in (`includeCollections`), keeping the always-loaded light cache an order of magnitude smaller and its JSON.parse correspondingly cheaper. */
 export const HEAVY_METADATA_KEYS = [
     "comments",
@@ -76,6 +81,12 @@ function getBodyCachePath(pmRoot) {
 function getCollectionsCachePath(pmRoot) {
     return path.join(pmRoot, "runtime", COLLECTIONS_CACHE_FILENAME);
 }
+function getDeltaCachePath(pmRoot) {
+    return path.join(pmRoot, "runtime", DELTA_CACHE_FILENAME);
+}
+function getManifestCachePath(pmRoot) {
+    return path.join(pmRoot, "runtime", MANIFEST_CACHE_FILENAME);
+}
 /**
  * In-process memo of parsed cache envelopes keyed by cache file path and validated
  * against the file's stat signature on every load. Commands that scan the corpus more
@@ -91,6 +102,70 @@ function getCollectionsCachePath(pmRoot) {
  */
 const ENVELOPE_MEMO_MAX_ENTRIES = 24;
 const envelopeMemo = new Map();
+const projectedBaseCursor = new WeakMap();
+function baseCursorFor(envelope) {
+    return projectedBaseCursor.get(envelope) ?? envelope.source_cursor;
+}
+function applyMetadataDelta(envelope, delta) {
+    const baseCursor = baseCursorFor(envelope);
+    if (delta.base_source_cursor !== baseCursor ||
+        envelope.source_cursor === delta.source_cursor) {
+        return;
+    }
+    projectedBaseCursor.set(envelope, baseCursor);
+    for (const [relativePath, change] of Object.entries(delta.changes)) {
+        if (change.entry)
+            envelope.entries[relativePath] = change.entry;
+        else
+            delete envelope.entries[relativePath];
+    }
+    envelope.directory_signatures = delta.directory_signatures;
+    envelope.source_cursor = delta.source_cursor;
+}
+function applyBodyDelta(envelope, delta) {
+    if (!envelope)
+        return;
+    const baseCursor = baseCursorFor(envelope);
+    if (delta.base_source_cursor !== baseCursor ||
+        envelope.source_cursor === delta.source_cursor) {
+        return;
+    }
+    projectedBaseCursor.set(envelope, baseCursor);
+    for (const [relativePath, change] of Object.entries(delta.changes)) {
+        if (change.body)
+            envelope.bodies[relativePath] = change.body;
+        else
+            delete envelope.bodies[relativePath];
+    }
+    envelope.source_cursor = delta.source_cursor;
+}
+function applyCollectionsDelta(envelope, delta) {
+    if (!envelope)
+        return;
+    const baseCursor = baseCursorFor(envelope);
+    if (delta.base_source_cursor !== baseCursor ||
+        envelope.source_cursor === delta.source_cursor) {
+        return;
+    }
+    projectedBaseCursor.set(envelope, baseCursor);
+    for (const [relativePath, change] of Object.entries(delta.changes)) {
+        if (change.collections)
+            envelope.collections[relativePath] = change.collections;
+        else
+            delete envelope.collections[relativePath];
+    }
+    envelope.source_cursor = delta.source_cursor;
+}
+function applyDerivedIndexDelta(metadata, bodies, collections, delta) {
+    if (!metadata ||
+        !delta ||
+        metadata.context_fingerprint !== delta.context_fingerprint) {
+        return;
+    }
+    applyMetadataDelta(metadata, delta);
+    applyBodyDelta(bodies, delta);
+    applyCollectionsDelta(collections, delta);
+}
 function memoizeEnvelope(cachePath, entry) {
     if (envelopeMemo.size >= ENVELOPE_MEMO_MAX_ENTRIES &&
         !envelopeMemo.has(cachePath)) {
@@ -143,6 +218,7 @@ async function loadCache(pmRoot) {
     return await loadEnvelopeMemoized(getCachePath(pmRoot), (raw) => {
         const parsed = JSON.parse(raw);
         if (parsed.version !== CACHE_VERSION ||
+            typeof parsed.source_cursor !== "string" ||
             typeof parsed.entries !== "object" ||
             parsed.entries === null) {
             return null;
@@ -154,6 +230,7 @@ async function loadBodyCache(pmRoot) {
     return await loadEnvelopeMemoized(getBodyCachePath(pmRoot), (raw) => {
         const parsed = JSON.parse(raw);
         if (parsed.version !== CACHE_VERSION ||
+            typeof parsed.source_cursor !== "string" ||
             typeof parsed.bodies !== "object" ||
             parsed.bodies === null) {
             return null;
@@ -165,6 +242,7 @@ async function loadCollectionsCache(pmRoot) {
     return await loadEnvelopeMemoized(getCollectionsCachePath(pmRoot), (raw) => {
         const parsed = JSON.parse(raw);
         if (parsed.version !== CACHE_VERSION ||
+            typeof parsed.source_cursor !== "string" ||
             typeof parsed.collections !== "object" ||
             parsed.collections === null) {
             return null;
@@ -172,6 +250,53 @@ async function loadCollectionsCache(pmRoot) {
         return parsed;
     });
 }
+async function loadDerivedIndexDelta(pmRoot) {
+    const deltaPath = getDeltaCachePath(pmRoot);
+    const envelope = await loadEnvelopeMemoized(deltaPath, (raw) => {
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== CACHE_VERSION ||
+            typeof parsed.base_source_cursor !== "string" ||
+            typeof parsed.source_cursor !== "string" ||
+            typeof parsed.changes !== "object" ||
+            parsed.changes === null) {
+            return null;
+        }
+        return parsed;
+    });
+    if (envelope)
+        return { envelope, invalid: false };
+    try {
+        await fs.stat(deltaPath);
+        return { envelope: null, invalid: true };
+    }
+    catch {
+        return { envelope: null, invalid: false };
+    }
+}
+async function loadDerivedIndexManifest(pmRoot) {
+    const manifestPath = getManifestCachePath(pmRoot);
+    const manifest = await loadEnvelopeMemoized(manifestPath, (raw) => {
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== CACHE_VERSION ||
+            typeof parsed.context_fingerprint !== "string" ||
+            typeof parsed.source_cursor !== "string" ||
+            !Number.isInteger(parsed.entry_count) ||
+            parsed.entry_count < 0) {
+            return null;
+        }
+        return parsed;
+    });
+    if (manifest)
+        return manifest;
+    try {
+        await fs.stat(manifestPath);
+        await removeDerivedIndexFiles(pmRoot);
+    }
+    catch {
+        // Missing manifests are the normal pre-index and small-workspace state.
+    }
+    return null;
+}
 async function persistCache(cachePath, envelope) {
     await fs.mkdir(path.dirname(cachePath), { recursive: true });
     await writeFileAtomic(cachePath, JSON.stringify(envelope));
@@ -256,10 +381,7 @@ async function readDirectorySignature(pmRoot, folder) {
         ];
     }
     catch {
-        return [
-            folder,
-            { exists: false, mtime_ms: 0, ctime_ms: 0, size: 0 },
-        ];
+        return [folder, { exists: false, mtime_ms: 0, ctime_ms: 0, size: 0 }];
     }
 }
 async function readDirectorySignatures(pmRoot, folders) {
@@ -464,12 +586,24 @@ async function persistMetadataCacheIfNeeded(params) {
         params.existingCache.context_fingerprint === params.contextFingerprint) {
         return;
     }
-    await persistCache(getCachePath(params.pmRoot), {
-        version: CACHE_VERSION,
-        context_fingerprint: params.contextFingerprint,
-        directory_signatures: params.directorySignatures,
-        entries: params.state.newEntries,
-    }).catch(() => { });
+    try {
+        await persistCache(getCachePath(params.pmRoot), {
+            version: CACHE_VERSION,
+            context_fingerprint: params.contextFingerprint,
+            source_cursor: params.sourceCursor,
+            directory_signatures: params.directorySignatures,
+            entries: params.state.newEntries,
+        });
+        await persistCache(getManifestCachePath(params.pmRoot), {
+            version: CACHE_VERSION,
+            context_fingerprint: params.contextFingerprint,
+            source_cursor: params.sourceCursor,
+            entry_count: Object.keys(params.state.newEntries).length,
+        });
+    }
+    catch {
+        // Cache persistence is best-effort; authoritative item reads rebuild it.
+    }
 }
 async function persistBodyCacheIfNeeded(params) {
     const bodyDirty = params.state.misses.body ||
@@ -483,6 +617,7 @@ async function persistBodyCacheIfNeeded(params) {
     await persistCache(getBodyCachePath(params.pmRoot), {
         version: CACHE_VERSION,
         context_fingerprint: params.contextFingerprint,
+        source_cursor: params.sourceCursor,
         bodies: params.state.newBodies,
     }).catch(() => { });
 }
@@ -499,16 +634,135 @@ async function persistCollectionsCacheIfNeeded(params) {
     await persistCache(getCollectionsCachePath(params.pmRoot), {
         version: CACHE_VERSION,
         context_fingerprint: params.contextFingerprint,
+        source_cursor: params.sourceCursor,
         collections: params.state.newCollections,
     }).catch(() => { });
 }
+/** Acquire the cross-process derived-index writer lock when an index exists. */
+export async function acquireItemMetadataDerivedIndexLock(pmRoot, author) {
+    const cache = await loadDerivedIndexManifest(pmRoot);
+    if (cache === null ||
+        cache.entry_count < DEFAULT_DERIVED_INDEX_MINIMUM_ITEMS) {
+        return async () => { };
+    }
+    return acquireLock(pmRoot, DERIVED_INDEX_LOCK_ID, 30, author, false, false, 3_000);
+}
+function relativeIndexPath(pmRoot, itemPath) {
+    const relative = path.relative(pmRoot, itemPath);
+    return relative === "" ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`) ||
+        path.isAbsolute(relative)
+        ? null
+        : relative;
+}
+async function removeDerivedIndexFiles(pmRoot) {
+    await Promise.all([
+        getCachePath(pmRoot),
+        getBodyCachePath(pmRoot),
+        getCollectionsCachePath(pmRoot),
+        getDeltaCachePath(pmRoot),
+        getManifestCachePath(pmRoot),
+    ].map(async (cachePath) => {
+        await fs.rm(cachePath, { force: true });
+        envelopeMemo.delete(cachePath);
+    }));
+}
+async function createDerivedIndexDeltaChange(params) {
+    if (params.mutation.document === null) {
+        return { entry: null, body: null, collections: null };
+    }
+    const stat = await fs.stat(params.mutation.itemPath);
+    const split = splitHeavyMetadata(params.mutation.document.metadata);
+    const signature = {
+        mtime_ms: stat.mtimeMs,
+        ctime_ms: stat.ctimeMs,
+        size: stat.size,
+    };
+    return {
+        entry: {
+            ...signature,
+            metadata: split.light,
+            body_length: params.mutation.document.body.length,
+        },
+        body: { ...signature, body: params.mutation.document.body },
+        collections: {
+            ...signature,
+            collections: split.heavy,
+        },
+    };
+}
+function selectDerivedIndexDeltaChanges(delta, contextFingerprint, baseSourceCursor) {
+    return delta?.context_fingerprint === contextFingerprint &&
+        delta.base_source_cursor === baseSourceCursor
+        ? structuredClone(delta.changes)
+        : {};
+}
+/**
+ * Project one already-committed authoritative item write into every compatible
+ * derived-index tier. Callers hold {@link acquireItemMetadataDerivedIndexLock}
+ * from before the item write until this function finishes, so independent pm
+ * mutations cannot publish a cursor that omits a concurrent write. One small
+ * atomic delta carries the shared source cursor and all tier projections, so
+ * mutation cost is bounded by changed items instead of total workspace size.
+ * Any refresh failure deletes the rebuildable cache so the next read scans.
+ */
+export async function refreshItemMetadataDerivedIndex(mutation) {
+    const relativePath = relativeIndexPath(mutation.pmRoot, mutation.itemPath);
+    const previousRelativePath = mutation.previousItemPath
+        ? relativeIndexPath(mutation.pmRoot, mutation.previousItemPath)
+        : undefined;
+    if (relativePath === null || previousRelativePath === null) {
+        await removeDerivedIndexFiles(mutation.pmRoot);
+        return ["metadata_derived_index_path_invalidated"];
+    }
+    try {
+        const contextFingerprint = computeContextFingerprint(mutation.preferredFormat, mutation.typeToFolder, mutation.schema, resolveActiveExtensionFieldNames());
+        const existingCache = await loadDerivedIndexManifest(mutation.pmRoot);
+        if (existingCache === null ||
+            existingCache.context_fingerprint !== contextFingerprint) {
+            return [];
+        }
+        const baseSourceCursor = existingCache.source_cursor;
+        const delta = await loadDerivedIndexDelta(mutation.pmRoot);
+        if (delta.invalid) {
+            await removeDerivedIndexFiles(mutation.pmRoot);
+            return ["metadata_derived_index_refresh_failed"];
+        }
+        const changes = selectDerivedIndexDeltaChanges(delta.envelope, contextFingerprint, baseSourceCursor);
+        if (previousRelativePath !== undefined) {
+            changes[previousRelativePath] = {
+                entry: null,
+                body: null,
+                collections: null,
+            };
+        }
+        changes[relativePath] = await createDerivedIndexDeltaChange({ mutation });
+        await persistCache(getDeltaCachePath(mutation.pmRoot), {
+            version: CACHE_VERSION,
+            context_fingerprint: contextFingerprint,
+            base_source_cursor: baseSourceCursor,
+            source_cursor: randomUUID(),
+            directory_signatures: await readDirectorySignatures(mutation.pmRoot, [
+                ...new Set(Object.values(mutation.typeToFolder)),
+            ]),
+            changes,
+        });
+        return [];
+    }
+    catch {
+        await removeDerivedIndexFiles(mutation.pmRoot).catch(() => { });
+        return ["metadata_derived_index_refresh_failed"];
+    }
+}
 function sortedCachedDocumentCandidates(state) {
     return [...state.documentsById.values()]
         .sort((left, right) => left.candidate.metadata.id.localeCompare(right.candidate.metadata.id))
         .map((entry) => entry.candidate);
 }
-function cacheTierMatchesContext(envelope, contextFingerprint) {
-    return envelope?.context_fingerprint === contextFingerprint;
+function cacheTierMatchesContext(envelope, contextFingerprint, sourceCursor) {
+    return (envelope?.context_fingerprint === contextFingerprint &&
+        envelope.source_cursor === sourceCursor);
 }
 function hasEveryDerivedIndexPart(keys, includeBody, includeCollections, previousBodies, previousCollections) {
     return keys.every((key) => (!includeBody || previousBodies[key] !== undefined) &&
@@ -553,9 +807,9 @@ function canUseDerivedIndex(params) {
     }
     const requiredTiersMatch = [
         !params.includeBody ||
-            cacheTierMatchesContext(params.existingBodyCache, params.contextFingerprint),
+            cacheTierMatchesContext(params.existingBodyCache, params.contextFingerprint, params.existingCache.source_cursor),
         !params.includeCollections ||
-            cacheTierMatchesContext(params.existingCollectionsCache, params.contextFingerprint),
+            cacheTierMatchesContext(params.existingCollectionsCache, params.contextFingerprint, params.existingCache.source_cursor),
     ];
     return (requiredTiersMatch.every(Boolean) &&
         hasEveryDerivedIndexPart(params.entryKeys, params.includeBody, params.includeCollections, params.previousBodies, params.previousCollections));
@@ -575,13 +829,17 @@ export async function listAllDocumentCandidatesCached(pmRoot, preferredFormat, t
     const includeCollections = options.includeCollections !== false;
     const extensionFieldNames = resolveActiveExtensionFieldNames();
     const contextFingerprint = computeContextFingerprint(preferredFormat, typeToFolder, schema, extensionFieldNames);
+    const delta = await loadDerivedIndexDelta(pmRoot);
+    if (delta.invalid)
+        await removeDerivedIndexFiles(pmRoot);
     const existingCache = await loadCache(pmRoot);
-    const previousEntries = selectPreviousMetadataEntries(existingCache, contextFingerprint);
     const existingBodyCache = includeBody ? await loadBodyCache(pmRoot) : null;
-    const previousBodies = selectPreviousBodyEntries(existingBodyCache, contextFingerprint);
     const existingCollectionsCache = includeCollections
         ? await loadCollectionsCache(pmRoot)
         : null;
+    applyDerivedIndexDelta(existingCache, existingBodyCache, existingCollectionsCache, delta.envelope);
+    const previousEntries = selectPreviousMetadataEntries(existingCache, contextFingerprint);
+    const previousBodies = selectPreviousBodyEntries(existingBodyCache, contextFingerprint);
     const previousCollections = selectPreviousCollectionEntries(existingCollectionsCache, contextFingerprint);
     const folders = [...new Set(Object.values(typeToFolder))];
     const directorySignaturesBefore = await readDirectorySignatures(pmRoot, folders);
@@ -633,11 +891,19 @@ export async function listAllDocumentCandidatesCached(pmRoot, preferredFormat, t
     const stableDirectorySignatures = directorySignaturesMatch(directorySignaturesBefore, directorySignaturesAfter)
         ? directorySignaturesAfter
         : {};
+    const metadataChanged = state.misses.metadata ||
+        Object.keys(previousEntries).length !==
+            Object.keys(state.newEntries).length ||
+        !directorySignaturesMatch(existingCache?.directory_signatures, stableDirectorySignatures);
+    const sourceCursor = metadataChanged || existingCache === null
+        ? randomUUID()
+        : existingCache.source_cursor;
     // Rewrite a cache file only when its contents changed: any re-parsed (missing or
     // stale) entry, or a different set of keys (additions/deletions).
     await persistMetadataCacheIfNeeded({
         pmRoot,
         contextFingerprint,
+        sourceCursor,
         existingCache,
         previousEntries,
         directorySignatures: stableDirectorySignatures,
@@ -647,6 +913,7 @@ export async function listAllDocumentCandidatesCached(pmRoot, preferredFormat, t
         await persistBodyCacheIfNeeded({
             pmRoot,
             contextFingerprint,
+            sourceCursor,
             existingBodyCache,
             previousBodies,
             state,
@@ -656,6 +923,7 @@ export async function listAllDocumentCandidatesCached(pmRoot, preferredFormat, t
         await persistCollectionsCacheIfNeeded({
             pmRoot,
             contextFingerprint,
+            sourceCursor,
             existingCollectionsCache,
             previousCollections,
             state,
@@ -690,4 +958,4 @@ export async function listAllDocumentsCachedLight(pmRoot, preferredFormat, typeT
     }));
 }
 //# sourceMappingURL=item-metadata-cache.js.map
-//# debugId=9af59769-ef30-5386-a290-593fe42d119f
+//# debugId=b956bd21-1ad5-5d38-a03c-fe613b5a8aab