@unbrained/pm-cli 2026.10.18 → 2026.10.20

package/dist/sdk/query/list.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9260454d-9ece-5b5f-a812-f9865b6f4ee4")}catch{}})();import{renderPmCommand}from"../command-line.js";import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{getActiveExtensionRegistrations,hasActiveOnReadHooks}from"../../core/extensions/index.js";import{toItemRecord}from"../../core/item/item-record.js";import{isTerminalStatus}from"../../core/item/status.js";import{collectDependencyBlockedIds}from"../actionability.js";import{isStatusAllFilterInput,parseStatusFilterCsv}from"../../core/item/status-filter.js";import{resolveItemTypeRegistry}from"../../core/item/type-registry.js";import{parseIntegerLimit}from"./parsers.js";import{parsePriorityFilterSet,parseStringFilterSet,parseTypeFilterSet}from"./multi-value-filters.js";import{collectRuntimeFilterValues,matchesRuntimeFilters}from"../../core/schema/runtime-field-filters.js";import{hasMissingMetadataFilter,itemMatchesMissingMetadata,lifecycleClassifierFromStatusRegistry}from"../../core/governance/metadata-coverage.js";import{contentFiltersNeedBody,contentFiltersNeedCollections,hasContentFieldFilter,itemMatchesContentFilters}from"../../core/governance/content-fields.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{compareTimestampStrings,matchesTimestampFilters,nowIso,resolveIsoOrRelative}from"../../core/shared/time.js";import{listAllItemMetadata,listAllItemMetadataLight,listAllItemMetadataWithBody}from"../../core/store/item-store.js";import{HEAVY_METADATA_KEYS,readItemMetadataDerivedIndexState}from"../../core/store/item-metadata-cache.js";import{queryItemMetadataIndex}from"../../core/store/item-metadata-query-index.js";import{resolvePmRoot}from"../../core/store/paths.js";import{readSettings}from"../../core/store/settings.js";import{LIST_FILTER_FLAG_CONTRACTS}from"../cli-contracts/flag-contracts.js";import{resolveWorkspaceRelationshipKindRegistry}from"../graph/assembly.js";import{collectHierarchyRelations,indexHierarchyRelations}from"../graph/hierarchy-integrity.js";import{createQueryFingerprint,encodeQueryCursor,resolveQueryCursorStart,selectCursorSemanticOptions}from"../pagination.js";import{BRIEF_LIST_FIELDS,DEFAULT_COMPACT_LIST_FIELDS,listListProjectionFields}from"./projection-contracts.js";import{BRIEF_LIST_FIELDS as BRIEF_LIST_FIELDS2,DEFAULT_COMPACT_LIST_FIELDS as DEFAULT_COMPACT_LIST_FIELDS2,LIST_COMMAND_DEFAULT_PROJECTIONS,listListProjectionFields as listListProjectionFields2}from"./projection-contracts.js";const resolveMissingMetadataFilters=options=>({acMissing:options.filterAcMissing===!0,estimatesMissing:options.filterEstimatesMissing===!0,resolutionMissing:options.filterResolutionMissing===!0,metadataMissing:options.filterMetadataMissing===!0,reviewerMissing:options.filterReviewerMissing===!0,riskMissing:options.filterRiskMissing===!0,confidenceMissing:options.filterConfidenceMissing===!0,sprintMissing:options.filterSprintMissing===!0,releaseMissing:options.filterReleaseMissing===!0}),CONTENT_FIELD_FLAG_MAPPINGS=[{field:"notes",presentKey:"hasNotes",absentKey:"noNotes",presentFlag:"--has-notes",absentFlag:"--no-notes"},{field:"learnings",presentKey:"hasLearnings",absentKey:"noLearnings",presentFlag:"--has-learnings",absentFlag:"--no-learnings"},{field:"files",presentKey:"hasFiles",absentKey:"noFiles",presentFlag:"--has-files",absentFlag:"--no-files"},{field:"docs",presentKey:"hasDocs",absentKey:"noDocs",presentFlag:"--has-docs",absentFlag:"--no-docs"},{field:"tests",presentKey:"hasTests",absentKey:"noTests",presentFlag:"--has-tests",absentFlag:"--no-tests"},{field:"comments",presentKey:"hasComments",absentKey:"noComments",presentFlag:"--has-comments",absentFlag:"--no-comments"},{field:"deps",presentKey:"hasDeps",absentKey:"noDeps",presentFlag:"--has-deps",absentFlag:"--no-deps"},{field:"body",presentKey:"hasBody",absentKey:"emptyBody",presentFlag:"--has-body",absentFlag:"--empty-body"},{field:"linked_command",presentKey:"hasLinkedCommand",absentKey:"noLinkedCommand",presentFlag:"--has-linked-command",absentFlag:"--no-linked-command"}],resolveContentFieldFilters=options=>{const conflict=CONTENT_FIELD_FLAG_MAPPINGS.find(mapping=>options[mapping.presentKey]===!0&&options[mapping.absentKey]===!0);if(conflict)throw new PmCliError(`Cannot combine ${conflict.presentFlag} with ${conflict.absentFlag} for the same field.`,EXIT_CODE.USAGE);return Object.fromEntries(CONTENT_FIELD_FLAG_MAPPINGS.flatMap(mapping=>options[mapping.presentKey]===!0?[[mapping.field,"present"]]:options[mapping.absentKey]===!0?[[mapping.field,"absent"]]:[]))},LIST_SORT_FIELDS=["priority","deadline","updated_at","created_at","title","parent"],LIST_SORT_ORDER_VALUES=["asc","desc"],HEAVY_PROJECTION_FIELDS=new Set(HEAVY_METADATA_KEYS);function resolveListCompleteness(warnings,indexed,strict){const unreadableItemCount=warnings.filter(warning=>warning.startsWith("item_list_item_read_failed:")).length,unreadableDirectoryCount=warnings.filter(warning=>warning.startsWith("item_list_directory_read_failed:")).length,completeness={status:indexed?"unchecked":unreadableItemCount+unreadableDirectoryCount>0?"partial":"complete",unreadable_item_count:unreadableItemCount,unreadable_directory_count:unreadableDirectoryCount};if(strict&&completeness.status==="partial")throw new PmCliError(`List source is incomplete: ${unreadableItemCount} item document(s) and ${unreadableDirectoryCount} item directory/directories could not be read.`,EXIT_CODE.GENERIC_FAILURE,{code:"list_source_incomplete",why:"Strict list reads fail closed so agents and SDK consumers never treat an omitted item as a complete workspace.",nextSteps:["Run pm validate --check-storage-integrity to locate unreadable tracker artifacts.","Repair the reported files or align the installed decoder version, then retry."]});return completeness}function isNonEmptyRecord(value){return typeof value=="object"&&value!==null&&!Array.isArray(value)&&Object.keys(value).length>0}const CONTENT_FILTER_ECHO_ENTRIES=[{key:"hasNotes",summaryKey:"has_notes"},{key:"hasLearnings",summaryKey:"has_learnings"},{key:"hasFiles",summaryKey:"has_files"},{key:"hasDocs",summaryKey:"has_docs"},{key:"hasTests",summaryKey:"has_tests"},{key:"hasComments",summaryKey:"has_comments"},{key:"hasDeps",summaryKey:"has_deps"},{key:"hasBody",summaryKey:"has_body"},{key:"hasLinkedCommand",summaryKey:"has_linked_command"},{key:"noNotes",summaryKey:"no_notes"},{key:"noLearnings",summaryKey:"no_learnings"},{key:"noFiles",summaryKey:"no_files"},{key:"noDocs",summaryKey:"no_docs"},{key:"noTests",summaryKey:"no_tests"},{key:"noComments",summaryKey:"no_comments"},{key:"noDeps",summaryKey:"no_deps"},{key:"emptyBody",summaryKey:"empty_body"},{key:"noLinkedCommand",summaryKey:"no_linked_command"}],GOVERNANCE_MISSING_ECHO_ENTRIES=[{key:"filterReviewerMissing",summaryKey:"filter_reviewer_missing"},{key:"filterRiskMissing",summaryKey:"filter_risk_missing"},{key:"filterConfidenceMissing",summaryKey:"filter_confidence_missing"},{key:"filterSprintMissing",summaryKey:"filter_sprint_missing"},{key:"filterReleaseMissing",summaryKey:"filter_release_missing"}];function applyContentFilterEcho(filters,options){for(const entry of CONTENT_FILTER_ECHO_ENTRIES)options[entry.key]===!0&&(filters[entry.summaryKey]=!0)}function applyGovernanceMissingFilterEcho(filters,options){for(const entry of GOVERNANCE_MISSING_ECHO_ENTRIES)options[entry.key]===!0&&(filters[entry.summaryKey]=!0)}function applyFilterValueEcho(filters,options,entries){for(const entry of entries){const value=options[entry.optionKey];value!==void 0&&(filters[entry.summaryKey]=entry.normalize?entry.normalize(value):value)}}function buildContentFilterEcho(options){const echo={};return applyContentFilterEcho(echo,options),echo}function buildGovernanceMissingFilterEcho(options){const echo={};return applyGovernanceMissingFilterEcho(echo,options),echo}const COMPACT_LIST_VALUE_FILTER_ECHO_ENTRIES=[{optionKey:"type",summaryKey:"type"},{optionKey:"tag",summaryKey:"tag"},{optionKey:"priority",summaryKey:"priority"},{optionKey:"deadlineBefore",summaryKey:"deadline_before"},{optionKey:"deadlineAfter",summaryKey:"deadline_after"},{optionKey:"updatedAfter",summaryKey:"updated_after"},{optionKey:"updatedBefore",summaryKey:"updated_before"},{optionKey:"createdAfter",summaryKey:"created_after"},{optionKey:"createdBefore",summaryKey:"created_before"},{optionKey:"ids",summaryKey:"ids"},{optionKey:"assignee",summaryKey:"assignee"},{optionKey:"assigneeFilter",summaryKey:"assignee_filter"},{optionKey:"parent",summaryKey:"parent"},{optionKey:"sprint",summaryKey:"sprint"},{optionKey:"release",summaryKey:"release"}],VERBOSE_LIST_VALUE_FILTER_ECHO_ENTRIES=[{optionKey:"type",summaryKey:"type"},{optionKey:"tag",summaryKey:"tag"},{optionKey:"priority",summaryKey:"priority"},{optionKey:"deadlineBefore",summaryKey:"deadline_before"},{optionKey:"deadlineAfter",summaryKey:"deadline_after"},{optionKey:"updatedAfter",summaryKey:"updated_after"},{optionKey:"updatedBefore",summaryKey:"updated_before"},{optionKey:"createdAfter",summaryKey:"created_after"},{optionKey:"createdBefore",summaryKey:"created_before"},{optionKey:"ids",summaryKey:"ids"},{optionKey:"assignee",summaryKey:"assignee"},{optionKey:"assigneeFilter",summaryKey:"assignee_filter"},{optionKey:"parent",summaryKey:"parent"},{optionKey:"sprint",summaryKey:"sprint"},{optionKey:"release",summaryKey:"release"},{optionKey:"limit",summaryKey:"limit"},{optionKey:"offset",summaryKey:"offset"},{optionKey:"includeBody",summaryKey:"include_body"},{optionKey:"compact",summaryKey:"compact"},{optionKey:"fields",summaryKey:"fields"}],VERBOSE_LIST_BOOLEAN_FILTER_ECHO_ENTRIES=[{key:"filterAcMissing",summaryKey:"filter_ac_missing"},{key:"filterEstimatesMissing",summaryKey:"filter_estimates_missing"},{key:"filterResolutionMissing",summaryKey:"filter_resolution_missing"},{key:"filterMetadataMissing",summaryKey:"filter_metadata_missing"}],LIST_RECENT_WINDOW="-7d";function buildCompactListFilterSummary(params){const{filtersStatus,options,treeEnabled,treeDepth,sortField,sortOrder,runtimeFieldFilters}=params,filters={};return filtersStatus!==null&&(filters.status=filtersStatus),options.dependencyBlocked===!0&&(filters.blocked_semantics="status_or_dependency"),applyFilterValueEcho(filters,options,COMPACT_LIST_VALUE_FILTER_ECHO_ENTRIES),applyListWindowFilterEcho(filters,options),options.filterAcMissing===!0&&(filters.filter_ac_missing=!0),options.filterEstimatesMissing===!0&&(filters.filter_estimates_missing=!0),options.filterResolutionMissing===!0&&(filters.filter_resolution_missing=!0),options.filterMetadataMissing===!0&&(filters.filter_metadata_missing=!0),applyGovernanceMissingFilterEcho(filters,options),applyContentFilterEcho(filters,options),options.limit!==void 0&&(filters.limit=options.limit),options.offset!==void 0&&(filters.offset=options.offset),options.includeBody===!0&&(filters.include_body=!0),options.fields!==void 0&&(filters.fields=options.fields),treeEnabled&&(filters.tree=!0,treeDepth!==void 0&&(filters.tree_depth=treeDepth)),sortField!==void 0&&(filters.sort=sortField,filters.order=sortOrder),isNonEmptyRecord(runtimeFieldFilters)&&(filters.runtime_filters=runtimeFieldFilters),filters}function compareDefaultSort(left,right,statusRegistry){const leftTerminal=isTerminalStatus(left.status,statusRegistry),rightTerminal=isTerminalStatus(right.status,statusRegistry);if(leftTerminal!==rightTerminal)return leftTerminal?1:-1;const byPriority=left.priority-right.priority;if(byPriority!==0)return byPriority;const byUpdated=compareTimestampStrings(right.updated_at,left.updated_at);return byUpdated!==0?byUpdated:(left.id??"").localeCompare(right.id??"")}function sortItemsDefault(items,statusRegistry){return[...items].sort((left,right)=>compareDefaultSort(left,right,statusRegistry))}function parseDeadline(raw,fieldLabel){if(raw!==void 0)return resolveIsoOrRelative(raw,new Date,fieldLabel)}function parseTimestampWindow(raw,fieldLabel){if(raw==null)return;const value=String(raw).trim();if(value.length!==0)return resolveIsoOrRelative(value,new Date,fieldLabel)}function resolveListUpdatedAfter(options){const hasUpdatedAfter=options.updatedAfter!=null&&String(options.updatedAfter).trim().length>0;if([options.today===!0,options.recent===!0,hasUpdatedAfter].filter(selected=>selected).length>1)throw new PmCliError("Choose only one updated_at window: --today, --recent, or --updated-after.",EXIT_CODE.USAGE);if(options.today===!0){const today=new Date;return today.setHours(0,0,0,0),today.toISOString()}return options.recent===!0?parseTimestampWindow(LIST_RECENT_WINDOW,"recent"):parseTimestampWindow(options.updatedAfter,"updated-after")}function applyListWindowFilterEcho(filters,options){options.today===!0&&(filters.today=!0),options.recent===!0&&(filters.recent=!0)}function parseIdsFilter(raw){if(raw==null)return;const value=String(raw).trim();if(value.length===0)throw new PmCliError("--ids requires at least one non-empty item ID",EXIT_CODE.USAGE);const ids=value.split(",").map(entry=>entry.trim()).filter(entry=>entry.length>0);if(ids.length===0)throw new PmCliError("--ids requires at least one non-empty item ID",EXIT_CODE.USAGE);return new Set(ids)}function parseOffset(raw){if(raw===void 0)return;const normalized=String(raw).trim(),parsed=normalized.length===0?Number.NaN:Number(normalized);if(!Number.isInteger(parsed)||parsed<0)throw new PmCliError("Offset filter must be a non-negative integer",EXIT_CODE.USAGE);return parsed}function parseFieldSelectors(raw){if(raw===void 0)return;const selectors=raw.split(",").map(entry=>entry.trim()).filter(entry=>entry.length>0);if(selectors.length===0)throw new PmCliError("List --fields requires a comma-separated list of field names",EXIT_CODE.USAGE);return[...new Set(selectors)]}function parseProjectionConfig(options,invokedCommand=options.projectionCommand??"list"){const compactRequested=options.compact===!0,briefRequested=options.brief===!0,fullRequested=options.full===!0,fieldSelectors=parseFieldSelectors(options.fields);if(Number(compactRequested)+Number(briefRequested)+Number(fullRequested)+ +(fieldSelectors!==void 0)>1)throw new PmCliError("List projection options are mutually exclusive. Use one of --compact, --brief, --full, or --fields.",EXIT_CODE.USAGE,{code:"projection_options_mutually_exclusive",recovery:{suggested_retry:`pm ${invokedCommand} --brief`,suggested_retry_args:[invokedCommand,"--brief"]}});if(fullRequested)return{mode:"full",fields:[]};if(briefRequested){const sortField=parseSortField(options.sort);return{mode:"brief",fields:[...new Set([...BRIEF_LIST_FIELDS,...sortField?[sortField]:[]])]}}return compactRequested?{mode:"compact",fields:[...DEFAULT_COMPACT_LIST_FIELDS]}:fieldSelectors?{mode:"fields",fields:[...new Set(fieldSelectors.map(field=>normalizeProjectionField(field)))]}:{mode:"full",fields:[]}}function normalizeProjectionField(field){return field.startsWith("item.")?field.slice(5):field}function validateListProjectionFields(projection,runtimeMetadataKeys,invokedCommand){if(projection.mode!=="fields")return;const allowedValues=listListProjectionFields(runtimeMetadataKeys),allowed=new Set(allowedValues.map(field=>normalizeProjectionField(field))),unknown=projection.fields.filter(field=>!allowed.has(normalizeProjectionField(field)));if(unknown.length>0){const suggestedRetryArguments=[invokedCommand,"--fields",projection.fields.filter(field=>!unknown.includes(field)).join(",")||"id,title,status"];throw new PmCliError(`Unknown list --fields value(s): ${unknown.join(", ")}`,EXIT_CODE.USAGE,{code:"unknown_field_projection",examples:["pm list-open --fields id,title,status,type,updated_at","pm list --fields id,title,parent,priority --limit 10","pm list-all --fields id,title,body --limit 5"],recovery:{allowed_values:allowedValues,suggested_retry:renderPmCommand(suggestedRetryArguments),suggested_retry_args:suggestedRetryArguments}})}}const LIST_SORT_FIELD_ALIASES=new Map([["updated","updated_at"],["update","updated_at"],["modified","updated_at"],["created","created_at"],["create","created_at"]]);function parseSortField(raw){if(raw===void 0)return;const normalized=raw.trim().toLowerCase(),aliased=LIST_SORT_FIELD_ALIASES.get(normalized);if(aliased)return aliased;if(!LIST_SORT_FIELDS.includes(normalized))throw new PmCliError(`Sort field must be one of ${LIST_SORT_FIELDS.join("|")} (aliases: updated->updated_at, created->created_at)`,EXIT_CODE.USAGE);return normalized}function parseSortOrder(raw){if(raw===void 0)return;const normalized=raw.trim().toLowerCase();if(!LIST_SORT_ORDER_VALUES.includes(normalized))throw new PmCliError(`Sort order must be one of ${LIST_SORT_ORDER_VALUES.join("|")}`,EXIT_CODE.USAGE);return normalized}function parseTreeDepth(raw){return parseIntegerLimit(raw,"--tree-depth")}function parseAssigneeFilter(raw){if(raw===void 0)return;const normalized=raw.trim().toLowerCase();if(!normalized)throw new PmCliError("Assignee filter must be one of assigned|unassigned",EXIT_CODE.USAGE);if(normalized!=="assigned"&&normalized!=="unassigned")throw new PmCliError(`Invalid assignee filter "${raw}". Allowed: assigned|unassigned`,EXIT_CODE.USAGE);return normalized}function resolveStatusFilter(status,statusRegistry){return parseStatusFilterCsv(status,statusRegistry,{strict:!0})}function parseListTagFilters(raw){return parseStringFilterSet(raw,{label:"--tag",normalize:tag=>tag.toLowerCase()})}function appendUnknownTagWarning(items,rawTags,warnings){const requestedTags=parseListTagFilters(rawTags);if(requestedTags===void 0)return;const knownTags=new Set(items.flatMap(item=>item.tags.map(tag=>tag.trim().toLowerCase()))),unknownTags=[...requestedTags].filter(tag=>!knownTags.has(tag));unknownTags.length>0&&warnings.push(`unknown_tags:${unknownTags.join(",")}`)}function assertListAssigneeFilters(assigneeFilter,assigneeModeFilter){if(assigneeFilter&&[...assigneeFilter].some(value=>value.toLowerCase()==="none"||value.toLowerCase()==="null"))throw new PmCliError('--assignee no longer accepts "none" or "null". Use --assignee-filter unassigned.',EXIT_CODE.USAGE);if(assigneeFilter!==void 0&&assigneeModeFilter==="unassigned")throw new PmCliError("Cannot combine --assignee with --assignee-filter unassigned",EXIT_CODE.USAGE)}function resolveListFilterSet(status,options,typeRegistry,statusRegistry){const assigneeFilter=parseStringFilterSet(options.assignee,{label:"--assignee"}),assigneeModeFilter=parseAssigneeFilter(options.assigneeFilter);assertListAssigneeFilters(assigneeFilter,assigneeModeFilter);const missingMetadataFilters=resolveMissingMetadataFilters(options),contentFieldFilters=resolveContentFieldFilters(options);return{idsFilter:parseIdsFilter(options.ids),statusSet:status&&status.length>0?new Set(status):void 0,excludeTerminal:options.excludeTerminal===!0,typeFilter:parseTypeFilterSet(options.type,typeRegistry),tagFilters:parseListTagFilters(options.tag),priorityFilter:parsePriorityFilterSet(options.priority),deadlineBefore:parseDeadline(options.deadlineBefore,"deadline-before"),deadlineAfter:parseDeadline(options.deadlineAfter,"deadline-after"),updatedAfter:resolveListUpdatedAfter(options),updatedBefore:parseTimestampWindow(options.updatedBefore,"updated-before"),createdAfter:parseTimestampWindow(options.createdAfter,"created-after"),createdBefore:parseTimestampWindow(options.createdBefore,"created-before"),assigneeFilter,assigneeModeFilter,parentFilter:options.parent?.trim(),treeEnabled:options.tree===!0,sprintFilter:parseStringFilterSet(options.sprint,{label:"--sprint"}),releaseFilter:parseStringFilterSet(options.release,{label:"--release"}),missingMetadataFilters,missingMetadataActive:hasMissingMetadataFilter(missingMetadataFilters),lifecycleClassifier:lifecycleClassifierFromStatusRegistry(statusRegistry),contentFieldFilters,contentFiltersActive:hasContentFieldFilter(contentFieldFilters)}}function matchesListIdentityFilters(item,filters,statusRegistry){return filters.idsFilter&&!filters.idsFilter.has(item.id)||filters.statusSet&&!filters.statusSet.has(item.status)||filters.excludeTerminal&&isTerminalStatus(item.status,statusRegistry)||filters.typeFilter&&!filters.typeFilter.has(item.type)||filters.tagFilters&&![...filters.tagFilters].some(tag=>(item.tags??[]).some(candidate=>candidate.trim().toLowerCase()===tag))?!1:filters.priorityFilter===void 0||filters.priorityFilter.has(item.priority)}function matchesListDateFilters(item,filters){return matchesTimestampFilters(item,filters)}function matchesListAssigneeFilterSet(item,filters){return filters.assigneeModeFilter==="assigned"&&!item.assignee||filters.assigneeModeFilter==="unassigned"&&item.assignee?!1:filters.assigneeFilter===void 0||item.assignee!==void 0&&filters.assigneeFilter.has(item.assignee)}function matchesListScopeFilters(item,filters,parentsByChild){const scalarParent=item.parent?.trim().toLowerCase(),logicalParentIds=[...new Set([...parentsByChild?.get(item.id.trim().toLowerCase())??[],...scalarParent?[scalarParent]:[]])];return filters.parentFilter!==void 0&&!filters.treeEnabled&&!logicalParentIds.includes(filters.parentFilter.trim().toLowerCase())||filters.sprintFilter!==void 0&&(item.sprint===void 0||!filters.sprintFilter.has(item.sprint))?!1:filters.releaseFilter===void 0||item.release!==void 0&&filters.releaseFilter.has(item.release)}function matchesListFilterSet(item,filters,statusRegistry,runtimeFieldFilters,parentsByChild){return!(!matchesListIdentityFilters(item,filters,statusRegistry)||!matchesListDateFilters(item,filters)||!matchesListAssigneeFilterSet(item,filters)||!matchesListScopeFilters(item,filters,parentsByChild)||filters.missingMetadataActive&&!itemMatchesMissingMetadata(item,filters.missingMetadataFilters,filters.lifecycleClassifier)||filters.contentFiltersActive&&!itemMatchesContentFilters(item,filters.contentFieldFilters)||!matchesRuntimeFilters(item,runtimeFieldFilters))}function applyFilters(items,status,options,typeRegistry,statusRegistry,runtimeFieldFilters,parentsByChild){const filters=resolveListFilterSet(status,options,typeRegistry,statusRegistry);return items.filter(item=>matchesListFilterSet(item,filters,statusRegistry,runtimeFieldFilters,parentsByChild))}function trimNonEmpty(value){if(typeof value!="string")return;const trimmed=value.trim();return trimmed.length>0?trimmed:void 0}function withTreeMetadata(item,depth,childCount,parentId){const itemRecord=toItemRecord(item),title=typeof itemRecord.title=="string"?itemRecord.title:"",parent=parentId??trimNonEmpty(typeof itemRecord.parent=="string"?itemRecord.parent:void 0)??null;return{...item,tree_depth:depth,tree_parent:parent,tree_children:childCount,tree_title:`${"  ".repeat(depth)}${title}`}}function buildListTreeIndexes(sortedItems,hierarchyIndexes){const byId=new Map,childrenByParent=new Map;for(const item of sortedItems){const itemId=item.id.trim().toLowerCase();byId.set(itemId,item);const parentIds=hierarchyIndexes?hierarchyIndexes.parents_by_child.get(itemId)??[]:[trimNonEmpty(item.parent)?.toLowerCase()].filter(value=>value!==void 0);for(const parentId of parentIds){const children=childrenByParent.get(parentId)??[];children.push(item),childrenByParent.set(parentId,children)}}return{byId,childrenByParent}}function resolveListTreeRoots(sortedItems,parentRoot,byId,childrenByParent,hierarchyIndexes){return parentRoot?[...childrenByParent.get(parentRoot.toLowerCase())??[]]:sortedItems.filter(item=>(hierarchyIndexes?hierarchyIndexes.parents_by_child.get(item.id.trim().toLowerCase())??[]:[trimNonEmpty(item.parent)?.toLowerCase()].filter(value=>value!==void 0)).every(parentId=>!byId.has(parentId)))}function orderItemsAsTree(sortedItems,parentRoot,maxDepth,hierarchyIndexes,completeItems=sortedItems){const{byId,childrenByParent}=buildListTreeIndexes(sortedItems,hierarchyIndexes),roots=resolveListTreeRoots(sortedItems,parentRoot,byId,childrenByParent,hierarchyIndexes),ordered=[],visited=new Set,canonicalIdByLowercase=new Map(completeItems.map(item=>[item.id.trim().toLowerCase(),item.id.trim()])),pending=[...roots].reverse().map(node=>({node,depth:0,parentId:parentRoot===void 0?void 0:canonicalIdByLowercase.get(parentRoot.trim().toLowerCase())??parentRoot.trim()}));for(;pending.length>0;){const{node,depth,parentId}=pending.pop(),nodeId=node.id.trim().toLowerCase();if(visited.has(nodeId))continue;visited.add(nodeId);const children=childrenByParent.get(nodeId)??[];if(ordered.push(withTreeMetadata(node,depth,children.length,parentId)),!(maxDepth!==void 0&&depth>=maxDepth))for(const child of[...children].reverse())pending.push({node:child,depth:depth+1,parentId:canonicalIdByLowercase.get(nodeId)})}if(parentRoot===void 0&&maxDepth===void 0)for(const item of sortedItems){const itemId=item.id.trim().toLowerCase();visited.has(itemId)||(visited.add(itemId),ordered.push(withTreeMetadata(item,0,childrenByParent.get(itemId)?.length??0)))}return ordered}function compareNullableString(left,right){return left===right?0:left===null?1:right===null?-1:left.localeCompare(right)}function compareNullableTimestamp(left,right){return left===right?0:left===null?1:right===null?-1:compareTimestampStrings(left,right)}function compareBySortField(left,right,field){switch(field){case"priority":return left.priority-right.priority;case"deadline":return compareNullableTimestamp(left.deadline??null,right.deadline??null);case"updated_at":return compareTimestampStrings(left.updated_at,right.updated_at);case"created_at":return compareTimestampStrings(left.created_at,right.created_at);case"title":return(left.title??"").localeCompare(right.title??"");case"parent":return compareNullableString(left.parent??null,right.parent??null);default:return 0}}function sortItems(items,sortField,sortOrder,statusRegistry){return sortField?[...items].sort((left,right)=>{const byField=compareBySortField(left,right,sortField);if(byField!==0)return sortOrder==="desc"?-byField:byField;const fallback=compareDefaultSort(left,right,statusRegistry);return sortOrder==="desc"?-fallback:fallback}):sortItemsDefault(items,statusRegistry)}function readListFieldValue(item,field,treeMode=!1){const normalized=normalizeProjectionField(field.trim());if(normalized.length===0)return null;const itemRecord=toItemRecord(item);return treeMode&&normalized==="title"&&typeof itemRecord.tree_title=="string"?itemRecord.tree_title:Object.prototype.hasOwnProperty.call(itemRecord,normalized)?itemRecord[normalized]??null:null}function projectListItems(items,projection,treeMode=!1){return projection.mode==="full"?items:items.map(item=>{const projected={};for(const field of projection.fields)projected[field]=readListFieldValue(item,field,treeMode);return projected})}function runtimeMetadataKeysForProjection(definitions){const keys=[];for(const field of definitions)keys.push(field.metadata_key);return keys}function resolveListPageLimit(options,totalRows){const explicitLimit=parseIntegerLimit(options.limit);if(explicitLimit!==void 0)return explicitLimit;if(options.noTruncate!==!0)return totalRows>=1e4?20:void 0}function resolveListPageStart(ordered,options,cursorFingerprint){return options.after===void 0?parseOffset(options.offset)??0:resolveQueryCursorStart(ordered,options.after,cursorFingerprint,item=>item.id)}function buildListPageExtras(limit,hasMore,nextCursor){return{...limit!==void 0?{applied_limit:limit}:{},has_more:hasMore,truncated:hasMore,next_cursor:nextCursor??null}}async function resolveListRuntimeContext(options,global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),statusRegistry=resolveRuntimeStatusRegistry(settings.schema),runtimeFieldRegistry=resolveRuntimeFieldRegistry(settings.schema),invokedCommand=options.projectionCommand??"list",projection=parseProjectionConfig(options,invokedCommand);return validateListProjectionFields(projection,runtimeMetadataKeysForProjection(runtimeFieldRegistry.definitions),invokedCommand),{pmRoot,settings,statusRegistry,runtimeFieldFilters:collectRuntimeFilterValues(options,runtimeFieldRegistry,"list"),typeRegistry:resolveItemTypeRegistry(settings,getActiveExtensionRegistrations()),projection}}async function loadListItems(options,runtime,listWarnings){const projectionNeedsBody=runtime.projection.fields.some(field=>normalizeProjectionField(field)==="body"),projectionNeedsCollections=runtime.projection.mode==="full"||runtime.projection.fields.some(field=>HEAVY_PROJECTION_FIELDS.has(normalizeProjectionField(field))),contentFieldFilters=resolveContentFieldFilters(options),contentNeedsCollections=contentFiltersNeedCollections(contentFieldFilters),contentNeedsBody=contentFiltersNeedBody(contentFieldFilters);return options.includeBody||projectionNeedsBody||contentNeedsBody?await listAllItemMetadataWithBody(runtime.pmRoot,runtime.settings.item_format,runtime.typeRegistry.type_to_folder,listWarnings,runtime.settings.schema):projectionNeedsCollections||contentNeedsCollections?await listAllItemMetadata(runtime.pmRoot,runtime.settings.item_format,runtime.typeRegistry.type_to_folder,listWarnings,runtime.settings.schema):await listAllItemMetadataLight(runtime.pmRoot,runtime.settings.item_format,runtime.typeRegistry.type_to_folder,listWarnings,runtime.settings.schema)}function resolveListOrderingOptions(options){const sortField=parseSortField(options.sort),sortOrder=parseSortOrder(options.order)??"asc",treeEnabled=options.tree===!0;if(!treeEnabled&&options.treeDepth!==void 0)throw new PmCliError("List --tree-depth requires --tree",EXIT_CODE.USAGE);if(!sortField&&options.order!==void 0)throw new PmCliError("List --order requires --sort",EXIT_CODE.USAGE);return{sortField,sortOrder,treeEnabled,treeDepth:treeEnabled?parseTreeDepth(options.treeDepth):void 0,parentRoot:treeEnabled?trimNonEmpty(options.parent):void 0}}function resolveListStatusSelection(status,options,statusRegistry){const explicitStatus=resolveStatusFilter(options.status,statusRegistry);let lifecycleStatus;options.lifecycleBucket==="in_progress"?lifecycleStatus=[statusRegistry.in_progress_status]:options.lifecycleBucket==="open"&&(lifecycleStatus=[...statusRegistry.active_statuses].filter(entry=>entry!==statusRegistry.in_progress_status).sort((left,right)=>left.localeCompare(right)));const resolvedStatus=explicitStatus??lifecycleStatus??resolveStatusFilter(status,statusRegistry),explicitAllStatuses=isStatusAllFilterInput(options.status),effectiveOptions=explicitStatus||explicitAllStatuses?{...options,excludeTerminal:!1}:options;let filtersStatus="all";return explicitAllStatuses?filtersStatus="all":explicitStatus!==void 0?filtersStatus=explicitStatus.length===1?explicitStatus[0]:explicitStatus:options.lifecycleBucket!==void 0?filtersStatus=options.lifecycleBucket:resolvedStatus!==void 0?filtersStatus=resolvedStatus.length===1?resolvedStatus[0]:resolvedStatus:effectiveOptions.excludeTerminal===!0&&(filtersStatus=null),{resolvedStatus,explicitAllStatuses,effectiveOptions,filtersStatus}}function pageAndProjectListItems(ordered,options,projection,treeEnabled,cursorFingerprint){if(options.after!==void 0&&options.offset!==void 0)throw new PmCliError("List --after cannot be combined with --offset.",EXIT_CODE.USAGE);const limit=resolveListPageLimit(options,ordered.length),offset=resolveListPageStart(ordered,options,cursorFingerprint),limited=limit===void 0?ordered.slice(offset):ordered.slice(offset,offset+limit),projected=projectListItems(limited,projection,treeEnabled),totalMatched=ordered.length,hasMore=limited.length>0&&offset+limited.length<totalMatched,nextCursor=hasMore&&limited.length>0?encodeQueryCursor(cursorFingerprint,limited[limited.length-1].id,offset+limited.length-1):void 0;return{projected,totalMatched,pageExtras:buildListPageExtras(limit,hasMore,nextCursor)}}function buildListCursorFingerprint(status,options,ordering,pmRoot){return createQueryFingerprint("list",{pmRoot,status,options:selectCursorSemanticOptions(options,LIST_FILTER_FLAG_CONTRACTS),sort:ordering.sortField??"default",order:ordering.sortOrder,tree:ordering.treeEnabled,tree_depth:ordering.treeDepth??null})}async function tryLoadIndexedListPage(params){const{options,runtime,statusSelection,ordering}=params,supportedOptionKeys=new Set(["status","limit","offset","compact","brief","full","fields","format","stream","includeBody","excludeTerminal","dependencyBlocked","lifecycleBucket","noTruncate","projectionCommand","truncate","notes","learnings","files","docs","tests","comments","deps","linkedCommand"]),projectionNeedsHeavyData=[runtime.projection.mode==="full",runtime.projection.fields.some(field=>{const normalized=normalizeProjectionField(field);return normalized==="body"||HEAVY_PROJECTION_FIELDS.has(normalized)})].includes(!0);if([options.limit===void 0,options.after!==void 0,options.noTruncate===!0,options.includeBody===!0,options.dependencyBlocked===!0,options.strictRead===!0,ordering.treeEnabled,ordering.sortField!==void 0,projectionNeedsHeavyData,hasActiveOnReadHooks(),Object.keys(runtime.runtimeFieldFilters).length>0,Object.entries(options).some(([key,value])=>value!==void 0&&!supportedOptionKeys.has(key))].includes(!0))return null;const indexState=await readItemMetadataDerivedIndexState(runtime.pmRoot,[...new Set(Object.values(runtime.typeRegistry.type_to_folder))]);if(!indexState)return null;const limit=parseIntegerLimit(options.limit),offset=parseOffset(options.offset)??0,indexed=await queryItemMetadataIndex({pmRoot:runtime.pmRoot,expectedSourceCursor:indexState.source_cursor,query:{statuses:statusSelection.resolvedStatus,excludeStatuses:statusSelection.resolvedStatus===void 0&&statusSelection.effectiveOptions.excludeTerminal===!0?[...runtime.statusRegistry.terminal_statuses]:void 0,terminalStatuses:[...runtime.statusRegistry.terminal_statuses],limit,offset}});if(!indexed)return null;const hasMore=indexed.items.length>0&&offset+indexed.items.length<indexed.total,nextCursor=hasMore?encodeQueryCursor(buildListCursorFingerprint(statusSelection.filtersStatus,options,ordering,runtime.pmRoot),indexed.items.at(-1).id,offset+indexed.items.length-1):void 0;return{projected:projectListItems(indexed.items,runtime.projection,!1),totalMatched:indexed.total,pageExtras:buildListPageExtras(limit,hasMore,nextCursor)}}function buildVerboseListFilters(params){const{filtersStatus,options,noTruncate,treeEnabled,treeDepth,sortField,sortOrder,runtimeFieldFilters}=params,filters={};filtersStatus!==null&&(filters.status=filtersStatus),options.dependencyBlocked===!0&&(filters.blocked_semantics="status_or_dependency");const optionRecord=options;for(const entry of VERBOSE_LIST_VALUE_FILTER_ECHO_ENTRIES){const value=optionRecord[entry.optionKey];value!=null&&(filters[entry.summaryKey]=value)}for(const entry of VERBOSE_LIST_BOOLEAN_FILTER_ECHO_ENTRIES)optionRecord[entry.key]===!0&&(filters[entry.summaryKey]=!0);return Object.assign(filters,buildGovernanceMissingFilterEcho(options),buildContentFilterEcho(options)),applyListWindowFilterEcho(filters,options),noTruncate&&(filters.no_truncate=!0),options.strictRead===!0&&(filters.strict_read=!0),treeEnabled&&(filters.tree=!0,treeDepth!==void 0&&(filters.tree_depth=treeDepth)),sortField!==void 0&&(filters.sort=sortField,filters.order=sortOrder),filters.runtime_filters=runtimeFieldFilters,filters}async function runList(status,options,global2){const runtime=await resolveListRuntimeContext(options,global2),listWarnings=[],ordering=resolveListOrderingOptions(options),statusSelection=resolveListStatusSelection(status,options,runtime.statusRegistry),noTruncate=options.noTruncate===!0,indexedPage=await tryLoadIndexedListPage({options,runtime,statusSelection,ordering});let page=indexedPage;if(!page){const items=await loadListItems(options,runtime,listWarnings),hierarchyIndexes=ordering.treeEnabled||trimNonEmpty(options.parent)!==void 0?indexHierarchyRelations(collectHierarchyRelations(items,resolveWorkspaceRelationshipKindRegistry())):void 0;appendUnknownTagWarning(items,options.tag,listWarnings);const filtered=applyFilters(items,statusSelection.resolvedStatus,statusSelection.effectiveOptions,runtime.typeRegistry,runtime.statusRegistry,runtime.runtimeFieldFilters,hierarchyIndexes?.parents_by_child),scoped=options.dependencyBlocked===!0?(()=>{const blockedIds=collectDependencyBlockedIds(items,runtime.statusRegistry);return filtered.filter(item=>blockedIds.has(item.id.trim().toLowerCase()))})():filtered,sorted=sortItems(scoped,ordering.sortField,ordering.sortOrder,runtime.statusRegistry),ordered=ordering.treeEnabled?orderItemsAsTree(sorted,ordering.parentRoot,ordering.treeDepth,hierarchyIndexes,items):sorted;page=pageAndProjectListItems(ordered,options,runtime.projection,ordering.treeEnabled,buildListCursorFingerprint(statusSelection.filtersStatus,options,ordering,runtime.pmRoot))}const now=nowIso(),warnings=[...new Set(listWarnings)].sort((left,right)=>left.localeCompare(right)),completeness=resolveListCompleteness(warnings,indexedPage!==null,options.strictRead===!0),projectionFields=runtime.projection.mode==="full"?null:[...runtime.projection.fields];if(runtime.projection.mode==="compact"&&options.compact===!0){const compactFilters=buildCompactListFilterSummary({filtersStatus:statusSelection.filtersStatus,options,treeEnabled:ordering.treeEnabled,treeDepth:ordering.treeDepth,sortField:ordering.sortField,sortOrder:ordering.sortOrder,runtimeFieldFilters:runtime.runtimeFieldFilters});return{items:page.projected,count:page.projected.length,total:page.totalMatched,...page.pageExtras,completeness,filters:compactFilters,projection:{mode:"compact",fields:projectionFields},...warnings.length>0?{warnings}:{}}}return{items:page.projected,count:page.projected.length,total:page.totalMatched,...page.pageExtras,completeness,filters:buildVerboseListFilters({filtersStatus:statusSelection.filtersStatus,options,noTruncate,treeEnabled:ordering.treeEnabled,treeDepth:ordering.treeDepth,sortField:ordering.sortField,sortOrder:ordering.sortOrder,runtimeFieldFilters:runtime.runtimeFieldFilters}),projection:{mode:runtime.projection.mode,fields:projectionFields},sorting:{sort:ordering.sortField??"default",order:ordering.sortField?ordering.sortOrder:"asc"},now,...warnings.length>0?{warnings}:{}}}const _testOnly={applyFilters,buildCompactListFilterSummary,buildContentFilterEcho,buildGovernanceMissingFilterEcho,resolveContentFieldFilters,resolveMissingMetadataFilters,compareBySortField,compareDefaultSort,compareNullableString,compareNullableTimestamp,normalizeProjectionField,parseAssigneeFilter,parseFieldSelectors,parseIdsFilter,parseOffset,parseProjectionConfig,resolveListUpdatedAfter,resolveListPageLimit,parseSortField,parseSortOrder,orderItemsAsTree,projectListItems,readListFieldValue,runtimeMetadataKeysForProjection,sortItems,trimNonEmpty,withTreeMetadata};export{BRIEF_LIST_FIELDS2 as BRIEF_LIST_FIELDS,DEFAULT_COMPACT_LIST_FIELDS2 as DEFAULT_COMPACT_LIST_FIELDS,LIST_COMMAND_DEFAULT_PROJECTIONS,LIST_SORT_FIELDS,LIST_SORT_ORDER_VALUES,_testOnly,applyFilterValueEcho,buildContentFilterEcho,buildGovernanceMissingFilterEcho,listListProjectionFields2 as listListProjectionFields,resolveContentFieldFilters,resolveMissingMetadataFilters,runList};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8c315632-500b-53c4-a8ed-99865c8c0246")}catch{}})();import{renderPmCommand}from"../command-line.js";import{assertInitializedTracker}from"../environment/tracker-preflight.js";import{getActiveExtensionRegistrations,hasActiveOnReadHooks}from"../../core/extensions/index.js";import{toItemRecord}from"../../core/item/item-record.js";import{isTerminalStatus}from"../../core/item/status.js";import{collectDependencyBlockedIds}from"../actionability.js";import{isStatusAllFilterInput,parseStatusFilterCsv}from"../../core/item/status-filter.js";import{resolveItemTypeRegistry}from"../../core/item/type-registry.js";import{parseIntegerLimit}from"./parsers.js";import{parsePriorityFilterSet,parseStringFilterSet,parseTypeFilterSet}from"./multi-value-filters.js";import{collectRuntimeFilterValues,matchesRuntimeFilters}from"../../core/schema/runtime-field-filters.js";import{hasMissingMetadataFilter,itemMatchesMissingMetadata,lifecycleClassifierFromStatusRegistry}from"../../core/governance/metadata-coverage.js";import{contentFiltersNeedBody,contentFiltersNeedCollections,hasContentFieldFilter,itemMatchesContentFilters}from"../../core/governance/content-fields.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{compareTimestampStrings,matchesTimestampFilters,nowIso,resolveIsoOrRelative}from"../../core/shared/time.js";import{listAllItemMetadata,listAllItemMetadataLight,listAllItemMetadataWithBody}from"../../core/store/item-store.js";import{HEAVY_METADATA_KEYS,readItemMetadataDerivedIndexState}from"../../core/store/item-metadata-cache.js";import{queryItemMetadataIndex}from"../../core/store/item-metadata-query-index.js";import{resolvePmRoot}from"../../core/store/paths.js";import{readSettings}from"../../core/store/settings.js";import{LIST_FILTER_FLAG_CONTRACTS}from"../cli-contracts/flag-contracts.js";import{resolveWorkspaceRelationshipKindRegistry}from"../graph/assembly.js";import{collectHierarchyRelations,indexHierarchyRelations}from"../graph/hierarchy-integrity.js";import{createQueryFingerprint,encodeQueryCursor,resolveQueryCursorStart,selectCursorSemanticOptions}from"../pagination.js";import{BRIEF_LIST_FIELDS,DEFAULT_COMPACT_LIST_FIELDS,listListProjectionFields}from"./projection-contracts.js";import{BRIEF_LIST_FIELDS as BRIEF_LIST_FIELDS2,DEFAULT_COMPACT_LIST_FIELDS as DEFAULT_COMPACT_LIST_FIELDS2,LIST_COMMAND_DEFAULT_PROJECTIONS,listListProjectionFields as listListProjectionFields2}from"./projection-contracts.js";const resolveMissingMetadataFilters=options=>({acMissing:options.filterAcMissing===!0,estimatesMissing:options.filterEstimatesMissing===!0,resolutionMissing:options.filterResolutionMissing===!0,metadataMissing:options.filterMetadataMissing===!0,reviewerMissing:options.filterReviewerMissing===!0,riskMissing:options.filterRiskMissing===!0,confidenceMissing:options.filterConfidenceMissing===!0,sprintMissing:options.filterSprintMissing===!0,releaseMissing:options.filterReleaseMissing===!0}),CONTENT_FIELD_FLAG_MAPPINGS=[{field:"notes",presentKey:"hasNotes",absentKey:"noNotes",presentFlag:"--has-notes",absentFlag:"--no-notes"},{field:"learnings",presentKey:"hasLearnings",absentKey:"noLearnings",presentFlag:"--has-learnings",absentFlag:"--no-learnings"},{field:"files",presentKey:"hasFiles",absentKey:"noFiles",presentFlag:"--has-files",absentFlag:"--no-files"},{field:"docs",presentKey:"hasDocs",absentKey:"noDocs",presentFlag:"--has-docs",absentFlag:"--no-docs"},{field:"tests",presentKey:"hasTests",absentKey:"noTests",presentFlag:"--has-tests",absentFlag:"--no-tests"},{field:"comments",presentKey:"hasComments",absentKey:"noComments",presentFlag:"--has-comments",absentFlag:"--no-comments"},{field:"deps",presentKey:"hasDeps",absentKey:"noDeps",presentFlag:"--has-deps",absentFlag:"--no-deps"},{field:"body",presentKey:"hasBody",absentKey:"emptyBody",presentFlag:"--has-body",absentFlag:"--empty-body"},{field:"linked_command",presentKey:"hasLinkedCommand",absentKey:"noLinkedCommand",presentFlag:"--has-linked-command",absentFlag:"--no-linked-command"}],resolveContentFieldFilters=options=>{const conflict=CONTENT_FIELD_FLAG_MAPPINGS.find(mapping=>options[mapping.presentKey]===!0&&options[mapping.absentKey]===!0);if(conflict)throw new PmCliError(`Cannot combine ${conflict.presentFlag} with ${conflict.absentFlag} for the same field.`,EXIT_CODE.USAGE);return Object.fromEntries(CONTENT_FIELD_FLAG_MAPPINGS.flatMap(mapping=>options[mapping.presentKey]===!0?[[mapping.field,"present"]]:options[mapping.absentKey]===!0?[[mapping.field,"absent"]]:[]))},LIST_SORT_FIELDS=["priority","deadline","updated_at","created_at","title","parent"],LIST_SORT_ORDER_VALUES=["asc","desc"],HEAVY_PROJECTION_FIELDS=new Set(HEAVY_METADATA_KEYS);function resolveListCompleteness(warnings,indexed,strict){const unreadableItemCount=warnings.filter(warning=>warning.startsWith("item_list_item_read_failed:")).length,unreadableDirectoryCount=warnings.filter(warning=>warning.startsWith("item_list_directory_read_failed:")).length,completeness={status:indexed?"unchecked":unreadableItemCount+unreadableDirectoryCount>0?"partial":"complete",unreadable_item_count:unreadableItemCount,unreadable_directory_count:unreadableDirectoryCount};if(strict&&completeness.status==="partial")throw new PmCliError(`List source is incomplete: ${unreadableItemCount} item document(s) and ${unreadableDirectoryCount} item directory/directories could not be read.`,EXIT_CODE.GENERIC_FAILURE,{code:"list_source_incomplete",why:"Strict list reads fail closed so agents and SDK consumers never treat an omitted item as a complete workspace.",nextSteps:["Run pm validate --check-storage-integrity to locate unreadable tracker artifacts.","Repair the reported files or align the installed decoder version, then retry."]});return completeness}function isNonEmptyRecord(value){return typeof value=="object"&&value!==null&&!Array.isArray(value)&&Object.keys(value).length>0}const CONTENT_FILTER_ECHO_ENTRIES=[{key:"hasNotes",summaryKey:"has_notes"},{key:"hasLearnings",summaryKey:"has_learnings"},{key:"hasFiles",summaryKey:"has_files"},{key:"hasDocs",summaryKey:"has_docs"},{key:"hasTests",summaryKey:"has_tests"},{key:"hasComments",summaryKey:"has_comments"},{key:"hasDeps",summaryKey:"has_deps"},{key:"hasBody",summaryKey:"has_body"},{key:"hasLinkedCommand",summaryKey:"has_linked_command"},{key:"noNotes",summaryKey:"no_notes"},{key:"noLearnings",summaryKey:"no_learnings"},{key:"noFiles",summaryKey:"no_files"},{key:"noDocs",summaryKey:"no_docs"},{key:"noTests",summaryKey:"no_tests"},{key:"noComments",summaryKey:"no_comments"},{key:"noDeps",summaryKey:"no_deps"},{key:"emptyBody",summaryKey:"empty_body"},{key:"noLinkedCommand",summaryKey:"no_linked_command"}],GOVERNANCE_MISSING_ECHO_ENTRIES=[{key:"filterReviewerMissing",summaryKey:"filter_reviewer_missing"},{key:"filterRiskMissing",summaryKey:"filter_risk_missing"},{key:"filterConfidenceMissing",summaryKey:"filter_confidence_missing"},{key:"filterSprintMissing",summaryKey:"filter_sprint_missing"},{key:"filterReleaseMissing",summaryKey:"filter_release_missing"}];function applyContentFilterEcho(filters,options){for(const entry of CONTENT_FILTER_ECHO_ENTRIES)options[entry.key]===!0&&(filters[entry.summaryKey]=!0)}function applyGovernanceMissingFilterEcho(filters,options){for(const entry of GOVERNANCE_MISSING_ECHO_ENTRIES)options[entry.key]===!0&&(filters[entry.summaryKey]=!0)}function applyFilterValueEcho(filters,options,entries){for(const entry of entries){const value=options[entry.optionKey];value!==void 0&&(filters[entry.summaryKey]=entry.normalize?entry.normalize(value):value)}}function buildContentFilterEcho(options){const echo={};return applyContentFilterEcho(echo,options),echo}function buildGovernanceMissingFilterEcho(options){const echo={};return applyGovernanceMissingFilterEcho(echo,options),echo}const COMPACT_LIST_VALUE_FILTER_ECHO_ENTRIES=[{optionKey:"type",summaryKey:"type"},{optionKey:"tag",summaryKey:"tag"},{optionKey:"priority",summaryKey:"priority"},{optionKey:"deadlineBefore",summaryKey:"deadline_before"},{optionKey:"deadlineAfter",summaryKey:"deadline_after"},{optionKey:"updatedAfter",summaryKey:"updated_after"},{optionKey:"updatedBefore",summaryKey:"updated_before"},{optionKey:"createdAfter",summaryKey:"created_after"},{optionKey:"createdBefore",summaryKey:"created_before"},{optionKey:"ids",summaryKey:"ids"},{optionKey:"assignee",summaryKey:"assignee"},{optionKey:"assigneeFilter",summaryKey:"assignee_filter"},{optionKey:"parent",summaryKey:"parent"},{optionKey:"sprint",summaryKey:"sprint"},{optionKey:"release",summaryKey:"release"}],VERBOSE_LIST_VALUE_FILTER_ECHO_ENTRIES=[{optionKey:"type",summaryKey:"type"},{optionKey:"tag",summaryKey:"tag"},{optionKey:"priority",summaryKey:"priority"},{optionKey:"deadlineBefore",summaryKey:"deadline_before"},{optionKey:"deadlineAfter",summaryKey:"deadline_after"},{optionKey:"updatedAfter",summaryKey:"updated_after"},{optionKey:"updatedBefore",summaryKey:"updated_before"},{optionKey:"createdAfter",summaryKey:"created_after"},{optionKey:"createdBefore",summaryKey:"created_before"},{optionKey:"ids",summaryKey:"ids"},{optionKey:"assignee",summaryKey:"assignee"},{optionKey:"assigneeFilter",summaryKey:"assignee_filter"},{optionKey:"parent",summaryKey:"parent"},{optionKey:"sprint",summaryKey:"sprint"},{optionKey:"release",summaryKey:"release"},{optionKey:"limit",summaryKey:"limit"},{optionKey:"offset",summaryKey:"offset"},{optionKey:"includeBody",summaryKey:"include_body"},{optionKey:"compact",summaryKey:"compact"},{optionKey:"fields",summaryKey:"fields"}],VERBOSE_LIST_BOOLEAN_FILTER_ECHO_ENTRIES=[{key:"filterAcMissing",summaryKey:"filter_ac_missing"},{key:"filterEstimatesMissing",summaryKey:"filter_estimates_missing"},{key:"filterResolutionMissing",summaryKey:"filter_resolution_missing"},{key:"filterMetadataMissing",summaryKey:"filter_metadata_missing"}],LIST_RECENT_WINDOW="-7d";function buildCompactListFilterSummary(params){const{filtersStatus,options,treeEnabled,treeDepth,sortField,sortOrder,runtimeFieldFilters}=params,filters={};return filtersStatus!==null&&(filters.status=filtersStatus),options.dependencyBlocked===!0&&(filters.blocked_semantics="status_or_dependency"),applyFilterValueEcho(filters,options,COMPACT_LIST_VALUE_FILTER_ECHO_ENTRIES),applyListWindowFilterEcho(filters,options),options.filterAcMissing===!0&&(filters.filter_ac_missing=!0),options.filterEstimatesMissing===!0&&(filters.filter_estimates_missing=!0),options.filterResolutionMissing===!0&&(filters.filter_resolution_missing=!0),options.filterMetadataMissing===!0&&(filters.filter_metadata_missing=!0),applyGovernanceMissingFilterEcho(filters,options),applyContentFilterEcho(filters,options),options.limit!==void 0&&(filters.limit=options.limit),options.offset!==void 0&&(filters.offset=options.offset),options.includeBody===!0&&(filters.include_body=!0),options.fields!==void 0&&(filters.fields=options.fields),treeEnabled&&(filters.tree=!0,treeDepth!==void 0&&(filters.tree_depth=treeDepth)),sortField!==void 0&&(filters.sort=sortField,filters.order=sortOrder),isNonEmptyRecord(runtimeFieldFilters)&&(filters.runtime_filters=runtimeFieldFilters),filters}function compareDefaultSort(left,right,statusRegistry){const leftTerminal=isTerminalStatus(left.status,statusRegistry),rightTerminal=isTerminalStatus(right.status,statusRegistry);if(leftTerminal!==rightTerminal)return leftTerminal?1:-1;const byPriority=left.priority-right.priority;if(byPriority!==0)return byPriority;const byUpdated=compareTimestampStrings(right.updated_at,left.updated_at);return byUpdated!==0?byUpdated:(left.id??"").localeCompare(right.id??"")}function sortItemsDefault(items,statusRegistry){return[...items].sort((left,right)=>compareDefaultSort(left,right,statusRegistry))}function parseDeadline(raw,fieldLabel){if(raw!==void 0)return resolveIsoOrRelative(raw,new Date,fieldLabel)}function parseTimestampWindow(raw,fieldLabel){if(raw==null)return;const value=String(raw).trim();if(value.length!==0)return resolveIsoOrRelative(value,new Date,fieldLabel)}function resolveListUpdatedAfter(options){const hasUpdatedAfter=options.updatedAfter!=null&&String(options.updatedAfter).trim().length>0;if([options.today===!0,options.recent===!0,hasUpdatedAfter].filter(selected=>selected).length>1)throw new PmCliError("Choose only one updated_at window: --today, --recent, or --updated-after.",EXIT_CODE.USAGE);if(options.today===!0){const today=new Date;return today.setHours(0,0,0,0),today.toISOString()}return options.recent===!0?parseTimestampWindow(LIST_RECENT_WINDOW,"recent"):parseTimestampWindow(options.updatedAfter,"updated-after")}function applyListWindowFilterEcho(filters,options){options.today===!0&&(filters.today=!0),options.recent===!0&&(filters.recent=!0)}function parseIdsFilter(raw){if(raw==null)return;const value=String(raw).trim();if(value.length===0)throw new PmCliError("--ids requires at least one non-empty item ID",EXIT_CODE.USAGE);const ids=value.split(",").map(entry=>entry.trim()).filter(entry=>entry.length>0);if(ids.length===0)throw new PmCliError("--ids requires at least one non-empty item ID",EXIT_CODE.USAGE);return new Set(ids)}function parseOffset(raw){if(raw===void 0)return;const normalized=String(raw).trim(),parsed=normalized.length===0?Number.NaN:Number(normalized);if(!Number.isInteger(parsed)||parsed<0)throw new PmCliError("Offset filter must be a non-negative integer",EXIT_CODE.USAGE);return parsed}function parseFieldSelectors(raw){if(raw===void 0)return;const selectors=raw.split(",").map(entry=>entry.trim()).filter(entry=>entry.length>0);if(selectors.length===0)throw new PmCliError("List --fields requires a comma-separated list of field names",EXIT_CODE.USAGE);return[...new Set(selectors)]}function parseProjectionConfig(options,invokedCommand=options.projectionCommand??"list"){const compactRequested=options.compact===!0,briefRequested=options.brief===!0,fullRequested=options.full===!0,fieldSelectors=parseFieldSelectors(options.fields);if(Number(compactRequested)+Number(briefRequested)+Number(fullRequested)+ +(fieldSelectors!==void 0)>1)throw new PmCliError("List projection options are mutually exclusive. Use one of --compact, --brief, --full, or --fields.",EXIT_CODE.USAGE,{code:"projection_options_mutually_exclusive",recovery:{suggested_retry:`pm ${invokedCommand} --brief`,suggested_retry_args:[invokedCommand,"--brief"]}});if(fullRequested)return{mode:"full",fields:[]};if(briefRequested){const sortField=parseSortField(options.sort);return{mode:"brief",fields:[...new Set([...BRIEF_LIST_FIELDS,...sortField?[sortField]:[]])]}}return compactRequested?{mode:"compact",fields:[...DEFAULT_COMPACT_LIST_FIELDS]}:fieldSelectors?{mode:"fields",fields:[...new Set(fieldSelectors.map(field=>normalizeProjectionField(field)))]}:{mode:"full",fields:[]}}function normalizeProjectionField(field){return field.startsWith("item.")?field.slice(5):field}function validateListProjectionFields(projection,runtimeMetadataKeys,invokedCommand){if(projection.mode!=="fields")return;const allowedValues=listListProjectionFields(runtimeMetadataKeys),allowed=new Set(allowedValues.map(field=>normalizeProjectionField(field))),unknown=projection.fields.filter(field=>!allowed.has(normalizeProjectionField(field)));if(unknown.length>0){const suggestedRetryArguments=[invokedCommand,"--fields",projection.fields.filter(field=>!unknown.includes(field)).join(",")||"id,title,status"];throw new PmCliError(`Unknown list --fields value(s): ${unknown.join(", ")}`,EXIT_CODE.USAGE,{code:"unknown_field_projection",examples:["pm list --status open --fields id,title,status","pm list --fields id,title,parent,priority --limit 10","pm list --all --fields id,title,body --limit 5"],recovery:{allowed_values:allowedValues,suggested_retry:renderPmCommand(suggestedRetryArguments),suggested_retry_args:suggestedRetryArguments}})}}const LIST_SORT_FIELD_ALIASES=new Map([["updated","updated_at"],["update","updated_at"],["modified","updated_at"],["created","created_at"],["create","created_at"]]);function parseSortField(raw){if(raw===void 0)return;const normalized=raw.trim().toLowerCase(),aliased=LIST_SORT_FIELD_ALIASES.get(normalized);if(aliased)return aliased;if(!LIST_SORT_FIELDS.includes(normalized))throw new PmCliError(`Sort field must be one of ${LIST_SORT_FIELDS.join("|")} (aliases: updated->updated_at, created->created_at)`,EXIT_CODE.USAGE);return normalized}function parseSortOrder(raw){if(raw===void 0)return;const normalized=raw.trim().toLowerCase();if(!LIST_SORT_ORDER_VALUES.includes(normalized))throw new PmCliError(`Sort order must be one of ${LIST_SORT_ORDER_VALUES.join("|")}`,EXIT_CODE.USAGE);return normalized}function parseTreeDepth(raw){return parseIntegerLimit(raw,"--tree-depth")}function parseAssigneeFilter(raw){if(raw===void 0)return;const normalized=raw.trim().toLowerCase();if(!normalized)throw new PmCliError("Assignee filter must be one of assigned|unassigned",EXIT_CODE.USAGE);if(normalized!=="assigned"&&normalized!=="unassigned")throw new PmCliError(`Invalid assignee filter "${raw}". Allowed: assigned|unassigned`,EXIT_CODE.USAGE);return normalized}function resolveStatusFilter(status,statusRegistry){return parseStatusFilterCsv(status,statusRegistry,{strict:!0})}function parseListTagFilters(raw){return parseStringFilterSet(raw,{label:"--tag",normalize:tag=>tag.toLowerCase()})}function appendUnknownTagWarning(items,rawTags,warnings){const requestedTags=parseListTagFilters(rawTags);if(requestedTags===void 0)return;const knownTags=new Set(items.flatMap(item=>item.tags.map(tag=>tag.trim().toLowerCase()))),unknownTags=[...requestedTags].filter(tag=>!knownTags.has(tag));unknownTags.length>0&&warnings.push(`unknown_tags:${unknownTags.join(",")}`)}function assertListAssigneeFilters(assigneeFilter,assigneeModeFilter){if(assigneeFilter&&[...assigneeFilter].some(value=>value.toLowerCase()==="none"||value.toLowerCase()==="null"))throw new PmCliError('--assignee no longer accepts "none" or "null". Use --assignee-filter unassigned.',EXIT_CODE.USAGE);if(assigneeFilter!==void 0&&assigneeModeFilter==="unassigned")throw new PmCliError("Cannot combine --assignee with --assignee-filter unassigned",EXIT_CODE.USAGE)}function resolveListFilterSet(status,options,typeRegistry,statusRegistry){const assigneeFilter=parseStringFilterSet(options.assignee,{label:"--assignee"}),assigneeModeFilter=parseAssigneeFilter(options.assigneeFilter);assertListAssigneeFilters(assigneeFilter,assigneeModeFilter);const missingMetadataFilters=resolveMissingMetadataFilters(options),contentFieldFilters=resolveContentFieldFilters(options);return{idsFilter:parseIdsFilter(options.ids),statusSet:status&&status.length>0?new Set(status):void 0,excludeTerminal:options.excludeTerminal===!0,typeFilter:parseTypeFilterSet(options.type,typeRegistry),tagFilters:parseListTagFilters(options.tag),priorityFilter:parsePriorityFilterSet(options.priority),deadlineBefore:parseDeadline(options.deadlineBefore,"deadline-before"),deadlineAfter:parseDeadline(options.deadlineAfter,"deadline-after"),updatedAfter:resolveListUpdatedAfter(options),updatedBefore:parseTimestampWindow(options.updatedBefore,"updated-before"),createdAfter:parseTimestampWindow(options.createdAfter,"created-after"),createdBefore:parseTimestampWindow(options.createdBefore,"created-before"),assigneeFilter,assigneeModeFilter,parentFilter:options.parent?.trim(),treeEnabled:options.tree===!0,sprintFilter:parseStringFilterSet(options.sprint,{label:"--sprint"}),releaseFilter:parseStringFilterSet(options.release,{label:"--release"}),missingMetadataFilters,missingMetadataActive:hasMissingMetadataFilter(missingMetadataFilters),lifecycleClassifier:lifecycleClassifierFromStatusRegistry(statusRegistry),contentFieldFilters,contentFiltersActive:hasContentFieldFilter(contentFieldFilters)}}function matchesListIdentityFilters(item,filters,statusRegistry){return filters.idsFilter&&!filters.idsFilter.has(item.id)||filters.statusSet&&!filters.statusSet.has(item.status)||filters.excludeTerminal&&isTerminalStatus(item.status,statusRegistry)||filters.typeFilter&&!filters.typeFilter.has(item.type)||filters.tagFilters&&![...filters.tagFilters].some(tag=>(item.tags??[]).some(candidate=>candidate.trim().toLowerCase()===tag))?!1:filters.priorityFilter===void 0||filters.priorityFilter.has(item.priority)}function matchesListDateFilters(item,filters){return matchesTimestampFilters(item,filters)}function matchesListAssigneeFilterSet(item,filters){return filters.assigneeModeFilter==="assigned"&&!item.assignee||filters.assigneeModeFilter==="unassigned"&&item.assignee?!1:filters.assigneeFilter===void 0||item.assignee!==void 0&&filters.assigneeFilter.has(item.assignee)}function matchesListScopeFilters(item,filters,parentsByChild){const scalarParent=item.parent?.trim().toLowerCase(),logicalParentIds=[...new Set([...parentsByChild?.get(item.id.trim().toLowerCase())??[],...scalarParent?[scalarParent]:[]])];return filters.parentFilter!==void 0&&!filters.treeEnabled&&!logicalParentIds.includes(filters.parentFilter.trim().toLowerCase())||filters.sprintFilter!==void 0&&(item.sprint===void 0||!filters.sprintFilter.has(item.sprint))?!1:filters.releaseFilter===void 0||item.release!==void 0&&filters.releaseFilter.has(item.release)}function matchesListFilterSet(item,filters,statusRegistry,runtimeFieldFilters,parentsByChild){return!(!matchesListIdentityFilters(item,filters,statusRegistry)||!matchesListDateFilters(item,filters)||!matchesListAssigneeFilterSet(item,filters)||!matchesListScopeFilters(item,filters,parentsByChild)||filters.missingMetadataActive&&!itemMatchesMissingMetadata(item,filters.missingMetadataFilters,filters.lifecycleClassifier)||filters.contentFiltersActive&&!itemMatchesContentFilters(item,filters.contentFieldFilters)||!matchesRuntimeFilters(item,runtimeFieldFilters))}function applyFilters(items,status,options,typeRegistry,statusRegistry,runtimeFieldFilters,parentsByChild){const filters=resolveListFilterSet(status,options,typeRegistry,statusRegistry);return items.filter(item=>matchesListFilterSet(item,filters,statusRegistry,runtimeFieldFilters,parentsByChild))}function trimNonEmpty(value){if(typeof value!="string")return;const trimmed=value.trim();return trimmed.length>0?trimmed:void 0}function withTreeMetadata(item,depth,childCount,parentId){const itemRecord=toItemRecord(item),title=typeof itemRecord.title=="string"?itemRecord.title:"",parent=parentId??trimNonEmpty(typeof itemRecord.parent=="string"?itemRecord.parent:void 0)??null;return{...item,tree_depth:depth,tree_parent:parent,tree_children:childCount,tree_title:`${"  ".repeat(depth)}${title}`}}function buildListTreeIndexes(sortedItems,hierarchyIndexes){const byId=new Map,childrenByParent=new Map;for(const item of sortedItems){const itemId=item.id.trim().toLowerCase();byId.set(itemId,item);const parentIds=hierarchyIndexes?hierarchyIndexes.parents_by_child.get(itemId)??[]:[trimNonEmpty(item.parent)?.toLowerCase()].filter(value=>value!==void 0);for(const parentId of parentIds){const children=childrenByParent.get(parentId)??[];children.push(item),childrenByParent.set(parentId,children)}}return{byId,childrenByParent}}function resolveListTreeRoots(sortedItems,parentRoot,byId,childrenByParent,hierarchyIndexes){return parentRoot?[...childrenByParent.get(parentRoot.toLowerCase())??[]]:sortedItems.filter(item=>(hierarchyIndexes?hierarchyIndexes.parents_by_child.get(item.id.trim().toLowerCase())??[]:[trimNonEmpty(item.parent)?.toLowerCase()].filter(value=>value!==void 0)).every(parentId=>!byId.has(parentId)))}function orderItemsAsTree(sortedItems,parentRoot,maxDepth,hierarchyIndexes,completeItems=sortedItems){const{byId,childrenByParent}=buildListTreeIndexes(sortedItems,hierarchyIndexes),roots=resolveListTreeRoots(sortedItems,parentRoot,byId,childrenByParent,hierarchyIndexes),ordered=[],visited=new Set,canonicalIdByLowercase=new Map(completeItems.map(item=>[item.id.trim().toLowerCase(),item.id.trim()])),pending=[...roots].reverse().map(node=>({node,depth:0,parentId:parentRoot===void 0?void 0:canonicalIdByLowercase.get(parentRoot.trim().toLowerCase())??parentRoot.trim()}));for(;pending.length>0;){const{node,depth,parentId}=pending.pop(),nodeId=node.id.trim().toLowerCase();if(visited.has(nodeId))continue;visited.add(nodeId);const children=childrenByParent.get(nodeId)??[];if(ordered.push(withTreeMetadata(node,depth,children.length,parentId)),!(maxDepth!==void 0&&depth>=maxDepth))for(const child of[...children].reverse())pending.push({node:child,depth:depth+1,parentId:canonicalIdByLowercase.get(nodeId)})}if(parentRoot===void 0&&maxDepth===void 0)for(const item of sortedItems){const itemId=item.id.trim().toLowerCase();visited.has(itemId)||(visited.add(itemId),ordered.push(withTreeMetadata(item,0,childrenByParent.get(itemId)?.length??0)))}return ordered}function compareNullableString(left,right){return left===right?0:left===null?1:right===null?-1:left.localeCompare(right)}function compareNullableTimestamp(left,right){return left===right?0:left===null?1:right===null?-1:compareTimestampStrings(left,right)}function compareBySortField(left,right,field){switch(field){case"priority":return left.priority-right.priority;case"deadline":return compareNullableTimestamp(left.deadline??null,right.deadline??null);case"updated_at":return compareTimestampStrings(left.updated_at,right.updated_at);case"created_at":return compareTimestampStrings(left.created_at,right.created_at);case"title":return(left.title??"").localeCompare(right.title??"");case"parent":return compareNullableString(left.parent??null,right.parent??null);default:return 0}}function sortItems(items,sortField,sortOrder,statusRegistry){return sortField?[...items].sort((left,right)=>{const byField=compareBySortField(left,right,sortField);if(byField!==0)return sortOrder==="desc"?-byField:byField;const fallback=compareDefaultSort(left,right,statusRegistry);return sortOrder==="desc"?-fallback:fallback}):sortItemsDefault(items,statusRegistry)}function readListFieldValue(item,field,treeMode=!1){const normalized=normalizeProjectionField(field.trim());if(normalized.length===0)return null;const itemRecord=toItemRecord(item);return treeMode&&normalized==="title"&&typeof itemRecord.tree_title=="string"?itemRecord.tree_title:Object.prototype.hasOwnProperty.call(itemRecord,normalized)?itemRecord[normalized]??null:null}function projectListItems(items,projection,treeMode=!1){return projection.mode==="full"?items:items.map(item=>{const projected={};for(const field of projection.fields)projected[field]=readListFieldValue(item,field,treeMode);return projected})}function runtimeMetadataKeysForProjection(definitions){const keys=[];for(const field of definitions)keys.push(field.metadata_key);return keys}function resolveListPageLimit(options,totalRows){const explicitLimit=parseIntegerLimit(options.limit);if(explicitLimit!==void 0)return explicitLimit;if(options.noTruncate!==!0)return totalRows>=1e4?20:void 0}function resolveListPageStart(ordered,options,cursorFingerprint){return options.after===void 0?parseOffset(options.offset)??0:resolveQueryCursorStart(ordered,options.after,cursorFingerprint,item=>item.id)}function buildListPageExtras(limit,hasMore,nextCursor){return{...limit!==void 0?{applied_limit:limit}:{},has_more:hasMore,truncated:hasMore,next_cursor:nextCursor??null}}async function resolveListRuntimeContext(options,global2){const pmRoot=resolvePmRoot(process.cwd(),global2.path);await assertInitializedTracker(pmRoot);const settings=await readSettings(pmRoot),statusRegistry=resolveRuntimeStatusRegistry(settings.schema),runtimeFieldRegistry=resolveRuntimeFieldRegistry(settings.schema),invokedCommand=options.projectionCommand??"list",projection=parseProjectionConfig(options,invokedCommand);return validateListProjectionFields(projection,runtimeMetadataKeysForProjection(runtimeFieldRegistry.definitions),invokedCommand),{pmRoot,settings,statusRegistry,runtimeFieldFilters:collectRuntimeFilterValues(options,runtimeFieldRegistry,"list"),typeRegistry:resolveItemTypeRegistry(settings,getActiveExtensionRegistrations()),projection}}async function loadListItems(options,runtime,listWarnings){const projectionNeedsBody=runtime.projection.fields.some(field=>normalizeProjectionField(field)==="body"),projectionNeedsCollections=runtime.projection.mode==="full"||runtime.projection.fields.some(field=>HEAVY_PROJECTION_FIELDS.has(normalizeProjectionField(field))),contentFieldFilters=resolveContentFieldFilters(options),contentNeedsCollections=contentFiltersNeedCollections(contentFieldFilters),contentNeedsBody=contentFiltersNeedBody(contentFieldFilters);return options.includeBody||projectionNeedsBody||contentNeedsBody?await listAllItemMetadataWithBody(runtime.pmRoot,runtime.settings.item_format,runtime.typeRegistry.type_to_folder,listWarnings,runtime.settings.schema):projectionNeedsCollections||contentNeedsCollections?await listAllItemMetadata(runtime.pmRoot,runtime.settings.item_format,runtime.typeRegistry.type_to_folder,listWarnings,runtime.settings.schema):await listAllItemMetadataLight(runtime.pmRoot,runtime.settings.item_format,runtime.typeRegistry.type_to_folder,listWarnings,runtime.settings.schema)}function resolveListOrderingOptions(options){const sortField=parseSortField(options.sort),sortOrder=parseSortOrder(options.order)??"asc",treeEnabled=options.tree===!0;if(!treeEnabled&&options.treeDepth!==void 0)throw new PmCliError("List --tree-depth requires --tree",EXIT_CODE.USAGE);if(!sortField&&options.order!==void 0)throw new PmCliError("List --order requires --sort",EXIT_CODE.USAGE);return{sortField,sortOrder,treeEnabled,treeDepth:treeEnabled?parseTreeDepth(options.treeDepth):void 0,parentRoot:treeEnabled?trimNonEmpty(options.parent):void 0}}function resolveListStatusSelection(status,options,statusRegistry){const explicitStatus=resolveStatusFilter(options.status,statusRegistry);let lifecycleStatus;options.lifecycleBucket==="in_progress"?lifecycleStatus=[statusRegistry.in_progress_status]:options.lifecycleBucket==="open"&&(lifecycleStatus=[...statusRegistry.active_statuses].filter(entry=>entry!==statusRegistry.in_progress_status).sort((left,right)=>left.localeCompare(right)));const resolvedStatus=explicitStatus??lifecycleStatus??resolveStatusFilter(status,statusRegistry),explicitAllStatuses=isStatusAllFilterInput(options.status),effectiveOptions=explicitStatus||explicitAllStatuses?{...options,excludeTerminal:!1}:options;let filtersStatus="all";return explicitAllStatuses?filtersStatus="all":explicitStatus!==void 0?filtersStatus=explicitStatus.length===1?explicitStatus[0]:explicitStatus:options.lifecycleBucket!==void 0?filtersStatus=options.lifecycleBucket:resolvedStatus!==void 0?filtersStatus=resolvedStatus.length===1?resolvedStatus[0]:resolvedStatus:effectiveOptions.excludeTerminal===!0&&(filtersStatus=null),{resolvedStatus,explicitAllStatuses,effectiveOptions,filtersStatus}}function pageAndProjectListItems(ordered,options,projection,treeEnabled,cursorFingerprint){if(options.after!==void 0&&options.offset!==void 0)throw new PmCliError("List --after cannot be combined with --offset.",EXIT_CODE.USAGE);const limit=resolveListPageLimit(options,ordered.length),offset=resolveListPageStart(ordered,options,cursorFingerprint),limited=limit===void 0?ordered.slice(offset):ordered.slice(offset,offset+limit),projected=projectListItems(limited,projection,treeEnabled),totalMatched=ordered.length,hasMore=limited.length>0&&offset+limited.length<totalMatched,nextCursor=hasMore&&limited.length>0?encodeQueryCursor(cursorFingerprint,limited[limited.length-1].id,offset+limited.length-1):void 0;return{projected,totalMatched,pageExtras:buildListPageExtras(limit,hasMore,nextCursor)}}function buildListCursorFingerprint(status,options,ordering,pmRoot){return createQueryFingerprint("list",{pmRoot,status,options:selectCursorSemanticOptions(options,LIST_FILTER_FLAG_CONTRACTS),sort:ordering.sortField??"default",order:ordering.sortOrder,tree:ordering.treeEnabled,tree_depth:ordering.treeDepth??null})}async function tryLoadIndexedListPage(params){const{options,runtime,statusSelection,ordering}=params,supportedOptionKeys=new Set(["status","limit","offset","compact","brief","full","fields","format","stream","includeBody","excludeTerminal","dependencyBlocked","lifecycleBucket","noTruncate","projectionCommand","truncate","notes","learnings","files","docs","tests","comments","deps","linkedCommand"]),projectionNeedsHeavyData=[runtime.projection.mode==="full",runtime.projection.fields.some(field=>{const normalized=normalizeProjectionField(field);return normalized==="body"||HEAVY_PROJECTION_FIELDS.has(normalized)})].includes(!0);if([options.limit===void 0,options.after!==void 0,options.noTruncate===!0,options.includeBody===!0,options.dependencyBlocked===!0,options.strictRead===!0,ordering.treeEnabled,ordering.sortField!==void 0,projectionNeedsHeavyData,hasActiveOnReadHooks(),Object.keys(runtime.runtimeFieldFilters).length>0,Object.entries(options).some(([key,value])=>value!==void 0&&!supportedOptionKeys.has(key))].includes(!0))return null;const indexState=await readItemMetadataDerivedIndexState(runtime.pmRoot,[...new Set(Object.values(runtime.typeRegistry.type_to_folder))]);if(!indexState)return null;const limit=parseIntegerLimit(options.limit),offset=parseOffset(options.offset)??0,indexed=await queryItemMetadataIndex({pmRoot:runtime.pmRoot,expectedSourceCursor:indexState.source_cursor,query:{statuses:statusSelection.resolvedStatus,excludeStatuses:statusSelection.resolvedStatus===void 0&&statusSelection.effectiveOptions.excludeTerminal===!0?[...runtime.statusRegistry.terminal_statuses]:void 0,terminalStatuses:[...runtime.statusRegistry.terminal_statuses],limit,offset}});if(!indexed)return null;const hasMore=indexed.items.length>0&&offset+indexed.items.length<indexed.total,nextCursor=hasMore?encodeQueryCursor(buildListCursorFingerprint(statusSelection.filtersStatus,options,ordering,runtime.pmRoot),indexed.items.at(-1).id,offset+indexed.items.length-1):void 0;return{projected:projectListItems(indexed.items,runtime.projection,!1),totalMatched:indexed.total,pageExtras:buildListPageExtras(limit,hasMore,nextCursor)}}function buildVerboseListFilters(params){const{filtersStatus,options,noTruncate,treeEnabled,treeDepth,sortField,sortOrder,runtimeFieldFilters}=params,filters={};filtersStatus!==null&&(filters.status=filtersStatus),options.dependencyBlocked===!0&&(filters.blocked_semantics="status_or_dependency");const optionRecord=options;for(const entry of VERBOSE_LIST_VALUE_FILTER_ECHO_ENTRIES){const value=optionRecord[entry.optionKey];value!=null&&(filters[entry.summaryKey]=value)}for(const entry of VERBOSE_LIST_BOOLEAN_FILTER_ECHO_ENTRIES)optionRecord[entry.key]===!0&&(filters[entry.summaryKey]=!0);return Object.assign(filters,buildGovernanceMissingFilterEcho(options),buildContentFilterEcho(options)),applyListWindowFilterEcho(filters,options),noTruncate&&(filters.no_truncate=!0),options.strictRead===!0&&(filters.strict_read=!0),treeEnabled&&(filters.tree=!0,treeDepth!==void 0&&(filters.tree_depth=treeDepth)),sortField!==void 0&&(filters.sort=sortField,filters.order=sortOrder),filters.runtime_filters=runtimeFieldFilters,filters}async function runList(status,options,global2){const runtime=await resolveListRuntimeContext(options,global2),listWarnings=[],ordering=resolveListOrderingOptions(options),statusSelection=resolveListStatusSelection(status,options,runtime.statusRegistry),noTruncate=options.noTruncate===!0,indexedPage=await tryLoadIndexedListPage({options,runtime,statusSelection,ordering});let page=indexedPage;if(!page){const items=await loadListItems(options,runtime,listWarnings),hierarchyIndexes=ordering.treeEnabled||trimNonEmpty(options.parent)!==void 0?indexHierarchyRelations(collectHierarchyRelations(items,resolveWorkspaceRelationshipKindRegistry())):void 0;appendUnknownTagWarning(items,options.tag,listWarnings);const filtered=applyFilters(items,statusSelection.resolvedStatus,statusSelection.effectiveOptions,runtime.typeRegistry,runtime.statusRegistry,runtime.runtimeFieldFilters,hierarchyIndexes?.parents_by_child),scoped=options.dependencyBlocked===!0?(()=>{const blockedIds=collectDependencyBlockedIds(items,runtime.statusRegistry);return filtered.filter(item=>blockedIds.has(item.id.trim().toLowerCase()))})():filtered,sorted=sortItems(scoped,ordering.sortField,ordering.sortOrder,runtime.statusRegistry),ordered=ordering.treeEnabled?orderItemsAsTree(sorted,ordering.parentRoot,ordering.treeDepth,hierarchyIndexes,items):sorted;page=pageAndProjectListItems(ordered,options,runtime.projection,ordering.treeEnabled,buildListCursorFingerprint(statusSelection.filtersStatus,options,ordering,runtime.pmRoot))}const now=nowIso(),warnings=[...new Set(listWarnings)].sort((left,right)=>left.localeCompare(right)),completeness=resolveListCompleteness(warnings,indexedPage!==null,options.strictRead===!0),projectionFields=runtime.projection.mode==="full"?null:[...runtime.projection.fields];if(runtime.projection.mode==="compact"&&options.compact===!0){const compactFilters=buildCompactListFilterSummary({filtersStatus:statusSelection.filtersStatus,options,treeEnabled:ordering.treeEnabled,treeDepth:ordering.treeDepth,sortField:ordering.sortField,sortOrder:ordering.sortOrder,runtimeFieldFilters:runtime.runtimeFieldFilters});return{items:page.projected,count:page.projected.length,total:page.totalMatched,...page.pageExtras,completeness,filters:compactFilters,projection:{mode:"compact",fields:projectionFields},...warnings.length>0?{warnings}:{}}}return{items:page.projected,count:page.projected.length,total:page.totalMatched,...page.pageExtras,completeness,filters:buildVerboseListFilters({filtersStatus:statusSelection.filtersStatus,options,noTruncate,treeEnabled:ordering.treeEnabled,treeDepth:ordering.treeDepth,sortField:ordering.sortField,sortOrder:ordering.sortOrder,runtimeFieldFilters:runtime.runtimeFieldFilters}),projection:{mode:runtime.projection.mode,fields:projectionFields},sorting:{sort:ordering.sortField??"default",order:ordering.sortField?ordering.sortOrder:"asc"},now,...warnings.length>0?{warnings}:{}}}const _testOnly={applyFilters,buildCompactListFilterSummary,buildContentFilterEcho,buildGovernanceMissingFilterEcho,resolveContentFieldFilters,resolveMissingMetadataFilters,compareBySortField,compareDefaultSort,compareNullableString,compareNullableTimestamp,normalizeProjectionField,parseAssigneeFilter,parseFieldSelectors,parseIdsFilter,parseOffset,parseProjectionConfig,resolveListUpdatedAfter,resolveListPageLimit,parseSortField,parseSortOrder,orderItemsAsTree,projectListItems,readListFieldValue,runtimeMetadataKeysForProjection,sortItems,trimNonEmpty,withTreeMetadata};export{BRIEF_LIST_FIELDS2 as BRIEF_LIST_FIELDS,DEFAULT_COMPACT_LIST_FIELDS2 as DEFAULT_COMPACT_LIST_FIELDS,LIST_COMMAND_DEFAULT_PROJECTIONS,LIST_SORT_FIELDS,LIST_SORT_ORDER_VALUES,_testOnly,applyFilterValueEcho,buildContentFilterEcho,buildGovernanceMissingFilterEcho,listListProjectionFields2 as listListProjectionFields,resolveContentFieldFilters,resolveMissingMetadataFilters,runList};
 //# sourceMappingURL=list.js.map

package/dist/sdk/relationship-context.d.ts

@@ -1,4 +1,6 @@
 import { RelationshipGraph,RelationshipKindRegistry,type RelationshipEdge,type RelationshipTraversalDirection } from "./relationships.js";
+/** Canonical default shared by the kernel and rendered-budget recovery. */
+export declare const DEFAULT_RELATIONSHIP_CONTEXT_TOKEN_BUDGET = 1200;
 /** Semantic family explaining why a node or edge participates in graph context. */
 export type RelationshipContextRole = "prerequisite" | "dependent" | "ancestor" | "descendant" | "provenance" | "related";
 /**

package/dist/sdk/relationship-context.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="c67d6023-2fb2-541f-9541-8aa317368dcf")}catch{}})();import{createQueryFingerprint,encodeQueryCursor,resolveQueryCursorStart}from"./pagination.js";import{createRelationshipKindRegistry}from"./relationships.js";const RELATIONSHIP_CONTEXT_ROLE_PRIORITY=["prerequisite","dependent","ancestor","descendant","provenance","related"],tokenEncoder=new TextEncoder;function positiveInteger(value,fallback,field){const resolved=value??fallback;if(!Number.isInteger(resolved)||resolved<1)throw new TypeError(`Relationship context ${field} must be positive`);return resolved}function estimateTokens(value){return Math.max(1,Math.ceil(tokenEncoder.encode(JSON.stringify(value)).byteLength/4))}function explainDirectEdge(edge,node,registry){const definition=registry.resolve(edge.kind);if(definition?.ordering){const before=(definition.precedence??"source_before_target")==="source_before_target"?edge.source:edge.target;return node===before?"prerequisite":"dependent"}if(definition?.hierarchy){const parent=definition.hierarchyDirection==="source_parent"?edge.source:edge.target;return node===parent?"ancestor":"descendant"}return edge.kind==="discovered_from"||edge.kind==="incident_from"?"provenance":"related"}function directReasons(rootEdges,root,node,registry){const reasons=rootEdges.filter(edge=>edge.source===root&&edge.target===node||edge.target===root&&edge.source===node).map(edge=>explainDirectEdge(edge,node,registry));return[...new Set(reasons)].sort()}function primaryRole(roles){return RELATIONSHIP_CONTEXT_ROLE_PRIORITY.find(role=>roles.includes(role))}function discoverNodes(graph,root,registry,options){const direction=options.direction??"both",maxDepth=options.maxDepth??3;if(!Number.isInteger(maxDepth)||maxDepth<0)throw new TypeError("Relationship context maxDepth must be non-negative");const seen=new Set([root]),queue=[{id:root,distance:0}],rows=[];let inspectedEdges=0,depthTruncated=!1;for(let index=0;index<queue.length;index+=1){options.signal?.throwIfAborted();const current=queue[index];if(current.distance>=maxDepth&&depthTruncated)continue;const adjacent=graph.neighborEdges(current.id,{direction,kinds:options.kinds,signal:options.signal});if(inspectedEdges+=adjacent.meta.inspectedEdges,current.distance>=maxDepth){adjacent.value.some(row=>!seen.has(row.id))&&(depthTruncated=!0);continue}for(const{id,edge}of adjacent.value){if(seen.has(id))continue;seen.add(id);const row={id,distance:current.distance+1,via:current.id,role:explainDirectEdge(edge,id,registry)};rows.push(row),queue.push(row)}}return rows.sort((left,right)=>left.distance-right.distance||left.id.localeCompare(right.id)),{rows,visitedNodes:queue.length,inspectedEdges,depthTruncated}}function summarizeDirectEdges(graph,root,registry,options){const directEdges={prerequisite:0,dependent:0,ancestor:0,descendant:0,provenance:0,related:0},rows=graph.neighborEdges(root,{direction:options.direction??"both",kinds:options.kinds,signal:options.signal}).value;for(const{id,edge}of rows)directEdges[explainDirectEdge(edge,id,registry)]+=1;return{directEdges,directTotal:rows.length,rootEdges:rows.map(({edge})=>edge)}}function selectContextNodes(params){const nodes=[];let usedTokens=params.initialTokens;for(const candidate of params.candidates){if(nodes.length>=params.nodeLimit)break;const direct=candidate.distance===1?directReasons(params.rootEdges,params.rootId,candidate.id,params.registry):[],node={...params.details.get(candidate.id)??{id:candidate.id},distance:candidate.distance,role:direct.length>0?primaryRole(direct):candidate.role,via:candidate.via,reasons:direct.length>0?direct:[`${candidate.role} via ${candidate.via} (depth ${candidate.distance})`]},cost=estimateTokens(node);if(usedTokens+cost>params.tokenBudget)break;nodes.push(node),usedTokens+=cost}if(params.candidates.length>0&&nodes.length===0)throw new TypeError("Relationship context tokenBudget cannot fit one node");return{nodes,usedTokens}}function selectContextEdges(params){const kinds=params.options.kinds?new Set(params.options.kinds.map(kind=>params.registry.require(kind).kind)):void 0,candidates=params.graph.edges().filter(edge=>{if(!params.included.has(edge.source)||!params.included.has(edge.target))return!1;if(kinds===void 0||kinds.has(edge.kind))return!0;const inverse=params.registry.resolve(edge.kind)?.inverse;return inverse!==void 0&&kinds.has(inverse)}),edges=[];let usedTokens=params.initialTokens;for(const edge of candidates){if(edges.length>=params.edgeLimit)break;const cost=estimateTokens(edge);if(usedTokens+cost>params.tokenBudget)break;edges.push(edge),usedTokens+=cost}return{edges,usedTokens,candidateCount:candidates.length}}function buildRelationshipContext(graph,rootId,details,options={}){if(!graph.nodes().includes(rootId))throw new TypeError(`Relationship node not found: ${rootId}`);const nodeLimit=positiveInteger(options.nodeLimit,20,"nodeLimit"),edgeLimit=positiveInteger(options.edgeLimit,40,"edgeLimit"),tokenBudget=positiveInteger(options.tokenBudget,1200,"tokenBudget"),registry=options.registry??createRelationshipKindRegistry(),byId=new Map(details.map(detail=>[detail.id,detail])),rootDetails=byId.get(rootId)??{id:rootId},{evidence:rootEvidence=[],...root}=rootDetails,evidence=[...rootEvidence],discovery=discoverNodes(graph,rootId,registry,options),{rootEdges,...directSummary}=summarizeDirectEdges(graph,rootId,registry,options),fingerprint=createQueryFingerprint("relationship-context",{rootId,direction:options.direction??"both",kinds:[...options.kinds??[]].sort(),maxDepth:options.maxDepth??3}),pageStart=resolveQueryCursorStart(discovery.rows,options.cursor,fingerprint,({id})=>id),candidates=discovery.rows.slice(pageStart),initialTokens=estimateTokens(root)+estimateTokens(evidence);if(initialTokens>tokenBudget)throw new TypeError("Relationship context tokenBudget cannot fit root and evidence");const nodeSelection=selectContextNodes({candidates,details:byId,rootEdges,rootId,registry,nodeLimit,tokenBudget,initialTokens}),{nodes}=nodeSelection,included=new Set([rootId,...nodes.map(({id})=>id)]),edgeSelection=selectContextEdges({graph,included,options,registry,edgeLimit,tokenBudget,initialTokens:nodeSelection.usedTokens}),{edges,usedTokens}=edgeSelection,consumed=pageStart+nodes.length,hasMoreNodes=consumed<discovery.rows.length,lastNode=nodes.at(-1),omittedEdges=edgeSelection.candidateCount-edges.length,truncated=discovery.depthTruncated||hasMoreNodes||omittedEdges>0,summary={rootId,...root.status===void 0?{}:{rootStatus:root.status},...directSummary,discoveredNodes:discovery.rows.length,returnedNodes:nodes.length,returnedEdges:edges.length,omittedNodes:discovery.rows.length-consumed,omittedEdges,evidenceCount:evidence.length,hasMore:hasMoreNodes};return{root,summary,nodes,edges,evidence,meta:{exact:!0,truncated,completeness:truncated?"truncated":"complete",nodeLimit,edgeLimit,tokenBudget,usedTokens,visitedNodes:discovery.visitedNodes,inspectedEdges:discovery.inspectedEdges,omittedNodes:discovery.rows.length-consumed,omittedEdges,...hasMoreNodes&&lastNode?{nextCursor:encodeQueryCursor(fingerprint,lastNode.id,consumed-1)}:{}}}}export{buildRelationshipContext};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5a56b848-63e7-5499-bed3-ee2b2d65e200")}catch{}})();import{createQueryFingerprint,encodeQueryCursor,resolveQueryCursorStart}from"./pagination.js";import{createRelationshipKindRegistry}from"./relationships.js";const DEFAULT_RELATIONSHIP_CONTEXT_TOKEN_BUDGET=1200,RELATIONSHIP_CONTEXT_ROLE_PRIORITY=["prerequisite","dependent","ancestor","descendant","provenance","related"],tokenEncoder=new TextEncoder;function positiveInteger(value,fallback,field){const resolved=value??fallback;if(!Number.isInteger(resolved)||resolved<1)throw new TypeError(`Relationship context ${field} must be positive`);return resolved}function estimateTokens(value){return Math.max(1,Math.ceil(tokenEncoder.encode(JSON.stringify(value)).byteLength/4))}function explainDirectEdge(edge,node,registry){const definition=registry.resolve(edge.kind);if(definition?.ordering){const before=(definition.precedence??"source_before_target")==="source_before_target"?edge.source:edge.target;return node===before?"prerequisite":"dependent"}if(definition?.hierarchy){const parent=definition.hierarchyDirection==="source_parent"?edge.source:edge.target;return node===parent?"ancestor":"descendant"}return edge.kind==="discovered_from"||edge.kind==="incident_from"?"provenance":"related"}function directReasons(rootEdges,root,node,registry){const reasons=rootEdges.filter(edge=>edge.source===root&&edge.target===node||edge.target===root&&edge.source===node).map(edge=>explainDirectEdge(edge,node,registry));return[...new Set(reasons)].sort()}function primaryRole(roles){return RELATIONSHIP_CONTEXT_ROLE_PRIORITY.find(role=>roles.includes(role))}function discoverNodes(graph,root,registry,options){const direction=options.direction??"both",maxDepth=options.maxDepth??3;if(!Number.isInteger(maxDepth)||maxDepth<0)throw new TypeError("Relationship context maxDepth must be non-negative");const seen=new Set([root]),queue=[{id:root,distance:0}],rows=[];let inspectedEdges=0,depthTruncated=!1;for(let index=0;index<queue.length;index+=1){options.signal?.throwIfAborted();const current=queue[index];if(current.distance>=maxDepth&&depthTruncated)continue;const adjacent=graph.neighborEdges(current.id,{direction,kinds:options.kinds,signal:options.signal});if(inspectedEdges+=adjacent.meta.inspectedEdges,current.distance>=maxDepth){adjacent.value.some(row=>!seen.has(row.id))&&(depthTruncated=!0);continue}for(const{id,edge}of adjacent.value){if(seen.has(id))continue;seen.add(id);const row={id,distance:current.distance+1,via:current.id,role:explainDirectEdge(edge,id,registry)};rows.push(row),queue.push(row)}}return rows.sort((left,right)=>left.distance-right.distance||left.id.localeCompare(right.id)),{rows,visitedNodes:queue.length,inspectedEdges,depthTruncated}}function summarizeDirectEdges(graph,root,registry,options){const directEdges={prerequisite:0,dependent:0,ancestor:0,descendant:0,provenance:0,related:0},rows=graph.neighborEdges(root,{direction:options.direction??"both",kinds:options.kinds,signal:options.signal}).value;for(const{id,edge}of rows)directEdges[explainDirectEdge(edge,id,registry)]+=1;return{directEdges,directTotal:rows.length,rootEdges:rows.map(({edge})=>edge)}}function selectContextNodes(params){const nodes=[];let usedTokens=params.initialTokens;for(const candidate of params.candidates){if(nodes.length>=params.nodeLimit)break;const direct=candidate.distance===1?directReasons(params.rootEdges,params.rootId,candidate.id,params.registry):[],node={...params.details.get(candidate.id)??{id:candidate.id},distance:candidate.distance,role:direct.length>0?primaryRole(direct):candidate.role,via:candidate.via,reasons:direct.length>0?direct:[`${candidate.role} via ${candidate.via} (depth ${candidate.distance})`]},cost=estimateTokens(node);if(usedTokens+cost>params.tokenBudget)break;nodes.push(node),usedTokens+=cost}if(params.candidates.length>0&&nodes.length===0)throw new TypeError("Relationship context tokenBudget cannot fit one node");return{nodes,usedTokens}}function selectContextEdges(params){const kinds=params.options.kinds?new Set(params.options.kinds.map(kind=>params.registry.require(kind).kind)):void 0,candidates=params.graph.edges().filter(edge=>{if(!params.included.has(edge.source)||!params.included.has(edge.target))return!1;if(kinds===void 0||kinds.has(edge.kind))return!0;const inverse=params.registry.resolve(edge.kind)?.inverse;return inverse!==void 0&&kinds.has(inverse)}),edges=[];let usedTokens=params.initialTokens;for(const edge of candidates){if(edges.length>=params.edgeLimit)break;const cost=estimateTokens(edge);if(usedTokens+cost>params.tokenBudget)break;edges.push(edge),usedTokens+=cost}return{edges,usedTokens,candidateCount:candidates.length}}function buildRelationshipContext(graph,rootId,details,options={}){if(!graph.nodes().includes(rootId))throw new TypeError(`Relationship node not found: ${rootId}`);const nodeLimit=positiveInteger(options.nodeLimit,20,"nodeLimit"),edgeLimit=positiveInteger(options.edgeLimit,40,"edgeLimit"),tokenBudget=positiveInteger(options.tokenBudget,DEFAULT_RELATIONSHIP_CONTEXT_TOKEN_BUDGET,"tokenBudget"),registry=options.registry??createRelationshipKindRegistry(),byId=new Map(details.map(detail=>[detail.id,detail])),rootDetails=byId.get(rootId)??{id:rootId},{evidence:rootEvidence=[],...root}=rootDetails,evidence=[...rootEvidence],discovery=discoverNodes(graph,rootId,registry,options),{rootEdges,...directSummary}=summarizeDirectEdges(graph,rootId,registry,options),fingerprint=createQueryFingerprint("relationship-context",{rootId,direction:options.direction??"both",kinds:[...options.kinds??[]].sort(),maxDepth:options.maxDepth??3}),pageStart=resolveQueryCursorStart(discovery.rows,options.cursor,fingerprint,({id})=>id),candidates=discovery.rows.slice(pageStart),initialTokens=estimateTokens(root)+estimateTokens(evidence);if(initialTokens>tokenBudget)throw new TypeError("Relationship context tokenBudget cannot fit root and evidence");const nodeSelection=selectContextNodes({candidates,details:byId,rootEdges,rootId,registry,nodeLimit,tokenBudget,initialTokens}),{nodes}=nodeSelection,included=new Set([rootId,...nodes.map(({id})=>id)]),edgeSelection=selectContextEdges({graph,included,options,registry,edgeLimit,tokenBudget,initialTokens:nodeSelection.usedTokens}),{edges,usedTokens}=edgeSelection,consumed=pageStart+nodes.length,hasMoreNodes=consumed<discovery.rows.length,lastNode=nodes.at(-1),omittedEdges=edgeSelection.candidateCount-edges.length,truncated=discovery.depthTruncated||hasMoreNodes||omittedEdges>0,summary={rootId,...root.status===void 0?{}:{rootStatus:root.status},...directSummary,discoveredNodes:discovery.rows.length,returnedNodes:nodes.length,returnedEdges:edges.length,omittedNodes:discovery.rows.length-consumed,omittedEdges,evidenceCount:evidence.length,hasMore:hasMoreNodes};return{root,summary,nodes,edges,evidence,meta:{exact:!0,truncated,completeness:truncated?"truncated":"complete",nodeLimit,edgeLimit,tokenBudget,usedTokens,visitedNodes:discovery.visitedNodes,inspectedEdges:discovery.inspectedEdges,omittedNodes:discovery.rows.length-consumed,omittedEdges,...hasMoreNodes&&lastNode?{nextCursor:encodeQueryCursor(fingerprint,lastNode.id,consumed-1)}:{}}}}export{DEFAULT_RELATIONSHIP_CONTEXT_TOKEN_BUDGET,buildRelationshipContext};
 //# sourceMappingURL=relationship-context.js.map

package/dist/sdk/runtime-extended-actions.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="01f25e4f-09a1-554f-9e0b-a999fcce5c55")}catch{}})();import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{transferMutationStdinTokenPolicy}from"./runtime-primitives.js";import{createUnknownSubcommandError}from"./agent/subcommand-recovery.js";import{resolvePmRoot}from"../core/store/paths.js";import{runEval}from"./eval.js";import{runMergeDriver}from"./merge/driver.js";import{runMergeInstall}from"./merge/install.js";import{runMergeReconcile}from"./merge/reconcile.js";import{runMergeReceiptEvidenceReport}from"./merge/receipts.js";import{listMutationEvents}from"./mutation-events.js";import{parseRuntimeInteger,readRuntimeString,readRuntimeStringArray}from"./runtime-input.js";import{runEvent,runMeet,runRemind}from"./scheduling-shortcuts.js";import{createWorkspaceSnapshot,deleteWorkspaceSnapshot,inspectWorkspaceSnapshot,listWorkspaceSnapshots,planWorkspaceSnapshotRestore,restoreWorkspaceSnapshotWithRecovery}from"./workspace-snapshot.js";import{readWorkspacePosition}from"./governance/workspace-position.js";function mergedInput(context){const input={...context.args,...context.options};return transferMutationStdinTokenPolicy(context.options,input)}function requiredString(input,key){const value=readRuntimeString(input,key);if(value!==void 0)return value;throw new PmCliError(`Missing required parameter: ${key}`,EXIT_CODE.USAGE)}function stringList(value){return typeof value=="string"?[value]:readRuntimeStringArray(value)}function runRuntimeEvalAction(context){return runEval(mergedInput(context),context.global)}function runRuntimeEventsAction(context){const input=mergedInput(context),rawCursorMode=input.cursorMode;if(rawCursorMode!==void 0&&rawCursorMode!=="batch"&&rawCursorMode!=="row")throw new PmCliError("Mutation event cursor mode must be batch or row.",EXIT_CODE.USAGE,{code:"invalid_event_cursor_mode"});const cursorMode=rawCursorMode;return listMutationEvents({cwd:readRuntimeString(input,"cwd"),pmRoot:readRuntimeString(input,"path"),since:readRuntimeString(input,"since"),type:stringList(input.type),author:stringList(input.author),item:stringList(input.item),limit:input.limit===void 0?void 0:parseRuntimeInteger(input.limit,"limit"),full:input.full===!0,cursorMode,...input.provenance===void 0?{}:{provenance:input.provenance===!0},...input.provenanceSummary===void 0?{}:{provenanceSummary:input.provenanceSummary===!0},...input.harness===void 0?{}:{harness:stringList(input.harness)},...input.agentInstance===void 0?{}:{agentInstance:stringList(input.agentInstance)},...input.provenanceFilter===void 0?{}:{provenanceFilter:stringList(input.provenanceFilter)}})}function runRuntimeMergeAction(context){const input=mergedInput(context),subcommand=requiredString(input,"subcommand");if(subcommand==="install")return runMergeInstall({dryRun:input.dryRun===!0},context.global);if(subcommand==="reconcile")return runMergeReconcile({dryRun:input.dryRun===!0,author:readRuntimeString(input,"author"),message:readRuntimeString(input,"message"),force:input.force===!0},context.global);if(subcommand==="report")return runMergeReceiptEvidenceReport({includeReconciled:input.includeReconciled===!0,cwd:readRuntimeString(input,"cwd")});if(subcommand==="driver")return runMergeDriver({artifact:requiredString(input,"artifact"),basePath:requiredString(input,"basePath"),oursPath:requiredString(input,"oursPath"),theirsPath:requiredString(input,"theirsPath"),outputPath:readRuntimeString(input,"outputPath")??readRuntimeString(input,"output"),itemPath:readRuntimeString(input,"itemPath"),prefer:readRuntimeString(input,"prefer")},context.global);throw createUnknownSubcommandError({command_path:"merge",token:subcommand,allowed:["install","reconcile","report","driver"],display_name:"merge"})}function runRuntimeWorkspaceAction(context){const input=mergedInput(context),subcommand=requiredString(input,"subcommand");if(subcommand==="position")return readWorkspacePosition(context.global);if(subcommand!=="snapshot")throw createUnknownSubcommandError({command_path:"workspace",token:subcommand,allowed:["position","snapshot"],display_name:"workspace"});const snapshotAction=readRuntimeString(input,"snapshotAction")??requiredString(input,"snapshot_action"),pmRoot=resolvePmRoot(process.cwd(),context.global.path);if(snapshotAction==="create")return createWorkspaceSnapshot(pmRoot,{name:readRuntimeString(input,"name")});if(snapshotAction==="list")return listWorkspaceSnapshots(pmRoot);const target=requiredString(input,"target");if(snapshotAction==="inspect")return inspectWorkspaceSnapshot(pmRoot,target);if(snapshotAction==="delete")return deleteWorkspaceSnapshot(pmRoot,target);if(snapshotAction==="restore")return input.dryRun===!0?planWorkspaceSnapshotRestore(pmRoot,target):restoreWorkspaceSnapshotWithRecovery(pmRoot,target,{force:input.force===!0,author:readRuntimeString(input,"author"),message:readRuntimeString(input,"message"),lockTtlSeconds:parseRuntimeInteger(input.lockTtlSeconds,"lockTtlSeconds"),lockWaitMs:parseRuntimeInteger(input.lockWaitMs,"lockWaitMs")});throw createUnknownSubcommandError({command_path:"workspace snapshot",token:snapshotAction,allowed:["create","list","inspect","restore","delete"],display_name:"workspace snapshot",token_kind:"action"})}function runRuntimeSchedulingAction(context){const input=mergedInput(context),title=requiredString(input,"title");return context.action==="meet"?runMeet(title,input,context.global):context.action==="event"?runEvent(title,input,context.global):runRemind(title,input,context.global)}export{runRuntimeEvalAction,runRuntimeEventsAction,runRuntimeMergeAction,runRuntimeSchedulingAction,runRuntimeWorkspaceAction};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e3fe4357-da47-54d5-99d7-62e4b6f86b2b")}catch{}})();import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{transferMutationStdinTokenPolicy}from"./runtime-primitives.js";import{createUnknownSubcommandError}from"./agent/subcommand-recovery.js";import{resolvePmRoot}from"../core/store/paths.js";import{runEval}from"./eval.js";import{runMergeDriver}from"./merge/driver.js";import{runMergeInstall}from"./merge/install.js";import{runMergeReconcile}from"./merge/reconcile.js";import{runMergeReceiptEvidenceReport}from"./merge/receipts.js";import{listMutationEvents}from"./mutation-events.js";import{parseRuntimeInteger,readRuntimeString,readRuntimeStringArray}from"./runtime-input.js";import{runEvent,runMeet,runRemind}from"./scheduling-shortcuts.js";import{createWorkspaceSnapshot,deleteWorkspaceSnapshot,inspectWorkspaceSnapshot,listWorkspaceSnapshots,planWorkspaceSnapshotRestore,restoreWorkspaceSnapshotWithRecovery}from"./workspace-snapshot.js";import{readWorkspacePosition}from"./governance/workspace-position.js";function mergedInput(context){const input={...context.args,...context.options};return transferMutationStdinTokenPolicy(context.options,input)}function requiredString(input,key){const value=readRuntimeString(input,key);if(value!==void 0)return value;throw new PmCliError(`Missing required parameter: ${key}`,EXIT_CODE.USAGE)}function stringList(value){return typeof value=="string"?[value]:readRuntimeStringArray(value)}function runRuntimeEvalAction(context){return runEval(mergedInput(context),context.global)}function runRuntimeEventsAction(context){const input=mergedInput(context),rawCursorMode=input.cursorMode;if(rawCursorMode!==void 0&&rawCursorMode!=="batch"&&rawCursorMode!=="row")throw new PmCliError("Mutation event cursor mode must be batch or row.",EXIT_CODE.USAGE,{code:"invalid_event_cursor_mode"});const cursorMode=rawCursorMode;return listMutationEvents({cwd:readRuntimeString(input,"cwd"),pmRoot:readRuntimeString(input,"path"),since:readRuntimeString(input,"since"),type:stringList(input.type),author:stringList(input.author),item:stringList(input.item),limit:input.limit===void 0?void 0:parseRuntimeInteger(input.limit,"limit"),full:input.full===!0,cursorMode,...input.provenance===void 0?{}:{provenance:input.provenance===!0},...input.provenanceSummary===void 0?{}:{provenanceSummary:input.provenanceSummary===!0},...input.harness===void 0?{}:{harness:stringList(input.harness)},...input.agentInstance===void 0?{}:{agentInstance:stringList(input.agentInstance)},...input.provenanceFilter===void 0?{}:{provenanceFilter:stringList(input.provenanceFilter)}})}function runRuntimeMergeAction(context){const input=mergedInput(context),subcommand=requiredString(input,"subcommand");if(subcommand==="install")return runMergeInstall({dryRun:input.dryRun===!0,preCommitHook:input.preCommitHook===!0},context.global);if(subcommand==="reconcile")return runMergeReconcile({dryRun:input.dryRun===!0,author:readRuntimeString(input,"author"),message:readRuntimeString(input,"message"),force:input.force===!0,stage:input.stage===!0},context.global);if(subcommand==="report")return runMergeReceiptEvidenceReport({includeReconciled:input.includeReconciled===!0,cwd:readRuntimeString(input,"cwd")});if(subcommand==="driver")return runMergeDriver({artifact:requiredString(input,"artifact"),basePath:requiredString(input,"basePath"),oursPath:requiredString(input,"oursPath"),theirsPath:requiredString(input,"theirsPath"),outputPath:readRuntimeString(input,"outputPath")??readRuntimeString(input,"output"),itemPath:readRuntimeString(input,"itemPath"),prefer:readRuntimeString(input,"prefer")},context.global);throw createUnknownSubcommandError({command_path:"merge",token:subcommand,allowed:["install","reconcile","report","driver"],display_name:"merge"})}function runRuntimeWorkspaceAction(context){const input=mergedInput(context),subcommand=requiredString(input,"subcommand");if(subcommand==="position")return readWorkspacePosition(context.global);if(subcommand!=="snapshot")throw createUnknownSubcommandError({command_path:"workspace",token:subcommand,allowed:["position","snapshot"],display_name:"workspace"});const snapshotAction=readRuntimeString(input,"snapshotAction")??requiredString(input,"snapshot_action"),pmRoot=resolvePmRoot(process.cwd(),context.global.path);if(snapshotAction==="create")return createWorkspaceSnapshot(pmRoot,{name:readRuntimeString(input,"name")});if(snapshotAction==="list")return listWorkspaceSnapshots(pmRoot);const target=requiredString(input,"target");if(snapshotAction==="inspect")return inspectWorkspaceSnapshot(pmRoot,target);if(snapshotAction==="delete")return deleteWorkspaceSnapshot(pmRoot,target);if(snapshotAction==="restore")return input.dryRun===!0?planWorkspaceSnapshotRestore(pmRoot,target):restoreWorkspaceSnapshotWithRecovery(pmRoot,target,{force:input.force===!0,author:readRuntimeString(input,"author"),message:readRuntimeString(input,"message"),lockTtlSeconds:parseRuntimeInteger(input.lockTtlSeconds,"lockTtlSeconds"),lockWaitMs:parseRuntimeInteger(input.lockWaitMs,"lockWaitMs")});throw createUnknownSubcommandError({command_path:"workspace snapshot",token:snapshotAction,allowed:["create","list","inspect","restore","delete"],display_name:"workspace snapshot",token_kind:"action"})}function runRuntimeSchedulingAction(context){const input=mergedInput(context),title=requiredString(input,"title");return context.action==="meet"?runMeet(title,input,context.global):context.action==="event"?runEvent(title,input,context.global):runRemind(title,input,context.global)}export{runRuntimeEvalAction,runRuntimeEventsAction,runRuntimeMergeAction,runRuntimeSchedulingAction,runRuntimeWorkspaceAction};
 //# sourceMappingURL=runtime-extended-actions.js.map

package/dist/sdk/structured-mutations.d.ts

@@ -42,6 +42,8 @@ id:string;
 op:BulkItemMutation["op"];
 /** Whether keyed upsert turned a create row into an update of an existing item. */
 upserted?:true;
+/** Lifecycle warnings for this row when returned by a staged document preview. */
+warnings?:readonly string[];
 }
 /** Fully validated mutation document ready for preview or commit. */
 export interface ResolvedItemMutationDocument {

package/dist/sdk/structured-mutations.js

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="78df5b0f-51cd-5c24-a1ee-a1d8433be5df")}catch{}})();import crypto from"node:crypto";import{ITEM_MUTATION_FACET_OPTION_MAPPINGS}from"./lifecycle/mutation-facet-contracts.js";import{normalizeItemId,normalizePrefix}from"../core/item/id.js";import{preserveMutationStdinTokenLiterals}from"../core/item/parse.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{levenshteinDistanceWithinLimit}from"../core/shared/levenshtein.js";import{describeUnknownError}from"./error-runtime.js";import{CLOSE_FLAG_CONTRACTS,RELEASE_FLAG_CONTRACTS}from"./cli-contracts/flag-contracts.js";import{CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS,UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS}from"./cli-contracts/commander-mutation-options.js";import{runtimeFieldOptionTarget}from"../core/schema/runtime-schema.js";import{CORE_ITEM_FIELD_KEYS as ITEM_FIELD_KEYS,resolveCoreUpsertMetadataKey}from"./lifecycle/core-item-fields.js";import{readRuntimeFieldOptionValue}from"../core/schema/runtime-field-values.js";import{assertMutationOptionValueTypes}from"./lifecycle/mutation-option-validation.js";const MUTATION_ROW_KEYS=["op","id","reason","options","unique","match"],REFERENCED_MUTATION_ROW_KEYS=[...MUTATION_ROW_KEYS,"ref"],DOCUMENT_MUTATION_ROW_KEYS=[...REFERENCED_MUTATION_ROW_KEYS,"item"],DERIVED_TRANSACTION_ID_PREFIX="mutate-",SYNTHESIZED_REFERENCE_PREFIX="row-",MUTATION_DOCUMENT_KEYS=["schema_version","mutations"],MUTATION_REFERENCE_SOURCE="[a-z][a-z0-9._-]{0,63}",MUTATION_REFERENCE_PATTERN=new RegExp(`^${MUTATION_REFERENCE_SOURCE}$`,"u"),MUTATION_DEPENDENCY_REFERENCE_PATTERN=new RegExp(`(^|,)id=@(${MUTATION_REFERENCE_SOURCE})(?=,|$)`,"gu"),flagToOptionKey=flag=>flag.slice(2).replaceAll(/-([a-z])/gu,(_match,letter)=>letter.toUpperCase()),ITEM_ENVELOPE_KEYS=["item","linked","schedule","claim_state","children","omission_receipt","row_contract","context_intent"],READ_ONLY_ITEM_KEYS=new Set(["created_at","updated_at","closed_at","version","format_version","path","author","collection_counts","notes_count","tests_count"]),UPDATE_READ_ONLY_ITEM_KEYS=new Set([...READ_ONLY_ITEM_KEYS,"completed_at","id"]),MUTATION_OPTION_KEYS={create:CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map(contract=>contract.target),update:UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map(contract=>contract.target),close:CLOSE_FLAG_CONTRACTS.map(contract=>flagToOptionKey(contract.flag)).filter(key=>key!=="reason"),release:RELEASE_FLAG_CONTRACTS.map(contract=>flagToOptionKey(contract.flag))};function deriveMutationTransactionId(input){const digest=crypto.createHash("sha256").update(input).digest("hex");return`${DERIVED_TRANSACTION_ID_PREFIX}${digest.slice(0,24)}`}function parseAtomicMutationControls(value){const controls={},compensation=value.createCompensation;if(compensation!==void 0){if(compensation!=="close"&&compensation!=="delete")throw new PmCliError("createCompensation must be close or delete.",EXIT_CODE.USAGE);controls.createCompensation=compensation}for(const key of["lockTtlSeconds","lockWaitMs"]){const raw=value[key];if(raw===void 0)continue;const parsed=typeof raw=="number"||typeof raw=="string"&&raw.trim().length>0?Number(raw):Number.NaN;if(!Number.isSafeInteger(parsed)||parsed<=0)throw new PmCliError(`${key} must be a positive safe integer.`,EXIT_CODE.USAGE);controls[key]=parsed}return controls}function isPlainObject(value){if(typeof value!="object"||value===null||Array.isArray(value))return!1;const prototype=Object.getPrototypeOf(value);return prototype===Object.prototype||prototype===null}function nearestKey(key,candidates){const limit=Math.max(1,Math.min(3,Math.floor(key.length/4)+1));let best;for(const candidate of candidates){const distance=levenshteinDistanceWithinLimit(key,candidate,limit);distance!==null&&(best===void 0||distance<best.distance)&&(best={key:candidate,distance})}return best?.key}function unknownKeyError(scope,key,candidates){const suggestion=nearestKey(key,candidates);return new PmCliError(suggestion===void 0?`${scope} does not recognize key "${key}". Allowed keys: ${candidates.join(", ")}.`:`${scope} does not recognize key "${key}". Did you mean "${suggestion}"?`,EXIT_CODE.USAGE,{code:"stdin_json_unknown_key",required:`Use documented ${scope} keys only.`,why:"Strict structured input prevents silent typos from creating incomplete or unintended mutations.",nextSteps:[suggestion===void 0?`Remove or correct "${key}".`:`Replace "${key}" with "${suggestion}".`]})}function parseJsonValue(input,label){try{return JSON.parse(input)}catch(error){const detail=error instanceof Error?error.message:String(error);throw new PmCliError(`${label} must be valid JSON: ${detail}`,EXIT_CODE.USAGE,{code:"stdin_json_invalid",required:`Pipe one valid JSON ${label.toLowerCase()} into stdin.`,why:"Structured mutation input must parse deterministically before any tracker write begins."})}}function validateMutationObject(value,index){if(!isPlainObject(value))throw new PmCliError(`Mutation ${index+1} must be an object.`,EXIT_CODE.USAGE);for(const key of Object.keys(value))if(!MUTATION_ROW_KEYS.includes(key))throw unknownKeyError(`mutation ${index+1}`,key,MUTATION_ROW_KEYS);return value}function validateMutationOptions(options,op,index,runtimeFields){if(options===void 0)return;if(!isPlainObject(options))throw new PmCliError(`Mutation ${index+1} options must be an object.`,EXIT_CODE.USAGE);const allowed=[...MUTATION_OPTION_KEYS[op],...runtimeFieldOptionKeys(op,runtimeFields)];for(const key of Object.keys(options))if(!allowed.includes(key))throw unknownKeyError(`mutation ${index+1} ${op} options`,key,allowed);return assertMutationOptionValueTypes(options,op,index),options}function validateMutationKeyGuard(value,op,index,field){if(value===void 0)return;const allowedOp=field==="unique"?"create":"update";if(op!==allowedOp)throw new PmCliError(`Mutation ${index+1} ${field} is only valid for ${allowedOp} operations.`,EXIT_CODE.USAGE);const key=isPlainObject(value)&&typeof value.key=="string"?value.key.trim():"";if(!isPlainObject(value)||key.length===0||value.value===void 0||value.value===null)throw new PmCliError(`Mutation ${index+1} ${field} must be an object with a non-empty key and a value.`,EXIT_CODE.USAGE);return{key,value:value.value}}function validateMutationRow(value,index,runtimeFields){const mutation=validateMutationObject(value,index),{op,id,reason}=mutation;if(op!=="create"&&op!=="update"&&op!=="close"&&op!=="release")throw new PmCliError(`Mutation ${index+1} op must be create, update, close, or release.`,EXIT_CODE.USAGE);const options=validateMutationOptions(mutation.options,op,index,runtimeFields),unique=validateMutationKeyGuard(mutation.unique,op,index,"unique"),match=validateMutationKeyGuard(mutation.match,op,index,"match");if(typeof id!="string"||id.trim().length===0)throw new PmCliError(`Mutation ${index+1} requires a non-empty id.`,EXIT_CODE.USAGE);const normalizedId=id.trim();if(op==="close"){if(typeof reason!="string"||reason.trim().length===0)throw new PmCliError(`Mutation ${index+1} close requires a non-empty reason.`,EXIT_CODE.USAGE);return{op,id:normalizedId,reason:reason.trim(),...options===void 0?{}:{options}}}if(op==="release")return{op,id:normalizedId,...options===void 0?{}:{options}};if(!isPlainObject(options))throw new PmCliError(`Mutation ${index+1} ${op} requires an options object.`,EXIT_CODE.USAGE);return{op,id:normalizedId,options,...unique===void 0?{}:{unique},...match===void 0?{}:{match}}}function parseItemMutationBatch(input,parseOptions={}){const parsed=parseJsonValue(input,"Mutation batch"),rows=Array.isArray(parsed)?parsed:isPlainObject(parsed)&&Array.isArray(parsed.mutations)?parsed.mutations:void 0;if(rows===void 0||rows.length===0)throw new PmCliError("Mutation batch must be a non-empty JSON array or an object with a non-empty mutations array.",EXIT_CODE.USAGE);const runtimeFields=parseOptions.runtimeFields??[];return rows.map((row,index)=>{const mutation=validateMutationRow(row,index,runtimeFields);return mutation.options!==void 0&&preserveMutationStdinTokenLiterals(mutation.options),mutation})}function deriveReferencedItemId(transactionId,reference,idPrefix){const digest=crypto.createHash("sha256").update(transactionId).update("\0").update(reference).digest("hex"),token=BigInt(`0x${digest.slice(0,16)}`).toString(36).padStart(13,"0").slice(-12);return`${normalizePrefix(idPrefix)}${token}`}function replaceExactMutationReference(value,references){if(typeof value!="string"||!value.startsWith("@"))return value;const reference=value.slice(1),resolved=references[reference];if(resolved===void 0)throw new PmCliError(`Unknown mutation reference "${value}".`,EXIT_CODE.USAGE);return resolved}function replaceDependencyReference(value,references){if(typeof value!="string")return value;const resolvedValue=value.replace(MUTATION_DEPENDENCY_REFERENCE_PATTERN,(_match,prefix,reference)=>{const resolved=references[reference];if(resolved===void 0)throw new PmCliError(`Unknown mutation reference "@${reference}".`,EXIT_CODE.USAGE);return`${prefix}id=${resolved}`});if(/(^|,)id=@/u.test(resolvedValue))throw new PmCliError(`Malformed mutation reference in dependency "${value}".`,EXIT_CODE.USAGE);return resolvedValue}function referencedAliases(value){return typeof value!="string"?[]:value.startsWith("@")?[value.slice(1)]:[...value.matchAll(MUTATION_DEPENDENCY_REFERENCE_PATTERN)].map(match=>match[1]).filter(reference=>reference!==void 0)}function assertAcyclicCreateReferences(rows,inputReferences){const graph=new Map;for(const[index,row]of rows.entries()){const reference=inputReferences[index];if(reference===void 0)continue;const mutationOptions=isPlainObject(row.options)?row.options:{},dependencies=Array.isArray(mutationOptions.dep)?mutationOptions.dep:mutationOptions.dep===void 0?[]:[mutationOptions.dep];graph.set(reference,[mutationOptions.parent,mutationOptions.blockedBy,...dependencies].flatMap(referencedAliases))}const visiting=new Set,visited=new Set,visit=reference=>{if(visiting.has(reference))throw new PmCliError(`Mutation reference cycle includes "@${reference}".`,EXIT_CODE.USAGE);if(!visited.has(reference)){visiting.add(reference);for(const dependency of graph.get(reference))graph.has(dependency)&&visit(dependency);visiting.delete(reference),visited.add(reference)}};for(const reference of graph.keys())visit(reference)}function parseJsonLinesRows(input){const candidates=input.split(/\r?\n/u).map((line,index)=>({line:line.trim(),number:index+1})).filter(entry=>entry.line.length>0);if(candidates.length<2)return null;const parsed=candidates.map(entry=>{try{return{...entry,ok:!0,value:JSON.parse(entry.line)}}catch(error){return{...entry,ok:!1,error}}}),first=parsed[0];if(!first.ok&&(first.line.startsWith("[")||first.line==="{"||parsed.at(-1).line==="}")||!parsed.some(entry=>entry.ok&&isPlainObject(entry.value)))return null;const rows=[];for(const entry of parsed){if(!entry.ok)throw new PmCliError(`Mutation document line ${entry.number} must be one valid JSON object: ${describeUnknownError(entry.error)}`,EXIT_CODE.USAGE,{code:"stdin_json_invalid",required:"Provide one JSON object per line (JSON Lines), a JSON array, or a {schema_version, mutations} document.",why:"Structured mutation input must parse deterministically before any tracker write begins."});if(!isPlainObject(entry.value))throw new PmCliError(`Mutation document line ${entry.number} must be a JSON object.`,EXIT_CODE.USAGE);rows.push(entry.value)}return rows}function isMutationEnvelope(value){return Object.hasOwn(value,"mutations")||Object.hasOwn(value,"schema_version")}function parseMutationDocumentEnvelope(input){let parsed;try{parsed=parseJsonValue(input,"Mutation document")}catch(error){const rows=parseJsonLinesRows(input);if(rows===null)throw error;return{schema_version:1,mutations:rows}}return Array.isArray(parsed)?{schema_version:1,mutations:parsed}:isPlainObject(parsed)&&!isMutationEnvelope(parsed)?{schema_version:1,mutations:[parsed]}:parsed}function normalizeDocumentRow(row,index){const normalized=Object.hasOwn(row,"op")?validateOperationRow(row,index):normalizeCreateDocumentRow(row,index);if(normalized.op==="create"&&normalized.id===void 0&&isPlainObject(normalized.item)&&normalized.item.id!==void 0){if(typeof normalized.item.id!="string")throw new PmCliError(`Mutation ${index+1} item id must be a string.`,EXIT_CODE.USAGE);normalized.id=normalized.item.id}return normalized}function validateOperationRow(row,index){for(const key of Object.keys(row))if(!DOCUMENT_MUTATION_ROW_KEYS.includes(key))throw unknownKeyError(`mutation ${index+1}`,key,DOCUMENT_MUTATION_ROW_KEYS);if(row.item!==void 0&&row.op!=="create")throw new PmCliError(`Mutation ${index+1} item documents are only valid for create operations.`,EXIT_CODE.USAGE);if(row.item!==void 0&&row.options!==void 0)throw new PmCliError(`Mutation ${index+1} must declare either item or options, not both.`,EXIT_CODE.USAGE);return{...row}}function normalizeCreateDocumentRow(row,index){const{ref,id,item,...fields}=row,document=item!==void 0?item:fields;if(item!==void 0&&Object.keys(fields).length>0)throw new PmCliError(`Mutation ${index+1} must not mix item document keys with top-level fields.`,EXIT_CODE.USAGE);if(!isPlainObject(document))throw new PmCliError(`Mutation ${index+1} item document must be an object.`,EXIT_CODE.USAGE);return{op:"create",...ref===void 0?{}:{ref},...id===void 0?{}:{id},item:document}}function parseMutationDocumentRows(input){const envelope=parseMutationDocumentEnvelope(input);if(!isPlainObject(envelope))throw new PmCliError("Mutation document must be a JSON array or object.",EXIT_CODE.USAGE);for(const key of Object.keys(envelope))if(!MUTATION_DOCUMENT_KEYS.includes(key))throw unknownKeyError("mutation document",key,MUTATION_DOCUMENT_KEYS);if(envelope.schema_version!==void 0&&envelope.schema_version!==1)throw new PmCliError("Mutation document schema_version must be 1.",EXIT_CODE.USAGE);if(!Array.isArray(envelope.mutations)||envelope.mutations.length===0)throw new PmCliError("Mutation document requires a non-empty mutations array.",EXIT_CODE.USAGE);return envelope.mutations.map((row,index)=>{if(!isPlainObject(row))throw new PmCliError(`Mutation ${index+1} must be an object.`,EXIT_CODE.USAGE);return normalizeDocumentRow(row,index)})}function excludeOwnCreateIds(upsert,rows,options){const ownIds=new Set(Object.values(collectMutationReferences(rows,options,Object.create(null))));for(const row of rows)row.op==="create"&&typeof row.id=="string"&&row.id.trim().length>0&&ownIds.add(normalizeItemId(row.id,options.idPrefix));return{...upsert,existing:upsert.existing.filter(candidate=>!ownIds.has(candidate.id))}}function synthesizeMissingReferences(rows){const declared=new Set(rows.map(row=>row.ref).filter(ref=>typeof ref=="string"));for(const[index,row]of rows.entries()){if(row.op!=="create"||row.ref!==void 0||typeof row.id=="string"&&row.id.trim().length>0)continue;const synthesized=`${SYNTHESIZED_REFERENCE_PREFIX}${index+1}`;if(declared.has(synthesized))throw new PmCliError(`Mutation ${index+1} receives the synthesized ref "${synthesized}", but another row declares that ref. Rename it or give mutation ${index+1} its own ref; ${SYNTHESIZED_REFERENCE_PREFIX}<n> aliases are reserved for rows without one.`,EXIT_CODE.USAGE);row.ref=synthesized}}function itemDocumentToBatchOptions(item,mode,runtimeFields){const converted=itemDocumentToMutationOptions(JSON.stringify(item),mode,{},runtimeFields);return delete converted.stdinJson,delete converted.documentAnnotationSnapshot,converted}function runtimeFieldOptionKeys(op,runtimeFields){return op!=="create"&&op!=="update"?[]:runtimeFields.filter(definition=>definition.commands.includes(op)).map(definition=>runtimeFieldOptionTarget(definition))}function convertItemDocumentRows(rows,runtimeFields){for(const row of rows)isPlainObject(row.item)&&(row.options=itemDocumentToBatchOptions(row.item,"create",runtimeFields),delete row.item)}function itemDocumentMetadataKey(key,runtimeFields){return runtimeFields.some(field=>field.metadata_key===key)?key:resolveCoreUpsertMetadataKey(key)}function readUpsertKeyValue(row,key,runtimeFields){const camel=key.replaceAll(/_([a-z])/gu,(_match,letter)=>letter.toUpperCase());if(isPlainObject(row.item)){if(row.item[key]!==void 0)return row.item[key];if(itemDocumentMetadataKey(camel,runtimeFields)===key&&row.item[camel]!==void 0)return row.item[camel]}const options=isPlainObject(row.options)?row.options:{},declared=runtimeFields.find(field=>field.metadata_key===key);return declared!==void 0&&options[runtimeFieldOptionTarget(declared)]!==void 0?options[runtimeFieldOptionTarget(declared)]:options[key]!==void 0?options[key]:options[camel]!==void 0?options[camel]:(Array.isArray(options.field)?options.field:[]).map(String).find(entry=>entry.startsWith(`${key}=`))?.slice(key.length+1)}function compareCodeUnits(left,right){return left<right?-1:+(left!==right)}function canonicalizeUpsertValue(value){return Array.isArray(value)?value.map(canonicalizeUpsertValue):isPlainObject(value)?Object.fromEntries(Object.entries(value).sort(([left],[right])=>compareCodeUnits(left,right)).map(([key,nested])=>[key,canonicalizeUpsertValue(nested)])):value}function stableUpsertValue(value){return typeof value=="string"?value.trim():JSON.stringify(canonicalizeUpsertValue(value))}function applyKeyedUpsert(rows,upsert,idPrefix,runtimeFields,references){const key=upsert.key.trim();if(key.length===0)throw new PmCliError("Upsert key must be a non-empty field name.",EXIT_CODE.USAGE);const existingByValue=indexUpsertCandidates(upsert.existing),seen=new Map,upserted=new Set;for(const[index,row]of rows.entries()){if(row.op!=="create")continue;const stable=readStableUpsertKey(row,key,index,seen,runtimeFields),match=resolveUpsertMatch(existingByValue.get(stable)??[],key,stable);if(match===void 0){row.unique={key,value:readUpsertKeyValue(row,key,runtimeFields)};continue}const id=normalizeItemId(match,idPrefix);typeof row.ref=="string"&&(references[row.ref]=id),convertRowToUpsertUpdate(row,id,runtimeFields,{key,value:readUpsertKeyValue(row,key,runtimeFields)}),upserted.add(index)}return upserted}function indexUpsertCandidates(existing){const existingByValue=new Map;for(const candidate of existing){if(candidate.value===void 0||candidate.value===null)continue;const stable=stableUpsertValue(candidate.value);existingByValue.set(stable,[...existingByValue.get(stable)??[],candidate.id])}return existingByValue}function readStableUpsertKey(row,key,index,seen,runtimeFields){const value=readUpsertKeyValue(row,key,runtimeFields);if(value==null||value==="")throw new PmCliError(`Mutation ${index+1} is missing the upsert key "${key}".`,EXIT_CODE.USAGE,{code:"upsert_key_missing",required:`Every create record must carry a non-empty "${key}" value when --upsert-key ${key} is set.`,why:"Keyed upsert identifies existing items by that field; a record without it cannot be matched or safely created."});const stable=stableUpsertValue(value),previous=seen.get(stable);if(previous!==void 0)throw new PmCliError(`Mutations ${previous+1} and ${index+1} share the upsert key value ${JSON.stringify(stable)} for "${key}".`,EXIT_CODE.USAGE,{code:"upsert_key_duplicate",required:"Each record must carry a distinct upsert key value within one batch.",why:"Two records with the same key would race for the same existing item."});return seen.set(stable,index),stable}function resolveUpsertMatch(matches,key,stable){if(matches.length>1)throw new PmCliError(`Upsert key "${key}" value ${JSON.stringify(stable)} matches ${matches.length} existing items: ${matches.join(", ")}.`,EXIT_CODE.CONFLICT,{code:"upsert_key_ambiguous",required:"Resolve the duplicate existing items or choose a key that is unique per item.",why:"An ambiguous key cannot select one item to update without guessing."});return matches[0]}function convertRowToUpsertUpdate(row,id,runtimeFields,match){const updateKeys=new Set([...MUTATION_OPTION_KEYS.update,...runtimeFieldOptionKeys("update",runtimeFields)]),options=isPlainObject(row.item)?itemDocumentToBatchOptions(row.item,"update",runtimeFields):Object.fromEntries(Object.entries(row.options).filter(([optionKey])=>updateKeys.has(optionKey)));delete row.item,delete row.ref,row.op="update",row.id=id,row.options=options,row.match=match}function collectMutationReferences(rows,options,references){for(const[index,row]of rows.entries())if(row.ref!==void 0){if(row.op!=="create")throw new PmCliError(`Mutation ${index+1} ref is only valid for create operations.`,EXIT_CODE.USAGE);if(typeof row.ref!="string"||!MUTATION_REFERENCE_PATTERN.test(row.ref))throw new PmCliError(`Mutation ${index+1} ref must match ${MUTATION_REFERENCE_PATTERN.source}.`,EXIT_CODE.USAGE);if(references[row.ref]!==void 0)throw new PmCliError(`Duplicate mutation ref "${row.ref}".`,EXIT_CODE.USAGE);references[row.ref]=typeof row.id=="string"&&row.id.trim().length>0?normalizeItemId(row.id,options.idPrefix):deriveReferencedItemId(options.transactionId,row.ref,options.idPrefix)}return references}function resolveItemMutationDocument(input,options){const rows=parseMutationDocumentRows(input);synthesizeMissingReferences(rows);const inputReferences=rows.map(row=>typeof row.ref=="string"?row.ref:void 0),references=Object.create(null),upserted=options.upsert===void 0?new Set:applyKeyedUpsert(rows,excludeOwnCreateIds(options.upsert,rows,options),options.idPrefix,options.runtimeFields??[],references);convertItemDocumentRows(rows,options.runtimeFields??[]),collectMutationReferences(rows,options,references),assertAcyclicCreateReferences(rows,inputReferences);const resolvedRows=rows.map(row=>{const resolved={...row},reference=typeof resolved.ref=="string"?resolved.ref:void 0;if(delete resolved.ref,reference!==void 0?resolved.id=references[reference]:resolved.id=replaceExactMutationReference(resolved.id,references),isPlainObject(resolved.options)){const mutationOptions={...resolved.options};for(const key of["parent","blockedBy"])mutationOptions[key]!==void 0&&(mutationOptions[key]=replaceExactMutationReference(mutationOptions[key],references));Array.isArray(mutationOptions.dep)?mutationOptions.dep=mutationOptions.dep.map(entry=>replaceDependencyReference(entry,references)):mutationOptions.dep!==void 0&&(mutationOptions.dep=replaceDependencyReference(mutationOptions.dep,references)),resolved.options=mutationOptions}return resolved}),mutations=parseItemMutationBatch(JSON.stringify(resolvedRows),{runtimeFields:options.runtimeFields??[]}),createIds=mutations.filter(mutation=>mutation.op==="create").map(mutation=>mutation.id);if(new Set(createIds).size!==createIds.length)throw new PmCliError("Duplicate resolved create id in mutation document.",EXIT_CODE.USAGE);const receiptRows=mutations.map((mutation,index)=>{const reference=inputReferences[index];return{index,...typeof reference=="string"?{ref:reference}:{},id:mutation.id,op:mutation.op,...upserted.has(index)?{upserted:!0}:{}}});return{schema_version:1,mutations,references,rows:receiptRows}}function serializePairs(value,keys){return keys.filter(key=>value[key]!==void 0&&value[key]!==null).map(key=>{const rendered=String(value[key]);return`${key}=${/[",\n\r\\]/u.test(rendered)?JSON.stringify(rendered):rendered}`}).join(",")}function serializeObjectArray(value,keys,label){if(value!==void 0){if(!Array.isArray(value)||!value.every(isPlainObject))throw new PmCliError(`${label} must be an array of objects.`,EXIT_CODE.USAGE);return value.map(entry=>serializePairs(entry,keys))}}function scalarItemOption(key,value){return key==="tags"&&Array.isArray(value)&&value.every(entry=>typeof entry=="string")?JSON.stringify(value):typeof value=="number"||typeof value=="boolean"?String(value):value}function appendFacetOptions(target,source,skipPersistedAnnotations=!1){for(const[sourceKey,targetKey,keys]of ITEM_MUTATION_FACET_OPTION_MAPPINGS){const sourceValue=source[sourceKey],serialized=serializeObjectArray(skipPersistedAnnotations&&["comments","notes","learnings"].includes(sourceKey)&&Array.isArray(sourceValue)?sourceValue.filter(entry=>!isPlainObject(entry)||entry.created_at===void 0):sourceValue,keys,sourceKey);serialized!==void 0&&serialized.length>0&&(target[targetKey]=serialized)}}function validateItemDocumentKeys(parsed,envelope){for(const key of Object.keys(parsed)){if(envelope){if(!ITEM_ENVELOPE_KEYS.includes(key))throw unknownKeyError("item envelope",key,ITEM_ENVELOPE_KEYS);continue}if(!ITEM_FIELD_KEYS.has(key)&&nearestKey(key,[...ITEM_FIELD_KEYS])===void 0&&nearestKey(key,ITEM_ENVELOPE_KEYS)==="item")throw unknownKeyError("item envelope",key,ITEM_ENVELOPE_KEYS)}}function resolveItemDocument(parsed){const envelope=Object.hasOwn(parsed,"item");validateItemDocumentKeys(parsed,envelope);const item=envelope?parsed.item:parsed;if(!isPlainObject(item))throw new PmCliError("Item document item must be an object.",EXIT_CODE.USAGE);return{item,...envelope&&isPlainObject(parsed.linked)?{linked:parsed.linked}:{}}}function appendItemDocumentEntry(documentOptions,key,value,mode,runtimeFields,explicitOptions){if((mode==="update"?UPDATE_READ_ONLY_ITEM_KEYS:READ_ONLY_ITEM_KEYS).has(key))return;const definition=runtimeFields.find(field=>field.metadata_key===key&&field.commands.includes(mode));if(definition!==void 0){const explicitValue=readRuntimeFieldOptionValue(explicitOptions,definition);documentOptions[runtimeFieldOptionTarget(definition)]=explicitValue!==void 0?explicitValue:definition.type==="array"||definition.type==="object"?JSON.stringify(value):value;return}if(!ITEM_FIELD_KEYS.has(key)){if(nearestKey(key,[...ITEM_FIELD_KEYS])!==void 0)throw unknownKeyError("item document",key,[...ITEM_FIELD_KEYS]);const fields=Array.isArray(documentOptions.field)?documentOptions.field:[];fields.push(`${key}=${typeof value=="string"?value:JSON.stringify(value)}`),documentOptions.field=fields;return}["dependencies","comments","notes","learnings","files","tests","docs","reminders","events","type_options"].includes(key)||(documentOptions[key.replaceAll(/_([a-z])/gu,(_match,letter)=>letter.toUpperCase())]=scalarItemOption(key,value))}function itemDocumentToMutationOptions(input,mode,explicitOptions={},runtimeFields=[]){const parsed=parseJsonValue(input,"Item document");if(!isPlainObject(parsed))throw new PmCliError("Item document must be a JSON object.",EXIT_CODE.USAGE);const{item,linked}=resolveItemDocument(parsed),documentOptions={};for(const[key,value]of Object.entries(item)){const metadataKey=itemDocumentMetadataKey(key,runtimeFields);metadataKey!==key&&Object.hasOwn(item,metadataKey)||appendItemDocumentEntry(documentOptions,metadataKey,value,mode,runtimeFields,explicitOptions)}if(appendFacetOptions(documentOptions,item,mode==="update"),linked!==void 0&&appendFacetOptions(documentOptions,linked),mode==="update"){const annotations=Object.fromEntries(["comments","notes","learnings"].filter(key=>Object.hasOwn(item,key)).map(key=>[key,item[key].filter(entry=>isPlainObject(entry)&&entry.created_at!==void 0)]));Object.keys(annotations).length>0&&(documentOptions.documentAnnotationSnapshot=annotations)}return{...documentOptions,...Object.fromEntries(Object.entries(explicitOptions).filter(([,value])=>value!==void 0)),...Array.isArray(documentOptions.field)&&Array.isArray(explicitOptions.field)?{field:[...documentOptions.field,...explicitOptions.field]}:{},stdinJson:void 0}}function validateItemMutationRows(value){return parseItemMutationBatch(JSON.stringify(value))}export{deriveMutationTransactionId,itemDocumentToMutationOptions,parseAtomicMutationControls,parseItemMutationBatch,resolveItemMutationDocument,stableUpsertValue,validateItemMutationRows};
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7b430d12-7a5b-52c2-9a6b-e4c33a39da76")}catch{}})();import crypto from"node:crypto";import{ITEM_MUTATION_FACET_OPTION_MAPPINGS}from"./lifecycle/mutation-facet-contracts.js";import{normalizeItemId,normalizePrefix}from"../core/item/id.js";import{preserveMutationStdinTokenLiterals}from"../core/item/parse.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{levenshteinDistanceWithinLimit}from"../core/shared/levenshtein.js";import{describeUnknownError}from"./error-runtime.js";import{CLOSE_FLAG_CONTRACTS,RELEASE_FLAG_CONTRACTS}from"./cli-contracts/flag-contracts.js";import{CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS,UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS}from"./cli-contracts/commander-mutation-options.js";import{runtimeFieldOptionTarget}from"../core/schema/runtime-schema.js";import{CORE_ITEM_FIELD_KEYS as ITEM_FIELD_KEYS,resolveCoreUpsertMetadataKey}from"./lifecycle/core-item-fields.js";import{readRuntimeFieldOptionValue}from"../core/schema/runtime-field-values.js";import{assertMutationOptionValueTypes}from"./lifecycle/mutation-option-validation.js";const MUTATION_ROW_KEYS=["op","id","reason","options","unique","match"],REFERENCED_MUTATION_ROW_KEYS=[...MUTATION_ROW_KEYS,"ref"],DOCUMENT_MUTATION_ROW_KEYS=[...REFERENCED_MUTATION_ROW_KEYS,"item"],DERIVED_TRANSACTION_ID_PREFIX="mutate-",SYNTHESIZED_REFERENCE_PREFIX="row-",MUTATION_DOCUMENT_KEYS=["schema_version","mutations"],MUTATION_REFERENCE_SOURCE="[a-z][a-z0-9._-]{0,63}",MUTATION_REFERENCE_PATTERN=new RegExp(`^${MUTATION_REFERENCE_SOURCE}$`,"u"),MUTATION_DEPENDENCY_REFERENCE_PATTERN=new RegExp(`(^|,)id=@(${MUTATION_REFERENCE_SOURCE})(?=,|$)`,"gu"),flagToOptionKey=flag=>flag.slice(2).replaceAll(/-([a-z])/gu,(_match,letter)=>letter.toUpperCase()),ITEM_ENVELOPE_KEYS=["item","linked","schedule","claim_state","children","omission_receipt","row_contract","context_intent"],READ_ONLY_ITEM_KEYS=new Set(["created_at","updated_at","closed_at","version","format_version","path","author","collection_counts","notes_count","tests_count"]),UPDATE_READ_ONLY_ITEM_KEYS=new Set([...READ_ONLY_ITEM_KEYS,"completed_at","id"]),MUTATION_OPTION_KEYS={create:CREATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map(contract=>contract.target),update:UPDATE_COMMANDER_OPTION_REGISTRATION_CONTRACTS.map(contract=>contract.target),close:CLOSE_FLAG_CONTRACTS.map(contract=>flagToOptionKey(contract.flag)).filter(key=>key!=="reason"),release:RELEASE_FLAG_CONTRACTS.map(contract=>flagToOptionKey(contract.flag))};function deriveMutationTransactionId(input){const digest=crypto.createHash("sha256").update(input).digest("hex");return`${DERIVED_TRANSACTION_ID_PREFIX}${digest.slice(0,24)}`}function parseAtomicMutationControls(value){const controls={},compensation=value.createCompensation;if(compensation!==void 0){if(compensation!=="close"&&compensation!=="delete")throw new PmCliError("createCompensation must be close or delete.",EXIT_CODE.USAGE);controls.createCompensation=compensation}for(const key of["lockTtlSeconds","lockWaitMs"]){const raw=value[key];if(raw===void 0)continue;const parsed=typeof raw=="number"||typeof raw=="string"&&raw.trim().length>0?Number(raw):Number.NaN;if(!Number.isSafeInteger(parsed)||parsed<=0)throw new PmCliError(`${key} must be a positive safe integer.`,EXIT_CODE.USAGE);controls[key]=parsed}return controls}function isPlainObject(value){if(typeof value!="object"||value===null||Array.isArray(value))return!1;const prototype=Object.getPrototypeOf(value);return prototype===Object.prototype||prototype===null}function nearestKey(key,candidates){const limit=Math.max(1,Math.min(3,Math.floor(key.length/4)+1));let best;for(const candidate of candidates){const distance=levenshteinDistanceWithinLimit(key,candidate,limit);distance!==null&&(best===void 0||distance<best.distance)&&(best={key:candidate,distance})}return best?.key}function unknownKeyError(scope,key,candidates){const suggestion=nearestKey(key,candidates);return new PmCliError(suggestion===void 0?`${scope} does not recognize key "${key}". Allowed keys: ${candidates.join(", ")}.`:`${scope} does not recognize key "${key}". Did you mean "${suggestion}"?`,EXIT_CODE.USAGE,{code:"stdin_json_unknown_key",required:`Use documented ${scope} keys only.`,why:"Strict structured input prevents silent typos from creating incomplete or unintended mutations.",nextSteps:[suggestion===void 0?`Remove or correct "${key}".`:`Replace "${key}" with "${suggestion}".`]})}function parseJsonValue(input,label){try{return JSON.parse(input)}catch(error){const detail=error instanceof Error?error.message:String(error);throw new PmCliError(`${label} must be valid JSON: ${detail}`,EXIT_CODE.USAGE,{code:"stdin_json_invalid",required:`Pipe one valid JSON ${label.toLowerCase()} into stdin.`,why:"Structured mutation input must parse deterministically before any tracker write begins."})}}function validateMutationObject(value,index){if(!isPlainObject(value))throw new PmCliError(`Mutation ${index+1} must be an object.`,EXIT_CODE.USAGE);for(const key of Object.keys(value))if(!MUTATION_ROW_KEYS.includes(key))throw unknownKeyError(`mutation ${index+1}`,key,MUTATION_ROW_KEYS);return value}function validateMutationOptions(options,op,index,runtimeFields){if(options===void 0)return;if(!isPlainObject(options))throw new PmCliError(`Mutation ${index+1} options must be an object.`,EXIT_CODE.USAGE);const allowed=[...MUTATION_OPTION_KEYS[op],...runtimeFieldOptionKeys(op,runtimeFields)];for(const key of Object.keys(options))if(!allowed.includes(key))throw unknownKeyError(`mutation ${index+1} ${op} options`,key,allowed);return assertMutationOptionValueTypes(options,op,index),options}function validateMutationKeyGuard(value,op,index,field){if(value===void 0)return;const allowedOp=field==="unique"?"create":"update";if(op!==allowedOp)throw new PmCliError(`Mutation ${index+1} ${field} is only valid for ${allowedOp} operations.`,EXIT_CODE.USAGE);const key=isPlainObject(value)&&typeof value.key=="string"?value.key.trim():"";if(!isPlainObject(value)||key.length===0||value.value===void 0||value.value===null)throw new PmCliError(`Mutation ${index+1} ${field} must be an object with a non-empty key and a value.`,EXIT_CODE.USAGE);return{key,value:value.value}}function validateMutationRow(value,index,runtimeFields){const mutation=validateMutationObject(value,index),{op,id,reason}=mutation;if(op!=="create"&&op!=="update"&&op!=="close"&&op!=="release")throw new PmCliError(`Mutation ${index+1} op must be create, update, close, or release.`,EXIT_CODE.USAGE);const options=validateMutationOptions(mutation.options,op,index,runtimeFields),unique=validateMutationKeyGuard(mutation.unique,op,index,"unique"),match=validateMutationKeyGuard(mutation.match,op,index,"match");if(typeof id!="string"||id.trim().length===0)throw new PmCliError(`Mutation ${index+1} requires a non-empty id.`,EXIT_CODE.USAGE);const normalizedId=id.trim();if(op==="close"){if(typeof reason!="string"||reason.trim().length===0)throw new PmCliError(`Mutation ${index+1} close requires a non-empty reason.`,EXIT_CODE.USAGE);return{op,id:normalizedId,reason:reason.trim(),...options===void 0?{}:{options}}}if(op==="release")return{op,id:normalizedId,...options===void 0?{}:{options}};if(!isPlainObject(options))throw new PmCliError(`Mutation ${index+1} ${op} requires an options object.`,EXIT_CODE.USAGE);return{op,id:normalizedId,options,...unique===void 0?{}:{unique},...match===void 0?{}:{match}}}function parseItemMutationBatch(input,parseOptions={}){const parsed=parseJsonValue(input,"Mutation batch"),rows=Array.isArray(parsed)?parsed:isPlainObject(parsed)&&Array.isArray(parsed.mutations)?parsed.mutations:void 0;if(rows===void 0||rows.length===0)throw new PmCliError("Mutation batch must be a non-empty JSON array or an object with a non-empty mutations array.",EXIT_CODE.USAGE);const runtimeFields=parseOptions.runtimeFields??[];return rows.map((row,index)=>{const mutation=validateMutationRow(row,index,runtimeFields);return mutation.options!==void 0&&preserveMutationStdinTokenLiterals(mutation.options),mutation})}function deriveReferencedItemId(transactionId,reference,idPrefix){const digest=crypto.createHash("sha256").update(transactionId).update("\0").update(reference).digest("hex"),token=BigInt(`0x${digest.slice(0,16)}`).toString(36).padStart(13,"0").slice(-12);return`${normalizePrefix(idPrefix)}${token}`}function replaceExactMutationReference(value,references){if(typeof value!="string"||!value.startsWith("@"))return value;const reference=value.slice(1),resolved=references[reference];if(resolved===void 0)throw new PmCliError(`Unknown mutation reference "${value}".`,EXIT_CODE.USAGE);return resolved}function replaceDependencyReference(value,references){if(typeof value!="string")return value;const resolvedValue=value.replace(MUTATION_DEPENDENCY_REFERENCE_PATTERN,(_match,prefix,reference)=>{const resolved=references[reference];if(resolved===void 0)throw new PmCliError(`Unknown mutation reference "@${reference}".`,EXIT_CODE.USAGE);return`${prefix}id=${resolved}`});if(/(^|,)id=@/u.test(resolvedValue))throw new PmCliError(`Malformed mutation reference in dependency "${value}".`,EXIT_CODE.USAGE);return resolvedValue}function referencedAliases(value){return typeof value!="string"?[]:value.startsWith("@")?[value.slice(1)]:[...value.matchAll(MUTATION_DEPENDENCY_REFERENCE_PATTERN)].map(match=>match[1]).filter(reference=>reference!==void 0)}function assertAcyclicCreateReferences(rows,inputReferences){const graph=new Map;for(const[index,row]of rows.entries()){const reference=inputReferences[index];if(reference===void 0)continue;const mutationOptions=isPlainObject(row.options)?row.options:{},dependencies=Array.isArray(mutationOptions.dep)?mutationOptions.dep:mutationOptions.dep===void 0?[]:[mutationOptions.dep];graph.set(reference,[mutationOptions.parent,mutationOptions.blockedBy,...dependencies].flatMap(referencedAliases))}const visiting=new Set,visited=new Set,visit=reference=>{if(visiting.has(reference))throw new PmCliError(`Mutation reference cycle includes "@${reference}".`,EXIT_CODE.USAGE);if(!visited.has(reference)){visiting.add(reference);for(const dependency of graph.get(reference))graph.has(dependency)&&visit(dependency);visiting.delete(reference),visited.add(reference)}};for(const reference of graph.keys())visit(reference)}function parseJsonLinesRows(input){const candidates=input.split(/\r?\n/u).map((line,index)=>({line:line.trim(),number:index+1})).filter(entry=>entry.line.length>0);if(candidates.length<2)return null;const parsed=candidates.map(entry=>{try{return{...entry,ok:!0,value:JSON.parse(entry.line)}}catch(error){return{...entry,ok:!1,error}}}),first=parsed[0];if(!first.ok&&(first.line.startsWith("[")||first.line==="{"||parsed.at(-1).line==="}")||!parsed.some(entry=>entry.ok&&isPlainObject(entry.value)))return null;const rows=[];for(const entry of parsed){if(!entry.ok)throw new PmCliError(`Mutation document line ${entry.number} must be one valid JSON object: ${describeUnknownError(entry.error)}`,EXIT_CODE.USAGE,{code:"stdin_json_invalid",required:"Provide one JSON object per line (JSON Lines), a JSON array, or a {schema_version, mutations} document.",why:"Structured mutation input must parse deterministically before any tracker write begins."});if(!isPlainObject(entry.value))throw new PmCliError(`Mutation document line ${entry.number} must be a JSON object.`,EXIT_CODE.USAGE);rows.push(entry.value)}return rows}function isMutationEnvelope(value){return Object.hasOwn(value,"mutations")||Object.hasOwn(value,"schema_version")}function parseMutationDocumentEnvelope(input){let parsed;try{parsed=parseJsonValue(input,"Mutation document")}catch(error){const rows=parseJsonLinesRows(input);if(rows===null)throw error;return{schema_version:1,mutations:rows}}return Array.isArray(parsed)?{schema_version:1,mutations:parsed}:isPlainObject(parsed)&&!isMutationEnvelope(parsed)?{schema_version:1,mutations:[parsed]}:parsed}function normalizeDocumentRow(row,index){const normalized=Object.hasOwn(row,"op")?validateOperationRow(row,index):normalizeCreateDocumentRow(row,index);if(normalized.op==="create"&&normalized.id===void 0&&isPlainObject(normalized.item)&&normalized.item.id!==void 0){if(typeof normalized.item.id!="string")throw new PmCliError(`Mutation ${index+1} item id must be a string.`,EXIT_CODE.USAGE);normalized.id=normalized.item.id}return normalized}function validateOperationRow(row,index){for(const key of Object.keys(row))if(!DOCUMENT_MUTATION_ROW_KEYS.includes(key))throw unknownKeyError(`mutation ${index+1}`,key,DOCUMENT_MUTATION_ROW_KEYS);if(row.item!==void 0&&row.op!=="create")throw new PmCliError(`Mutation ${index+1} item documents are only valid for create operations.`,EXIT_CODE.USAGE);if(row.item!==void 0&&row.options!==void 0)throw new PmCliError(`Mutation ${index+1} must declare either item or options, not both.`,EXIT_CODE.USAGE);return{...row}}function normalizeCreateDocumentRow(row,index){const{ref,id,item,...fields}=row,document=item!==void 0?item:fields;if(item!==void 0&&Object.keys(fields).length>0)throw new PmCliError(`Mutation ${index+1} must not mix item document keys with top-level fields.`,EXIT_CODE.USAGE);if(!isPlainObject(document))throw new PmCliError(`Mutation ${index+1} item document must be an object.`,EXIT_CODE.USAGE);return{op:"create",...ref===void 0?{}:{ref},...id===void 0?{}:{id},item:document}}function parseMutationDocumentRows(input){const envelope=parseMutationDocumentEnvelope(input);if(!isPlainObject(envelope))throw new PmCliError("Mutation document must be a JSON array or object.",EXIT_CODE.USAGE);for(const key of Object.keys(envelope))if(!MUTATION_DOCUMENT_KEYS.includes(key))throw unknownKeyError("mutation document",key,MUTATION_DOCUMENT_KEYS);if(envelope.schema_version!==void 0&&envelope.schema_version!==1)throw new PmCliError("Mutation document schema_version must be 1.",EXIT_CODE.USAGE);if(!Array.isArray(envelope.mutations)||envelope.mutations.length===0)throw new PmCliError("Mutation document requires a non-empty mutations array.",EXIT_CODE.USAGE);return envelope.mutations.map((row,index)=>{if(!isPlainObject(row))throw new PmCliError(`Mutation ${index+1} must be an object.`,EXIT_CODE.USAGE);return normalizeDocumentRow(row,index)})}function excludeOwnCreateIds(upsert,rows,options){const ownIds=new Set(Object.values(collectMutationReferences(rows,options,Object.create(null))));for(const row of rows)row.op==="create"&&typeof row.id=="string"&&row.id.trim().length>0&&ownIds.add(normalizeItemId(row.id,options.idPrefix));return{...upsert,existing:upsert.existing.filter(candidate=>!ownIds.has(candidate.id))}}function synthesizeMissingReferences(rows){const declared=new Set(rows.map(row=>row.ref).filter(ref=>typeof ref=="string"));for(const[index,row]of rows.entries()){if(row.op!=="create"||row.ref!==void 0||typeof row.id=="string"&&row.id.trim().length>0)continue;const synthesized=`${SYNTHESIZED_REFERENCE_PREFIX}${index+1}`;if(declared.has(synthesized))throw new PmCliError(`Mutation ${index+1} receives the synthesized ref "${synthesized}", but another row declares that ref. Rename it or give mutation ${index+1} its own ref; ${SYNTHESIZED_REFERENCE_PREFIX}<n> aliases are reserved for rows without one.`,EXIT_CODE.USAGE);row.ref=synthesized}}function itemDocumentToBatchOptions(item,mode,runtimeFields){const converted=itemDocumentToMutationOptions(JSON.stringify(item),mode,{},runtimeFields);return delete converted.stdinJson,delete converted.documentAnnotationSnapshot,converted}function runtimeFieldOptionKeys(op,runtimeFields){return op!=="create"&&op!=="update"?[]:runtimeFields.filter(definition=>definition.commands.includes(op)).map(definition=>runtimeFieldOptionTarget(definition))}function convertItemDocumentRows(rows,runtimeFields){for(const row of rows)isPlainObject(row.item)&&(row.options=itemDocumentToBatchOptions(row.item,"create",runtimeFields),delete row.item)}function itemDocumentMetadataKey(key,runtimeFields){return runtimeFields.some(field=>field.metadata_key===key)?key:resolveCoreUpsertMetadataKey(key)}function readUpsertKeyValue(row,key,runtimeFields){const camel=key.replaceAll(/_([a-z])/gu,(_match,letter)=>letter.toUpperCase());if(isPlainObject(row.item)){if(row.item[key]!==void 0)return row.item[key];if(itemDocumentMetadataKey(camel,runtimeFields)===key&&row.item[camel]!==void 0)return row.item[camel]}const options=isPlainObject(row.options)?row.options:{},declared=runtimeFields.find(field=>field.metadata_key===key);return declared!==void 0&&options[runtimeFieldOptionTarget(declared)]!==void 0?options[runtimeFieldOptionTarget(declared)]:options[key]!==void 0?options[key]:options[camel]!==void 0?options[camel]:(Array.isArray(options.field)?options.field:[]).map(String).find(entry=>entry.startsWith(`${key}=`))?.slice(key.length+1)}function compareCodeUnits(left,right){return left<right?-1:+(left!==right)}function canonicalizeUpsertValue(value){return Array.isArray(value)?value.map(canonicalizeUpsertValue):isPlainObject(value)?Object.fromEntries(Object.entries(value).sort(([left],[right])=>compareCodeUnits(left,right)).map(([key,nested])=>[key,canonicalizeUpsertValue(nested)])):value}function stableUpsertValue(value){return typeof value=="string"?value.trim():JSON.stringify(canonicalizeUpsertValue(value))}function applyKeyedUpsert(rows,upsert,idPrefix,runtimeFields,references){const key=upsert.key.trim();if(key.length===0)throw new PmCliError("Upsert key must be a non-empty field name.",EXIT_CODE.USAGE);const existingByValue=indexUpsertCandidates(upsert.existing),seen=new Map,upserted=new Set;for(const[index,row]of rows.entries()){if(row.op!=="create")continue;const stable=readStableUpsertKey(row,key,index,seen,runtimeFields),match=resolveUpsertMatch(existingByValue.get(stable)??[],key,stable);if(match===void 0){row.unique={key,value:readUpsertKeyValue(row,key,runtimeFields)};continue}const id=normalizeItemId(match,idPrefix);typeof row.ref=="string"&&(references[row.ref]=id),convertRowToUpsertUpdate(row,id,runtimeFields,{key,value:readUpsertKeyValue(row,key,runtimeFields)}),upserted.add(index)}return upserted}function indexUpsertCandidates(existing){const existingByValue=new Map;for(const candidate of existing){if(candidate.value===void 0||candidate.value===null)continue;const stable=stableUpsertValue(candidate.value);existingByValue.set(stable,[...existingByValue.get(stable)??[],candidate.id])}return existingByValue}function readStableUpsertKey(row,key,index,seen,runtimeFields){const value=readUpsertKeyValue(row,key,runtimeFields);if(value==null||value==="")throw new PmCliError(`Mutation ${index+1} is missing the upsert key "${key}".`,EXIT_CODE.USAGE,{code:"upsert_key_missing",required:`Every create record must carry a non-empty "${key}" value when --upsert-key ${key} is set.`,why:"Keyed upsert identifies existing items by that field; a record without it cannot be matched or safely created."});const stable=stableUpsertValue(value),previous=seen.get(stable);if(previous!==void 0)throw new PmCliError(`Mutations ${previous+1} and ${index+1} share the upsert key value ${JSON.stringify(stable)} for "${key}".`,EXIT_CODE.USAGE,{code:"upsert_key_duplicate",required:"Each record must carry a distinct upsert key value within one batch.",why:"Two records with the same key would race for the same existing item."});return seen.set(stable,index),stable}function resolveUpsertMatch(matches,key,stable){if(matches.length>1)throw new PmCliError(`Upsert key "${key}" value ${JSON.stringify(stable)} matches ${matches.length} existing items: ${matches.join(", ")}.`,EXIT_CODE.CONFLICT,{code:"upsert_key_ambiguous",required:"Resolve the duplicate existing items or choose a key that is unique per item.",why:"An ambiguous key cannot select one item to update without guessing."});return matches[0]}function convertRowToUpsertUpdate(row,id,runtimeFields,match){const updateKeys=new Set([...MUTATION_OPTION_KEYS.update,...runtimeFieldOptionKeys("update",runtimeFields)]),options=isPlainObject(row.item)?itemDocumentToBatchOptions(row.item,"update",runtimeFields):Object.fromEntries(Object.entries(row.options).filter(([optionKey])=>updateKeys.has(optionKey)));delete row.item,delete row.ref,row.op="update",row.id=id,row.options=options,row.match=match}function collectMutationReferences(rows,options,references){for(const[index,row]of rows.entries())if(row.ref!==void 0){if(row.op!=="create")throw new PmCliError(`Mutation ${index+1} ref is only valid for create operations.`,EXIT_CODE.USAGE);if(typeof row.ref!="string"||!MUTATION_REFERENCE_PATTERN.test(row.ref))throw new PmCliError(`Mutation ${index+1} ref must match ${MUTATION_REFERENCE_PATTERN.source}.`,EXIT_CODE.USAGE);if(references[row.ref]!==void 0)throw new PmCliError(`Duplicate mutation ref "${row.ref}".`,EXIT_CODE.USAGE);references[row.ref]=typeof row.id=="string"&&row.id.trim().length>0?normalizeItemId(row.id,options.idPrefix):deriveReferencedItemId(options.transactionId,row.ref,options.idPrefix)}return references}function resolveItemMutationDocument(input,options){const rows=parseMutationDocumentRows(input);synthesizeMissingReferences(rows);const inputReferences=rows.map(row=>typeof row.ref=="string"?row.ref:void 0),references=Object.create(null),upserted=options.upsert===void 0?new Set:applyKeyedUpsert(rows,excludeOwnCreateIds(options.upsert,rows,options),options.idPrefix,options.runtimeFields??[],references);convertItemDocumentRows(rows,options.runtimeFields??[]),collectMutationReferences(rows,options,references),assertAcyclicCreateReferences(rows,inputReferences);const resolvedRows=rows.map(row=>{const resolved={...row},reference=typeof resolved.ref=="string"?resolved.ref:void 0;if(delete resolved.ref,reference!==void 0?resolved.id=references[reference]:resolved.id=replaceExactMutationReference(resolved.id,references),isPlainObject(resolved.options)){const mutationOptions={...resolved.options};for(const key of["parent","blockedBy"])mutationOptions[key]!==void 0&&(mutationOptions[key]=replaceExactMutationReference(mutationOptions[key],references));Array.isArray(mutationOptions.dep)?mutationOptions.dep=mutationOptions.dep.map(entry=>replaceDependencyReference(entry,references)):mutationOptions.dep!==void 0&&(mutationOptions.dep=replaceDependencyReference(mutationOptions.dep,references)),resolved.options=mutationOptions}return resolved}),mutations=parseItemMutationBatch(JSON.stringify(resolvedRows),{runtimeFields:options.runtimeFields??[]}),createIds=mutations.filter(mutation=>mutation.op==="create").map(mutation=>mutation.id);if(new Set(createIds).size!==createIds.length)throw new PmCliError("Duplicate resolved create id in mutation document.",EXIT_CODE.USAGE);const receiptRows=mutations.map((mutation,index)=>{const reference=inputReferences[index];return{index,...typeof reference=="string"?{ref:reference}:{},id:mutation.id,op:mutation.op,...upserted.has(index)?{upserted:!0}:{}}});return{schema_version:1,mutations,references,rows:receiptRows}}function serializePairs(value,keys){return keys.filter(key=>value[key]!==void 0&&value[key]!==null).map(key=>{const rendered=String(value[key]);return`${key}=${/[",\n\r\\]/u.test(rendered)?JSON.stringify(rendered):rendered}`}).join(",")}function serializeObjectArray(value,keys,label){if(value!==void 0){if(!Array.isArray(value)||!value.every(isPlainObject))throw new PmCliError(`${label} must be an array of objects.`,EXIT_CODE.USAGE);return value.map(entry=>serializePairs(entry,keys))}}function scalarItemOption(key,value){return key==="tags"&&Array.isArray(value)&&value.every(entry=>typeof entry=="string")?JSON.stringify(value):typeof value=="number"||typeof value=="boolean"?String(value):value}function appendFacetOptions(target,source,skipPersistedAnnotations=!1){for(const[sourceKey,targetKey,keys]of ITEM_MUTATION_FACET_OPTION_MAPPINGS){const sourceValue=source[sourceKey],serialized=serializeObjectArray(skipPersistedAnnotations&&["comments","notes","learnings"].includes(sourceKey)&&Array.isArray(sourceValue)?sourceValue.filter(entry=>!isPlainObject(entry)||entry.created_at===void 0):sourceValue,keys,sourceKey);serialized!==void 0&&serialized.length>0&&(target[targetKey]=serialized)}}function validateItemDocumentKeys(parsed,envelope){for(const key of Object.keys(parsed)){if(envelope){if(!ITEM_ENVELOPE_KEYS.includes(key))throw unknownKeyError("item envelope",key,ITEM_ENVELOPE_KEYS);continue}if(!ITEM_FIELD_KEYS.has(key)&&nearestKey(key,[...ITEM_FIELD_KEYS])===void 0&&nearestKey(key,ITEM_ENVELOPE_KEYS)==="item")throw unknownKeyError("item envelope",key,ITEM_ENVELOPE_KEYS)}}function resolveItemDocument(parsed){const envelope=Object.hasOwn(parsed,"item");validateItemDocumentKeys(parsed,envelope);const item=envelope?parsed.item:parsed;if(!isPlainObject(item))throw new PmCliError("Item document item must be an object.",EXIT_CODE.USAGE);return{item,...envelope&&isPlainObject(parsed.linked)?{linked:parsed.linked}:{}}}function appendItemDocumentEntry(documentOptions,key,value,mode,runtimeFields,explicitOptions){if((mode==="update"?UPDATE_READ_ONLY_ITEM_KEYS:READ_ONLY_ITEM_KEYS).has(key))return;const definition=runtimeFields.find(field=>field.metadata_key===key&&field.commands.includes(mode));if(definition!==void 0){const explicitValue=readRuntimeFieldOptionValue(explicitOptions,definition);documentOptions[runtimeFieldOptionTarget(definition)]=explicitValue!==void 0?explicitValue:definition.type==="array"||definition.type==="object"?JSON.stringify(value):value;return}if(!ITEM_FIELD_KEYS.has(key)){if(nearestKey(key,[...ITEM_FIELD_KEYS])!==void 0)throw unknownKeyError("item document",key,[...ITEM_FIELD_KEYS]);const fields=Array.isArray(documentOptions.field)?documentOptions.field:[];fields.push(`${key}=${typeof value=="string"?value:JSON.stringify(value)}`),documentOptions.field=fields;return}["dependencies","comments","notes","learnings","files","tests","docs","reminders","events","type_options"].includes(key)||(documentOptions[key.replaceAll(/_([a-z])/gu,(_match,letter)=>letter.toUpperCase())]=scalarItemOption(key,value))}function itemDocumentToMutationOptions(input,mode,explicitOptions={},runtimeFields=[]){const parsed=parseJsonValue(input,"Item document");if(!isPlainObject(parsed))throw new PmCliError("Item document must be a JSON object.",EXIT_CODE.USAGE);const{item,linked}=resolveItemDocument(parsed),documentOptions={};for(const[key,value]of Object.entries(item)){const metadataKey=itemDocumentMetadataKey(key,runtimeFields);metadataKey!==key&&Object.hasOwn(item,metadataKey)||appendItemDocumentEntry(documentOptions,metadataKey,value,mode,runtimeFields,explicitOptions)}if(appendFacetOptions(documentOptions,item,mode==="update"),linked!==void 0&&appendFacetOptions(documentOptions,linked),mode==="update"){const annotations=Object.fromEntries(["comments","notes","learnings"].filter(key=>Object.hasOwn(item,key)).map(key=>[key,item[key].filter(entry=>isPlainObject(entry)&&entry.created_at!==void 0)]));Object.keys(annotations).length>0&&(documentOptions.documentAnnotationSnapshot=annotations)}return{...documentOptions,...Object.fromEntries(Object.entries(explicitOptions).filter(([,value])=>value!==void 0)),...Array.isArray(documentOptions.field)&&Array.isArray(explicitOptions.field)?{field:[...documentOptions.field,...explicitOptions.field]}:{},stdinJson:void 0}}function validateItemMutationRows(value){return parseItemMutationBatch(JSON.stringify(value))}export{deriveMutationTransactionId,itemDocumentToMutationOptions,parseAtomicMutationControls,parseItemMutationBatch,resolveItemMutationDocument,stableUpsertValue,validateItemMutationRows};
 //# sourceMappingURL=structured-mutations.js.map

package/docs/COMMANDS.md

@@ -890,6 +890,20 @@ Linked files and docs keep reviews reproducible. `deps` is read-only and project
 
 Structured key/value forms reject unrecognized keys with an `Allowed keys: …` error (matching `test --add`), so a typoed key (`lable=` instead of `label=`) fails fast instead of being silently dropped: `--add`/`--file`/`--doc` accept `path,scope,note`; `--add-glob` accepts `pattern,glob,path,scope,note`; `--remove` accepts `path`; `--migrate` accepts `from,to`; create/update `--dep` accepts `id,kind,type,author,created_at,source_kind`; `--reminder` accepts `at,date,text,title`; `--event` accepts `start,date,end,duration,title,description,location,timezone,all_day` and the `recur_*` recurrence keys. Set `source_kind=global` for a dependency owned by another workspace: pm preserves its id verbatim, materializes it as an external graph endpoint, and excludes it from dangling-local-reference findings. Explicit remote locators also retain their spelling; other dependency and parent references share local `id_prefix` normalization, including uppercase and `#` shorthand. Bare values (`--add src/cli/main.ts`) skip key validation.
 
+Context `meta.usedTokens` measures the selected built-in JSON or TOON emission,
+including its newline, alias counts, omission receipt and optional discovery or
+token-accounting metadata. If the required rendered packet cannot fit in the requested
+token budget, `pm item deps` returns usage exit code 2 with
+`invalid_argument_value`. Structured `recovery.token_budget` reports the requested
+budget and a verified feasible budget. Its `minimum_status` is `exact` only after
+every smaller positive budget is checked; bounded searches can instead report
+`feasible_only` or `unavailable` with no invented minimum. When a feasible budget
+is known, `suggested_retry_args` preserves the tracker, query and output options
+in an executable context retry with that `--token-budget`. A separate
+`next_best_command` provides a compact tree-summary inspection.
+(Repository tracker: [pm-odw3j8](https://github.com/unbraind/pm-cli/blob/main/.agents/pm/tasks/pm-odw3j8.toon);
+tracker records are excluded from npm.)
+
 ## Graph Queries
 
 ```bash
@@ -1095,6 +1109,19 @@ When more than one history stream is drifted, the `history_drift` remediation co
 
 `pm health` also runs a read-only `locks` check alongside the storage check: it classifies every file in `locks/` with the exact policy `pm gc --scope locks` acts on and reports `active_lock_count`, `stale_lock_count`, `unreadable_lock_count`, and `unparseable_lock_count` (counts appear in all projection modes; nothing is ever removed). It warns with `locks_stale_count:<n>` when stale locks exist (fix: `pm gc --scope locks`) and `locks_unreadable:<n>` when lock files cannot be read (inspect first: `pm gc --scope locks --dry-run`).
 
+## Single-commit merge settlement
+
+Tracked by [pm-gh1475](../.agents/pm/issues/pm-gh1475.toon).
+Use `git merge --no-commit --no-ff <branch>`, then
+`pm merge reconcile --stage` and `git commit` to include authenticated lossless
+audit history in the original merge commit. `--stage --dry-run` previews without
+writing. Automatic staging refuses competing values, forced acceptance,
+non-history validation failures, unstaged edits to reconciliation artifacts,
+and unresolved index entries. `pm merge install --pre-commit-hook` explicitly
+installs a merge-aware hook for that paused-merge workflow and preserves existing
+unowned hooks. Default installation remains hook-free. See
+[Merge safety](MERGE_SAFETY.md#settle-a-lossless-merge-in-one-commit).
+
 ## History and Recovery
 
 After a branch merge that touched tracker history, preview and apply the

package/docs/CONFIGURATION.md

@@ -336,6 +336,20 @@ pm get <id> --full --json
 pm contracts --json
 ```
 
+`--output-format json|toon` selects encoding on both reads and mutations.
+Item collection and lifecycle commands accept `--format json|toon` as a
+compatibility alias, before or after the command:
+
+```bash
+pm comments <id> --format json
+pm --format json create Task "Follow up" --create-mode progressive
+```
+
+Command-specific formats retain their meaning, including `list --format csv`,
+`deps --format graph`, and `config set item-format --format toon`. Use
+`--output-format` to select the envelope encoding alongside those options.
+Package commands retain their declared flag vocabulary.
+
 `pm calendar` (provided by the optional `calendar` package — `pm install calendar --project`) defaults to markdown because date-centric summaries are easier to scan in that format.
 
 ## Validation Policies