@unbrained/pm-cli 2026.9.19 → 2026.9.21

package/dist/sdk/query/search.js

@@ -1,3 +1,2 @@
-!(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]="c1f323c4-410f-5e51-ba94-29caaccfbac7")}catch(e2){}})();import{assertInitializedTracker}from"../environment/tracker-preflight.js";import fs from"node:fs/promises";import path from"node:path";import{toNonEmptyStringOrUndefined}from"../../core/shared/primitives.js";import{isPathWithinDirectory}from"../../core/fs/path-utils.js";import{getActiveExtensionRegistrations,runActiveOnReadHooks}from"../../core/extensions/index.js";import{collectRegisteredItemFieldNames}from"../../core/extensions/item-fields.js";import{resolveRegisteredSearchProvider,resolveRegisteredVectorStoreAdapter}from"../../core/extensions/runtime-registrations.js";import{resolveItemTypeRegistry}from"../../core/item/type-registry.js";import{parseLimit}from"./parsers.js";import{parsePriorityFilterSet,parseStringFilterSet,parseTypeFilterSet}from"./multi-value-filters.js";import{resolveProviderConfigSource,executeEmbeddingRequest,resolveEmbeddingProviders}from"../../core/search/providers.js";import{buildDeterministicQueryExpansions,mergeQueryExpansions,normalizeQueryExpansionOutput,normalizeRerankOutput,rerankCandidatesWithEmbeddings,resolveQueryExpansionConfig,resolveRerankConfig}from"../../core/search/relevance.js";import{resolveSettingsWithSemanticRuntimeDefaults}from"../../core/search/semantic-defaults.js";import{executeVectorQuery,resolveVectorStores}from"../../core/search/vector-stores.js";import{readVectorizationStatusLedger}from"../../core/search/cache.js";import{buildEventCorpus,buildPlanFlatCorpus,buildReminderCorpus,buildSearchCorpus,resolveSearchCorpusFields}from"../../core/search/corpus.js";import{buildBm25Index,flattenSearchCorpusText,resolveBm25Params,scoreBm25Query,tokenizeBm25}from"../../core/search/bm25.js";import{collectStaleVectorizationIds}from"../../core/search/staleness.js";import{parseItemDocument}from"../../core/item/item-format.js";import{toItemRecord}from"../../core/item/item-record.js";import{isTerminalStatus}from"../../core/item/status.js";import{parseStatusFilterCsv}from"../../core/item/status-filter.js";import{collectRuntimeFilterValues,matchesRuntimeFilters}from"../../core/schema/runtime-field-filters.js";import{hasMissingMetadataFilter,itemMatchesMissingMetadata,lifecycleClassifierFromStatusRegistry}from"../../core/governance/metadata-coverage.js";import{hasContentFieldFilter,itemMatchesContentFilters}from"../../core/governance/content-fields.js";import{resolveContentFieldFilters,resolveMissingMetadataFilters}from"./list.js";import{buildCompactSearchFilterSummary,buildVerboseSearchFilters}from"./search-rendering.js";import{resolveRuntimeFieldRegistry,resolveRuntimeStatusRegistry}from"../../core/schema/runtime-schema.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{PmCliError}from"../../core/shared/errors.js";import{tokenizeAlphaNumeric}from"../../core/shared/text-normalization.js";import{compareTimestampStrings,matchesTimestampFilters,nowIso}from"../../core/shared/time.js";import{listAllDocumentCandidatesCached}from"../../core/store/item-metadata-cache.js";import{listAllItemMetadata}from"../../core/store/item-store.js";import{getItemPath,resolveGlobalPmRoot,resolvePmRoot}from"../../core/store/paths.js";import{readSettings}from"../../core/store/settings.js";import{resolveSearchPage}from"./search-pagination.js";import{normalizeSearchPhrase,parseMinScoreOverride,parseSearchBoolean,parseSearchDeadline,parseSearchMatchMode,parseSearchProjection,parseSearchTokens,parseSemanticWeightOverride,parseTimestampWindow,resolveEffectiveSearchMode,resolveHybridSemanticWeight,resolveSearchMaxResults,resolveSearchScoreThreshold,resolveSearchTuning,validateSearchProjectionFields}from"./search-contracts.js";import{readWorkspaceMemory,searchWorkspaceMemoryReadResult}from"../workspace-memory.js";import{resolveEffectiveSearchMode as resolveEffectiveSearchMode2,resolveHybridSemanticWeight as resolveHybridSemanticWeight2,resolveSearchMaxResults as resolveSearchMaxResults2,resolveSearchScoreThreshold as resolveSearchScoreThreshold2,resolveSearchTuning as resolveSearchTuning2}from"./search-contracts.js";const LONG_QUERY_TOKEN_THRESHOLD=2;const LONG_QUERY_TITLE_EXACT_BONUS=120;const LONG_QUERY_PHRASE_MULTIPLIER=6;const ALL_TERMS_COVERAGE_BONUS=40;const EXACT_ID_MATCH_SCORE=1e3;const SHORT_ID_MATCH_SCORE=900;const HIGHLIGHT_OPEN="\xAB";const HIGHLIGHT_CLOSE="\xBB";const HIGHLIGHT_SNIPPET_RADIUS=60;const INLINE_QUERY_FILTER_FIELDS=["tag","status","type","priority"];function collectErrorCauseCodes(error){const codes=[];let current=error;for(let depth=0;depth<5&&current&&typeof current==="object";depth+=1){const code=current.code;if(typeof code==="string"){codes.push(code.toLowerCase())}current=current.cause}return codes.join(" ")}function classifyImplicitSemanticFallbackReason(error){const message=(error instanceof Error?error.message:String(error)).toLowerCase();const causeCodes=collectErrorCauseCodes(error);const haystack=`${message} ${causeCodes}`;if(haystack.includes("timed out")||haystack.includes("timeout")||haystack.includes("etimedout")){return"timeout"}if(haystack.includes("econnrefused")||haystack.includes("connection refused")||haystack.includes("connect ")||haystack.includes("enotfound")||haystack.includes("eai_again")||haystack.includes("econnreset")||haystack.includes("fetch failed")){return"connection"}return"error"}function buildExplicitSemanticFallbackWarning(requestedMode,error){const reason=classifyImplicitSemanticFallbackReason(error);return`search_${requestedMode}_fallback:${reason}:using_keyword_mode`}function resolveVectorIndexRecovery(registrations){const hasReindex=registrations?.commands?.some(registration=>registration.command.trim()==="reindex")===true;return hasReindex?{command:"pm reindex --mode hybrid",args:["reindex","--mode","hybrid"]}:{command:"pm install search-advanced --project",args:["install","search-advanced","--project"],follow_up_command:"pm reindex --mode hybrid",follow_up_args:["reindex","--mode","hybrid"]}}async function maybeEmitVectorIndexStaleWarning(pmRoot,filteredDocuments,warnings){try{const ledger=await readVectorizationStatusLedger(pmRoot);if(ledger.warnings.length>0){warnings.push(...ledger.warnings)}const staleIds=collectStaleVectorizationIds(filteredDocuments.map(document=>({id:document.metadata.id,updated_at:document.metadata.updated_at})),ledger.entries);if(staleIds.length===0){return}const recovery=resolveVectorIndexRecovery(getActiveExtensionRegistrations());warnings.push(...formatVectorIndexRecoveryWarnings(staleIds.length,recovery));process.stderr.write(`[pm] warning: ${staleIds.length} item${staleIds.length===1?" is":"s are"} new or modified since the last reindex and ${staleIds.length===1?"is":"are"} NOT in the semantic index yet \u2014 run '${recovery.command}'${recovery.follow_up_command?`, then '${recovery.follow_up_command}'`:""}. (Write-time embedding is governed by search.mutation_refresh_policy; staleness means the embed was skipped, failed, or the backend was unreachable.)
-`)}catch{}}function formatVectorIndexRecoveryWarnings(staleCount,recovery){return[`vector_index_stale:${staleCount}`,`vector_index_recovery:${recovery.args.join(" ")}`,...recovery.follow_up_args?[`vector_index_recovery_follow_up:${recovery.follow_up_args.join(" ")}`]:[]]}const _testOnlySearchCommand={applyFilters,applyExactQueryFilters,applyInlineQueryFilters,buildHitHighlights,buildVerboseSearchFilters,buildExplicitSemanticFallbackWarning,buildCompactSearchFilterSummary,buildHybridLexicalScore,buildRerankCorpus,buildSemanticHits,classifyImplicitSemanticFallbackReason,collectErrorCauseCodes,collectExactPhraseFields,collectLinkedPaths,combineHybridHits,computeBuiltInBm25Hits,computeSemanticOrHybridHits,resolveBuiltInBm25Mode,countOccurrences,dependencyEntries,documentContainsExactPhrase,emptySearchResult,highlightFieldSnippet,loadDocuments,markTokenRuns,parseInlineQueryFilters,maybeEmitVectorIndexStaleWarning,loadLinkedCorpus,mergeVectorHitsById,normalizeExtensionProviderHits,normalizeScoreMap,parseProjectionConfig:parseSearchProjection,parseTimestampWindow,parseTokens:parseSearchTokens,projectSearchHits,readSearchFieldValue,requireSemanticDependencies,resolveExtensionSearchProvider,resolveExtensionSearchProviderByName,resolveExtensionVectorAdapter,resolveLinkedCorpusRoots,scoreDocument,sortHits,stringArray,textEntries,validateSearchProjectionFields};function parseInlineQueryFilters(query){const inlineFilters={};const residualTokens=[];for(const token of query.split(/\s+/).filter(entry=>entry.length>0)){const separatorIndex=token.indexOf(":");const field=separatorIndex>0?token.slice(0,separatorIndex).toLowerCase():"";const value=separatorIndex>0?token.slice(separatorIndex+1):"";const matchedField=INLINE_QUERY_FILTER_FIELDS.includes(field)?field:void 0;if(matchedField&&value.length>0&&inlineFilters[matchedField]===void 0){inlineFilters[matchedField]=value;continue}residualTokens.push(token)}return{residualQuery:residualTokens.join(" "),inlineFilters}}function applyInlineQueryFilters(options,inlineFilters,warnings){const merged={...options};for(const field of INLINE_QUERY_FILTER_FIELDS){const inlineValue=inlineFilters[field];if(inlineValue===void 0){continue}if(toNonEmptyStringOrUndefined(merged[field])!==void 0){warnings.push(`search_inline_filter_ignored:${field}:flag_takes_precedence`);continue}merged[field]=inlineValue}return merged}function stringArray(value){return Array.isArray(value)?value.filter(entry=>typeof entry==="string"):[]}function textEntries(value){return Array.isArray(value)?value.filter(entry=>typeof entry==="object"&&entry!==null&&typeof entry.text==="string"):[]}function dependencyEntries(value){return Array.isArray(value)?value.filter(entry=>typeof entry==="object"&&entry!==null&&typeof entry.id==="string"&&typeof entry.kind==="string"):[]}function collectExactPhraseFields(document){const item=document.metadata;return[item.title,item.description,item.status,stringArray(item.tags).join(" "),document.body,textEntries(item.comments).map(entry=>entry.text).join(" "),textEntries(item.notes).map(entry=>entry.text).join(" "),textEntries(item.learnings).map(entry=>entry.text).join(" "),buildReminderCorpus(item).join(" "),buildEventCorpus(item).join(" "),dependencyEntries(item.dependencies).map(entry=>`${entry.id} ${entry.kind}`).join(" "),buildPlanFlatCorpus(item)]}function documentContainsExactPhrase(document,normalizedQuery){return collectExactPhraseFields(document).some(fieldValue=>normalizeSearchPhrase(fieldValue).includes(normalizedQuery))}function applyExactQueryFilters(items,normalizedQuery,options){if(!options.titleExact&&!options.phraseExact){return items}return items.filter(document=>{if(options.titleExact&&normalizeSearchPhrase(document.metadata.title)!==normalizedQuery){return false}if(options.phraseExact&&!documentContainsExactPhrase(document,normalizedQuery)){return false}return true})}function assertSearchAssigneeFilter(assigneeFilter){if(assigneeFilter&&[...assigneeFilter].some(value=>value.toLowerCase()==="none"||value.toLowerCase()==="null")){throw new PmCliError('--assignee no longer accepts "none" or "null".',EXIT_CODE.USAGE)}}function resolveSearchMetadataFilterSet(options,typeRegistry,statusFilter){const assigneeFilter=parseStringFilterSet(options.assignee,{label:"--assignee"});assertSearchAssigneeFilter(assigneeFilter);const missingMetadataFilters=resolveMissingMetadataFilters(options);const contentFieldFilters=resolveContentFieldFilters(options);return{typeFilter:parseTypeFilterSet(options.type,typeRegistry),tagFilter:parseStringFilterSet(options.tag,{label:"--tag",normalize:tag=>tag.toLowerCase()}),priorityFilter:parsePriorityFilterSet(options.priority),deadlineBefore:parseSearchDeadline(options.deadlineBefore,"deadline-before"),deadlineAfter:parseSearchDeadline(options.deadlineAfter,"deadline-after"),updatedAfter:parseTimestampWindow(options.updatedAfter,"updated-after"),updatedBefore:parseTimestampWindow(options.updatedBefore,"updated-before"),createdAfter:parseTimestampWindow(options.createdAfter,"created-after"),createdBefore:parseTimestampWindow(options.createdBefore,"created-before"),assigneeFilter,sprintFilter:parseStringFilterSet(options.sprint,{label:"--sprint"}),releaseFilter:parseStringFilterSet(options.release,{label:"--release"}),parentFilter:options.parent?.trim(),statusSet:statusFilter&&statusFilter.length>0?new Set(statusFilter):void 0,missingMetadataFilters,missingMetadataActive:hasMissingMetadataFilter(missingMetadataFilters),contentFieldFilters,contentFiltersActive:hasContentFieldFilter(contentFieldFilters)}}function matchesScalarSearchFilters(item,filters){return matchesIdentitySearchFilters(item,filters)&&matchesTimestampSearchFilters(item,filters)&&matchesOwnerSearchFilters(item,filters)}function matchesIdentitySearchFilters(item,filters){if(filters.statusSet&&!filters.statusSet.has(item.status))return false;if(filters.typeFilter&&!filters.typeFilter.has(item.type))return false;const tagFilter=filters.tagFilter;if(tagFilter&&!stringArray(item.tags).some(tag=>tagFilter.has(tag)))return false;if(filters.priorityFilter!==void 0&&!filters.priorityFilter.has(item.priority))return false;return true}function matchesTimestampSearchFilters(item,filters){return matchesTimestampFilters(item,filters)}function matchesOwnerSearchFilters(item,filters){if(filters.assigneeFilter!==void 0&&(item.assignee===void 0||!filters.assigneeFilter.has(item.assignee)))return false;if(filters.sprintFilter!==void 0&&(item.sprint===void 0||!filters.sprintFilter.has(item.sprint)))return false;if(filters.releaseFilter!==void 0&&(item.release===void 0||!filters.releaseFilter.has(item.release)))return false;if(filters.parentFilter!==void 0&&item.parent!==filters.parentFilter)return false;return true}function matchesSearchMetadataFilters(document,filters,runtimeFieldFilters,lifecycleClassifier){const item=document.metadata;if(!matchesScalarSearchFilters(item,filters)){return false}if(!matchesRuntimeFilters(item,runtimeFieldFilters)){return false}if(filters.missingMetadataActive&&!itemMatchesMissingMetadata(item,filters.missingMetadataFilters,lifecycleClassifier)){return false}if(filters.contentFiltersActive&&!itemMatchesContentFilters(item,filters.contentFieldFilters)){return false}return true}function applyFilters(items,options,typeRegistry,runtimeFieldFilters,statusFilter,lifecycleClassifier){const filters=resolveSearchMetadataFilterSet(options,typeRegistry,statusFilter);return items.filter(document=>matchesSearchMetadataFilters(document,filters,runtimeFieldFilters,lifecycleClassifier))}function countOccurrences(haystack,needle){let count=0;let index=0;while(true){const foundAt=haystack.indexOf(needle,index);if(foundAt<0){return count}count+=1;index=foundAt+needle.length}}function tokenizeForExactTokenMatch(value){return tokenizeAlphaNumeric(value)}function collectLinkedPaths(item){const fromFiles=(item.files??[]).map(entry=>({scope:entry.scope,path:entry.path.trim()}));const fromDocs=(item.docs??[]).map(entry=>({scope:entry.scope,path:entry.path.trim()}));const fromTests=(item.tests??[]).filter(entry=>typeof entry.path==="string"&&entry.path.trim().length>0).map(entry=>({scope:entry.scope,path:entry.path.trim()}));const sorted=[...fromFiles,...fromDocs,...fromTests].filter(entry=>entry.path.length>0).sort((a,b)=>a.scope.localeCompare(b.scope)||a.path.localeCompare(b.path));const deduped=new Map;for(const entry of sorted){deduped.set(`${entry.scope}:${entry.path}`,entry)}return[...deduped.values()]}async function resolveContainmentRoot(root){const resolved=path.resolve(root);try{const realpathRoot=await fs.realpath(resolved);return{resolved,realpath:realpathRoot}}catch{return null}}async function resolveLinkedCorpusRoots(projectRoot,globalRoot){const[projectContainmentRoot,globalContainmentRoot]=await Promise.all([resolveContainmentRoot(projectRoot),resolveContainmentRoot(globalRoot)]);return{projectContainmentRoot,globalContainmentRoot}}async function loadLinkedCorpus(document,roots){const linkedPaths=collectLinkedPaths(document.metadata);const chunks=[];for(const linkedPath of linkedPaths){const containmentRoot=linkedPath.scope==="global"?roots.globalContainmentRoot:roots.projectContainmentRoot;if(!containmentRoot){continue}const resolved=path.resolve(containmentRoot.resolved,linkedPath.path);if(!isPathWithinDirectory(containmentRoot.resolved,resolved)){continue}let linkedRealpath;try{linkedRealpath=await fs.realpath(resolved)}catch{continue}if(!isPathWithinDirectory(containmentRoot.realpath,linkedRealpath)){continue}try{await runActiveOnReadHooks({path:resolved,scope:linkedPath.scope});chunks.push(await fs.readFile(resolved,"utf8"))}catch{}}return chunks.join("\n")}const SEARCHABLE_FIELD_BUILDERS=[{name:"title",weightKey:"title_weight",value:document=>document.metadata.title},{name:"description",weightKey:"description_weight",value:document=>document.metadata.description},{name:"tags",weightKey:"tags_weight",value:document=>stringArray(document.metadata.tags).join(" ")},{name:"status",weightKey:"status_weight",value:document=>typeof document.metadata.status==="string"?document.metadata.status:""},{name:"body",weightKey:"body_weight",value:document=>document.body},{name:"comments",weightKey:"comments_weight",value:document=>textEntries(document.metadata.comments).map(entry=>entry.text).join(" ")},{name:"notes",weightKey:"notes_weight",value:document=>textEntries(document.metadata.notes).map(entry=>entry.text).join(" ")},{name:"learnings",weightKey:"learnings_weight",value:document=>textEntries(document.metadata.learnings).map(entry=>entry.text).join(" ")},{name:"reminders",weightKey:"reminders_weight",value:document=>buildReminderCorpus(document.metadata).join(" ")},{name:"events",weightKey:"events_weight",value:document=>buildEventCorpus(document.metadata).join(" ")},{name:"dependencies",weightKey:"dependencies_weight",value:document=>dependencyEntries(document.metadata.dependencies).map(entry=>`${entry.id} ${entry.kind}`).join(" ")},{name:"plan",weightKey:"body_weight",value:document=>buildPlanFlatCorpus(document.metadata)}];const SEARCHABLE_FIELD_BUILDER_BY_NAME=new Map(SEARCHABLE_FIELD_BUILDERS.map(builder=>[builder.name,builder]));function escapeRegExpLiteral(value){return value.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}function markTokenRuns(text,tokens){const escaped=tokens.filter(token=>token.length>0).sort((left,right)=>right.length-left.length).map(escapeRegExpLiteral);if(escaped.length===0){return text}const pattern=new RegExp(escaped.join("|"),"gi");return text.replace(pattern,match=>`${HIGHLIGHT_OPEN}${match}${HIGHLIGHT_CLOSE}`)}function highlightFieldSnippet(text,tokens){if(text.length===0){return null}const lowerText=text.toLowerCase();let firstMatchIndex=-1;let firstMatchLength=0;for(const token of tokens){if(token.length===0){continue}const index=lowerText.indexOf(token);if(index>=0&&(firstMatchIndex<0||index<firstMatchIndex)){firstMatchIndex=index;firstMatchLength=token.length}}if(firstMatchIndex<0){return null}const windowStart=Math.max(0,firstMatchIndex-HIGHLIGHT_SNIPPET_RADIUS);const windowEnd=Math.min(text.length,firstMatchIndex+firstMatchLength+HIGHLIGHT_SNIPPET_RADIUS);const marked=markTokenRuns(text.slice(windowStart,windowEnd),tokens);const prefix=windowStart>0?"\u2026":"";const suffix=windowEnd<text.length?"\u2026":"";return`${prefix}${marked}${suffix}`}function buildHitHighlights(document,matchedFields,tokens){const highlights=[];for(const field of matchedFields){const builder=SEARCHABLE_FIELD_BUILDER_BY_NAME.get(field);if(builder===void 0){continue}const snippet=highlightFieldSnippet(builder.value(document),tokens);if(snippet!==null){highlights.push({field,snippet})}}return highlights}function buildSearchableScoringFields(document,linkedCorpus,tuning){return[...SEARCHABLE_FIELD_BUILDERS.map(builder=>({name:builder.name,value:builder.value(document),weight:tuning[builder.weightKey]})),{name:"linked_content",value:linkedCorpus,weight:tuning.linked_content_weight}]}function buildExactIdSearchHit(item,normalizedQuery,idPrefix){const normalizedId=normalizeSearchPhrase(item.id);const normalizedIdPrefix=typeof idPrefix==="string"?idPrefix.trim().toLowerCase():"";const normalizedIdPrefixPhrase=normalizeSearchPhrase(normalizedIdPrefix);const normalizedShortId=normalizedIdPrefixPhrase.length>0&&normalizedId.startsWith(normalizedIdPrefixPhrase)?normalizedId.slice(normalizedIdPrefixPhrase.length).trim():normalizedId;if(normalizedQuery!==normalizedId&&normalizedQuery!==normalizedShortId){return null}return{item,score:normalizedQuery===normalizedId?EXACT_ID_MATCH_SCORE:SHORT_ID_MATCH_SCORE,matched_fields:["id"],matched_all_terms:true,exact_id_match:true}}function scoreTokenMatches(tokens,titleTokenCounts,searchableFields,tuning,state){for(const token of tokens){const exactTitleMatches=titleTokenCounts.get(token)??0;if(exactTitleMatches>0){state.score+=exactTitleMatches*tuning.title_exact_bonus;state.matched.add("title");state.matchedTokens.add(token)}for(const field of searchableFields){const occurrences=countOccurrences(field.value.toLowerCase(),token);if(occurrences>0){state.score+=occurrences*field.weight;state.matched.add(field.name);state.matchedTokens.add(token)}}}}function scorePhraseMatches(item,normalizedQuery,searchableFields,state){const normalizedTitle=normalizeSearchPhrase(item.title);if(normalizedTitle===normalizedQuery){state.score+=LONG_QUERY_TITLE_EXACT_BONUS;state.matched.add("title")}for(const field of searchableFields){const phraseOccurrences=countOccurrences(normalizeSearchPhrase(field.value),normalizedQuery);if(phraseOccurrences>0){state.score+=phraseOccurrences*field.weight*LONG_QUERY_PHRASE_MULTIPLIER;state.matched.add(field.name)}}}function scoreDocument(document,tokens,normalizedQuery,linkedCorpus,tuning,idPrefix,applyCoverageBonus=false){const item=document.metadata;const exactIdHit=buildExactIdSearchHit(item,normalizedQuery,idPrefix);if(exactIdHit){return exactIdHit}const titleTokenCounts=new Map;for(const token of tokenizeForExactTokenMatch(item.title)){titleTokenCounts.set(token,(titleTokenCounts.get(token)??0)+1)}const searchableFields=buildSearchableScoringFields(document,linkedCorpus,tuning);const state={score:0,matched:new Set,matchedTokens:new Set};scoreTokenMatches(tokens,titleTokenCounts,searchableFields,tuning,state);const distinctTokens=new Set(tokens);const matchedAllTerms=distinctTokens.size>0&&state.matchedTokens.size===distinctTokens.size;if(applyCoverageBonus&&distinctTokens.size>1&&matchedAllTerms){state.score+=ALL_TERMS_COVERAGE_BONUS}const isLongPhraseQuery=tokens.length>=LONG_QUERY_TOKEN_THRESHOLD&&normalizedQuery.includes(" ");if(isLongPhraseQuery){scorePhraseMatches(item,normalizedQuery,searchableFields,state)}if(state.score<=0){return null}return{item,score:state.score,matched_fields:[...state.matched].sort((a,b)=>a.localeCompare(b)),matched_all_terms:matchedAllTerms}}function sortHits(items,statusRegistry){return[...items].sort((a,b)=>{const byScore=b.score-a.score;if(byScore!==0)return byScore;const aTerminal=isTerminalStatus(a.item.status,statusRegistry);const bTerminal=isTerminalStatus(b.item.status,statusRegistry);if(aTerminal!==bTerminal){return aTerminal?1:-1}const byPriority=a.item.priority-b.item.priority;if(byPriority!==0)return byPriority;const byUpdated=compareTimestampStrings(b.item.updated_at,a.item.updated_at);if(byUpdated!==0)return byUpdated;return a.item.id.localeCompare(b.item.id)})}function buildHybridLexicalScore(document,tokens,normalizedQuery,includeLinked,linkedCorpusById,tuning,idPrefix,applyCoverageBonus=false){return scoreDocument(document,tokens,normalizedQuery,includeLinked?linkedCorpusById.get(document.metadata.id)??"":"",tuning,idPrefix,applyCoverageBonus)}function normalizeScoreMap(scoreById){if(scoreById.size===0){return new Map}const values=[...scoreById.values()];const minScore=Math.min(...values);const maxScore=Math.max(...values);if(maxScore===minScore){return new Map([...scoreById.keys()].map(id=>[id,1]))}const normalized=new Map;for(const[id,score]of scoreById){normalized.set(id,(score-minScore)/(maxScore-minScore))}return normalized}function emptySearchResult(query,mode,matchMode,options,includeLinked,scoreThreshold,hybridSemanticWeight,queryExpansion,rerank,projection,warnings,runtimeFieldFilters,countOnly,modeSource){const countExtras=countOnly?{total:0,count_only:true}:{};const compactSummaryMode=projection.mode==="compact"&&options.compact===true;if(compactSummaryMode){const compactFilters=buildCompactSearchFilterSummary({mode,matchMode,options,includeLinked,titleExact:options.titleExact===true,phraseExact:options.phraseExact===true,scoreThreshold,hybridSemanticWeight,runtimeFieldFilters});return{query:query.trim(),mode,...compactModeSource(modeSource),items:[],count:0,...countExtras,filters:compactFilters,...warnings.length>0?{warnings}:{}}}const projectionFields=projection.mode==="full"?null:[...projection.fields];return{query:query.trim(),mode,mode_source:modeSource,items:[],count:0,...countExtras,filters:buildVerboseSearchFilters({effectiveMode:mode,matchMode,options,includeLinked,titleExact:options.titleExact===true,phraseExact:options.phraseExact===true,scoreThreshold,hybridSemanticWeight,queryExpansion,rerank,runtimeFieldFilters:runtimeFieldFilters??{}}),projection:{mode:projection.mode,fields:projectionFields},now:nowIso(),...warnings.length>0?{warnings}:{}}}function requireSemanticDependencies(requestedMode,providerResolution,vectorResolution,hasExtensionVectorQuery){if(!providerResolution.active){throw new PmCliError(`Search mode '${requestedMode}' requires a configured embedding provider in settings.providers.openai or settings.providers.ollama`,EXIT_CODE.USAGE)}if(!vectorResolution.active&&!hasExtensionVectorQuery){throw new PmCliError(`Search mode '${requestedMode}' requires a configured vector store in settings.vector_store.qdrant/settings.vector_store.lancedb or an extension adapter selected by settings.vector_store.adapter`,EXIT_CODE.USAGE)}return{provider:providerResolution.active,vectorStore:vectorResolution.active??null}}const toOptionalNonEmptyString=toNonEmptyStringOrUndefined;function resolveExtensionSearchProviderByName(providerName){const registrations=getActiveExtensionRegistrations();const resolved=resolveRegisteredSearchProvider(registrations,providerName);if(!resolved){return null}const runtimeDefinition=resolved.runtime_definition??resolved.definition;const query=runtimeDefinition.query;const queryExpansion=runtimeDefinition.queryExpansion??runtimeDefinition.query_expansion;const rerank=runtimeDefinition.rerank;const registeredName=toOptionalNonEmptyString(runtimeDefinition.name)??toOptionalNonEmptyString(resolved.definition.name)??providerName;if(!registeredName){return null}const hooks={providerName:registeredName,...typeof query==="function"?{query}:{},...typeof queryExpansion==="function"?{queryExpansion}:{},...typeof rerank==="function"?{rerank}:{}};if(!hooks.query&&!hooks.queryExpansion&&!hooks.rerank){return null}return hooks}function resolveExtensionSearchProvider(settings){const providerName=toOptionalNonEmptyString(settings.search?.provider);const resolved=resolveExtensionSearchProviderByName(providerName);if(!resolved?.query){return null}return{providerName:resolved.providerName,query:resolved.query}}function resolveExtensionVectorAdapter(settings){const registrations=getActiveExtensionRegistrations();const adapterName=toOptionalNonEmptyString(settings.vector_store?.adapter);const resolved=resolveRegisteredVectorStoreAdapter(registrations,adapterName);if(!resolved){return null}const runtimeDefinition=resolved.runtime_definition??resolved.definition;const query=runtimeDefinition.query;if(typeof query!=="function"){return null}const upsert=runtimeDefinition.upsert;const runtimeAdapterName=toOptionalNonEmptyString(runtimeDefinition.name)??toOptionalNonEmptyString(resolved.definition.name)??adapterName??"extension";return{adapterName:runtimeAdapterName,query,...typeof upsert==="function"?{upsert}:{}}}function normalizeExtensionProviderHits(providerName,raw,filteredById){const rawHits=Array.isArray(raw)?raw:raw?.hits;if(!Array.isArray(rawHits)){throw new PmCliError(`Extension search provider "${providerName}" must return an array of hits or { hits: [...] }`,EXIT_CODE.GENERIC_FAILURE)}const seen=new Set;const hits=[];for(const rawHit of rawHits){if(typeof rawHit!=="object"||rawHit===null){continue}const id=toOptionalNonEmptyString(rawHit.id);const score=rawHit.score;if(!id||typeof score!=="number"||!Number.isFinite(score)||seen.has(id)){continue}const document=filteredById.get(id);if(!document){continue}const matchedFieldsRaw=rawHit.matched_fields;const matchedFields=Array.isArray(matchedFieldsRaw)&&matchedFieldsRaw.every(entry=>typeof entry==="string")?[...new Set(matchedFieldsRaw.map(entry=>entry.trim()).filter(entry=>entry.length>0))].sort((a,b)=>a.localeCompare(b)):[`provider:${providerName}`];seen.add(id);hits.push({item:document.metadata,score,matched_fields:matchedFields})}return hits}function buildSemanticHits(vectorHits,filteredById){const semanticHits=[];const semanticScores=new Map;for(const vectorHit of vectorHits){if(semanticScores.has(vectorHit.id)){continue}const document=filteredById.get(vectorHit.id);if(!document){continue}semanticScores.set(vectorHit.id,vectorHit.score);semanticHits.push({item:document.metadata,score:vectorHit.score,matched_fields:["semantic"]})}return{semanticHits,semanticScores}}function forceExactIdHitsToTop(rankedHits,keywordHits){const exactIdHits=keywordHits.filter(hit=>hit.exact_id_match===true);if(exactIdHits.length===0){return rankedHits}const exactIdIds=new Set(exactIdHits.map(hit=>hit.item.id));const remaining=rankedHits.filter(hit=>!exactIdIds.has(hit.item.id));const maxRemainingScore=remaining.reduce((max,hit)=>Math.max(max,hit.score),0);const orderedExactHits=exactIdHits.sort((left,right)=>right.score-left.score);const bandBase=maxRemainingScore+orderedExactHits.length+1;const promoted=orderedExactHits.map((hit,index)=>({...hit,score:bandBase-index,matched_fields:["id"]}));return[...promoted,...remaining]}function combineHybridHits(filteredById,semanticScores,keywordHits,hybridSemanticWeight,semanticFieldLabel="semantic"){const keywordScores=new Map(keywordHits.map(entry=>[entry.item.id,entry.score]));const keywordMatches=new Map(keywordHits.map(entry=>[entry.item.id,entry.matched_fields]));const normalizedSemantic=normalizeScoreMap(semanticScores);const normalizedKeyword=normalizeScoreMap(keywordScores);const candidateIds=new Set([...semanticScores.keys(),...keywordScores.keys()]);const keywordWeight=1-hybridSemanticWeight;return[...candidateIds].map(id=>{const document=filteredById.get(id);const semanticScore=normalizedSemantic.get(id)??0;const keywordScore=normalizedKeyword.get(id)??0;const combinedScore=semanticScore*hybridSemanticWeight+keywordScore*keywordWeight;if(combinedScore<=0){return null}const matchedFields=new Set;if(semanticScores.has(id)){matchedFields.add(semanticFieldLabel)}for(const field of keywordMatches.get(id)??[]){matchedFields.add(field)}return{item:document.metadata,score:combinedScore,matched_fields:[...matchedFields].sort((a,b)=>a.localeCompare(b))}}).filter(entry=>entry!==null)}function resolveBuiltInBm25Mode(params){const normalized=params.configuredProvider?.trim().toLowerCase();if(normalized==="bm25"){return"explicit"}if(normalized==="auto"&&!params.hasEmbeddingProvider&&!params.hasExtensionSearchProvider){return"auto-fallback"}return null}function computeBuiltInBm25Hits(params){const bm25Documents=params.filteredDocuments.map(document=>({id:document.metadata.id,text:flattenSearchCorpusText(buildSearchCorpus(document,{fields:params.corpusFields}))}));const index=buildBm25Index(bm25Documents);const bm25Scores=scoreBm25Query(index,tokenizeBm25(params.query),params.bm25Params);const filteredById=new Map(params.filteredDocuments.map(document=>[document.metadata.id,document]));if(params.requestedMode==="semantic"){const semanticHits=[...bm25Scores].map(([id,score])=>({item:filteredById.get(id).metadata,score,matched_fields:["bm25"]}));return forceExactIdHitsToTop(semanticHits,params.keywordHits)}const hybridHits=combineHybridHits(filteredById,bm25Scores,params.keywordHits,params.hybridSemanticWeight,"bm25");return forceExactIdHitsToTop(hybridHits,params.keywordHits)}function mergeVectorHitsById(vectorHitGroups){const bestById=new Map;for(const group of vectorHitGroups){for(const hit of group){const existing=bestById.get(hit.id);if(!existing||hit.score>existing.score){bestById.set(hit.id,hit)}}}const merged=[...bestById.values()];merged.sort((left,right)=>{if(left.score!==right.score){return right.score-left.score}return left.id.localeCompare(right.id)});return merged}function buildRerankCorpus(document){const metadata=document.metadata;const tags=Array.isArray(metadata?.tags)?metadata.tags.join(" "):"";return[metadata?.title,metadata?.description,metadata?.type,metadata?.status,tags,document.body].map(entry=>typeof entry==="string"?entry.trim():"").filter(entry=>entry.length>0).join("\n")}async function resolveExpandedSemanticQueries(context,queryTrimmed){const baseExpandedQueries=context.queryExpansion.enabled?buildDeterministicQueryExpansions(queryTrimmed,context.queryExpansion.max_queries):[queryTrimmed];const expandedQueries=baseExpandedQueries.length>0?baseExpandedQueries:[queryTrimmed];if(!context.queryExpansion.enabled){return expandedQueries}if(context.queryExpansionExtension?.expand){try{const rawExpansion=await Promise.resolve(context.queryExpansionExtension.expand({query:queryTrimmed,mode:context.requestedMode,settings:context.settings}));return mergeQueryExpansions(expandedQueries,normalizeQueryExpansionOutput(rawExpansion),context.queryExpansion.max_queries)}catch{context.warnings.push(`search_query_expansion_provider_failed:${context.queryExpansionExtension.providerName}:using_builtin`);return expandedQueries}}if(context.queryExpansion.provider&&context.queryExpansion.provider!=="openai"&&context.queryExpansion.provider!=="ollama"){context.warnings.push(`search_query_expansion_provider_unavailable:${context.queryExpansion.provider}:using_builtin`)}return expandedQueries}async function executeSemanticVectorQuery(context,semanticVector,semanticLimit,vectorQueryOptions){if(context.extensionVectorAdapter?.query){try{return await Promise.resolve(context.extensionVectorAdapter.query({vector:semanticVector,limit:semanticLimit,settings:context.settings}))}catch(error){if(!context.vectorStore){throw new PmCliError(`Extension vector adapter query failed and no built-in fallback store is configured (${error instanceof Error?error.message:String(error)})`,EXIT_CODE.GENERIC_FAILURE)}context.warnings.push(`search_vector_adapter_failed:${context.extensionVectorAdapter.adapterName}:using_builtin`);return await executeVectorQuery(context.vectorStore,semanticVector,semanticLimit,vectorQueryOptions)}}if(context.vectorStore){return await executeVectorQuery(context.vectorStore,semanticVector,semanticLimit,vectorQueryOptions)}throw new PmCliError("Semantic search requires either a configured vector store or an extension vector adapter query handler",EXIT_CODE.USAGE)}function buildRerankCandidateContexts(hybridHits,filteredById,topK){const sortedForCandidates=[...hybridHits].sort((left,right)=>{if(left.score!==right.score){return right.score-left.score}return left.item.id.localeCompare(right.item.id)});return sortedForCandidates.slice(0,topK).map(hit=>{const document=filteredById.get(hit.item.id);return document?{hit,text:buildRerankCorpus(document)}:null}).filter(entry=>entry!==null)}async function resolveExtensionRerankScores(context,queryTrimmed,candidateContexts){if(!context.rerankExtension?.rerank){return null}try{const rawRerank=await Promise.resolve(context.rerankExtension.rerank({query:queryTrimmed,mode:"hybrid",model:context.rerank.model,top_k:context.rerank.top_k,settings:context.settings,candidates:candidateContexts.map(entry=>({id:entry.hit.item.id,text:entry.text,score:entry.hit.score}))}));const normalizedRerank=normalizeRerankOutput(rawRerank);if(normalizedRerank.length>0){return new Map(normalizedRerank.map(entry=>[entry.id,entry.score]))}context.warnings.push(`search_rerank_provider_invalid_response:${context.rerankExtension.providerName}:using_builtin`);return null}catch{context.warnings.push(`search_rerank_provider_failed:${context.rerankExtension.providerName}:using_builtin`);return null}}async function resolveRerankScores(context,queryTrimmed,candidateContexts){const extensionScores=await resolveExtensionRerankScores(context,queryTrimmed,candidateContexts);if(extensionScores){return extensionScores}const rerankCandidates=candidateContexts.map(entry=>({id:entry.hit.item.id,text:entry.text}));try{return await rerankCandidatesWithEmbeddings(context.provider,context.rerank.model,queryTrimmed,rerankCandidates,context.embeddingTimeoutMs)}catch{context.warnings.push("search_rerank_failed:using_hybrid_scores");return null}}function applyRerankScores(hybridHits,rerankScores){const rerankedIds=new Set(rerankScores.keys());const rerankedHits=hybridHits.map(hit=>{const rerankScore=rerankScores.get(hit.item.id);if(rerankScore===void 0){return hit}const matchedFields=new Set(hit.matched_fields);matchedFields.add("rerank");return{...hit,score:rerankScore,matched_fields:[...matchedFields].sort((left,right)=>left.localeCompare(right))}});rerankedHits.sort((left,right)=>{const leftWasReranked=rerankedIds.has(left.item.id);const rightWasReranked=rerankedIds.has(right.item.id);if(leftWasReranked!==rightWasReranked){return leftWasReranked?-1:1}if(left.score!==right.score){return right.score-left.score}return left.item.id.localeCompare(right.item.id)});return rerankedHits}async function applyHybridRerank(context,queryTrimmed,hybridHits,filteredById){if(!context.rerank.enabled||hybridHits.length<=1){return hybridHits}const candidateContexts=buildRerankCandidateContexts(hybridHits,filteredById,context.rerank.top_k);const rerankScores=await resolveRerankScores(context,queryTrimmed,candidateContexts);return rerankScores&&rerankScores.size>0?applyRerankScores(hybridHits,rerankScores):hybridHits}async function computeSemanticOrHybridHits(context){const semanticLimit=Math.max(context.limit??context.maxResults,context.maxResults);const embeddingOptions=context.embeddingTimeoutMs!==void 0?{timeout_ms:context.embeddingTimeoutMs}:{};const vectorQueryOptions=context.vectorQueryTimeoutMs!==void 0?{timeout_ms:context.vectorQueryTimeoutMs}:{};const queryTrimmed=context.query.trim();const expandedQueries=await resolveExpandedSemanticQueries(context,queryTrimmed);const queryVectors=await executeEmbeddingRequest(context.provider,expandedQueries,embeddingOptions);const queryVectorGroups=await Promise.all(queryVectors.map(async semanticVector=>await executeSemanticVectorQuery(context,semanticVector,semanticLimit,vectorQueryOptions)));const vectorHits=mergeVectorHitsById(queryVectorGroups);const filteredById=new Map(context.filteredDocuments.map(document=>[document.metadata.id,document]));const{semanticHits,semanticScores}=buildSemanticHits(vectorHits,filteredById);const vectorMatchCount=semanticScores.size;if(context.requestedMode==="semantic"){return{hits:forceExactIdHitsToTop(semanticHits,context.keywordHits),vectorMatchCount}}const hybridHits=await applyHybridRerank(context,queryTrimmed,combineHybridHits(filteredById,semanticScores,context.keywordHits,context.hybridSemanticWeight),filteredById);return{hits:forceExactIdHitsToTop(hybridHits,context.keywordHits),vectorMatchCount}}async function loadDocuments(pmRoot,itemFormat,typeToFolder,schema){const extensionFieldNames=collectRegisteredItemFieldNames(getActiveExtensionRegistrations());const readDocumentBody=async(metadata,preferredPath,preferredFormat)=>{const tryRead=async(targetPath,format)=>{await runActiveOnReadHooks({path:targetPath,scope:"project"});const raw=await fs.readFile(targetPath,"utf8");const parsed=parseItemDocument(raw,{format,schema,extensionFieldNames,onWarning:warning=>listWarnings.push(warning)});return parsed.body};try{return await tryRead(preferredPath,preferredFormat)}catch{const alternateFormat=preferredFormat==="toon"?"json_markdown":"toon";const alternatePath=getItemPath(pmRoot,metadata.type,metadata.id,alternateFormat,typeToFolder);try{return await tryRead(alternatePath,alternateFormat)}catch{listWarnings.push(`item_list_item_read_failed:${path.relative(pmRoot,alternatePath)}`);return""}}};const listWarnings=[];const cachedDocuments=await listAllDocumentCandidatesCached(pmRoot,itemFormat,typeToFolder,listWarnings,schema);const documents=[];if(cachedDocuments.length===0){const itemMetadataDocuments=await listAllItemMetadata(pmRoot,itemFormat,typeToFolder,listWarnings,schema);for(const metadata of itemMetadataDocuments){const preferredPath=getItemPath(pmRoot,metadata.type,metadata.id,itemFormat,typeToFolder);const body=await readDocumentBody(metadata,preferredPath,itemFormat);documents.push({metadata,body})}return{documents,warnings:[...new Set(listWarnings)].sort((left,right)=>left.localeCompare(right))}}for(const cachedDocument of cachedDocuments){if(typeof cachedDocument.body==="string"){documents.push({metadata:cachedDocument.metadata,body:cachedDocument.body});continue}const body=await readDocumentBody(cachedDocument.metadata,cachedDocument.item_path,cachedDocument.item_format);documents.push({metadata:cachedDocument.metadata,body})}return{documents,warnings:[...new Set(listWarnings)].sort((left,right)=>left.localeCompare(right))}}function readSearchFieldValue(hit,field){const normalized=field.trim();if(normalized.length===0){return null}if(normalized==="score"){return hit.score}if(normalized==="matched_fields"){return hit.matched_fields}if(normalized.startsWith("item.")){const itemKey=normalized.slice("item.".length);if(itemKey.length===0){return null}const itemRecord2=toItemRecord(hit.item);return itemRecord2[itemKey]??null}const hitRecord=hit;const itemRecord=toItemRecord(hit.item);if(Object.prototype.hasOwnProperty.call(itemRecord,normalized)){return itemRecord[normalized]??null}if(Object.prototype.hasOwnProperty.call(hitRecord,normalized)){return hitRecord[normalized]??null}return null}function projectSearchHits(hits,projection){if(projection.mode==="full"){return hits.map(({matched_all_terms:_matchedAllTerms,exact_id_match:_exactIdMatch,...hit})=>hit)}return hits.map(hit=>{const projected={};for(const field of projection.fields){projected[field]=readSearchFieldValue(hit,field)}return projected})}function resolveQueryExpansionExtension(queryExpansion){const provider=resolveExtensionSearchProviderByName(queryExpansion.provider??void 0);return provider?.queryExpansion?{providerName:provider.providerName,expand:provider.queryExpansion}:null}function resolveRerankExtension(settings){const provider=resolveExtensionSearchProviderByName(toOptionalNonEmptyString(settings.search?.provider));return provider?.rerank?{providerName:provider.providerName,rerank:provider.rerank}:null}function prepareSearchInput(rawQuery,rawOptions){const inlineWarnings=[];const inlineParse=parseInlineQueryFilters(rawQuery);const hasInlineFilters=Object.keys(inlineParse.inlineFilters).length>0;if(hasInlineFilters&&inlineParse.residualQuery.trim().length===0){throw new PmCliError("Inline field:value tokens consumed the entire query, leaving no search terms.",EXIT_CODE.USAGE,{examples:["pm search auth tag:area:search","pm list --tag area:search --status open"],nextSteps:["Add keyword terms alongside the inline filters, or use pm list for pure tag/status/type/priority filtering."]})}const query=hasInlineFilters?inlineParse.residualQuery:rawQuery;const options=applyInlineQueryFilters(rawOptions,inlineParse.inlineFilters,inlineWarnings);return{query,options,inlineWarnings,highlight:options.highlight===true,includeLinked:parseSearchBoolean(options.includeLinked),titleExact:parseSearchBoolean(options.titleExact),phraseExact:parseSearchBoolean(options.phraseExact),matchMode:parseSearchMatchMode(typeof options.matchMode==="string"?options.matchMode:void 0),minScoreOverride:parseMinScoreOverride(options.minScore),countOnly:options.count===true,tokens:parseSearchTokens(query),normalizedQuery:normalizeSearchPhrase(query),limit:parseLimit(options.limit),projection:parseSearchProjection(options,rawQuery),modeWasExplicit:typeof options.mode==="string"&&options.mode.trim().length>0}}async function resolveSearchRuntimeContext(prepared,global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const storedSettings=await readSettings(pmRoot);const settings=resolveSettingsWithSemanticRuntimeDefaults(storedSettings).settings;const statusRegistry=resolveRuntimeStatusRegistry(settings.schema);const runtimeFieldRegistry=resolveRuntimeFieldRegistry(settings.schema);validateSearchProjectionFields(prepared.projection,runtimeFieldRegistry,prepared.query);const runtimeFieldFilters=collectRuntimeFilterValues(prepared.options,runtimeFieldRegistry,"search");const typeRegistry=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations());const providerResolution=resolveEmbeddingProviders(settings);const vectorResolution=resolveVectorStores(settings,pmRoot);const extensionSearchProvider=resolveExtensionSearchProvider(settings);const extensionVectorAdapter=resolveExtensionVectorAdapter(settings);const semanticWeightOverride=parseSemanticWeightOverride(prepared.options.semanticWeight);const queryExpansion=resolveQueryExpansionConfig(settings,providerResolution.active?.name??null);const rerank=resolveRerankConfig(settings,providerResolution.active?.model??toOptionalNonEmptyString(settings.search?.embedding_model)??"text-embedding-3-small");return{pmRoot,settings,statusRegistry,runtimeFieldRegistry,runtimeFieldFilters,typeRegistry,maxResults:resolveSearchMaxResults(settings),scoreThreshold:prepared.minScoreOverride??resolveSearchScoreThreshold(settings),semanticWeightProvided:prepared.options.semanticWeight!==void 0,semanticWeightOverride,hybridSemanticWeight:semanticWeightOverride??resolveHybridSemanticWeight(settings),tuning:resolveSearchTuning(settings),providerResolution,vectorResolution,extensionSearchProvider,extensionVectorAdapter,bm25Mode:resolveBuiltInBm25Mode({configuredProvider:toOptionalNonEmptyString(settings.search?.provider),hasEmbeddingProvider:providerResolution.active!==null,hasExtensionSearchProvider:extensionSearchProvider!==null}),queryExpansion,queryExpansionExtension:resolveQueryExpansionExtension(queryExpansion),rerank,rerankExtension:resolveRerankExtension(settings),...resolveRuntimeSearchMode({requested:prepared.options.mode,settings,configuredProvider:storedSettings.search?.provider??null,providerResolution,vectorResolution,extensionSearchProvider,extensionVectorAdapter})}}function resolveRuntimeSearchMode(params){const providerConfigured=resolveProviderConfigSource(params.providerResolution.active?.name,params.configuredProvider)==="configured";const builtInRunnable=providerConfigured&&(params.vectorResolution.active!==null||params.extensionVectorAdapter!==null);const semanticRunnable=params.extensionSearchProvider!==null||builtInRunnable;const resolution=resolveEffectiveSearchMode({requested:params.requested,settings:params.settings,semanticRunnable});return{effectiveMode:resolution.mode,modeSource:resolution.source}}async function loadFilteredSearchCorpus(prepared,runtime){const loadedDocuments=await loadDocuments(runtime.pmRoot,runtime.settings.item_format??"toon",runtime.typeRegistry.type_to_folder,runtime.settings.schema);const statusFilter=parseStatusFilterCsv(typeof prepared.options.status==="string"?prepared.options.status:void 0,runtime.statusRegistry,{strict:true});const lifecycleClassifier=lifecycleClassifierFromStatusRegistry(runtime.statusRegistry);const metadataFilteredDocuments=applyFilters(loadedDocuments.documents,prepared.options,runtime.typeRegistry,runtime.runtimeFieldFilters,statusFilter,lifecycleClassifier);return{warnings:loadedDocuments.warnings,allDocuments:loadedDocuments.documents,filteredDocuments:applyExactQueryFilters(metadataFilteredDocuments,prepared.normalizedQuery,{titleExact:prepared.titleExact,phraseExact:prepared.phraseExact||prepared.matchMode==="exact"})}}async function collectLinkedCorpusById(includeLinked,effectiveMode,filteredDocuments){const linkedCorpusById=new Map;if(!includeLinked||effectiveMode!=="keyword"&&effectiveMode!=="hybrid"){return linkedCorpusById}const projectRoot=process.cwd();const linkedCorpusRoots=await resolveLinkedCorpusRoots(projectRoot,resolveGlobalPmRoot(projectRoot));const linkedCorpusEntries=await Promise.all(filteredDocuments.map(async document=>[document.metadata.id,await loadLinkedCorpus(document,linkedCorpusRoots)]));for(const[id,corpus]of linkedCorpusEntries){linkedCorpusById.set(id,corpus)}return linkedCorpusById}async function computeKeywordSearchHits(prepared,runtime,filteredDocuments){const linkedCorpusById=await collectLinkedCorpusById(prepared.includeLinked,runtime.effectiveMode,filteredDocuments);const applyCoverageBonus=prepared.matchMode==="or";return filteredDocuments.map(document=>buildHybridLexicalScore(document,prepared.tokens,prepared.normalizedQuery,prepared.includeLinked,linkedCorpusById,runtime.tuning,runtime.settings.id_prefix,applyCoverageBonus)).filter(entry=>entry!==null).filter(entry=>prepared.matchMode!=="and"||entry.matched_all_terms===true)}function buildEmptySearchResultFromContext(response,countOnly){return emptySearchResult(response.query,response.effectiveMode,response.matchMode,response.options,response.includeLinked,response.scoreThreshold,response.hybridSemanticWeight,response.queryExpansion,response.rerank,response.projection,response.warnings,response.runtimeFieldFilters,countOnly,response.modeSource)}async function executeBuiltInBm25Search(prepared,runtime,filteredDocuments,keywordHits,warnings){if(runtime.bm25Mode===null||runtime.effectiveMode==="keyword"){return null}const hits=computeBuiltInBm25Hits({requestedMode:runtime.effectiveMode,query:prepared.query,filteredDocuments,keywordHits,corpusFields:resolveSearchCorpusFields(runtime.settings),bm25Params:resolveBm25Params(runtime.settings),hybridSemanticWeight:runtime.hybridSemanticWeight});if(runtime.bm25Mode==="auto-fallback"){warnings.push(`search_${runtime.effectiveMode}_offline_bm25:no_embedding_provider:using_lexical_bm25`)}return hits}async function executeExtensionSearchProvider(prepared,runtime,filteredDocuments,filteredById){if(!runtime.extensionSearchProvider){return null}const canUseBuiltInSemantic=runtime.providerResolution.active!==null&&(runtime.vectorResolution.active!==null||runtime.extensionVectorAdapter!==null);try{const providerResponse=await Promise.resolve(runtime.extensionSearchProvider.query({query:prepared.query,mode:runtime.effectiveMode,tokens:prepared.tokens,options:prepared.options,settings:runtime.settings,documents:filteredDocuments}));return normalizeExtensionProviderHits(runtime.extensionSearchProvider.providerName,providerResponse,filteredById)}catch(error){if(!canUseBuiltInSemantic){throw new PmCliError(`Extension search provider "${runtime.extensionSearchProvider.providerName}" failed: ${error instanceof Error?error.message:String(error)}`,EXIT_CODE.GENERIC_FAILURE)}return null}}function maybeApplyNoVectorFallback(effectiveMode,semanticResult,keywordHits,warnings){if(semanticResult.vectorMatchCount>0){return semanticResult.hits}warnings.push(`search_${effectiveMode}_degraded:no_vector_matches:results_are_lexical`);return effectiveMode==="semantic"?keywordHits:semanticResult.hits}async function prepareBuiltInSemanticSearch(runtime,effectiveMode,filteredDocuments,warnings,modeWasExplicit){const builtInSemanticWillRun=!runtime.extensionSearchProvider&&runtime.providerResolution.active!==null&&(runtime.vectorResolution.active!==null||runtime.extensionVectorAdapter!==null);if(modeWasExplicit&&builtInSemanticWillRun){await maybeEmitVectorIndexStaleWarning(runtime.pmRoot,filteredDocuments,warnings)}if(!runtime.extensionSearchProvider){requireSemanticDependencies(effectiveMode,runtime.providerResolution,runtime.vectorResolution,runtime.extensionVectorAdapter!==null)}}async function executeSemanticSearch(input){const{prepared,runtime,filteredDocuments,keywordHits,warnings,modeWasExplicit}=input;let hits=keywordHits;const bm25Hits=await executeBuiltInBm25Search(prepared,runtime,filteredDocuments,keywordHits,warnings);const semanticMode=runtime.effectiveMode;if(bm25Hits!==null||semanticMode==="keyword"){return{effectiveMode:runtime.effectiveMode,hits:bm25Hits??hits}}try{await prepareBuiltInSemanticSearch(runtime,semanticMode,filteredDocuments,warnings,modeWasExplicit);if(filteredDocuments.length===0||prepared.limit===0){return{effectiveMode:runtime.effectiveMode,hits:[]}}const filteredById=new Map(filteredDocuments.map(document=>[document.metadata.id,document]));hits=await executeExtensionSearchProvider(prepared,runtime,filteredDocuments,filteredById)??hits;if(hits===keywordHits){const{provider,vectorStore}=requireSemanticDependencies(semanticMode,runtime.providerResolution,runtime.vectorResolution,runtime.extensionVectorAdapter!==null);const semanticResult=await computeSemanticOrHybridHits({requestedMode:semanticMode,query:prepared.query,filteredDocuments,keywordHits,hybridSemanticWeight:runtime.hybridSemanticWeight,limit:prepared.limit,maxResults:runtime.maxResults,provider,vectorStore,extensionVectorAdapter:runtime.extensionVectorAdapter,queryExpansion:runtime.queryExpansion,queryExpansionExtension:runtime.queryExpansionExtension,rerank:runtime.rerank,rerankExtension:runtime.rerankExtension,warnings,settings:runtime.settings});hits=maybeApplyNoVectorFallback(semanticMode,semanticResult,keywordHits,warnings)}return{effectiveMode:runtime.effectiveMode,hits}}catch(error){warnings.push(buildExplicitSemanticFallbackWarning(runtime.effectiveMode,error));return{effectiveMode:"keyword",hits:keywordHits}}}function buildCountOnlySearchResult(response,total){if(response.projection.mode==="compact"&&response.options.compact===true){return withSearchWarnings({query:response.query.trim(),mode:response.effectiveMode,...compactModeSource(response.modeSource),items:[],count:total,total,count_only:true,filters:buildCompactSearchFilterSummary({mode:response.effectiveMode,matchMode:response.matchMode,options:response.options,includeLinked:response.includeLinked,titleExact:response.titleExact,phraseExact:response.phraseExact,scoreThreshold:response.scoreThreshold,hybridSemanticWeight:response.hybridSemanticWeight,runtimeFieldFilters:response.runtimeFieldFilters})},response.warnings)}const projectionFields=response.projection.mode==="full"?null:[...response.projection.fields];return withSearchWarnings({query:response.query.trim(),mode:response.effectiveMode,mode_source:response.modeSource,items:[],count:total,total,count_only:true,filters:buildVerboseSearchFilters({effectiveMode:response.effectiveMode,matchMode:response.matchMode,options:response.options,includeLinked:response.includeLinked,titleExact:response.titleExact,phraseExact:response.phraseExact,scoreThreshold:response.scoreThreshold,hybridSemanticWeight:response.hybridSemanticWeight,queryExpansion:response.queryExpansion,rerank:response.rerank,runtimeFieldFilters:response.runtimeFieldFilters}),projection:{mode:response.projection.mode,fields:projectionFields},now:nowIso()},response.warnings)}function compactModeSource(source){return source==="settings"?{mode_source:source}:{}}function withSearchWarnings(result,warnings){if(warnings.length===0){return result}return{...result,warnings}}function withSearchWorkspaceMemory(result,memory){return memory?{...result,workspace_memory:memory}:result}function attachSearchHighlights(prepared,filteredDocuments,limited){if(!prepared.highlight){return{hits:limited,projection:prepared.projection}}const documentById=new Map(filteredDocuments.map(document=>[document.metadata.id,document]));const hits=limited.map(hit=>({...hit,highlights:buildHitHighlights(documentById.get(hit.item.id),hit.matched_fields,prepared.tokens)}));if(prepared.projection.mode==="full"||prepared.projection.fields.includes("highlights")){return{hits,projection:prepared.projection}}return{hits,projection:{mode:prepared.projection.mode,fields:[...prepared.projection.fields,"highlights"]}}}function buildSearchResultForHits(response,projectedItems,total,limitedCount,effectiveProjection,pageExtras){const truncationExtras=limitedCount<total?{total}:{};if(response.projection.mode==="compact"&&response.options.compact===true){return withSearchWarnings({query:response.query.trim(),mode:response.effectiveMode,...compactModeSource(response.modeSource),items:projectedItems,count:projectedItems.length,...truncationExtras,...pageExtras,filters:buildCompactSearchFilterSummary({mode:response.effectiveMode,matchMode:response.matchMode,options:response.options,includeLinked:response.includeLinked,titleExact:response.titleExact,phraseExact:response.phraseExact,scoreThreshold:response.scoreThreshold,hybridSemanticWeight:response.hybridSemanticWeight,runtimeFieldFilters:response.runtimeFieldFilters})},response.warnings)}const finalProjectionFields=effectiveProjection.mode==="full"?null:[...effectiveProjection.fields];return{query:response.query.trim(),mode:response.effectiveMode,mode_source:response.modeSource,items:projectedItems,count:projectedItems.length,...truncationExtras,...pageExtras,filters:buildVerboseSearchFilters({effectiveMode:response.effectiveMode,matchMode:response.matchMode,options:response.options,includeLinked:response.includeLinked,titleExact:response.titleExact,phraseExact:response.phraseExact,scoreThreshold:response.scoreThreshold,hybridSemanticWeight:response.hybridSemanticWeight,queryExpansion:response.queryExpansion,rerank:response.rerank,runtimeFieldFilters:response.runtimeFieldFilters}),projection:{mode:effectiveProjection.mode,fields:finalProjectionFields},now:nowIso(),...response.warnings.length>0?{warnings:response.warnings}:{}}}function assertSearchPagingOptions(options){if(options.after!==void 0&&options.count===true){throw new PmCliError("Search --after cannot be combined with --count.",EXIT_CODE.USAGE)}}async function runSearch(rawQuery,rawOptions,global2){assertSearchPagingOptions(rawOptions);const prepared=prepareSearchInput(rawQuery,rawOptions);const runtime=await resolveSearchRuntimeContext(prepared,global2);const corpus=await loadFilteredSearchCorpus(prepared,runtime);const warnings=corpus.warnings;warnings.push(...prepared.inlineWarnings);const workspaceMemory=await readWorkspaceMemory(corpus.allDocuments.map(document=>document.metadata),{pmRoot:runtime.pmRoot,statusRegistry:runtime.statusRegistry,now:nowIso()});warnings.push(...workspaceMemory.warnings);const workspaceMemoryResult=searchWorkspaceMemoryReadResult(workspaceMemory,prepared.query);if(runtime.effectiveMode==="hybrid"&&runtime.semanticWeightProvided&&runtime.semanticWeightOverride===void 0){warnings.push("search_hybrid_semantic_weight_override_invalid:using_settings_default")}const responseBase={query:prepared.query,modeSource:runtime.modeSource,matchMode:prepared.matchMode,options:prepared.options,includeLinked:prepared.includeLinked,titleExact:prepared.titleExact,phraseExact:prepared.phraseExact,scoreThreshold:runtime.scoreThreshold,hybridSemanticWeight:runtime.hybridSemanticWeight,queryExpansion:runtime.queryExpansion,rerank:runtime.rerank,projection:prepared.projection,warnings,runtimeFieldFilters:runtime.runtimeFieldFilters};if(runtime.effectiveMode==="keyword"&&(corpus.filteredDocuments.length===0||prepared.limit===0&&!prepared.countOnly)){return withSearchWorkspaceMemory(buildEmptySearchResultFromContext({...responseBase,effectiveMode:runtime.effectiveMode},prepared.countOnly),workspaceMemoryResult)}const keywordHits=await computeKeywordSearchHits(prepared,runtime,corpus.filteredDocuments);const modeResult=await executeSemanticSearch({prepared,runtime,filteredDocuments:corpus.filteredDocuments,keywordHits,warnings,modeWasExplicit:prepared.modeWasExplicit});if(modeResult.effectiveMode!=="keyword"&&modeResult.hits.length===0&&(corpus.filteredDocuments.length===0||prepared.limit===0&&!prepared.countOnly)){return withSearchWorkspaceMemory(buildEmptySearchResultFromContext({...responseBase,effectiveMode:modeResult.effectiveMode},prepared.countOnly),workspaceMemoryResult)}const thresholded=modeResult.hits.filter(entry=>entry.exact_id_match===true||entry.score>=runtime.scoreThreshold);const sorted=sortHits(thresholded,runtime.statusRegistry);const total=sorted.length;const page=resolveSearchPage({sorted,query:prepared.query,mode:modeResult.effectiveMode,searchOptions:prepared.options,limit:prepared.limit??runtime.maxResults});const response={...responseBase,effectiveMode:modeResult.effectiveMode};if(prepared.countOnly){return withSearchWorkspaceMemory(buildCountOnlySearchResult(response,total),workspaceMemoryResult)}const{hits:projectedHits,projection:effectiveProjection}=attachSearchHighlights(prepared,corpus.filteredDocuments,page.limited);const projectedItems=projectSearchHits(projectedHits,effectiveProjection);return withSearchWorkspaceMemory(buildSearchResultForHits(response,projectedItems,total,page.limited.length,effectiveProjection,page.pageExtras),workspaceMemoryResult)}export{_testOnlySearchCommand,classifyImplicitSemanticFallbackReason,collectErrorCauseCodes,formatVectorIndexRecoveryWarnings,resolveEffectiveSearchMode2 as resolveEffectiveSearchMode,resolveHybridSemanticWeight2 as resolveHybridSemanticWeight,resolveSearchMaxResults2 as resolveSearchMaxResults,resolveSearchScoreThreshold2 as resolveSearchScoreThreshold,resolveSearchTuning2 as resolveSearchTuning,resolveVectorIndexRecovery,runSearch};
+!(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]="9e7719a0-9efa-59c2-85d5-e7a5eb30d8e3")}catch(e2){}})();import{getActiveExtensionRegistrations}from"../../core/extensions/index.js";import{lifecycleClassifierFromStatusRegistry}from"../../core/governance/metadata-coverage.js";import{parseStatusFilterCsv}from"../../core/item/status-filter.js";import{resolveItemTypeRegistry}from"../../core/item/type-registry.js";import{collectRuntimeFilterValues}from"../../core/schema/runtime-field-filters.js";import{resolveRuntimeFieldRegistry,resolveRuntimeStatusRegistry}from"../../core/schema/runtime-schema.js";import{resolveBm25Params}from"../../core/search/bm25.js";import{resolveSearchCorpusFields}from"../../core/search/corpus.js";import{resolveEmbeddingProviders,resolveProviderConfigSource}from"../../core/search/providers.js";import{resolveQueryExpansionConfig,resolveRerankConfig}from"../../core/search/relevance.js";import{resolveSettingsWithSemanticRuntimeDefaults}from"../../core/search/semantic-defaults.js";import{resolveVectorStores}from"../../core/search/vector-stores.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{PmCliError}from"../../core/shared/errors.js";import{nowIso}from"../../core/shared/time.js";import{resolvePmRoot}from"../../core/store/paths.js";import{readSettings}from"../../core/store/settings.js";import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{readWorkspaceMemory,searchWorkspaceMemoryReadResult}from"../workspace-memory.js";import{parseSearchProjection,parseSearchTokens,parseSemanticWeightOverride,parseTimestampWindow,resolveEffectiveSearchMode,resolveHybridSemanticWeight,resolveSearchMaxResults,resolveSearchScoreThreshold,resolveSearchTuning,validateSearchProjectionFields}from"./search-contracts.js";import{resolveSearchPage}from"./search-pagination.js";import{buildCompactSearchFilterSummary,buildVerboseSearchFilters}from"./search-rendering.js";import{collectLinkedCorpusById,collectLinkedPaths,loadDocuments,loadLinkedCorpus,resolveLinkedCorpusRoots}from"./search/corpus.js";import{applyExactQueryFilters,applyFilters,collectExactPhraseFields,dependencyEntries,documentContainsExactPhrase,stringArray,textEntries}from"./search/filters.js";import{applyInlineQueryFilters,assertSearchPagingOptions,parseInlineQueryFilters,prepareSearchInput}from"./search/input.js";import{buildHitHighlights,buildHybridLexicalScore,countOccurrences,highlightFieldSnippet,markTokenRuns,normalizeScoreMap,scoreDocument,sortHits}from"./search/lexical.js";import{attachSearchHighlights,buildCountOnlySearchResult,buildEmptySearchResultFromContext,buildSearchResultForHits,emptySearchResult,projectSearchHits,readSearchFieldValue,withSearchWorkspaceMemory}from"./search/response.js";import{buildExplicitSemanticFallbackWarning,buildRerankCorpus,buildSemanticHits,classifyImplicitSemanticFallbackReason,collectErrorCauseCodes,combineHybridHits,computeBuiltInBm25Hits,computeSemanticOrHybridHits,maybeEmitVectorIndexStaleWarning,mergeVectorHitsById,normalizeExtensionProviderHits,requireSemanticDependencies,resolveBuiltInBm25Mode,resolveExtensionSearchProvider,resolveExtensionSearchProviderByName,resolveExtensionVectorAdapter,resolveQueryExpansionExtension,resolveRerankExtension,toOptionalNonEmptyString}from"./search/semantic.js";import{resolveEffectiveSearchMode as resolveEffectiveSearchMode2,resolveHybridSemanticWeight as resolveHybridSemanticWeight2,resolveSearchMaxResults as resolveSearchMaxResults2,resolveSearchScoreThreshold as resolveSearchScoreThreshold2,resolveSearchTuning as resolveSearchTuning2}from"./search-contracts.js";import{classifyImplicitSemanticFallbackReason as classifyImplicitSemanticFallbackReason2,collectErrorCauseCodes as collectErrorCauseCodes2,formatVectorIndexRecoveryWarnings,resolveVectorIndexRecovery}from"./search/semantic.js";const _testOnlySearchCommand={applyFilters,applyExactQueryFilters,applyInlineQueryFilters,buildHitHighlights,buildVerboseSearchFilters,buildExplicitSemanticFallbackWarning,buildCompactSearchFilterSummary,buildHybridLexicalScore,buildRerankCorpus,buildSemanticHits,classifyImplicitSemanticFallbackReason,collectErrorCauseCodes,collectExactPhraseFields,collectLinkedPaths,combineHybridHits,computeBuiltInBm25Hits,computeSemanticOrHybridHits,resolveBuiltInBm25Mode,countOccurrences,dependencyEntries,documentContainsExactPhrase,emptySearchResult,highlightFieldSnippet,loadDocuments,markTokenRuns,parseInlineQueryFilters,maybeEmitVectorIndexStaleWarning,loadLinkedCorpus,mergeVectorHitsById,normalizeExtensionProviderHits,normalizeScoreMap,parseProjectionConfig:parseSearchProjection,parseTimestampWindow,parseTokens:parseSearchTokens,projectSearchHits,readSearchFieldValue,requireSemanticDependencies,resolveExtensionSearchProvider,resolveExtensionSearchProviderByName,resolveExtensionVectorAdapter,resolveLinkedCorpusRoots,scoreDocument,sortHits,stringArray,textEntries,validateSearchProjectionFields};async function resolveSearchRuntimeContext(prepared,global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const storedSettings=await readSettings(pmRoot);const settings=resolveSettingsWithSemanticRuntimeDefaults(storedSettings).settings;const statusRegistry=resolveRuntimeStatusRegistry(settings.schema);const runtimeFieldRegistry=resolveRuntimeFieldRegistry(settings.schema);validateSearchProjectionFields(prepared.projection,runtimeFieldRegistry,prepared.query);const runtimeFieldFilters=collectRuntimeFilterValues(prepared.options,runtimeFieldRegistry,"search");const typeRegistry=resolveItemTypeRegistry(settings,getActiveExtensionRegistrations());const providerResolution=resolveEmbeddingProviders(settings);const vectorResolution=resolveVectorStores(settings,pmRoot);const extensionSearchProvider=resolveExtensionSearchProvider(settings);const extensionVectorAdapter=resolveExtensionVectorAdapter(settings);const semanticWeightOverride=parseSemanticWeightOverride(prepared.options.semanticWeight);const queryExpansion=resolveQueryExpansionConfig(settings,providerResolution.active?.name??null);const rerank=resolveRerankConfig(settings,providerResolution.active?.model??toOptionalNonEmptyString(settings.search?.embedding_model)??"text-embedding-3-small");return{pmRoot,settings,statusRegistry,runtimeFieldRegistry,runtimeFieldFilters,typeRegistry,maxResults:resolveSearchMaxResults(settings),scoreThreshold:prepared.minScoreOverride??resolveSearchScoreThreshold(settings),semanticWeightProvided:prepared.options.semanticWeight!==void 0,semanticWeightOverride,hybridSemanticWeight:semanticWeightOverride??resolveHybridSemanticWeight(settings),tuning:resolveSearchTuning(settings),providerResolution,vectorResolution,extensionSearchProvider,extensionVectorAdapter,bm25Mode:resolveBuiltInBm25Mode({configuredProvider:toOptionalNonEmptyString(settings.search?.provider),hasEmbeddingProvider:providerResolution.active!==null,hasExtensionSearchProvider:extensionSearchProvider!==null}),queryExpansion,queryExpansionExtension:resolveQueryExpansionExtension(queryExpansion),rerank,rerankExtension:resolveRerankExtension(settings),...resolveRuntimeSearchMode({requested:prepared.options.mode,settings,configuredProvider:storedSettings.search?.provider??null,providerResolution,vectorResolution,extensionSearchProvider,extensionVectorAdapter})}}function resolveRuntimeSearchMode(params){const providerConfigured=resolveProviderConfigSource(params.providerResolution.active?.name,params.configuredProvider)==="configured";const builtInRunnable=providerConfigured&&(params.vectorResolution.active!==null||params.extensionVectorAdapter!==null);const semanticRunnable=params.extensionSearchProvider!==null||builtInRunnable;const resolution=resolveEffectiveSearchMode({requested:params.requested,settings:params.settings,semanticRunnable});return{effectiveMode:resolution.mode,modeSource:resolution.source}}async function loadFilteredSearchCorpus(prepared,runtime){const loadedDocuments=await loadDocuments(runtime.pmRoot,runtime.settings.item_format??"toon",runtime.typeRegistry.type_to_folder,runtime.settings.schema);const statusFilter=parseStatusFilterCsv(typeof prepared.options.status==="string"?prepared.options.status:void 0,runtime.statusRegistry,{strict:true});const lifecycleClassifier=lifecycleClassifierFromStatusRegistry(runtime.statusRegistry);const metadataFilteredDocuments=applyFilters(loadedDocuments.documents,prepared.options,runtime.typeRegistry,runtime.runtimeFieldFilters,statusFilter,lifecycleClassifier);return{warnings:loadedDocuments.warnings,allDocuments:loadedDocuments.documents,filteredDocuments:applyExactQueryFilters(metadataFilteredDocuments,prepared.normalizedQuery,{titleExact:prepared.titleExact,phraseExact:prepared.phraseExact||prepared.matchMode==="exact"})}}async function computeKeywordSearchHits(prepared,runtime,filteredDocuments){const linkedCorpusById=await collectLinkedCorpusById(prepared.includeLinked,runtime.effectiveMode,filteredDocuments);const applyCoverageBonus=prepared.matchMode==="or";return filteredDocuments.map(document=>buildHybridLexicalScore(document,prepared.tokens,prepared.normalizedQuery,prepared.includeLinked,linkedCorpusById,runtime.tuning,runtime.settings.id_prefix,applyCoverageBonus)).filter(entry=>entry!==null).filter(entry=>prepared.matchMode!=="and"||entry.matched_all_terms===true)}async function executeBuiltInBm25Search(prepared,runtime,filteredDocuments,keywordHits,warnings){if(runtime.bm25Mode===null||runtime.effectiveMode==="keyword"){return null}const hits=computeBuiltInBm25Hits({requestedMode:runtime.effectiveMode,query:prepared.query,filteredDocuments,keywordHits,corpusFields:resolveSearchCorpusFields(runtime.settings),bm25Params:resolveBm25Params(runtime.settings),hybridSemanticWeight:runtime.hybridSemanticWeight});if(runtime.bm25Mode==="auto-fallback"){warnings.push(`search_${runtime.effectiveMode}_offline_bm25:no_embedding_provider:using_lexical_bm25`)}return hits}async function executeExtensionSearchProvider(prepared,runtime,filteredDocuments,filteredById){if(!runtime.extensionSearchProvider){return null}const canUseBuiltInSemantic=runtime.providerResolution.active!==null&&(runtime.vectorResolution.active!==null||runtime.extensionVectorAdapter!==null);try{const providerResponse=await Promise.resolve(runtime.extensionSearchProvider.query({query:prepared.query,mode:runtime.effectiveMode,tokens:prepared.tokens,options:prepared.options,settings:runtime.settings,documents:filteredDocuments}));return normalizeExtensionProviderHits(runtime.extensionSearchProvider.providerName,providerResponse,filteredById)}catch(error){if(!canUseBuiltInSemantic){throw new PmCliError(`Extension search provider "${runtime.extensionSearchProvider.providerName}" failed: ${error instanceof Error?error.message:String(error)}`,EXIT_CODE.GENERIC_FAILURE)}return null}}function maybeApplyNoVectorFallback(effectiveMode,semanticResult,keywordHits,warnings){if(semanticResult.vectorMatchCount>0){return semanticResult.hits}warnings.push(`search_${effectiveMode}_degraded:no_vector_matches:results_are_lexical`);return effectiveMode==="semantic"?keywordHits:semanticResult.hits}async function prepareBuiltInSemanticSearch(runtime,effectiveMode,filteredDocuments,warnings,modeWasExplicit){const builtInSemanticWillRun=!runtime.extensionSearchProvider&&runtime.providerResolution.active!==null&&(runtime.vectorResolution.active!==null||runtime.extensionVectorAdapter!==null);if(modeWasExplicit&&builtInSemanticWillRun){await maybeEmitVectorIndexStaleWarning(runtime.pmRoot,filteredDocuments,warnings)}if(!runtime.extensionSearchProvider){requireSemanticDependencies(effectiveMode,runtime.providerResolution,runtime.vectorResolution,runtime.extensionVectorAdapter!==null)}}async function executeSemanticSearch(input){const{prepared,runtime,filteredDocuments,keywordHits,warnings,modeWasExplicit}=input;let hits=keywordHits;const bm25Hits=await executeBuiltInBm25Search(prepared,runtime,filteredDocuments,keywordHits,warnings);const semanticMode=runtime.effectiveMode;if(bm25Hits!==null||semanticMode==="keyword"){return{effectiveMode:runtime.effectiveMode,hits:bm25Hits??hits}}try{await prepareBuiltInSemanticSearch(runtime,semanticMode,filteredDocuments,warnings,modeWasExplicit);if(filteredDocuments.length===0||prepared.limit===0){return{effectiveMode:runtime.effectiveMode,hits:[]}}const filteredById=new Map(filteredDocuments.map(document=>[document.metadata.id,document]));hits=await executeExtensionSearchProvider(prepared,runtime,filteredDocuments,filteredById)??hits;if(hits===keywordHits){const{provider,vectorStore}=requireSemanticDependencies(semanticMode,runtime.providerResolution,runtime.vectorResolution,runtime.extensionVectorAdapter!==null);const semanticResult=await computeSemanticOrHybridHits({requestedMode:semanticMode,query:prepared.query,filteredDocuments,keywordHits,hybridSemanticWeight:runtime.hybridSemanticWeight,limit:prepared.limit,maxResults:runtime.maxResults,provider,vectorStore,extensionVectorAdapter:runtime.extensionVectorAdapter,queryExpansion:runtime.queryExpansion,queryExpansionExtension:runtime.queryExpansionExtension,rerank:runtime.rerank,rerankExtension:runtime.rerankExtension,warnings,settings:runtime.settings});hits=maybeApplyNoVectorFallback(semanticMode,semanticResult,keywordHits,warnings)}return{effectiveMode:runtime.effectiveMode,hits}}catch(error){warnings.push(buildExplicitSemanticFallbackWarning(runtime.effectiveMode,error));return{effectiveMode:"keyword",hits:keywordHits}}}async function runSearch(rawQuery,rawOptions,global2){assertSearchPagingOptions(rawOptions);const prepared=prepareSearchInput(rawQuery,rawOptions);const runtime=await resolveSearchRuntimeContext(prepared,global2);const corpus=await loadFilteredSearchCorpus(prepared,runtime);const warnings=corpus.warnings;warnings.push(...prepared.inlineWarnings);const workspaceMemory=await readWorkspaceMemory(corpus.allDocuments.map(document=>document.metadata),{pmRoot:runtime.pmRoot,statusRegistry:runtime.statusRegistry,now:nowIso()});warnings.push(...workspaceMemory.warnings);const workspaceMemoryResult=searchWorkspaceMemoryReadResult(workspaceMemory,prepared.query);if(runtime.effectiveMode==="hybrid"&&runtime.semanticWeightProvided&&runtime.semanticWeightOverride===void 0){warnings.push("search_hybrid_semantic_weight_override_invalid:using_settings_default")}const responseBase={query:prepared.query,modeSource:runtime.modeSource,matchMode:prepared.matchMode,options:prepared.options,includeLinked:prepared.includeLinked,titleExact:prepared.titleExact,phraseExact:prepared.phraseExact,scoreThreshold:runtime.scoreThreshold,hybridSemanticWeight:runtime.hybridSemanticWeight,queryExpansion:runtime.queryExpansion,rerank:runtime.rerank,projection:prepared.projection,warnings,runtimeFieldFilters:runtime.runtimeFieldFilters};if(runtime.effectiveMode==="keyword"&&(corpus.filteredDocuments.length===0||prepared.limit===0&&!prepared.countOnly)){return withSearchWorkspaceMemory(buildEmptySearchResultFromContext({...responseBase,effectiveMode:runtime.effectiveMode},prepared.countOnly),workspaceMemoryResult)}const keywordHits=await computeKeywordSearchHits(prepared,runtime,corpus.filteredDocuments);const modeResult=await executeSemanticSearch({prepared,runtime,filteredDocuments:corpus.filteredDocuments,keywordHits,warnings,modeWasExplicit:prepared.modeWasExplicit});if(modeResult.effectiveMode!=="keyword"&&modeResult.hits.length===0&&(corpus.filteredDocuments.length===0||prepared.limit===0&&!prepared.countOnly)){return withSearchWorkspaceMemory(buildEmptySearchResultFromContext({...responseBase,effectiveMode:modeResult.effectiveMode},prepared.countOnly),workspaceMemoryResult)}const thresholded=modeResult.hits.filter(entry=>entry.exact_id_match===true||entry.score>=runtime.scoreThreshold);const sorted=sortHits(thresholded,runtime.statusRegistry);const total=sorted.length;const page=resolveSearchPage({sorted,query:prepared.query,mode:modeResult.effectiveMode,searchOptions:prepared.options,limit:prepared.limit??runtime.maxResults});const response={...responseBase,effectiveMode:modeResult.effectiveMode};if(prepared.countOnly){return withSearchWorkspaceMemory(buildCountOnlySearchResult(response,total),workspaceMemoryResult)}const{hits:projectedHits,projection:effectiveProjection}=attachSearchHighlights(prepared,corpus.filteredDocuments,page.limited);const projectedItems=projectSearchHits(projectedHits,effectiveProjection);return withSearchWorkspaceMemory(buildSearchResultForHits(response,projectedItems,total,page.limited.length,effectiveProjection,page.pageExtras),workspaceMemoryResult)}export{_testOnlySearchCommand,classifyImplicitSemanticFallbackReason2 as classifyImplicitSemanticFallbackReason,collectErrorCauseCodes2 as collectErrorCauseCodes,formatVectorIndexRecoveryWarnings,resolveEffectiveSearchMode2 as resolveEffectiveSearchMode,resolveHybridSemanticWeight2 as resolveHybridSemanticWeight,resolveSearchMaxResults2 as resolveSearchMaxResults,resolveSearchScoreThreshold2 as resolveSearchScoreThreshold,resolveSearchTuning2 as resolveSearchTuning,resolveVectorIndexRecovery,runSearch};
 //# sourceMappingURL=search.js.map

package/dist/sdk/runtime/actions.d.ts

@@ -0,0 +1,4 @@
+import type { McpActionHandler } from "./context.js";
+/** Built-in action dispatch registry; each entry delegates behavior to its owning SDK operation. */
+declare const SDK_ACTION_HANDLERS: Record<string, McpActionHandler>;
+export { SDK_ACTION_HANDLERS };

package/dist/sdk/runtime/actions.js

@@ -0,0 +1,2 @@
+!(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]="a23d5ebd-6257-53e1-bed4-815b99a10bbb")}catch(e2){}})();import{projectMutationResult}from"../../core/output/mutation-projection.js";import{withQuerySummary}from"../../core/output/query-summary.js";import{PmCliError}from"../../core/shared/errors.js";import{resolvePmRoot}from"../../core/store/paths.js";import{createUnknownSubcommandError}from"../agent/subcommand-recovery.js";import{normalizeAnnotationTransportOptions}from"../annotations.js";import{acknowledgeUnknownAuthorHistoryEventsFromTransport}from"../author-attribution.js";import{runContracts}from"../cli-contracts/runtime-contracts.js";import{runComments}from"../comments.js";import{runConfig}from"../config.js";import{applyContextIntentProjection}from"../context-intent-contracts.js";import{runDeps}from"../dependencies.js";import{runDocs}from"../docs.js";import{runDuplicates}from"../duplicates.js";import{runExtension}from"../extension.js";import{runFiles,runFilesDiscover,runFilesLookup}from"../files.js";import{runAssuranceDispatch}from"../governance/assurance-action.js";import{runGc}from"../governance/gc.js";import{runHealth}from"../governance/health.js";import{runUpgrade}from"../governance/upgrade.js";import{runValidate}from"../governance/validate.js";import{runGraph}from"../graph/run.js";import{runMcpHistoryCompactAction,runMcpHistoryRepairAction}from"../history-mcp.js";import{runHistoryRedact}from"../history-redact.js";import{runHistoryAttest}from"../history/attestation-command.js";import{runInit}from"../init.js";import{runLearnings}from"../learnings.js";import{runAppend}from"../lifecycle/append.js";import{runCloseMany}from"../lifecycle/close-many.js";import{runCopy}from"../lifecycle/copy.js";import{runCreate}from"../lifecycle/create.js";import{runDelete}from"../lifecycle/delete.js";import{runFocus}from"../lifecycle/focus.js";import{runMcpClaimAction,runMcpCloseAction,runMcpReleaseAction,runMcpReopenAction,runMcpTaskCompositionAction}from"../lifecycle/mcp-actions.js";import{runPlan}from"../lifecycle/plan.js";import{runRestore}from"../lifecycle/restore.js";import{runUpdateMany}from"../lifecycle/update-many.js";import{runUpdate}from"../lifecycle/update.js";import{runNotes}from"../notes.js";import{PROFILE_SUBCOMMANDS,runProfileApply,runProfileLint,runProfileList,runProfileShow}from"../profile.js";import{normalizeActivityProjectionOptions,runActivity}from"../query/activity.js";import{runAggregate}from"../query/aggregate.js";import{runContext}from"../query/context.js";import{runGet}from"../query/get.js";import{runHistory}from"../query/history.js";import{runList}from"../query/list.js";import{runNext}from"../query/next.js";import{runSearch}from"../query/search.js";import{runRuntimeEvalAction,runRuntimeEventsAction,runRuntimeMergeAction,runRuntimeSchedulingAction,runRuntimeWorkspaceAction}from"../runtime-extended-actions.js";import{closeManyOptionsFromFlat,graphOptionsFromFlat,parseRuntimeInteger as parseMcpInteger,readRuntimeString as readString,readRuntimeStringArray as readStringArray,resolveRuntimeLimit,updateManyOptionsFromFlat,withAddNoteOption,withFilesDiscoveryOptions,withMutationCompaction}from"../runtime-input.js";import{statsCommandOptionsFromRuntime}from"../runtime-stats-options.js";import{runStats}from"../stats.js";import{runTelemetry}from"../telemetry.js";import{runTestAll}from"../test/batch.js";import{runTest}from"../test/execution.js";import{runtimeFilesLookupOptions}from"../traceability/runtime-files-lookup.js";import{getOwnHandler,readRequiredString}from"./context.js";import{runMcpSchemaAction}from"./schema.js";function readMcpTarget(ctx){return readString(ctx.args,"target")??readString(ctx.options,"target")}function requireMcpItemId(ctx,source=ctx.options){return ctx.id??readRequiredString(source,"id")}async function runMcpListAction(ctx){const listOptions=applyContextIntentProjection("list",ctx.options);if(listOptions.compact===void 0&&listOptions.brief===void 0&&listOptions.full===void 0&&listOptions.fields===void 0&&listOptions.includeBody===void 0){listOptions.compact=true}return withQuerySummary(await runList(readString(ctx.args,"status")??readString(listOptions,"status"),listOptions,ctx.global),listOptions)}async function runMcpSearchAction(ctx){const query=readRequiredString(ctx.args,"query");const searchOptions=applyContextIntentProjection("search",ctx.options,[query]);if(searchOptions.compact===void 0&&searchOptions.full===void 0&&searchOptions.fields===void 0){searchOptions.compact=true}return withQuerySummary(await runSearch(query,searchOptions,ctx.global),searchOptions)}async function runMcpCreateAction(ctx){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(ctx.args,ctx.options);return projectMutationResult(await runCreate(runnerOptions,ctx.global),{changedFields,compactEnvelope:changedFields==="compact"&&!idOnly,idOnly})}async function runMcpCopyAction(ctx){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(ctx.args,ctx.options);const copyOptions={...runnerOptions,...runnerOptions.title===void 0&&typeof ctx.args.title==="string"?{title:ctx.args.title}:{},...runnerOptions.message===void 0&&typeof ctx.args.message==="string"?{message:ctx.args.message}:{}};return projectMutationResult(await runCopy(requireMcpItemId(ctx,copyOptions),copyOptions,ctx.global),{changedFields,compactEnvelope:changedFields==="compact"&&!idOnly,idOnly})}async function runMcpUpdateAction(ctx){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(ctx.args,ctx.options);return projectMutationResult(await runUpdate(requireMcpItemId(ctx,runnerOptions),runnerOptions,ctx.global),{changedFields,compactEnvelope:changedFields==="compact"&&!idOnly,idOnly})}function runMcpCommentsAction(ctx){const commentOptions=normalizeAnnotationTransportOptions(ctx.options);const isListing=commentOptions.add===void 0&&commentOptions.stdin===void 0&&commentOptions.file===void 0&&commentOptions.edit===void 0&&commentOptions.delete===void 0;if(isListing){commentOptions.includeMeta=true;if(commentOptions.limit===void 0&&commentOptions.fullHistory!==true){commentOptions.limit="20"}}return runComments(requireMcpItemId(ctx),commentOptions,ctx.global)}function runMcpFilesLookupAction(ctx,paths){return runFilesLookup(runtimeFilesLookupOptions(ctx.options,paths,parseMcpInteger),ctx.global)}function runMcpFilesAction(ctx){const lookupPaths=readStringArray(ctx.options.lookupPath);if(lookupPaths&&lookupPaths.length>0){return runMcpFilesLookupAction(ctx,lookupPaths)}const fileId=requireMcpItemId(ctx);return ctx.options.discover===true?runFilesDiscover(fileId,withFilesDiscoveryOptions(ctx.options),ctx.global):runFiles(fileId,withAddNoteOption(ctx.options),ctx.global)}function runMcpTelemetryAction(ctx){return runTelemetry({subcommand:readString(ctx.args,"subcommand")??readString(ctx.options,"subcommand"),limit:resolveRuntimeLimit(ctx.args,ctx.options)},ctx.global)}function runMcpHealthAction(ctx){const healthOptions={...ctx.options};if(healthOptions.brief===void 0&&healthOptions.summary===void 0&&healthOptions.full===void 0){healthOptions.summary=true}return runHealth(ctx.global,healthOptions)}function runMcpConfigAction(ctx){const configAction=readString(ctx.args,"configAction")??readString(ctx.options,"configAction")??readString(ctx.options,"action");if(configAction===void 0)throw new PmCliError("Missing required argument: configAction",64);const value=readString(ctx.args,"value")??readString(ctx.options,"value");const options=readString(ctx.options,"policy")!==void 0&&value!==void 0?{...ctx.options,value}:ctx.options;return runConfig(readString(ctx.args,"scope")??readString(ctx.options,"scope")??"project",configAction,readString(ctx.args,"key")??readString(ctx.options,"key"),options,ctx.global,readString(ctx.options,"policy")===void 0?value:void 0)}function runMcpActivityAction(ctx){const options=ctx.options;return runActivity(normalizeActivityProjectionOptions(options),ctx.global)}function parseMcpIntegerPrefix(value,label){if(typeof value==="number"){if(!Number.isFinite(value)||!Number.isInteger(value)){throw new PmCliError(`${label} must be a finite integer.`,64)}return value}if(typeof value==="string"&&value.trim().length>0){const trimmed=value.trim();if(!/^[+-]?\d+(?:st|nd|rd|th)?$/i.test(trimmed)){throw new PmCliError(`${label} must be a finite integer.`,64)}const parsed=Number.parseInt(trimmed,10);if(!Number.isInteger(parsed)){throw new PmCliError(`${label} must be a finite integer.`,64)}return parsed}return void 0}function runMcpPlanAction(ctx){const subcommand=readString(ctx.args,"subcommand")??readRequiredString(ctx.options,"subcommand");const planRecord=ctx.options;return runPlan({subcommand,id:typeof ctx.id==="string"?ctx.id:typeof planRecord.id==="string"?planRecord.id:void 0,stepRef:readMcpPlanStepRef(ctx),reorderTo:parseMcpIntegerPrefix(planRecord.reorderTo??ctx.args.reorderTo,"plan reorderTo"),options:ctx.options,global:ctx.global})}function readMcpPlanStepRef(ctx){return typeof ctx.options.stepRef==="string"?ctx.options.stepRef:typeof ctx.args.stepRef==="string"?ctx.args.stepRef:void 0}function runMcpProfileAction(ctx){const subcommand=readString(ctx.args,"subcommand")??readRequiredString(ctx.options,"subcommand");const normalizedSubcommand=subcommand.trim().toLowerCase();const profileName=readString(ctx.args,"name")??readString(ctx.options,"name");const handlers={list:()=>runProfileList(),show:()=>runProfileShow(profileName),lint:()=>runProfileLint(profileName),apply:()=>runProfileApply(profileName,{dryRun:ctx.args.dryRun===true||ctx.options.dryRun===true,author:readString(ctx.args,"author")??readString(ctx.options,"author"),force:ctx.args.force===true||ctx.options.force===true},ctx.global)};const handler=getOwnHandler(handlers,normalizedSubcommand);if(!handler){throw createUnknownSubcommandError({command_path:"profile",token:subcommand,allowed:PROFILE_SUBCOMMANDS,exit_code:64})}return handler()}async function runMcpAppendAction(ctx){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(ctx.args,ctx.options);return projectMutationResult(await runAppend(requireMcpItemId(ctx,runnerOptions),runnerOptions,ctx.global),{changedFields,compactEnvelope:changedFields==="compact"&&!idOnly,idOnly})}async function runMcpUpdateManyAction(ctx){const{changedFields,runnerOptions}=withMutationCompaction(ctx.args,ctx.options);return projectMutationResult(await runUpdateMany(updateManyOptionsFromFlat(runnerOptions),ctx.global),{changedFields})}async function runMcpCloseManyAction(ctx){const{changedFields,runnerOptions}=withMutationCompaction(ctx.args,ctx.options);const topLevelReason=readString(ctx.args,"reason");const closeManyRunnerOptions=topLevelReason!==void 0&&runnerOptions.reason===void 0?{...runnerOptions,reason:topLevelReason}:{...runnerOptions};if(ctx.force&&closeManyRunnerOptions.force===void 0){closeManyRunnerOptions.force=true}return projectMutationResult(await runCloseMany(closeManyOptionsFromFlat(closeManyRunnerOptions),ctx.global),{changedFields})}async function runMcpRestoreAction(ctx){const{changedFields,idOnly,runnerOptions}=withMutationCompaction(ctx.args,ctx.options);const target=readString(runnerOptions,"target")??readRequiredString(ctx.args,"target");return projectMutationResult(await runRestore(requireMcpItemId(ctx,runnerOptions),target,runnerOptions,ctx.global),{changedFields,compactEnvelope:changedFields==="compact"&&!idOnly,idOnly})}function runMcpGraphAction(ctx){const merged={...ctx.args,...ctx.options};return runGraph(readRequiredString(merged,"subcommand"),readString(merged,"id")??ctx.id,readString(merged,"target"),graphOptionsFromFlat(merged),ctx.global)}function runMcpHistoryAuthorAcknowledgeAction(ctx){return acknowledgeUnknownAuthorHistoryEventsFromTransport(resolvePmRoot(process.cwd(),ctx.global.path),{...ctx.args,...ctx.options})}const SDK_ACTION_HANDLERS={init:ctx=>runInit(readString(ctx.args,"prefix"),ctx.global,ctx.options),context:ctx=>runContext(applyContextIntentProjection("context",ctx.options),ctx.global),next:ctx=>runNext(applyContextIntentProjection("next",ctx.options),ctx.global),eval:runRuntimeEvalAction,events:runRuntimeEventsAction,merge:runRuntimeMergeAction,workspace:runRuntimeWorkspaceAction,meet:runRuntimeSchedulingAction,event:runRuntimeSchedulingAction,remind:runRuntimeSchedulingAction,list:runMcpListAction,get:ctx=>{const id=requireMcpItemId(ctx);return runGet(id,ctx.global,applyContextIntentProjection("get",ctx.options,[id]))},search:runMcpSearchAction,duplicates:ctx=>{const status=typeof ctx.options.status==="string"?[ctx.options.status]:readStringArray(ctx.options.status);return runDuplicates(ctx.global,{exhaustive:ctx.options.exhaustive===true,...status.length===0?{}:{status},since:readString(ctx.options,"since"),threshold:typeof ctx.options.threshold==="number"?ctx.options.threshold:void 0,limit:ctx.options.limit==="default"?void 0:parseMcpInteger(ctx.options.limit,"limit")})},create:runMcpCreateAction,copy:runMcpCopyAction,focus:ctx=>runFocus(ctx.id,{clear:ctx.options.clear===true||ctx.args.clear===true},ctx.global),update:runMcpUpdateAction,"item-reopen":runMcpReopenAction,restore:runMcpRestoreAction,claim:runMcpClaimAction,release:runMcpReleaseAction,"start-task":ctx=>runMcpTaskCompositionAction(ctx,"start_task"),"pause-task":ctx=>runMcpTaskCompositionAction(ctx,"pause_task"),"close-task":ctx=>runMcpTaskCompositionAction(ctx,"close_task"),close:runMcpCloseAction,comments:runMcpCommentsAction,notes:ctx=>runNotes(requireMcpItemId(ctx),normalizeAnnotationTransportOptions(ctx.options),ctx.global),learnings:ctx=>runLearnings(requireMcpItemId(ctx),normalizeAnnotationTransportOptions(ctx.options),ctx.global),files:runMcpFilesAction,docs:ctx=>runDocs(requireMcpItemId(ctx),withAddNoteOption(ctx.options),ctx.global),test:ctx=>runTest(requireMcpItemId(ctx),ctx.options,ctx.global),"test-all":ctx=>runTestAll(ctx.options,ctx.global),telemetry:runMcpTelemetryAction,validate:ctx=>runValidate(ctx.options,ctx.global,{runUpdate:(id,options,global2)=>runUpdate(id,options,global2)}),health:runMcpHealthAction,assurance:ctx=>runAssuranceDispatch(ctx.args,ctx.options,ctx.global),contracts:ctx=>runContracts(ctx.options,ctx.global),config:runMcpConfigAction,activity:runMcpActivityAction,aggregate:ctx=>runAggregate(ctx.options,ctx.global),extension:ctx=>runExtension(readMcpTarget(ctx),ctx.options,ctx.global),package:ctx=>runExtension(readMcpTarget(ctx),ctx.options,ctx.global),install:ctx=>runExtension(readMcpTarget(ctx),{...ctx.options,install:true},ctx.global),upgrade:ctx=>runUpgrade(readMcpTarget(ctx),ctx.options,ctx.global),delete:ctx=>runDelete(requireMcpItemId(ctx),ctx.options,ctx.global),deps:ctx=>runDeps(requireMcpItemId(ctx),ctx.options,ctx.global),graph:runMcpGraphAction,"files-discover":ctx=>runFilesDiscover(requireMcpItemId(ctx),ctx.options,ctx.global),"files-lookup":ctx=>runMcpFilesLookupAction(ctx,readStringArray(ctx.options.paths)),history:ctx=>runHistory(requireMcpItemId(ctx),ctx.options,ctx.global),"history-redact":ctx=>runHistoryRedact(requireMcpItemId(ctx),ctx.options,ctx.global),"history-repair":runMcpHistoryRepairAction,"history-compact":runMcpHistoryCompactAction,"history-attest":ctx=>runHistoryAttest(ctx.options,ctx.global),"history-author-acknowledge":runMcpHistoryAuthorAcknowledgeAction,plan:runMcpPlanAction,schema:runMcpSchemaAction,profile:runMcpProfileAction,stats:ctx=>runStats(ctx.global,statsCommandOptionsFromRuntime(ctx.options)),append:runMcpAppendAction,"update-many":runMcpUpdateManyAction,"close-many":runMcpCloseManyAction,gc:ctx=>runGc(ctx.global,ctx.options)};export{SDK_ACTION_HANDLERS};
+//# sourceMappingURL=actions.js.map

package/dist/sdk/runtime/context.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @module sdk/runtime/context
+ * Defines internal action context and required argument validation.
+ */
+import { activateExtensions } from "../../core/extensions/index.js";
+import type { GlobalOptions } from "../../core/shared/command-types.js";
+import { type PmContextIntentPackageModule } from "../context-intent-runtime.js";
+/** Read a required non-empty string from an action argument bag. */
+export declare function readRequiredString(args: Record<string, unknown>, key: string): string;
+/** Resolved extension activation result used by the request-local runtime context. */
+type ExtensionActivationResult = Awaited<ReturnType<typeof activateExtensions>>;
+/**
+ * The active extension runtime exposed to an action while it executes: the merged
+ * registration registry (custom item types, fields, profiles) plus the command handler
+ * registry used to dispatch extension-contributed actions. `null` when extensions are
+ * disabled, no workspace exists yet, or activation failed (see {@link withActiveExtensions}).
+ */
+type ActiveExtensionRuntime = {
+    registrations: ExtensionActivationResult["registrations"];
+    commands: ExtensionActivationResult["commands"];
+    pmRoot: string;
+    packages: readonly PmContextIntentPackageModule[];
+};
+/** Normalized action arguments and active runtime state passed to a built-in handler. */
+interface McpActionDispatchContext {
+    action: string;
+    args: Record<string, unknown>;
+    options: Record<string, unknown>;
+    id: string | undefined;
+    force: boolean;
+    global: GlobalOptions;
+    activeExtensions: ActiveExtensionRuntime | null;
+}
+/** Built-in action handler returning a value or asynchronous result before read projection. */
+type McpActionHandler = (ctx: McpActionDispatchContext) => Promise<unknown> | unknown;
+/** Look up only an own registry entry so inherited object properties cannot become actions. */
+declare function getOwnHandler<T>(handlers: Readonly<Record<string, T>>, key: string): T | undefined;
+export { ActiveExtensionRuntime, ExtensionActivationResult, McpActionDispatchContext, McpActionHandler, getOwnHandler };

package/dist/sdk/runtime/context.js

@@ -0,0 +1,2 @@
+!(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]="c6f4c40f-50cf-568f-8a45-860ac4be3c97")}catch(e2){}})();import{PmCliError}from"../../core/shared/errors.js";import{readRuntimeString as readString}from"../runtime-input.js";function readRequiredString(args,key){const value=readString(args,key);if(!value){throw new PmCliError(`Missing required argument: ${key}`,64)}return value}function getOwnHandler(handlers,key){return Object.prototype.hasOwnProperty.call(handlers,key)?handlers[key]:void 0}export{getOwnHandler,readRequiredString};
+//# sourceMappingURL=context.js.map

package/dist/sdk/runtime/schema.d.ts

@@ -0,0 +1,4 @@
+import type { McpActionDispatchContext } from "./context.js";
+/** Translate schema transport arguments into the matching SDK schema or workflow-policy operation. */
+declare function runMcpSchemaAction(ctx: McpActionDispatchContext): Promise<unknown> | unknown;
+export { runMcpSchemaAction };

package/dist/sdk/runtime/schema.js

@@ -0,0 +1,2 @@
+!(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]="0475c8ad-b70d-5d98-b1cb-8176131a61a8")}catch(e2){}})();import{createUnknownSubcommandError}from"../agent/subcommand-recovery.js";import{WORKFLOW_POLICY_ACTIONS,runWorkflowPolicyAction}from"../governance/workflow-policy.js";import{parseRuntimeInteger as parseMcpInteger,readRuntimeString as readString,readRuntimeStringArray as readStringArray}from"../runtime-input.js";import{SCHEMA_SUBCOMMANDS,runSchemaAddField,runSchemaAddStatus,runSchemaAddType,runSchemaApplyPreset,runSchemaEvolutionMigration,runSchemaInferTypes,runSchemaList,runSchemaListFields,runSchemaRemoveField,runSchemaRemoveStatus,runSchemaRemoveType,runSchemaShow,runSchemaShowField,runSchemaShowStatus}from"../schema.js";import{getOwnHandler,readRequiredString}from"./context.js";function createMcpSchemaContext(ctx){const subcommand=readString(ctx.args,"subcommand")??readRequiredString(ctx.options,"subcommand");const aliasSource=ctx.args.alias??ctx.options.alias;return{ctx,subcommand:subcommand.trim().toLowerCase(),name:readString(ctx.args,"name")??readString(ctx.options,"name"),author:readString(ctx.args,"author")??readString(ctx.options,"author"),force:ctx.args.force===true||ctx.options.force===true,aliases:aliasSource===void 0?void 0:readStringArray(aliasSource)}}function runMcpSchemaReadOrRemoveAction(schema){const{ctx,subcommand,name,author,force}=schema;const simpleHandlers={list:()=>runSchemaList(ctx.global),show:()=>runSchemaShow(name,ctx.global),"show-status":()=>runSchemaShowStatus(name,ctx.global),"list-fields":()=>runSchemaListFields(ctx.global),"show-field":()=>runSchemaShowField(name,ctx.global),"remove-type":()=>runSchemaRemoveType(name,{author,force},ctx.global),"remove-field":()=>runSchemaRemoveField(name,{author,force},ctx.global),"remove-status":()=>runSchemaRemoveStatus(name,{author,force},ctx.global),"apply-preset":()=>runSchemaApplyPreset(readString(ctx.args,"typePreset")??readString(ctx.options,"typePreset"),{author,force},ctx.global)};const handler=getOwnHandler(simpleHandlers,subcommand);return handler?handler():null}function runMcpSchemaAddFieldAction(schema){const{ctx,name,author,force,aliases}=schema;const commandsSource=ctx.args.commands??ctx.options.commands;const requiredTypesSource=ctx.args.requiredTypes??ctx.options.requiredTypes;return runSchemaAddField(name,{type:readString(ctx.args,"fieldType")??readString(ctx.options,"fieldType"),commands:commandsSource===void 0?void 0:readStringArray(commandsSource),description:readString(ctx.args,"description")??readString(ctx.options,"description"),cliFlag:readString(ctx.args,"cliFlag")??readString(ctx.options,"cliFlag"),alias:aliases,required:ctx.args.required===true||ctx.options.required===true,requiredOnCreate:ctx.args.requiredOnCreate===true||ctx.options.requiredOnCreate===true,allowUnset:!(ctx.args.allowUnset===false||ctx.options.allowUnset===false),requiredTypes:requiredTypesSource===void 0?void 0:readStringArray(requiredTypesSource),author,force},ctx.global)}function runMcpSchemaAddStatusAction(schema){const{ctx,name,author,force,aliases}=schema;const roleSource=ctx.args.role??ctx.options.role;return runSchemaAddStatus(name,{role:roleSource===void 0?void 0:readStringArray(roleSource),alias:aliases,description:readString(ctx.args,"description")??readString(ctx.options,"description"),order:parseMcpInteger(ctx.args.order??ctx.options.order,"schema add-status order"),author,force},ctx.global)}function runMcpSchemaAddTypeAction(schema){const{ctx,name,author,force,aliases}=schema;return runSchemaAddType(name,{description:readString(ctx.args,"description")??readString(ctx.options,"description"),defaultStatus:readString(ctx.args,"defaultStatus")??readString(ctx.args,"default_status")??readString(ctx.options,"defaultStatus")??readString(ctx.options,"default_status"),folder:readString(ctx.args,"folder")??readString(ctx.options,"folder"),alias:aliases,author,force},ctx.global)}function runMcpSchemaMigrationAction(schema){const{ctx,subcommand,name,author,force}=schema;const to=readString(ctx.args,"to")??readRequiredString(ctx.options,"to");const migrationId=readString(ctx.args,"migrationId")??readString(ctx.args,"migration_id")??readString(ctx.options,"migrationId")??readString(ctx.options,"migration_id");const fieldTypeScope=readString(ctx.args,"fieldTypeScope")??readString(ctx.options,"fieldTypeScope")??readString(ctx.args,"type")??readString(ctx.options,"type");const request=subcommand==="rename-type"?{kind:"rename-type",from:name??"",to}:subcommand==="rename-field"?{kind:"rename-field",from:name??"",to,...fieldTypeScope===void 0?{}:{type:fieldTypeScope}}:{kind:"remap-status",from:name??"",to};return runSchemaEvolutionMigration(request,{migrationId,dryRun:ctx.args.dryRun===true||ctx.options.dryRun===true,author,force},ctx.global)}function runMcpSchemaAction(ctx){const schema=createMcpSchemaContext(ctx);const policyAction=WORKFLOW_POLICY_ACTIONS.find(action=>action===schema.subcommand);if(policyAction)return runWorkflowPolicyAction(policyAction,schema.name,{definition:ctx.args.definition??ctx.options.definition,policy:readString(ctx.args,"policy")??readString(ctx.options,"policy"),message:readString(ctx.args,"message")??readString(ctx.options,"message"),author:schema.author,dryRun:ctx.args.dryRun===true||ctx.options.dryRun===true},ctx.global);const simpleResult=runMcpSchemaReadOrRemoveAction(schema);if(simpleResult!==null){return simpleResult}if(["rename-type","rename-field","remap-status"].includes(schema.subcommand)){return runMcpSchemaMigrationAction(schema)}if(schema.subcommand==="add-field"){return runMcpSchemaAddFieldAction(schema)}if(schema.subcommand==="add-status"){return runMcpSchemaAddStatusAction(schema)}if(schema.subcommand==="add-type"){if(ctx.args.infer===true||ctx.options.infer===true){return runSchemaInferTypes({minCount:parseMcpInteger(ctx.args.minCount??ctx.options.minCount,"schema infer minCount"),apply:ctx.args.apply===true||ctx.options.apply===true,author:schema.author,force:schema.force},ctx.global)}return runMcpSchemaAddTypeAction(schema)}throw createUnknownSubcommandError({command_path:"schema",token:schema.subcommand,allowed:SCHEMA_SUBCOMMANDS,exit_code:64})}export{runMcpSchemaAction};
+//# sourceMappingURL=schema.js.map

package/dist/sdk/runtime.d.ts

@@ -1,126 +1,122 @@
-/**
- * @module sdk/runtime
- *
- * Defines public SDK APIs and package-author helpers for Runtime.
- */
-export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, type EnsurePmGitignoreResult, } from "./workspace.js";
-export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
-export type { FlagDefinition } from "../core/extensions/loader.js";
-export * from "./cli-contracts/agent-output-contracts.js";
 import { EXIT_CODE } from "../core/shared/constants.js";
 import type { ItemMetadata } from "../types/index.js";
-import { type PmCompleteListOptions, type PmCompleteListResult } from "./query/complete-list.js";
-export { PmCompleteListValidationError, assertCompleteListResult, certifyCompleteListResult, createCompleteListOptions, inspectCompleteListResult, type PmCompleteListCertificate, type PmCompleteListFailureReceipt, type PmCompleteListFinding, type PmCompleteListFindingCode, type PmCompleteListInspection, type PmCompleteListOptions, type PmCompleteListResult } from "./query/complete-list.js";
-export { getWorkspaceContracts } from "./query/workspace-contracts.js";
-export type { WorkspaceExtensionCommandContract, WorkspaceFieldContract, } from "./workspace-contracts.js";
-import { type PmReadOutputOptions, type PmReadOutputResultFor } from "./read-output-contracts.js";
-export type { PmReadOutputBudgetExceeded, PmReadOutputOptions, PmReadOutputResult, PmReadOutputResultFor, PmReadOutputSurfaceContract, } from "./read-output-contracts.js";
-export type { PmReadOutputSessionReceipt, PmReadOutputSessionState, } from "./read-output-session.js";
-export type { PmContextIntentContract } from "./context-intent-contracts.js";
-export type { PmErrorCodeContract } from "./error-code-catalog.js";
-export { clearWorkspaceContractsCache } from "./workspace-contracts-cache.js";
+import { type AcknowledgeUnknownAuthorEventsOptions, type UnknownAuthorAcknowledgmentResult } from "./author-attribution.js";
+import { type ContractsCommandOptions, type ContractsResult } from "./cli-contracts/runtime-contracts.js";
+import type { PmCreateActionOptions, PmUpdateActionOptions } from "./cli-contracts/typed-action-inputs.js";
+import type { CommentsCommandOptions, CommentsResult } from "./comments.js";
+import type { ConfigCommandOptions, ConfigResult } from "./config.js";
+import type { DepsCommandOptions, DepsResult } from "./dependencies.js";
+import type { DocsCommandOptions, DocsResult } from "./docs.js";
+import { type DuplicatesCommandOptions, type DuplicatesResult } from "./duplicates.js";
+import { type ExtensionCommandOptions, type ExtensionCommandResult } from "./extension.js";
+import type { FilesCommandOptions, FilesDiscoverOptions, FilesDiscoverResult, FilesLookupOptions, FilesLookupResult, FilesResult } from "./files.js";
 import { type AssuranceActionInput, type AssuranceActionResult } from "./governance/assurance-action.js";
-import { type WorkflowPolicyAction, type WorkflowPolicyActionOptions, type WorkflowPolicyActionResult } from "./governance/workflow-policy.js";
-export * from "./governance/workflow-policy.js";
-export type * from "./governance/assurance-action-contracts.js";
-import { type AggregateOptions, type AggregateResult } from "./query/aggregate.js";
-export { runStartTask, runPauseTask, runCloseTask, type TaskCompositionOptions } from "./lifecycle/task-composition.js";
-import { runHistoryAttest, type HistoryAttestCommandOptions } from "./history/attestation-command.js";
-import { type UpgradeCommandOptions, type UpgradeResult } from "./governance/upgrade.js";
-import { type CreateResult } from "./lifecycle/create.js";
-import { type UpdateResult } from "./lifecycle/update.js";
-import type { ReopenCommandOptions, ReopenResult } from "./lifecycle/reopen.js";
-import { type PlanCommandOptions, type PlanCommandResult, type PlanSubcommand } from "./lifecycle/plan.js";
-import { type ContextOptions, type ContextResult } from "./query/context.js";
-import { type NextOptions, type NextResult } from "./query/next.js";
-import { type CopyResult } from "./lifecycle/copy.js";
-import { type DeleteResult } from "./lifecycle/delete.js";
-import { type RestoreResult } from "./lifecycle/restore.js";
-import { type FocusResult } from "./lifecycle/focus.js";
-import { type GetOptions, type GetResult } from "./query/get.js";
 import { type GcCommandOptions, type GcResult } from "./governance/gc.js";
 import { type HealthResult, type RunHealthOptions } from "./governance/health.js";
+import { type UpgradeCommandOptions, type UpgradeResult } from "./governance/upgrade.js";
 import { type ValidateCommandOptions, type ValidateCountsResult, type ValidateResult } from "./governance/validate.js";
-import { type ExtensionCommandOptions, type ExtensionCommandResult } from "./extension.js";
-import { type AcknowledgeUnknownAuthorEventsOptions, type UnknownAuthorAcknowledgmentResult } from "./author-attribution.js";
+import { type WorkflowPolicyAction, type WorkflowPolicyActionOptions, type WorkflowPolicyActionResult } from "./governance/workflow-policy.js";
+import { type GraphCommandOptions, type GraphResult, type GraphSubcommand } from "./graph/run.js";
 import { type HistoryCompactBulkCommandOptions, type HistoryCompactBulkResult, type HistoryCompactCommandOptions, type HistoryCompactResult } from "./history-compact.js";
 import { type HistoryRedactCommandOptions, type HistoryRedactResult } from "./history-redact.js";
 import { type HistoryRepairAllResult, type HistoryRepairCommandOptions, type HistoryRepairResult } from "./history-repair.js";
-import { actionGlobalOptions as globalOptions, closeManyOptionsFromFlat, extensionOptionsFromArgs, mutationListOptions, normalizeActionName, normalizeCommandPath, normalizeMcpOptionsArrays, normalizeMcpUpdateOptions, optionsWithAuthor, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeStringArray as readStringArray, updateManyOptionsFromFlat, withAddNoteOption, withFilesDiscoveryOptions, withMutationCompaction } from "./runtime-input.js";
-import type { PmCreateActionOptions, PmUpdateActionOptions } from "./cli-contracts/typed-action-inputs.js";
-import { type GraphCommandOptions, type GraphResult, type GraphSubcommand } from "./graph/run.js";
+import { runHistoryAttest, type HistoryAttestCommandOptions } from "./history/attestation-command.js";
+import type { InitCommandOptions, InitResult } from "./init.js";
+import type { LearningsCommandOptions, LearningsResult } from "./learnings.js";
 import type { AppendCommandOptions, AppendResult } from "./lifecycle/append.js";
 import type { ClaimNextResult, ClaimResult, ReleaseResult } from "./lifecycle/claim.js";
 import type { CloseResult } from "./lifecycle/close.js";
-import { type ContractsCommandOptions, type ContractsResult } from "./cli-contracts/runtime-contracts.js";
+import { type CopyResult } from "./lifecycle/copy.js";
+import { type CreateResult } from "./lifecycle/create.js";
+import { type DeleteResult } from "./lifecycle/delete.js";
+import { type FocusResult } from "./lifecycle/focus.js";
+import { type PlanCommandOptions, type PlanCommandResult, type PlanSubcommand } from "./lifecycle/plan.js";
+import type { ReopenCommandOptions, ReopenResult } from "./lifecycle/reopen.js";
+import { type RestoreResult } from "./lifecycle/restore.js";
+import { type UpdateResult } from "./lifecycle/update.js";
+import type { NotesCommandOptions, NotesResult } from "./notes.js";
+import type { ProfileApplyCommandOptions, ProfileApplyResult, ProfileLintResult, ProfileListResult, ProfileResult, ProfileShowResult, ProfileSubcommand } from "./profile.js";
+import { type AggregateOptions, type AggregateResult } from "./query/aggregate.js";
+import { type PmCompleteListOptions, type PmCompleteListResult } from "./query/complete-list.js";
+import { type ContextOptions, type ContextResult } from "./query/context.js";
+import { type GetOptions, type GetResult } from "./query/get.js";
 import { type ListOptions, type ListResult } from "./query/list.js";
+import { type NextOptions, type NextResult } from "./query/next.js";
 import { type SearchOptions, type SearchResult } from "./query/search.js";
+import { type PmReadOutputOptions, type PmReadOutputResultFor } from "./read-output-contracts.js";
+import { closeManyOptionsFromFlat, extensionOptionsFromArgs, actionGlobalOptions as globalOptions, mutationListOptions, normalizeActionName, normalizeCommandPath, normalizeMcpOptionsArrays, normalizeMcpUpdateOptions, optionsWithAuthor, readRuntimeScalarString as readScalarString, readRuntimeScalarStringAllowBlank as readScalarStringAllowBlank, readRuntimeStringArray as readStringArray, updateManyOptionsFromFlat, withAddNoteOption, withFilesDiscoveryOptions, withMutationCompaction } from "./runtime-input.js";
+import type { ClaimNextOptions, CloseTaskResult, GetContractsOptions, PauseTaskResult, PmActionInput, PmActionName, PmActionOptions, PmClientCloseActionOptions, PmClientFullMutationOptions, PmClientOptions, PmClientRunArgs, SchemaResult, StartTaskResult } from "./runtime-public-contracts.js";
+import { readRequiredString } from "./runtime/context.js";
+import { type RunSchemaEvolutionMigrationOptions, type SchemaAddFieldCommandOptions, type SchemaAddFieldResult, type SchemaAddStatusCommandOptions, type SchemaAddStatusResult, type SchemaAddTypeCommandOptions, type SchemaAddTypeInferCommandOptions, type SchemaAddTypeInferResult, type SchemaAddTypeResult, type SchemaApplyPresetCommandOptions, type SchemaApplyPresetResult, type SchemaEvolutionMigrationRequest, type SchemaEvolutionMigrationResult, type SchemaInspectResult, type SchemaListFieldsResult, type SchemaListResult, type SchemaRemoveFieldCommandOptions, type SchemaRemoveFieldResult, type SchemaRemoveStatusCommandOptions, type SchemaRemoveStatusResult, type SchemaRemoveTypeCommandOptions, type SchemaRemoveTypeResult, type SchemaShowFieldResult, type SchemaShowResult, type SchemaShowStatusResult, type SchemaSubcommand } from "./schema.js";
 import { type StatsCommandOptions, type StatsResult } from "./stats.js";
-import { type DuplicatesCommandOptions, type DuplicatesResult } from "./duplicates.js";
-import type { CommentsCommandOptions, CommentsResult } from "./comments.js";
-import type { ConfigCommandOptions, ConfigResult } from "./config.js";
-import type { DepsCommandOptions, DepsResult } from "./dependencies.js";
-import type { DocsCommandOptions, DocsResult } from "./docs.js";
-import type { FilesCommandOptions, FilesDiscoverOptions, FilesDiscoverResult, FilesLookupOptions, FilesLookupResult, FilesResult } from "./files.js";
-import type { InitCommandOptions, InitResult } from "./init.js";
-import type { LearningsCommandOptions, LearningsResult } from "./learnings.js";
-import type { NotesCommandOptions, NotesResult } from "./notes.js";
-import type { ProfileApplyCommandOptions, ProfileApplyResult, ProfileLintResult, ProfileListResult, ProfileResult, ProfileShowResult, ProfileSubcommand } from "./profile.js";
-import { type SchemaAddFieldCommandOptions, type SchemaAddFieldResult, type SchemaAddStatusCommandOptions, type SchemaAddStatusResult, type SchemaAddTypeCommandOptions, type SchemaAddTypeInferCommandOptions, type SchemaAddTypeInferResult, type SchemaAddTypeResult, type SchemaApplyPresetCommandOptions, type SchemaApplyPresetResult, type SchemaInspectResult, type SchemaListFieldsResult, type SchemaListResult, type RunSchemaEvolutionMigrationOptions, type SchemaEvolutionMigrationRequest, type SchemaEvolutionMigrationResult, type SchemaRemoveFieldCommandOptions, type SchemaRemoveFieldResult, type SchemaRemoveStatusCommandOptions, type SchemaRemoveStatusResult, type SchemaRemoveTypeCommandOptions, type SchemaRemoveTypeResult, type SchemaShowFieldResult, type SchemaShowResult, type SchemaShowStatusResult, type SchemaSubcommand } from "./schema.js";
-export type { ClaimResult, CloseResult, CreateResult, ReleaseResult, UpdateResult, };
-export { getActiveExtensionRegistrations, runActiveOnReadHooks, runActiveOnWriteHooks, } from "../core/extensions/index.js";
-export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic, } from "../core/fs/fs-utils.js";
-export { appendHistoryEntry, createHistoryEntry, } from "../core/history/history.js";
-export { classifyHistoryEvent, HISTORY_EVENT_CLASSIFICATION_VERSION, MAINTENANCE_HISTORY_OPERATIONS, SUBSTANTIVE_HISTORY_OPERATIONS, type HistoryEventClass } from "../core/history/event-classification.js";
-export { generateItemId, normalizeItemId, normalizeRawItemId, } from "../core/item/id.js";
-export { readBooleanOption, readCsvListOption, readStringOption, } from "./package-runtime-options.js";
-export { PM_CLI_EXPECTED_ERROR_NAME, createPmCliExpectedError, isPmCliExpectedError, type CreatePmCliExpectedErrorOptions, type PmCliExpectedError, } from "./errors.js";
-export { commitImportedItem, emptyImportedDocument, ensureTrackerInitialized, selectImportAuthor, toEstimatedMinutesValue, toImportBoolean, toImportConfidence, toImportInteger, toImportLinkedDocs, toImportLinkedFiles, toImportLinkedTests, toImportLogEntries, toImportNormalizedEnum, toImportNumberMap, toImportPriority, toImportStatus, toImportStringList, toImportStringMap, toImportTags, toNonEmptyImportString, type CommitImportedItemParams, type CommitImportedItemResult, type ImportLinkedScope, type ImportPriorityValue, type ToImportLinkedArtifactsOptions, type ToImportLinkedTestsOptions, type ToImportLogEntriesOptions, } from "./package-import-adapters.js";
-export { canonicalDocument, normalizeItemMetadata, serializeItemDocument, splitFrontMatter, } from "../core/item/item-format.js";
-export { BASELINE_ITEM_FORMAT_VERSION, CURRENT_ITEM_FORMAT_VERSION, classifyItemFormatVersion, effectiveItemFormatVersion, normalizeItemFormatVersion, scanItemFormatVersions, type ItemFormatVersionScanEntry, type ItemFormatVersionScanResult, type ItemFormatVersionStatus, } from "../core/item/item-format-version.js";
+export { PM_GITIGNORE_END, PM_GITIGNORE_START, ensurePmGitignore, getPmGitignoreBlock, type EnsurePmGitignoreResult } from "./workspace.js";
+export { SEARCH_EXTENSION_FLAG_DEFINITIONS } from "./extension-contracts.js";
+export type { FlagDefinition } from "../core/extensions/loader.js";
+export * from "./cli-contracts/agent-output-contracts.js";
+export { PmCompleteListValidationError, assertCompleteListResult, certifyCompleteListResult, createCompleteListOptions, inspectCompleteListResult, type PmCompleteListCertificate, type PmCompleteListFailureReceipt, type PmCompleteListFinding, type PmCompleteListFindingCode, type PmCompleteListInspection, type PmCompleteListOptions, type PmCompleteListResult } from "./query/complete-list.js";
+export { getWorkspaceContracts } from "./query/workspace-contracts.js";
+export type { WorkspaceExtensionCommandContract, WorkspaceFieldContract } from "./workspace-contracts.js";
+export type { PmReadOutputBudgetExceeded, PmReadOutputOptions, PmReadOutputResult, PmReadOutputResultFor, PmReadOutputSurfaceContract } from "./read-output-contracts.js";
+export type { PmReadOutputSessionReceipt, PmReadOutputSessionState } from "./read-output-session.js";
+export type { PmContextIntentContract } from "./context-intent-contracts.js";
+export type { PmErrorCodeContract } from "./error-code-catalog.js";
+export { clearWorkspaceContractsCache } from "./workspace-contracts-cache.js";
+export * from "./governance/workflow-policy.js";
+export type * from "./governance/assurance-action-contracts.js";
+export { runCloseTask, runPauseTask, runStartTask, type TaskCompositionOptions } from "./lifecycle/task-composition.js";
+export type { ClaimResult, CloseResult, CreateResult, ReleaseResult, UpdateResult };
+export { getActiveExtensionRegistrations, runActiveOnReadHooks, runActiveOnWriteHooks } from "../core/extensions/index.js";
+export { pathExists, readFileIfExists, removeFileIfExists, writeFileAtomic } from "../core/fs/fs-utils.js";
+export { appendHistoryEntry, createHistoryEntry } from "../core/history/history.js";
+export { HISTORY_EVENT_CLASSIFICATION_VERSION, MAINTENANCE_HISTORY_OPERATIONS, SUBSTANTIVE_HISTORY_OPERATIONS, classifyHistoryEvent, type HistoryEventClass } from "../core/history/event-classification.js";
+export { generateItemId, normalizeItemId, normalizeRawItemId } from "../core/item/id.js";
+export { readBooleanOption, readCsvListOption, readStringOption } from "./package-runtime-options.js";
+export { PM_CLI_EXPECTED_ERROR_NAME, createPmCliExpectedError, isPmCliExpectedError, type CreatePmCliExpectedErrorOptions, type PmCliExpectedError } from "./errors.js";
+export { commitImportedItem, emptyImportedDocument, ensureTrackerInitialized, selectImportAuthor, toEstimatedMinutesValue, toImportBoolean, toImportConfidence, toImportInteger, toImportLinkedDocs, toImportLinkedFiles, toImportLinkedTests, toImportLogEntries, toImportNormalizedEnum, toImportNumberMap, toImportPriority, toImportStatus, toImportStringList, toImportStringMap, toImportTags, toNonEmptyImportString, type CommitImportedItemParams, type CommitImportedItemResult, type ImportLinkedScope, type ImportPriorityValue, type ToImportLinkedArtifactsOptions, type ToImportLinkedTestsOptions, type ToImportLogEntriesOptions } from "./package-import-adapters.js";
+export { canonicalDocument, normalizeItemMetadata, serializeItemDocument, splitFrontMatter } from "../core/item/item-format.js";
+export { BASELINE_ITEM_FORMAT_VERSION, CURRENT_ITEM_FORMAT_VERSION, classifyItemFormatVersion, effectiveItemFormatVersion, normalizeItemFormatVersion, scanItemFormatVersions, type ItemFormatVersionScanEntry, type ItemFormatVersionScanResult, type ItemFormatVersionStatus } from "../core/item/item-format-version.js";
 export { parseTags } from "../core/item/parse.js";
 export { isTerminalStatus, normalizeStatusInput } from "../core/item/status.js";
 export { resolveItemTypeRegistry } from "../core/item/type-registry.js";
 export { acquireLock } from "../core/lock/lock.js";
-export { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry, } from "../core/schema/runtime-schema.js";
+export { resolveRuntimeFieldRegistry, resolveRuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
 export { EXIT_CODE };
 export { PmCliError } from "../core/shared/errors.js";
 export { isTimestampLiteral, nowIso } from "../core/shared/time.js";
-export { jaccardSimilarity, normalizeSimilarityText, scoreItemSimilarity, tokenizeSimilarityText, type ItemSimilarityScore, } from "./similarity-scoring.js";
-export { listAllItemMetadata, listAllItemMetadataLight, locateItem, readLocatedItem, } from "../core/store/item-store.js";
-export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot, } from "../core/store/paths.js";
+export { jaccardSimilarity, normalizeSimilarityText, scoreItemSimilarity, tokenizeSimilarityText, type ItemSimilarityScore } from "./similarity-scoring.js";
+export { listAllItemMetadata, listAllItemMetadataLight, locateItem, readLocatedItem } from "../core/store/item-store.js";
+export { getHistoryPath, getItemPath, getSettingsPath, resolveImplicitPmRoot, resolvePmRoot } from "../core/store/paths.js";
 export { readSettings } from "../core/store/settings.js";
-export { runAggregate, type AggregateOptions, type AggregateResult, type AggregateRow, } from "./query/aggregate.js";
-export { CONTEXT_OUTPUT_VALUES, runContext, type BlockerEntry, type ContextFocusItem, type ContextOptions, type ContextOutputFormat, type ContextResult, type HierarchyChild, type HierarchyNode, type HotFile, type ProgressEntry, type RecentContextItem, type StaleEntry, type TestHealthSummary, type WorkloadEntry, } from "./query/context.js";
+export { runAggregate, type AggregateOptions, type AggregateResult, type AggregateRow } from "./query/aggregate.js";
+export { CONTEXT_OUTPUT_VALUES, runContext, type BlockerEntry, type ContextFocusItem, type ContextOptions, type ContextOutputFormat, type ContextResult, type HierarchyChild, type HierarchyNode, type HotFile, type ProgressEntry, type RecentContextItem, type StaleEntry, type TestHealthSummary, type WorkloadEntry } from "./query/context.js";
 export { runGet, type GetOptions, type GetResult } from "./query/get.js";
-export { runList, type ListFullResult, type ListCompactResult, type ListedItem, type ListOptions, type ListProjectedItem, type ListProjectedItemCore, type ListResult, type ListResultItem, type ListSortField, type ListSortOrder, type ListTreeItem, type ListTreeMetadata, type ListVerboseResult, } from "./query/list.js";
-export { closeItem, runClose, type CloseCommandOptions, } from "./lifecycle/close.js";
-export { runCopy, type CopyOptions, type CopyResult, } from "./lifecycle/copy.js";
-export { runDelete, type DeleteCommandOptions, type DeleteResult, } from "./lifecycle/delete.js";
-export { runFocus, type FocusOptions, type FocusResult, } from "./lifecycle/focus.js";
-export { runRestore, type RestoreCommandOptions, type RestoreResult, } from "./lifecycle/restore.js";
-export { DEFAULT_TERMINAL_TRANSITION_POLICY, applyTerminalOrderingPolicy, requireTerminalReason, resolveTerminalReason, type CloseOperationOptions, type CloseOperationResult, type TerminalOrderingMutation, type TerminalReasonInput, type TerminalReasonResolution, type TerminalReasonSource, type TerminalTransitionPolicy, } from "./lifecycle-policy.js";
+export { runList, type ListCompactResult, type ListFullResult, type ListOptions, type ListProjectedItem, type ListProjectedItemCore, type ListResult, type ListResultItem, type ListSortField, type ListSortOrder, type ListTreeItem, type ListTreeMetadata, type ListVerboseResult, type ListedItem } from "./query/list.js";
+export { closeItem, runClose, type CloseCommandOptions } from "./lifecycle/close.js";
+export { runCopy, type CopyOptions, type CopyResult } from "./lifecycle/copy.js";
+export { runDelete, type DeleteCommandOptions, type DeleteResult } from "./lifecycle/delete.js";
+export { runFocus, type FocusOptions, type FocusResult } from "./lifecycle/focus.js";
+export { runRestore, type RestoreCommandOptions, type RestoreResult } from "./lifecycle/restore.js";
+export { DEFAULT_TERMINAL_TRANSITION_POLICY, applyTerminalOrderingPolicy, requireTerminalReason, resolveTerminalReason, type CloseOperationOptions, type CloseOperationResult, type TerminalOrderingMutation, type TerminalReasonInput, type TerminalReasonResolution, type TerminalReasonSource, type TerminalTransitionPolicy } from "./lifecycle-policy.js";
 export { runUpdate, type UpdateCommandOptions } from "./lifecycle/update.js";
 export { runReopen, type PreviousTerminalEvidence, type RecurrenceReceipt, type ReopenCommandOptions, type ReopenResult } from "./lifecycle/reopen.js";
-export { NEXT_OUTPUT_VALUES, runNext, type NextActionableItem, type NextBlockerRef, type NextOptions, type NextOutputFormat, type NextRecommendation, type NextResult, } from "./query/next.js";
-export { runSearch, type SearchCompactResult, type SearchHit, type SearchHitHighlight, type SearchMatchMode, type SearchOptions, type SearchResult, type SearchResultItem, type SearchVerboseResult, } from "./query/search.js";
-export { runStats, type StatsCommandOptions, type StatsResult, } from "./stats.js";
-export { runDuplicates, type DuplicatesCommandOptions, type DuplicatesResult, } from "./duplicates.js";
-export { renderCalendarMarkdown, renderCalendarToon, resolveCalendarOutputFormat, runCalendar, type CalendarOptions, type CalendarResult, } from "./query/calendar.js";
-export { renderGuideMarkdown, resolveGuideOutputFormat, runGuide, type GuideDepth, type GuideOptions, type GuideOutputFormat, type GuideResult, } from "./guide.js";
-export { runCompletion, type CompletionResult, type CompletionShell, } from "./completion.js";
-export { runReindex, type ReindexOptions, type ReindexResult, } from "./governance/reindex.js";
-export { loadCreateTemplateOptions, runTemplatesList, runTemplatesSave, runTemplatesShow, type CreateTemplateOptions, type TemplatesListResult, type TemplatesSaveResult, type TemplatesShowResult, } from "./templates.js";
-export { runTestRunsList, runTestRunsLogs, runTestRunsResume, runTestRunsStatus, runTestRunsStop, type TestRunsListCommandOptions, type TestRunsLogsCommandOptions, type TestRunsResumeCommandOptions, type TestRunsStopCommandOptions, } from "./test/runs.js";
-export { CONFIDENCE_TEXT_VALUES, DEPENDENCY_KIND_VALUES, BUILTIN_ITEM_TYPE_VALUES, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, RISK_VALUES, STATUS_VALUES, } from "../types/index.js";
+export { NEXT_OUTPUT_VALUES, runNext, type NextActionableItem, type NextBlockerRef, type NextOptions, type NextOutputFormat, type NextRecommendation, type NextResult } from "./query/next.js";
+export { runSearch, type SearchCompactResult, type SearchHit, type SearchHitHighlight, type SearchMatchMode, type SearchOptions, type SearchResult, type SearchResultItem, type SearchVerboseResult } from "./query/search.js";
+export { runStats, type StatsCommandOptions, type StatsResult } from "./stats.js";
+export { runDuplicates, type DuplicatesCommandOptions, type DuplicatesResult } from "./duplicates.js";
+export { renderCalendarMarkdown, renderCalendarToon, resolveCalendarOutputFormat, runCalendar, type CalendarOptions, type CalendarResult } from "./query/calendar.js";
+export { renderGuideMarkdown, resolveGuideOutputFormat, runGuide, type GuideDepth, type GuideOptions, type GuideOutputFormat, type GuideResult } from "./guide.js";
+export { runCompletion, type CompletionResult, type CompletionShell } from "./completion.js";
+export { runReindex, type ReindexOptions, type ReindexResult } from "./governance/reindex.js";
+export { loadCreateTemplateOptions, runTemplatesList, runTemplatesSave, runTemplatesShow, type CreateTemplateOptions, type TemplatesListResult, type TemplatesSaveResult, type TemplatesShowResult } from "./templates.js";
+export { runTestRunsList, runTestRunsLogs, runTestRunsResume, runTestRunsStatus, runTestRunsStop, type TestRunsListCommandOptions, type TestRunsLogsCommandOptions, type TestRunsResumeCommandOptions, type TestRunsStopCommandOptions } from "./test/runs.js";
+export { BUILTIN_ITEM_TYPE_VALUES, CONFIDENCE_TEXT_VALUES, DEPENDENCY_KIND_VALUES, ISSUE_SEVERITY_VALUES, ITEM_TYPE_VALUES, RISK_VALUES, STATUS_VALUES } from "../types/index.js";
 export type { GlobalOptions } from "../core/shared/command-types.js";
 /** Inputs that customize the package command operation. */
 export type PackageCommandOptions = ExtensionCommandOptions;
 /** Structured result returned by the package command operation. */
 export type PackageCommandResult = ExtensionCommandResult;
-export type { Dependency, ItemDocument, ItemMetadata, ItemStatus, ItemType, LinkedDoc, LinkedFile, LinkedTest, LogNote, PmSettings, } from "../types/index.js";
-import type { ClaimNextOptions, CloseTaskResult, GetContractsOptions, PauseTaskResult, PmActionInput, PmActionName, PmActionOptions, PmClientCloseActionOptions, PmClientFullMutationOptions, PmClientOptions, PmClientRunArgs, SchemaResult, StartTaskResult } from "./runtime-public-contracts.js";
-export type { ClaimNextOptions, CloseTaskResult, GetContractsOptions, PauseTaskResult, PmActionInput, PmActionName, PmActionOptions, PmClientCloseActionOptions, PmClientFullMutationOptions, PmClientMutationOptions, PmClientOptions, PmClientRunArgs, SchemaResult, StartTaskResult, WorkspaceContracts, WorkspaceContractsOptions, } from "./runtime-public-contracts.js";
+export type { Dependency, ItemDocument, ItemMetadata, ItemStatus, ItemType, LinkedDoc, LinkedFile, LinkedTest, LogNote, PmSettings } from "../types/index.js";
+export type { ClaimNextOptions, CloseTaskResult, GetContractsOptions, PauseTaskResult, PmActionInput, PmActionName, PmActionOptions, PmClientCloseActionOptions, PmClientFullMutationOptions, PmClientMutationOptions, PmClientOptions, PmClientRunArgs, SchemaResult, StartTaskResult, WorkspaceContracts, WorkspaceContractsOptions } from "./runtime-public-contracts.js";
 type ReadOptions<Options> = Options & PmReadOutputOptions;
 type ReadPromise<Result, Options> = Promise<PmReadOutputResultFor<Result, Options>>;
 /**
@@ -602,8 +598,6 @@ export declare function packageDeactivate(target: string, options?: PackageComma
 export declare function upgrade(target?: string, options?: UpgradeCommandOptions, clientOptions?: PmClientOptions): Promise<UpgradeResult>;
 /** Implements get contracts for the public runtime surface of this module. */
 export declare function getContracts(pmRootOrOptions?: string | GetContractsOptions, options?: GetContractsOptions): Promise<ContractsResult>;
-/** Read a required non-empty string from an action argument bag. */
-export declare function readRequiredString(args: Record<string, unknown>, key: string): string;
 /** Options for executing direct SDK work inside the workspace extension lifecycle. */
 export interface ActiveExtensionScopeOptions {
     /** Workspace resolution directory; defaults to the process working directory. */
@@ -660,4 +654,5 @@ declare global {
     var __pmCliActionRunnerTestHooks: typeof actionRunnerTestHooks | undefined;
 }
 export type { ContractsCommandOptions, ContractsResult };
-export type { AppendCommandOptions, AppendResult, CommentsCommandOptions, CommentsResult, ConfigCommandOptions, ConfigResult, DepsCommandOptions, DepsResult, DocsCommandOptions, DocsResult, ExtensionCommandOptions, ExtensionCommandResult, FilesCommandOptions, FilesDiscoverOptions, FilesDiscoverResult, FilesLookupOptions, FilesLookupResult, FilesResult, GcCommandOptions, GcResult, HealthResult, InitCommandOptions, InitResult, LearningsCommandOptions, LearningsResult, NotesCommandOptions, NotesResult, ProfileApplyCommandOptions, ProfileApplyResult, ProfileLintResult, ProfileListResult, ProfileResult, ProfileShowResult, ProfileSubcommand, RunHealthOptions, SchemaAddFieldCommandOptions, SchemaAddFieldResult, SchemaAddStatusCommandOptions, SchemaAddStatusResult, SchemaAddTypeCommandOptions, SchemaAddTypeInferCommandOptions, SchemaAddTypeInferResult, SchemaAddTypeResult, SchemaApplyPresetCommandOptions, SchemaApplyPresetResult, SchemaInspectResult, SchemaListFieldsResult, SchemaListResult, RunSchemaEvolutionMigrationOptions, SchemaEvolutionMigrationRequest, SchemaEvolutionMigrationResult, SchemaRemoveFieldCommandOptions, SchemaRemoveFieldResult, SchemaRemoveStatusCommandOptions, SchemaRemoveStatusResult, SchemaRemoveTypeCommandOptions, SchemaRemoveTypeResult, SchemaShowFieldResult, SchemaShowResult, SchemaShowStatusResult, SchemaSubcommand, UpgradeCommandOptions, UpgradeResult, ValidateCommandOptions, ValidateCountsResult, ValidateResult, };
+export { readRequiredString } from "./runtime/context.js";
+export type { AppendCommandOptions, AppendResult, CommentsCommandOptions, CommentsResult, ConfigCommandOptions, ConfigResult, DepsCommandOptions, DepsResult, DocsCommandOptions, DocsResult, ExtensionCommandOptions, ExtensionCommandResult, FilesCommandOptions, FilesDiscoverOptions, FilesDiscoverResult, FilesLookupOptions, FilesLookupResult, FilesResult, GcCommandOptions, GcResult, HealthResult, InitCommandOptions, InitResult, LearningsCommandOptions, LearningsResult, NotesCommandOptions, NotesResult, ProfileApplyCommandOptions, ProfileApplyResult, ProfileLintResult, ProfileListResult, ProfileResult, ProfileShowResult, ProfileSubcommand, RunHealthOptions, RunSchemaEvolutionMigrationOptions, SchemaAddFieldCommandOptions, SchemaAddFieldResult, SchemaAddStatusCommandOptions, SchemaAddStatusResult, SchemaAddTypeCommandOptions, SchemaAddTypeInferCommandOptions, SchemaAddTypeInferResult, SchemaAddTypeResult, SchemaApplyPresetCommandOptions, SchemaApplyPresetResult, SchemaEvolutionMigrationRequest, SchemaEvolutionMigrationResult, SchemaInspectResult, SchemaListFieldsResult, SchemaListResult, SchemaRemoveFieldCommandOptions, SchemaRemoveFieldResult, SchemaRemoveStatusCommandOptions, SchemaRemoveStatusResult, SchemaRemoveTypeCommandOptions, SchemaRemoveTypeResult, SchemaShowFieldResult, SchemaShowResult, SchemaShowStatusResult, SchemaSubcommand, UpgradeCommandOptions, UpgradeResult, ValidateCommandOptions, ValidateCountsResult, ValidateResult };