@unbrained/pm-cli 2026.10.3 → 2026.10.5

package/dist/sdk/read-output-contracts.js

@@ -1,2 +1,2 @@
-!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d1ed05d5-c83a-555c-95f5-5b2f62b9bc64")}catch(e2){}})();import{READ_OUTPUT_DIMENSION_FLAGS,READ_OUTPUT_COMPOSITION_FLAGS}from"./read-output/options.js";import{resolvePmHistoryOperation}from"./cli-contracts/command-aliases.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{compactReadOutputToBudget,estimateReadOutputTokens,projectReadOutputItemToBrief,preserveReadOutputRowContract,resolveReadOutputRecoveryBudget,updateReadOutputReceiptEstimate}from"./read-output-budget.js";import{resolveReadOutputRecoveryBudget as resolveReadOutputRecoveryBudget2}from"./read-output-budget.js";import{resolvePmCommandOutputBudget}from"./cli-contracts/agent-output-contracts.js";import{boundReadOutputRows,countReadOutputRows,mapReadOutputRows,readOutputBudgetCollections,readOutputContinuationRowCollections,readOutputRowPaths,readOutputRowCollections,refreshReadOutputDeliveredCounts}from"./read-output-rows.js";import{applyReadOutputContinuation,decodeReadOutputContinuationCursor,encodeReadOutputContinuationCursor,prioritizeAssuranceAssertions,readOutputCollectionFingerprint}from"./read-output/continuation.js";import{decodeReadOutputContinuationCursor as decodeReadOutputContinuationCursor2,encodeReadOutputContinuationCursor as encodeReadOutputContinuationCursor2,PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES,readOutputCollectionFingerprint as readOutputCollectionFingerprint2}from"./read-output/continuation.js";import{applyReadOutputSessionReferences,attachReadOutputSessionReceipt,parseReadOutputSession,readOutputSessionRemainingTokens}from"./read-output-session.js";import{decodeQueryCursorEnvelope,encodeQueryCursor}from"./pagination.js";import{READ_OUTPUT_INVOCATION_PROVENANCE}from"./read-output/provenance.js";const PM_READ_OUTPUT_DIMENSIONS=["include","amount","cost","encoding"];const PM_READ_OUTPUT_SURFACES=["list","context","search","get","next","health","deps","graph","history","activity","validate","events","contracts","comments","notes","files","docs","stats","aggregate","duplicates","package-catalog","package-manage","comments-audit","assurance"];const READ_OUTPUT_PRECEDENCE=["canonical","legacy","intent","default"];const CANONICAL_OPTIONS=READ_OUTPUT_DIMENSION_FLAGS;const PM_READ_OUTPUT_OPTION_FLAGS=Object.freeze(PM_READ_OUTPUT_DIMENSIONS.map(dimension=>CANONICAL_OPTIONS[dimension]));const PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS=READ_OUTPUT_COMPOSITION_FLAGS;const LEGACY_FLAGS_BY_COMMAND={list:{include:["--brief","--compact","--fields","--full"],amount:["--after","--limit","--no-truncate"],cost:["--token-budget"],encoding:["--format","--stream"]},context:{include:["--fields","--section"],amount:["--after","--depth","--limit"],cost:["--token-budget"],encoding:["--format"]},search:{include:["--compact","--fields","--full"],amount:["--after","--limit"],cost:["--token-budget"],encoding:["--format"]},get:{include:["--fields","--full"],amount:["--depth"],cost:["--token-budget"],encoding:["--format"]},next:{amount:["--blocked-limit","--limit"],cost:["--token-budget"],encoding:["--format"]},health:{include:["--brief","--check-only","--full","--summary"]},deps:{include:["--collapse","--full","--summary"],amount:["--edge-limit","--max-depth","--node-limit"],cost:["--token-budget"],encoding:["--format"]},graph:{include:["--full","--summary"],amount:["--after","--limit","--max-depth","--max-paths"]},history:{include:["--compact","--full"],amount:["--limit"],encoding:["--format"]},activity:{include:["--compact","--full"],amount:["--limit","--unbounded"],encoding:["--stream"]},validate:{include:["--counts","--full"]},events:{include:["--full"],amount:["--limit"],encoding:["--follow"]},contracts:{include:["--full","--summary"]},comments:{amount:["--limit"]},notes:{amount:["--limit"]},files:{amount:["--limit","--no-truncate","--offset"]},docs:{},stats:{},aggregate:{},duplicates:{amount:["--limit"]},"package-catalog":{},"package-manage":{},"comments-audit":{},assurance:{}};const VALUE_BEARING_INCLUDE_ALIASES=new Set(["--collapse","--fields","--section"]);const BEHAVIOR_PRESERVING_MIGRATION_HINTS=Object.freeze({"--after":"--after retains cursor-position semantics; use --output-limit <n> separately to bound returned rows.","--check-only":"--check-only retains health side-effect semantics; --output-include does not suppress vector refresh.","--collapse":"--collapse retains dependency grouping semantics; --output-include does not replace it.","--depth":"--depth retains traversal or detail-depth semantics; --output-limit does not replace it.","--follow":"--follow retains event-tail semantics; --output-format does not enable following.","--max-depth":"--max-depth retains graph traversal-depth semantics; --output-limit does not replace it.","--max-paths":"--max-paths retains graph path-search semantics; use --output-limit separately to bound returned rows.","--no-truncate":"--no-truncate is a compatibility alias; prefer --output-limit unbounded.","--offset":"--offset retains positional pagination semantics; use --output-limit separately to bound returned rows.","--stream":"--stream retains command streaming semantics; --output-format selects only static result encoding.","--unbounded":"--unbounded is a compatibility alias; prefer --output-limit unbounded."});function flagSelector(flag){return flag.slice(2).replaceAll("-","_")}function migrationHint(flag,dimension){const behaviorHint=BEHAVIOR_PRESERVING_MIGRATION_HINTS[flag];if(behaviorHint!==void 0)return behaviorHint;const suffix=dimension==="include"?VALUE_BEARING_INCLUDE_ALIASES.has(flag)?"<csv>":flagSelector(flag):dimension==="amount"?"<n>":dimension==="cost"?"<tokens>":"<toon|json>";return`${flag} is a compatibility alias; prefer ${CANONICAL_OPTIONS[dimension]} ${suffix}.`}function buildSurfaceContract(command){const legacy=LEGACY_FLAGS_BY_COMMAND[command];const dimensions=Object.freeze(Object.fromEntries(PM_READ_OUTPUT_DIMENSIONS.map(dimension=>[dimension,Object.freeze({dimension,canonical_option:CANONICAL_OPTIONS[dimension],applicable:true,inapplicable_reason:null,legacy_aliases:Object.freeze((legacy[dimension]??[]).map(flag=>Object.freeze({flag,semantics:BEHAVIOR_PRESERVING_MIGRATION_HINTS[flag]===void 0?"replacement":"behavior_preserving",migration_hint:migrationHint(flag,dimension),visibility:"hidden_alias"})))})])));return Object.freeze({command,dimensions,precedence:READ_OUTPUT_PRECEDENCE,budget_retention_policy:command==="assurance"?"verdict_priority":"ordered_prefix",projection_modes:Object.freeze([...readOutputIncludeModeOptions(command).keys()])})}const PM_READ_OUTPUT_SURFACE_CONTRACTS=Object.freeze(PM_READ_OUTPUT_SURFACES.map(buildSurfaceContract));const SURFACE_CONTRACT_BY_COMMAND=new Map(PM_READ_OUTPUT_SURFACE_CONTRACTS.map(contract=>[contract.command,contract]));function resolveReadOutputSurface(command,options={}){const normalizedCommand=resolvePmHistoryOperation(command.trim().toLowerCase());const packageMode=normalizedCommand==="package catalog"||normalizedCommand==="packages catalog"||normalizedCommand==="package-catalog"||(normalizedCommand==="package"||normalizedCommand==="packages"||normalizedCommand==="extension")&&(options.catalog===true||options.target==="catalog"||options.action==="catalog");const root=packageMode?"package-catalog":normalizedCommand==="package manage"||normalizedCommand==="package-manage"?"package-manage":normalizedCommand.split(" ")[0];const normalized=root.startsWith("list-")?"list":root==="ctx"?"context":root;return PM_READ_OUTPUT_SURFACES.includes(normalized)?normalized:void 0}const CANONICAL_OPTION_KEYS=["outputInclude","output_include","outputLimit","output_limit","outputBudget","output_budget","outputFormat","output_format","outputSession","output_session","outputCursor","output_cursor","outputRowContract","output_row_contract"];const HYBRID_READ_MUTATION_KEYS={comments:["add","body","stdin","file","edit","delete"],notes:["add","addJson","stdin","file","edit","delete"],files:["add","addGlob","remove","migrate","apply","note"],docs:["add","addGlob","remove","migrate","note"],"package-catalog":["activate","adopt","adoptAll","deactivate","doctor","init","install","manage","migrate","reload","scaffold","uninstall"]};function hasCanonicalReadOutputOptions(options){return CANONICAL_OPTION_KEYS.some(key=>key!=="outputFormat"&&key!=="output_format"&&options[key]!==void 0)}const READ_OUTPUT_VALUE_VALIDATORS=[{keys:["outputInclude","output_include"],valid:value=>stringList(value)!==void 0,message:"--output-include requires at least one comma-separated field or section."},{keys:["outputLimit","output_limit"],valid:value=>value==="unbounded"||positiveInteger(value)!==void 0,message:"--output-limit must be a positive integer or unbounded."},{keys:["outputBudget","output_budget"],valid:value=>value==="unbounded"||positiveInteger(value)!==void 0,message:"--output-budget must be a positive integer or unbounded."},{keys:["outputSession","output_session"],valid:value=>{parseReadOutputSession(value);return true},message:"--output-session must be a valid session-state object."},{keys:["outputCursor","output_cursor"],valid:value=>typeof value==="string"&&value.trim().length>0,message:"--output-cursor requires a non-empty continuation cursor."}];function validateReadOutputOptions(command,options){const encoding=options.outputFormat??options.output_format;if(encoding!==void 0&&encoding!=="json"&&encoding!=="toon"){throw new PmCliError("--output-format must be toon or json.",EXIT_CODE.USAGE)}if(!hasCanonicalReadOutputOptions(options))return;const normalizedCommand=resolveReadOutputSurface(command,options);if(!normalizedCommand){throw new PmCliError(`Universal output controls apply only to read commands; ${command||"this command"} is not a read surface.`,EXIT_CODE.USAGE)}if((HYBRID_READ_MUTATION_KEYS[normalizedCommand]??[]).some(key=>options[key]!==void 0&&options[key]!==false)){throw new PmCliError(`Universal output controls cannot be combined with a ${normalizedCommand} mutation.`,EXIT_CODE.USAGE)}for(const validator of READ_OUTPUT_VALUE_VALIDATORS){const value=validator.keys.map(key=>options[key]).find(entry=>entry!==void 0);if(value!==void 0&&!validator.valid(value)){throw new PmCliError(validator.message,EXIT_CODE.USAGE)}}}function readOutputIncludeModeOptions(command){const surface=resolveReadOutputSurface(command);if(!surface)return new Map;return new Map((LEGACY_FLAGS_BY_COMMAND[surface].include??[]).filter(flag=>!VALUE_BEARING_INCLUDE_ALIASES.has(flag)&&BEHAVIOR_PRESERVING_MIGRATION_HINTS[flag]===void 0).map(flag=>[flagSelector(flag),optionKey(flag)]))}function applyReadOutputIncludeModes(command,includeValue,commandOptions){const requested=stringList(includeValue)??[];const modeOptions=readOutputIncludeModeOptions(command);const selectors=[];const modes=[];const optionsWithProvenance=commandOptions;const existingProvenance=optionsWithProvenance[READ_OUTPUT_INVOCATION_PROVENANCE];const canonicalModes=new Set(existingProvenance?.canonical_include_modes??[]);const explicitLegacyAliases=new Set(existingProvenance?.explicit_legacy_aliases??[]);for(const token of requested){const option=modeOptions.get(token);if(option===void 0){selectors.push(token);continue}const legacyFlag=`--${token.replaceAll("_","-")}`;if(isRequestedOption(readOption(commandOptions,legacyFlag))){explicitLegacyAliases.add(legacyFlag)}commandOptions[option]=true;modes.push(token);canonicalModes.add(token)}const forwardedGetFieldSelectors=resolveReadOutputSurface(command)==="get"?selectors.filter(selector=>selector!=="item"):[];const forwardedGetFields=forwardedGetFieldSelectors.length>0;if(forwardedGetFields){commandOptions.fields=[...new Set([...stringList(commandOptions.fields)??[],...forwardedGetFieldSelectors])].join(",");canonicalModes.add("fields")}if(modes.length>0||forwardedGetFields){optionsWithProvenance[READ_OUTPUT_INVOCATION_PROVENANCE]={canonical_include_modes:[...canonicalModes],explicit_legacy_aliases:[...explicitLegacyAliases],...existingProvenance?.cli_invocation_observed===true?{cli_invocation_observed:true}:{}}}return{selectors,modes}}function normalizeReadOutputIncludeModeOptions(command,options){const include=options.outputInclude??options.output_include;if(include===void 0)return;const{selectors,modes}=applyReadOutputIncludeModes(command,include,options);if(modes.length===0)return;const residual=selectors.length>0?selectors.join(","):void 0;options.outputInclude=residual;if(Object.hasOwn(options,"output_include")){options.output_include=residual}}function optionKey(flag){return flag.slice(2).replace(/-([a-z])/gu,(_,character)=>character.toUpperCase())}function readOption(options,flag){const key=optionKey(flag);if(Object.hasOwn(options,key))return options[key];const snakeKey=flag.slice(2).replaceAll("-","_");if(Object.hasOwn(options,snakeKey))return options[snakeKey];if(flag==="--no-truncate"&&options.truncate===false)return true;return void 0}function isRequestedOption(value){return value!==void 0&&value!==false&&value!==null}function stringList(value){const values=Array.isArray(value)?value:[value];const normalized=values.flatMap(entry=>typeof entry==="string"?entry.split(","):[]).map(entry=>entry.trim()).filter(Boolean);return normalized.length>0?[...new Set(normalized)]:void 0}function positiveInteger(value){const parsed=typeof value==="number"?value:typeof value==="string"&&/^\d+$/u.test(value.trim())?Number(value):Number.NaN;return Number.isSafeInteger(parsed)&&parsed>0?parsed:void 0}function resolveLegacyDimension(contract,options,usable,ignore){for(const alias of contract.legacy_aliases){if(ignore(alias.flag))continue;const value=readOption(options,alias.flag);const candidate={value,flag:alias.flag};if(isRequestedOption(value)&&usable(candidate))return candidate}return void 0}function resolveIncludeValue(canonical,legacy){const canonicalList=stringList(canonical);if(canonicalList)return{source:"canonical",value:canonicalList};if(!legacy)return void 0;return{source:"legacy",value:stringList(legacy.value)??[flagSelector(legacy.flag)]}}function resolveAmountValue(canonical,legacy){if(canonical==="unbounded"){return{source:"canonical",value:"unbounded"}}const canonicalLimit=positiveInteger(canonical);if(canonicalLimit!==void 0){return{source:"canonical",value:canonicalLimit}}if(!legacy)return void 0;if(legacy.flag==="--no-truncate"||legacy.flag==="--unbounded"){return{source:"legacy",value:"unbounded"}}const legacyLimit=positiveInteger(legacy.value);return legacyLimit===void 0?void 0:{source:"legacy",value:legacyLimit}}function resolveCostValue(canonical,legacy){if(canonical==="unbounded"){return{source:"canonical",value:"unbounded"}}const canonicalBudget=positiveInteger(canonical);if(canonicalBudget!==void 0){return{source:"canonical",value:canonicalBudget}}if(!legacy)return void 0;const legacyBudget=positiveInteger(legacy.value);return legacyBudget===void 0?void 0:{source:"legacy",value:legacyBudget}}function resolveEncodingValue(canonical,legacy){if(canonical==="json"||canonical==="toon"){return{source:"canonical",value:canonical}}if(!legacy)return void 0;if(legacy.flag==="--stream"||legacy.flag==="--follow"){return{source:"legacy",value:"stream"}}return legacy.value==="json"||legacy.value==="toon"?{source:"legacy",value:legacy.value}:void 0}function shouldIgnoreReadOutputLegacyAlias(provenance,dimension,flag){if(!provenance)return false;const explicitLegacyAliases=new Set(provenance.explicit_legacy_aliases);if(provenance.cli_invocation_observed===true||provenance.sdk_invocation_observed===true){return!explicitLegacyAliases.has(flag)}const forwardedIncludeAliases=new Set(provenance.canonical_include_modes.map(mode=>`--${mode.replaceAll("_","-")}`));return dimension==="include"&&forwardedIncludeAliases.has(flag)&&!explicitLegacyAliases.has(flag)}function hasCompleteReadOutputIntent(command,legacyByDimension,provenance){const root=command.trim().toLowerCase().replaceAll(/\s+/gu," ").split(" ")[0];return root==="list-all"||legacyByDimension.amount?.flag==="--no-truncate"||legacyByDimension.include?.flag==="--full"||provenance?.canonical_include_modes.includes("full")===true}function canonicalReadOutputOptionsUsed(resolvedByDimension,provenance){return PM_READ_OUTPUT_DIMENSIONS.flatMap(dimension=>resolvedByDimension[dimension]?.source==="canonical"||dimension==="include"&&(provenance?.canonical_include_modes.length??0)>0?[CANONICAL_OPTIONS[dimension]]:[])}function resolveReadOutputDimensions(command,options){const normalizedCommand=resolveReadOutputSurface(command,options);if(!normalizedCommand)return void 0;const contract=SURFACE_CONTRACT_BY_COMMAND.get(normalizedCommand);const invocationProvenance=options[READ_OUTPUT_INVOCATION_PROVENANCE];const legacyResolvers={include:candidate=>resolveIncludeValue(void 0,candidate),amount:candidate=>resolveAmountValue(void 0,candidate),cost:candidate=>resolveCostValue(void 0,candidate),encoding:candidate=>resolveEncodingValue(void 0,candidate)};const legacyByDimension=Object.fromEntries(PM_READ_OUTPUT_DIMENSIONS.map(dimension=>[dimension,resolveLegacyDimension(contract.dimensions[dimension],options,candidate=>legacyResolvers[dimension](candidate)!==void 0,flag=>shouldIgnoreReadOutputLegacyAlias(invocationProvenance,dimension,flag))]));const legacyAliasesUsed=PM_READ_OUTPUT_DIMENSIONS.flatMap(dimension=>{const resolved=legacyByDimension[dimension];return resolved?[resolved.flag]:[]});const migrationHints=PM_READ_OUTPUT_DIMENSIONS.flatMap(dimension=>{const resolved=legacyByDimension[dimension];if(!resolved)return[];const alias=contract.dimensions[dimension].legacy_aliases.find(entry=>entry.flag===resolved.flag);return[alias.migration_hint]});const encoding=resolveEncodingValue(options.outputFormat??options.output_format,legacyByDimension.encoding);const include=resolveIncludeValue(options.outputInclude??options.output_include,legacyByDimension.include);const amount=resolveAmountValue(options.outputLimit??options.output_limit,legacyByDimension.amount);const explicitCost=resolveCostValue(options.outputBudget??options.output_budget,legacyByDimension.cost);const completeResultIntent=hasCompleteReadOutputIntent(command,legacyByDimension,invocationProvenance);const budget=resolvePmCommandOutputBudget(command,{generateFallback:true});const resolvedOutputFormat=encoding?.value==="json"||options.resolvedOutputFormat==="json"?"json":"toon";const cost=explicitCost??(completeResultIntent?{source:"intent",value:"unbounded"}:{source:"default",value:budget.default_max_estimated_tokens_by_format[resolvedOutputFormat]});const resolvedByDimension={include,amount,cost,encoding};return{command:normalizedCommand,include,amount,cost,encoding,canonical_options_used:canonicalReadOutputOptionsUsed(resolvedByDimension,invocationProvenance),legacy_aliases_used:legacyAliasesUsed,migration_hints:migrationHints,precedence:READ_OUTPUT_PRECEDENCE}}function isRecord(value){return value!==null&&typeof value==="object"&&!Array.isArray(value)}const ENVELOPE_KEYS=new Set(["applied_bound","applied_limit","completeness","continuation_kind","continuation_path","continuation_contract","count","filters","has_more","next_cursor","now","omission_receipt","projection","budget_retention_policy","row_contract","sorting","total","truncated"]);const GET_STABLE_DERIVED_ITEM_SELECTORS=["collection_counts","notes_count","tests_count"];function projectRecordFields(value,selectors){const selected=new Set(selectors.map(selector=>selector.split(".")[0]));return Object.fromEntries(Object.entries(value).filter(([key])=>selected.has(key)))}function getProjectionVocabulary(result){const item=isRecord(result.item)?result.item:{};const itemFields=[...new Set([...Object.keys(item),...GET_STABLE_DERIVED_ITEM_SELECTORS.filter(key=>Object.hasOwn(item,key))])].sort((left,right)=>left.localeCompare(right));const sections=Object.keys(result).filter(key=>key!=="item"&&key!=="read_output"&&!ENVELOPE_KEYS.has(key)).sort((left,right)=>left.localeCompare(right));return{item,itemFields,sections,valid:[...itemFields,"item",...itemFields.map(field=>`item.${field}`),...sections]}}function applyGetIncludeProjection(result,selectors){const vocabulary=getProjectionVocabulary(result);const unknown=selectors.filter(selector=>!vocabulary.valid.includes(selector));if(unknown.length>0){throw new PmCliError(`Unknown --output-include selector(s) for get: ${unknown.join(", ")}. Valid selectors: ${vocabulary.valid.join(", ")}.`,EXIT_CODE.USAGE)}const fullItem=selectors.includes("item");const itemSelectors=selectors.flatMap(selector=>selector.startsWith("item.")?[selector.slice("item.".length)]:vocabulary.itemFields.includes(selector)?[selector]:[]).filter((selector,index,values)=>values.indexOf(selector)===index);if(fullItem&&itemSelectors.length>0){throw new PmCliError("--output-include cannot mix a full item with projected item fields; use item or item.<field>, not both.",EXIT_CODE.USAGE)}const selectedSections=new Set(selectors.filter(selector=>vocabulary.sections.includes(selector)));const projected=Object.fromEntries(Object.entries(result).filter(([key])=>ENVELOPE_KEYS.has(key)||selectedSections.has(key)));if(fullItem){projected.item=vocabulary.item}else if(itemSelectors.length>0){projected.item=projectRecordFields(vocabulary.item,itemSelectors)}const omittedFieldGroups=[...fullItem?[]:itemSelectors.length>0?vocabulary.itemFields.filter(field=>!itemSelectors.includes(field)).map(field=>({name:`item.${field}`,restore_with:`--output-include item.${field}`})):[{name:"item",restore_with:"--output-include item"}],...vocabulary.sections.filter(section=>!selectedSections.has(section)).map(section=>({name:section,restore_with:`--output-include ${section}`}))];const inheritedOmittedFieldGroups=isRecord(projected.omission_receipt)&&Array.isArray(projected.omission_receipt.omitted_field_groups)?projected.omission_receipt.omitted_field_groups:[];const combinedOmittedFieldGroups=[...inheritedOmittedFieldGroups,...omittedFieldGroups];projected.omission_receipt={has_omissions:combinedOmittedFieldGroups.length>0,omitted_field_group_count:combinedOmittedFieldGroups.length,omitted_field_groups:combinedOmittedFieldGroups};return projected}function countPopulatedRows(result){let populated=0;mapReadOutputRows({...result},entry=>{if(isRecord(entry)&&Object.keys(entry).length>0)populated+=1;return entry});return populated}function rejectEmptyIncludeProjection(command,original,shaped,selectors){if(countPopulatedRows(original)===0||countPopulatedRows(shaped)>0){return}const modes=[...readOutputIncludeModeOptions(command).keys()];const domain=modes.length>0?` Declared ${command} projection modes: ${modes.join(", ")}.`:` The ${command} surface declares no projection modes; name row fields instead.`;throw new PmCliError(`Unknown --output-include selector(s) for ${command}: ${selectors.join(", ")}. No selector matched any returned row field.${domain}`,EXIT_CODE.USAGE)}function applyIncludeProjection(command,result,selectors){if(command==="get"){return applyGetIncludeProjection(result,selectors)}const rows=readOutputRowPaths(result);const qualifiedRowSelectors=selectors.flatMap(selector=>rows.flatMap(rowPath=>selector.startsWith(`${rowPath}.`)?[selector.slice(rowPath.length+1)]:[]));const selectedRoot=selectors.some(selector=>Object.hasOwn(result,selector.split(".")[0])&&!rows.some(rowPath=>selector.startsWith(`${rowPath}.`)));if(rows.length>0&&(!selectedRoot||qualifiedRowSelectors.length>0)){const projected={...result};const rowSelectors=qualifiedRowSelectors.length>0?qualifiedRowSelectors:selectors;const shaped=mapReadOutputRows(projected,entry=>isRecord(entry)?projectRecordFields(entry,rowSelectors):entry);rejectEmptyIncludeProjection(command,result,shaped,rowSelectors);return shaped}return Object.fromEntries(Object.entries(result).filter(([key])=>selectors.some(selector=>selector.split(".")[0]===key)||ENVELOPE_KEYS.has(key)))}function applyAmountBound(result,amount){if(amount==="unbounded")return result;const{result:bounded,truncated}=boundReadOutputRows(result,amount);if(!truncated)return bounded;bounded.has_more=true;bounded.truncated=true;if(typeof bounded.count==="number"){const activeRowKey=isRecord(bounded.projection)?bounded.projection.row_key:void 0;bounded.count=typeof activeRowKey==="string"&&Array.isArray(bounded[activeRowKey])?bounded[activeRowKey].length:countReadOutputRows(bounded)}bounded.applied_bound={kind:"output_limit",source:"explicit",value:amount};return bounded}function requestedDimensions(resolved){return PM_READ_OUTPUT_DIMENSIONS.filter(dimension=>resolved[dimension]!==void 0&&resolved[dimension]?.source!=="default"||resolved.canonical_options_used.includes(CANONICAL_OPTIONS[dimension]))}function readOutputMeasurementFormat(options){const format=options.resolvedOutputFormat??options.outputFormat??options.output_format??options.format;return format==="json"||format==="toon"?format:void 0}function attachReadOutputSessionContracts(result,state,receipt,format){let withSession=attachReadOutputSessionReceipt(result,state,format);preserveReadOutputRowContract(result,withSession);for(let iteration=0;iteration<8;iteration+=1){const previousReadEstimate=receipt.estimated_tokens;const previousSessionEstimate=withSession.read_session.spent_this_call_tokens;updateReadOutputReceiptEstimate(withSession,receipt,format);const previous=withSession;withSession=attachReadOutputSessionReceipt(withSession,state,format);preserveReadOutputRowContract(previous,withSession);const sessionEstimate=withSession.read_session.spent_this_call_tokens;if(receipt.estimated_tokens===previousReadEstimate&&sessionEstimate===previousSessionEstimate){return withSession}}return withSession}function stabilizeReadOutputReceiptEstimates(result,options){if(!isRecord(result.read_output))return result;const format=readOutputMeasurementFormat(options);const receipt=result.read_output;const session=parseReadOutputSession(options.outputSession??options.output_session);if(session===void 0){updateReadOutputReceiptEstimate(result,receipt,format);return result}return attachReadOutputSessionContracts(result,session,receipt,format)}function attachValidateDiagnosticRowContract(command,result){if(command!=="validate")return result;const projection=isRecord(result.projection)?result.projection:void 0;const declaredFieldGroups=Array.isArray(projection?.declared_field_groups)?projection.declared_field_groups:[];if(!declaredFieldGroups.some(group=>isRecord(group)&&group.name==="diagnostic_rows")){return result}const diagnosticCollectionPaths=[...new Set(readOutputBudgetCollections(result).map(({path})=>path).filter(path=>/^checks\.\d+\.details\./u.test(path)))];const diagnosticRowKeys=diagnosticCollectionPaths.filter(path=>!diagnosticCollectionPaths.some(candidate=>candidate!==path&&path.startsWith(`${candidate}.`)));if(diagnosticRowKeys.length===0)return result;const existingContract=isRecord(result.row_contract)?result.row_contract:{};const existingRowKeys=Array.isArray(existingContract.row_keys)?existingContract.row_keys.filter(entry=>typeof entry==="string"):[];const existingContinuationRowKeys=Array.isArray(existingContract.continuation_row_keys)?existingContract.continuation_row_keys.filter(entry=>typeof entry==="string"):[];const rowKeys=existingRowKeys.length>0?existingRowKeys:diagnosticRowKeys;const continuationRowKeys=[...new Set(diagnosticRowKeys)];return JSON.stringify(rowKeys)===JSON.stringify(existingRowKeys)&&JSON.stringify(continuationRowKeys)===JSON.stringify(existingContinuationRowKeys)?result:{...result,row_contract:{...existingContract,row_keys:rowKeys,continuation_row_keys:continuationRowKeys,jq_selector:typeof existingContract.jq_selector==="string"?existingContract.jq_selector:".checks[].details"}}}function projectReadOutputRows(result,resolved,session,cursor){let projected={...result};if(resolved.include?.source==="canonical"){projected=applyIncludeProjection(resolved.command,projected,resolved.include.value)}if(resolved.command==="assurance"){projected=prioritizeAssuranceAssertions(projected)}refreshReadOutputDeliveredCounts(projected,result);projected=applyReadOutputContinuation(projected,resolved.command,cursor);if(resolved.command==="history"&&cursor){const historyRowKeys=["compact_history","provenance_history","history","diff"];projected=Object.fromEntries(Object.entries(projected).filter(([key])=>!historyRowKeys.includes(key)||key===cursor.path));if(isRecord(projected.projection)){projected.projection={...projected.projection,row_key:cursor.path}}if(isRecord(projected.row_contract)){const rowContract=projected.row_contract;projected.row_contract={...rowContract,row_keys:[cursor.path],...Array.isArray(rowContract.continuation_row_keys)?{continuation_row_keys:[cursor.path]}:{}}}projected.count=Object.keys(projected[cursor.path]).length}const continuationSource=result.count_only===true?{...projected,count_only:true,count:result.count}:projected;if(resolved.amount?.source==="canonical"){projected=applyAmountBound(projected,resolved.amount.value)}refreshReadOutputDeliveredCounts(projected,continuationSource);return session===void 0?projected:applyReadOutputSessionReferences(projected,session)}function resolveBindingReadOutputBudget(resolved,session){const budgets=[...resolved.cost!==void 0&&resolved.cost.value!=="unbounded"&&(resolved.cost.source==="canonical"||resolved.cost.source==="default")?[{source:resolved.cost.source,tokens:resolved.cost.value}]:[],...session===void 0?[]:[{source:"session",tokens:readOutputSessionRemainingTokens(session)}]];return budgets.sort((left,right)=>left.tokens-right.tokens)[0]}function canonicalReadOutputReceiptFields(resolved){const canonicalOptions=resolved.canonical_options_used;return canonicalOptions&&canonicalOptions.length>0?{canonical_options_used:canonicalOptions}:{}}function omitReadOutputForBudget(resolved,requested,session,bindingBudget,omittedResultEstimatedTokens,format){const minimalReceipt={contract_version:1,command:resolved.command,requested_dimensions:requested,...bindingBudget.source==="default"?{budget_source:bindingBudget.source,budget_tokens:bindingBudget.tokens}:{},precedence:resolved.precedence,...canonicalReadOutputReceiptFields(resolved),legacy_aliases_used:[],migration_hints:[],estimated_tokens:0,within_budget:false,strings_compacted:false,rows_compacted:false,result_omitted:true,...session===void 0?{omitted_result_estimated_tokens:omittedResultEstimatedTokens}:{}};const omitted={output_budget_exceeded:{omitted_result:true,reason:"requested_budget_infeasible",restore_with:"Unbounded",recovery:{outputBudget:"unbounded"}},read_output:minimalReceipt};const boundedOmission=session===void 0?omitted:attachReadOutputSessionContracts(omitted,session,minimalReceipt,format);if(session===void 0){updateReadOutputReceiptEstimate(boundedOmission,minimalReceipt,format)}if(session!==void 0&&minimalReceipt.estimated_tokens>bindingBudget.tokens){throw new PmCliError("The remaining output-session budget cannot fit its mandatory receipts; start a new session with a larger token_budget.",EXIT_CODE.USAGE)}return boundedOmission}function requiresReadOutputAudit(resolved,options){return options.outputRowContract===true||options.output_row_contract===true||resolved.canonical_options_used.includes("--output-include")||resolved.command==="list"&&resolved.canonical_options_used.length>0&&resolved.include?.value.includes("full")===true}function canReturnReadOutputUnchanged(resolved,session,result,format,options){if(session!==void 0||requiresReadOutputAudit(resolved,options))return false;if(resolved.amount?.source==="canonical"&&resolved.amount.value!=="unbounded"){const limit=resolved.amount.value;if(readOutputRowCollections(result).some(({value})=>(Array.isArray(value)?value.length:Object.keys(value).length)>limit))return false}return resolved.cost===void 0||resolved.cost.value==="unbounded"||resolved.cost.source==="legacy"||estimateReadOutputTokens(options.outputRowContract===false?Object.fromEntries(Object.entries(result).filter(([key])=>key!=="row_contract")):result,format)<=resolved.cost.value}function attachReadOutputTruncationDisclosure(projected,resolved,receipt,bindingBudget,continuationCursorRebased,measuredResultTokens,collectionsBeforeBudget){if(!receipt.rows_compacted)return;const overridden=resolved.amount?.value==="unbounded"?["amount"]:[];const afterByPath=new Map(readOutputContinuationRowCollections(projected).map(collection=>[collection.path,Array.isArray(collection.value)?collection.value.length:Object.keys(collection.value).length]));const continuations=[...collectionsBeforeBudget.entries()].flatMap(([path,before])=>{const retainedRows=afterByPath.get(path);if(retainedRows>=before.rows)return[];const offset=before.baseOffset+retainedRows;return[{path,cursor:encodeReadOutputContinuationCursor({command:resolved.command,path,offset,total_rows:before.totalRows,fingerprint:before.fingerprint}),retained_rows:retainedRows,remaining_rows:before.totalRows-offset,total_rows:before.totalRows}]});const primary=continuations[0];const continuationHint=primary?"; page --output-cursor":"";const budgetHint=bindingBudget.source==="session"?`Truncated by the remaining ${bindingBudget.tokens}-token session budget; start a new output session with a larger token_budget${continuationHint}.`:`${bindingBudget.tokens}-token: raise --output-budget${continuationHint}`;receipt.migration_hints=[budgetHint,...resolved.migration_hints];const recoveryBudget=resolveReadOutputRecoveryBudget({effective_budget_tokens:bindingBudget.tokens,measured_result_tokens:measuredResultTokens});if(primary&&!continuationCursorRebased&&(typeof projected.next_cursor!=="string"||projected.continuation_kind==="output_cursor")){projected.next_cursor=primary.cursor}projected.continuation_kind=continuationCursorRebased?"producer_cursor":primary?"output_cursor":"none";projected.output_budget_truncation={reason:"output_budget_reached",budget_source:bindingBudget.source,budget_tokens:bindingBudget.tokens,overridden_dimensions:overridden,compacted_row_paths:receipt.compacted_row_paths,continuation_cursor_rebased:continuationCursorRebased,continuation_available:continuations.length>0,recovery_budget_multiplier:primary?1:recoveryBudget.recovery_budget_multiplier,continuations,restore_with:primary?"recovery":`Retry with --output-budget ${recoveryBudget.output_budget} because no declared row collection can be continued.`,recovery:primary?{cursor:primary.cursor,cli:"--output-cursor",sdk:"outputCursor",mcp:"outputCursor"}:{cli:`--output-budget ${recoveryBudget.output_budget}`,sdk:{outputBudget:recoveryBudget.output_budget},mcp:{outputBudget:recoveryBudget.output_budget}}}}function rebaseBudgetCompactedCursor(projected,originalItemCount,cursorSource,cursorContinuesExistingPage){if(typeof cursorSource!=="string"||!Array.isArray(projected.items)){return false}const retainedCount=projected.items.length;if(retainedCount===0||retainedCount>=originalItemCount){return false}let cursor;try{cursor=decodeQueryCursorEnvelope(cursorSource)}catch{return false}const sourceIndex=cursor.after_index;if(sourceIndex===void 0)return false;const last=projected.items.at(-1);if(Object.prototype.toString.call(last)!=="[object Object]"){return false}const lastId=Reflect.get(last,"id");if(typeof lastId!=="string"||lastId.length===0)return false;const afterIndex=cursorContinuesExistingPage?sourceIndex-(originalItemCount-retainedCount):sourceIndex+retainedCount;if(afterIndex<0)return false;projected.next_cursor=encodeQueryCursor(cursor.fingerprint,lastId,afterIndex,cursor.snapshot);return true}function captureReadOutputContinuationState(projected,command,cursor,options){const collectionsBeforeBudget=new Map(readOutputContinuationRowCollections(projected).map(collection=>{const rows=Array.isArray(collection.value)?collection.value.length:Object.keys(collection.value).length;const continued=cursor?.path===collection.path;return[collection.path,{rows,totalRows:continued?cursor.total_rows:rows,baseOffset:continued?cursor.offset:0,fingerprint:continued?cursor.fingerprint:readOutputCollectionFingerprint(collection.path,collection.value,command)}]}));const cursorContinuesExistingPage=typeof projected.next_cursor==="string";return{collectionsBeforeBudget,originalItemCount:Array.isArray(projected.items)?projected.items.length:0,cursorContinuesExistingPage,cursorSource:cursorContinuesExistingPage?projected.next_cursor:options.after}}function compactReadOutputProjection(projected,source,countOnly,resolved,receipt,bindingBudget,session,continuationState,measuredResultTokens,format){const deliveredSource={...source,count_only:countOnly};const assuranceMinimumRows=resolved.command==="assurance"&&Array.isArray(projected.assertions)?projected.assertions.filter(row=>isRecord(row)&&row.verdict!=="pass").length:0;const minimumRowsByPath=new Map;if(assuranceMinimumRows>0){minimumRowsByPath.set("assertions",assuranceMinimumRows)}if(resolved.command==="history"&&Array.isArray(projected.diff)){for(const collection of readOutputBudgetCollections(projected)){if(!collection.path.startsWith("diff."))continue;minimumRowsByPath.set(collection.path,Object.keys(collection.value).length)}}return compactReadOutputToBudget(projected,receipt,bindingBudget.tokens,minimumRowsByPath,format,compacted=>{refreshReadOutputDeliveredCounts(compacted,deliveredSource);const continuationCursorRebased=rebaseBudgetCompactedCursor(compacted,continuationState.originalItemCount,continuationState.cursorSource,continuationState.cursorContinuesExistingPage);attachReadOutputTruncationDisclosure(compacted,resolved,receipt,bindingBudget,continuationCursorRebased,measuredResultTokens,continuationState.collectionsBeforeBudget);if(resolved.command==="history"&&isRecord(compacted.projection)){compacted.has_more=typeof compacted.next_cursor==="string"||compacted.applied_bound?.kind==="output_limit";const rowKey=compacted.projection.row_key;if(typeof rowKey==="string"&&Array.isArray(compacted[rowKey])){compacted.count=compacted[rowKey].length}}if(session!==void 0){Object.assign(compacted,attachReadOutputSessionContracts(compacted,session,receipt,format))}},resolved.command==="history"&&Array.isArray(projected.diff))}function applyReadOutputDimensions(command,options,result){const resolved=resolveReadOutputDimensions(command,options);if(!resolved)return result;const format=readOutputMeasurementFormat(options);const session=parseReadOutputSession(options.outputSession??options.output_session);const rawCursor=options.outputCursor??options.output_cursor;const cursor=typeof rawCursor==="string"?decodeReadOutputContinuationCursor(rawCursor):void 0;const requested=requestedDimensions(resolved);const continuationReadyResult=attachValidateDiagnosticRowContract(resolved.command,result);if(cursor===void 0&&canReturnReadOutputUnchanged(resolved,session,continuationReadyResult,format,options)){return continuationReadyResult}const bindingBudget=resolveBindingReadOutputBudget(resolved,session);let projected=projectReadOutputRows(continuationReadyResult,resolved,session,cursor);preserveReadOutputRowContract(projected,projected,options.outputRowContract===false);const receipt={contract_version:1,command:resolved.command,requested_dimensions:requested,...bindingBudget?.source==="default"?{budget_source:bindingBudget.source,budget_tokens:bindingBudget.tokens}:{},precedence:resolved.precedence,...canonicalReadOutputReceiptFields(resolved),legacy_aliases_used:resolved.legacy_aliases_used,migration_hints:resolved.migration_hints,estimated_tokens:0,within_budget:true,strings_compacted:false,rows_compacted:false,result_omitted:false};projected.read_output=receipt;projected=session===void 0?projected:attachReadOutputSessionContracts(projected,session,receipt,format);updateReadOutputReceiptEstimate(projected,receipt,format);if(bindingBudget!==void 0&&receipt.estimated_tokens>bindingBudget.tokens){const brief=projectReadOutputItemToBrief(resolved.command,options,projected);if(brief!==void 0){receipt.applied_depth="brief";receipt.degradation_reason="output_budget_reached";preserveReadOutputRowContract(projected,brief);projected=stabilizeReadOutputReceiptEstimates(brief,options)}if(receipt.estimated_tokens>bindingBudget.tokens){projected=compactReadOutputProjection(projected,projected,continuationReadyResult.count_only===true,resolved,receipt,bindingBudget,session,captureReadOutputContinuationState(projected,resolved.command,cursor,options),receipt.estimated_tokens,format)}}if(bindingBudget!==void 0&&receipt.estimated_tokens>bindingBudget.tokens){return omitReadOutputForBudget(resolved,requested,session,bindingBudget,receipt.estimated_tokens,format)}return projected}function isReadOutputBudgetExceeded(result){return isRecord(result)&&isRecord(result.output_budget_exceeded)&&result.output_budget_exceeded.omitted_result===true&&result.output_budget_exceeded.reason==="requested_budget_infeasible"}function resolveReadOutputEncoding(command,options){const canonical=options.outputFormat??options.output_format;if(canonical==="json"||canonical==="toon")return canonical;const encoding=resolveReadOutputDimensions(command,options)?.encoding;return encoding?.value==="json"||encoding?.value==="toon"?encoding.value:void 0}export{PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS,PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES,PM_READ_OUTPUT_DIMENSIONS,PM_READ_OUTPUT_OPTION_FLAGS,PM_READ_OUTPUT_SURFACES,PM_READ_OUTPUT_SURFACE_CONTRACTS,applyReadOutputDimensions,applyReadOutputIncludeModes,decodeReadOutputContinuationCursor2 as decodeReadOutputContinuationCursor,encodeReadOutputContinuationCursor2 as encodeReadOutputContinuationCursor,isReadOutputBudgetExceeded,normalizeReadOutputIncludeModeOptions,readOutputCollectionFingerprint2 as readOutputCollectionFingerprint,readOutputIncludeModeOptions,resolveReadOutputDimensions,resolveReadOutputEncoding,resolveReadOutputRecoveryBudget2 as resolveReadOutputRecoveryBudget,resolveReadOutputSurface,stabilizeReadOutputReceiptEstimates,validateReadOutputOptions};
+(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]="f339a0cc-ca55-5953-9ab7-fb766e9b7e36")}catch{}})();import{READ_OUTPUT_DIMENSION_FLAGS,READ_OUTPUT_COMPOSITION_FLAGS}from"./read-output/options.js";import{resolvePmHistoryOperation}from"./cli-contracts/command-aliases.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{compactReadOutputToBudget,estimateReadOutputTokens,projectReadOutputItemToBrief,preserveReadOutputRowContract,resolveReadOutputRecoveryBudget,updateReadOutputReceiptEstimate}from"./read-output-budget.js";import{resolveReadOutputRecoveryBudget as resolveReadOutputRecoveryBudget2}from"./read-output-budget.js";import{resolvePmCommandOutputBudget}from"./cli-contracts/agent-output-contracts.js";import{boundReadOutputRows,countReadOutputRows,mapReadOutputRows,readOutputBudgetCollections,readOutputContinuationRowCollections,readOutputRowPaths,readOutputRowCollections,refreshReadOutputDeliveredCounts}from"./read-output-rows.js";import{applyReadOutputContinuation,decodeReadOutputContinuationCursor,encodeReadOutputContinuationCursor,prioritizeAssuranceAssertions,readOutputCollectionFingerprint}from"./read-output/continuation.js";import{decodeReadOutputContinuationCursor as decodeReadOutputContinuationCursor2,encodeReadOutputContinuationCursor as encodeReadOutputContinuationCursor2,PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES,readOutputCollectionFingerprint as readOutputCollectionFingerprint2}from"./read-output/continuation.js";import{applyReadOutputSessionReferences,attachReadOutputSessionReceipt,parseReadOutputSession,readOutputSessionRemainingTokens}from"./read-output-session.js";import{decodeQueryCursorEnvelope,encodeQueryCursor}from"./pagination.js";import{READ_OUTPUT_INVOCATION_PROVENANCE}from"./read-output/provenance.js";const PM_READ_OUTPUT_DIMENSIONS=["include","amount","cost","encoding"],PM_READ_OUTPUT_SURFACES=["list","context","search","get","next","health","deps","graph","history","activity","validate","events","contracts","comments","notes","files","docs","stats","aggregate","duplicates","package-catalog","package-manage","comments-audit","assurance"],READ_OUTPUT_PRECEDENCE=["canonical","legacy","intent","default"],CANONICAL_OPTIONS=READ_OUTPUT_DIMENSION_FLAGS,PM_READ_OUTPUT_OPTION_FLAGS=Object.freeze(PM_READ_OUTPUT_DIMENSIONS.map(dimension=>CANONICAL_OPTIONS[dimension])),PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS=READ_OUTPUT_COMPOSITION_FLAGS,LEGACY_FLAGS_BY_COMMAND={list:{include:["--brief","--compact","--fields","--full"],amount:["--after","--limit","--no-truncate"],cost:["--token-budget"],encoding:["--format","--stream"]},context:{include:["--fields","--section"],amount:["--after","--depth","--limit"],cost:["--token-budget"],encoding:["--format"]},search:{include:["--compact","--fields","--full"],amount:["--after","--limit"],cost:["--token-budget"],encoding:["--format"]},get:{include:["--fields","--full"],amount:["--depth"],cost:["--token-budget"],encoding:["--format"]},next:{amount:["--blocked-limit","--limit"],cost:["--token-budget"],encoding:["--format"]},health:{include:["--brief","--check-only","--full","--summary"]},deps:{include:["--collapse","--full","--summary"],amount:["--edge-limit","--max-depth","--node-limit"],cost:["--token-budget"],encoding:["--format"]},graph:{include:["--full","--summary"],amount:["--after","--limit","--max-depth","--max-paths"]},history:{include:["--compact","--full"],amount:["--limit"],encoding:["--format"]},activity:{include:["--compact","--full"],amount:["--limit","--unbounded"],encoding:["--stream"]},validate:{include:["--counts","--full"]},events:{include:["--full"],amount:["--limit"],encoding:["--follow"]},contracts:{include:["--full","--summary"]},comments:{amount:["--limit"]},notes:{amount:["--limit"]},files:{amount:["--limit","--no-truncate","--offset"]},docs:{},stats:{},aggregate:{},duplicates:{amount:["--limit"]},"package-catalog":{},"package-manage":{},"comments-audit":{},assurance:{}},VALUE_BEARING_INCLUDE_ALIASES=new Set(["--collapse","--fields","--section"]),BEHAVIOR_PRESERVING_MIGRATION_HINTS=Object.freeze({"--after":"--after retains cursor-position semantics; use --output-limit <n> separately to bound returned rows.","--check-only":"--check-only retains health side-effect semantics; --output-include does not suppress vector refresh.","--collapse":"--collapse retains dependency grouping semantics; --output-include does not replace it.","--depth":"--depth retains traversal or detail-depth semantics; --output-limit does not replace it.","--follow":"--follow retains event-tail semantics; --output-format does not enable following.","--max-depth":"--max-depth retains graph traversal-depth semantics; --output-limit does not replace it.","--max-paths":"--max-paths retains graph path-search semantics; use --output-limit separately to bound returned rows.","--no-truncate":"--no-truncate is a compatibility alias; prefer --output-limit unbounded.","--offset":"--offset retains positional pagination semantics; use --output-limit separately to bound returned rows.","--stream":"--stream retains command streaming semantics; --output-format selects only static result encoding.","--unbounded":"--unbounded is a compatibility alias; prefer --output-limit unbounded."});function flagSelector(flag){return flag.slice(2).replaceAll("-","_")}function migrationHint(flag,dimension){const behaviorHint=BEHAVIOR_PRESERVING_MIGRATION_HINTS[flag];if(behaviorHint!==void 0)return behaviorHint;const suffix=dimension==="include"?VALUE_BEARING_INCLUDE_ALIASES.has(flag)?"<csv>":flagSelector(flag):dimension==="amount"?"<n>":dimension==="cost"?"<tokens>":"<toon|json>";return`${flag} is a compatibility alias; prefer ${CANONICAL_OPTIONS[dimension]} ${suffix}.`}function buildSurfaceContract(command){const legacy=LEGACY_FLAGS_BY_COMMAND[command],dimensions=Object.freeze(Object.fromEntries(PM_READ_OUTPUT_DIMENSIONS.map(dimension=>[dimension,Object.freeze({dimension,canonical_option:CANONICAL_OPTIONS[dimension],applicable:!0,inapplicable_reason:null,legacy_aliases:Object.freeze((legacy[dimension]??[]).map(flag=>Object.freeze({flag,semantics:BEHAVIOR_PRESERVING_MIGRATION_HINTS[flag]===void 0?"replacement":"behavior_preserving",migration_hint:migrationHint(flag,dimension),visibility:"hidden_alias"})))})])));return Object.freeze({command,dimensions,precedence:READ_OUTPUT_PRECEDENCE,budget_retention_policy:command==="assurance"?"verdict_priority":"ordered_prefix",projection_modes:Object.freeze([...readOutputIncludeModeOptions(command).keys()])})}const PM_READ_OUTPUT_SURFACE_CONTRACTS=Object.freeze(PM_READ_OUTPUT_SURFACES.map(buildSurfaceContract)),SURFACE_CONTRACT_BY_COMMAND=new Map(PM_READ_OUTPUT_SURFACE_CONTRACTS.map(contract=>[contract.command,contract]));function resolveReadOutputSurface(command,options={}){const normalizedCommand=resolvePmHistoryOperation(command.trim().toLowerCase()),root=normalizedCommand==="package catalog"||normalizedCommand==="packages catalog"||normalizedCommand==="package-catalog"||(normalizedCommand==="package"||normalizedCommand==="packages"||normalizedCommand==="extension")&&(options.catalog===!0||options.target==="catalog"||options.action==="catalog")?"package-catalog":normalizedCommand==="package manage"||normalizedCommand==="package-manage"?"package-manage":normalizedCommand.split(" ")[0],normalized=root.startsWith("list-")?"list":root==="ctx"?"context":root;return PM_READ_OUTPUT_SURFACES.includes(normalized)?normalized:void 0}const CANONICAL_OPTION_KEYS=["outputInclude","output_include","outputLimit","output_limit","outputBudget","output_budget","outputFormat","output_format","outputSession","output_session","outputCursor","output_cursor","outputRowContract","output_row_contract"],HYBRID_READ_MUTATION_KEYS={comments:["add","body","stdin","file","edit","delete"],notes:["add","addJson","stdin","file","edit","delete"],files:["add","addGlob","remove","migrate","apply","note"],docs:["add","addGlob","remove","migrate","note"],"package-catalog":["activate","adopt","adoptAll","deactivate","doctor","init","install","manage","migrate","reload","scaffold","uninstall"]};function hasCanonicalReadOutputOptions(options){return CANONICAL_OPTION_KEYS.some(key=>key!=="outputFormat"&&key!=="output_format"&&options[key]!==void 0)}const READ_OUTPUT_VALUE_VALIDATORS=[{keys:["outputInclude","output_include"],valid:value=>stringList(value)!==void 0,message:"--output-include requires at least one comma-separated field or section."},{keys:["outputLimit","output_limit"],valid:value=>value==="unbounded"||positiveInteger(value)!==void 0,message:"--output-limit must be a positive integer or unbounded."},{keys:["outputBudget","output_budget"],valid:value=>value==="unbounded"||positiveInteger(value)!==void 0,message:"--output-budget must be a positive integer or unbounded."},{keys:["outputSession","output_session"],valid:value=>(parseReadOutputSession(value),!0),message:"--output-session must be a valid session-state object."},{keys:["outputCursor","output_cursor"],valid:value=>typeof value=="string"&&value.trim().length>0,message:"--output-cursor requires a non-empty continuation cursor."}];function validateReadOutputOptions(command,options){const encoding=options.outputFormat??options.output_format;if(encoding!==void 0&&encoding!=="json"&&encoding!=="toon")throw new PmCliError("--output-format must be toon or json.",EXIT_CODE.USAGE);if(!hasCanonicalReadOutputOptions(options))return;const normalizedCommand=resolveReadOutputSurface(command,options);if(!normalizedCommand)throw new PmCliError(`Universal output controls apply only to read commands; ${command||"this command"} is not a read surface.`,EXIT_CODE.USAGE);if((HYBRID_READ_MUTATION_KEYS[normalizedCommand]??[]).some(key=>options[key]!==void 0&&options[key]!==!1))throw new PmCliError(`Universal output controls cannot be combined with a ${normalizedCommand} mutation.`,EXIT_CODE.USAGE);for(const validator of READ_OUTPUT_VALUE_VALIDATORS){const value=validator.keys.map(key=>options[key]).find(entry=>entry!==void 0);if(value!==void 0&&!validator.valid(value))throw new PmCliError(validator.message,EXIT_CODE.USAGE)}}function readOutputIncludeModeOptions(command){const surface=resolveReadOutputSurface(command);return surface?new Map((LEGACY_FLAGS_BY_COMMAND[surface].include??[]).filter(flag=>!VALUE_BEARING_INCLUDE_ALIASES.has(flag)&&BEHAVIOR_PRESERVING_MIGRATION_HINTS[flag]===void 0).map(flag=>[flagSelector(flag),optionKey(flag)])):new Map}function applyReadOutputIncludeModes(command,includeValue,commandOptions){const requested=stringList(includeValue)??[],modeOptions=readOutputIncludeModeOptions(command),selectors=[],modes=[],optionsWithProvenance=commandOptions,existingProvenance=optionsWithProvenance[READ_OUTPUT_INVOCATION_PROVENANCE],canonicalModes=new Set(existingProvenance?.canonical_include_modes??[]),explicitLegacyAliases=new Set(existingProvenance?.explicit_legacy_aliases??[]);for(const token of requested){const option=modeOptions.get(token);if(option===void 0){selectors.push(token);continue}const legacyFlag=`--${token.replaceAll("_","-")}`;isRequestedOption(readOption(commandOptions,legacyFlag))&&explicitLegacyAliases.add(legacyFlag),commandOptions[option]=!0,modes.push(token),canonicalModes.add(token)}const forwardedGetFieldSelectors=resolveReadOutputSurface(command)==="get"?selectors.filter(selector=>selector!=="item"):[],forwardedGetFields=forwardedGetFieldSelectors.length>0;return forwardedGetFields&&(commandOptions.fields=[...new Set([...stringList(commandOptions.fields)??[],...forwardedGetFieldSelectors])].join(","),canonicalModes.add("fields")),(modes.length>0||forwardedGetFields)&&(optionsWithProvenance[READ_OUTPUT_INVOCATION_PROVENANCE]={canonical_include_modes:[...canonicalModes],explicit_legacy_aliases:[...explicitLegacyAliases],...existingProvenance?.cli_invocation_observed===!0?{cli_invocation_observed:!0}:{}}),{selectors,modes}}function normalizeReadOutputIncludeModeOptions(command,options){const include=options.outputInclude??options.output_include;if(include===void 0)return;const{selectors,modes}=applyReadOutputIncludeModes(command,include,options);if(modes.length===0)return;const residual=selectors.length>0?selectors.join(","):void 0;options.outputInclude=residual,Object.hasOwn(options,"output_include")&&(options.output_include=residual)}function optionKey(flag){return flag.slice(2).replace(/-([a-z])/gu,(_,character)=>character.toUpperCase())}function readOption(options,flag){const key=optionKey(flag);if(Object.hasOwn(options,key))return options[key];const snakeKey=flag.slice(2).replaceAll("-","_");if(Object.hasOwn(options,snakeKey))return options[snakeKey];if(flag==="--no-truncate"&&options.truncate===!1)return!0}function isRequestedOption(value){return value!==void 0&&value!==!1&&value!==null}function stringList(value){const normalized=(Array.isArray(value)?value:[value]).flatMap(entry=>typeof entry=="string"?entry.split(","):[]).map(entry=>entry.trim()).filter(Boolean);return normalized.length>0?[...new Set(normalized)]:void 0}function positiveInteger(value){const parsed=typeof value=="number"?value:typeof value=="string"&&/^\d+$/u.test(value.trim())?Number(value):Number.NaN;return Number.isSafeInteger(parsed)&&parsed>0?parsed:void 0}function resolveLegacyDimension(contract,options,usable,ignore){for(const alias of contract.legacy_aliases){if(ignore(alias.flag))continue;const value=readOption(options,alias.flag),candidate={value,flag:alias.flag};if(isRequestedOption(value)&&usable(candidate))return candidate}}function resolveIncludeValue(canonical,legacy){const canonicalList=stringList(canonical);if(canonicalList)return{source:"canonical",value:canonicalList};if(legacy)return{source:"legacy",value:stringList(legacy.value)??[flagSelector(legacy.flag)]}}function resolveAmountValue(canonical,legacy){if(canonical==="unbounded")return{source:"canonical",value:"unbounded"};const canonicalLimit=positiveInteger(canonical);if(canonicalLimit!==void 0)return{source:"canonical",value:canonicalLimit};if(!legacy)return;if(legacy.flag==="--no-truncate"||legacy.flag==="--unbounded")return{source:"legacy",value:"unbounded"};const legacyLimit=positiveInteger(legacy.value);return legacyLimit===void 0?void 0:{source:"legacy",value:legacyLimit}}function resolveCostValue(canonical,legacy){if(canonical==="unbounded")return{source:"canonical",value:"unbounded"};const canonicalBudget=positiveInteger(canonical);if(canonicalBudget!==void 0)return{source:"canonical",value:canonicalBudget};if(!legacy)return;const legacyBudget=positiveInteger(legacy.value);return legacyBudget===void 0?void 0:{source:"legacy",value:legacyBudget}}function resolveEncodingValue(canonical,legacy){if(canonical==="json"||canonical==="toon")return{source:"canonical",value:canonical};if(legacy)return legacy.flag==="--stream"||legacy.flag==="--follow"?{source:"legacy",value:"stream"}:legacy.value==="json"||legacy.value==="toon"?{source:"legacy",value:legacy.value}:void 0}function shouldIgnoreReadOutputLegacyAlias(provenance,dimension,flag){if(!provenance)return!1;const explicitLegacyAliases=new Set(provenance.explicit_legacy_aliases);if(provenance.cli_invocation_observed===!0||provenance.sdk_invocation_observed===!0)return!explicitLegacyAliases.has(flag);const forwardedIncludeAliases=new Set(provenance.canonical_include_modes.map(mode=>`--${mode.replaceAll("_","-")}`));return dimension==="include"&&forwardedIncludeAliases.has(flag)&&!explicitLegacyAliases.has(flag)}function hasCompleteReadOutputIntent(command,legacyByDimension,provenance){return command.trim().toLowerCase().replaceAll(/\s+/gu," ").split(" ")[0]==="list-all"||legacyByDimension.amount?.flag==="--no-truncate"||legacyByDimension.include?.flag==="--full"||provenance?.canonical_include_modes.includes("full")===!0}function canonicalReadOutputOptionsUsed(resolvedByDimension,provenance){return PM_READ_OUTPUT_DIMENSIONS.flatMap(dimension=>resolvedByDimension[dimension]?.source==="canonical"||dimension==="include"&&(provenance?.canonical_include_modes.length??0)>0?[CANONICAL_OPTIONS[dimension]]:[])}function resolveReadOutputDimensions(command,options){const normalizedCommand=resolveReadOutputSurface(command,options);if(!normalizedCommand)return;const contract=SURFACE_CONTRACT_BY_COMMAND.get(normalizedCommand),invocationProvenance=options[READ_OUTPUT_INVOCATION_PROVENANCE],legacyResolvers={include:candidate=>resolveIncludeValue(void 0,candidate),amount:candidate=>resolveAmountValue(void 0,candidate),cost:candidate=>resolveCostValue(void 0,candidate),encoding:candidate=>resolveEncodingValue(void 0,candidate)},legacyByDimension=Object.fromEntries(PM_READ_OUTPUT_DIMENSIONS.map(dimension=>[dimension,resolveLegacyDimension(contract.dimensions[dimension],options,candidate=>legacyResolvers[dimension](candidate)!==void 0,flag=>shouldIgnoreReadOutputLegacyAlias(invocationProvenance,dimension,flag))])),legacyAliasesUsed=PM_READ_OUTPUT_DIMENSIONS.flatMap(dimension=>{const resolved=legacyByDimension[dimension];return resolved?[resolved.flag]:[]}),migrationHints=PM_READ_OUTPUT_DIMENSIONS.flatMap(dimension=>{const resolved=legacyByDimension[dimension];return resolved?[contract.dimensions[dimension].legacy_aliases.find(entry=>entry.flag===resolved.flag).migration_hint]:[]}),encoding=resolveEncodingValue(options.outputFormat??options.output_format,legacyByDimension.encoding),include=resolveIncludeValue(options.outputInclude??options.output_include,legacyByDimension.include),amount=resolveAmountValue(options.outputLimit??options.output_limit,legacyByDimension.amount),explicitCost=resolveCostValue(options.outputBudget??options.output_budget,legacyByDimension.cost),completeResultIntent=hasCompleteReadOutputIntent(command,legacyByDimension,invocationProvenance),budget=resolvePmCommandOutputBudget(command,{generateFallback:!0}),resolvedOutputFormat=encoding?.value==="json"||options.resolvedOutputFormat==="json"?"json":"toon",cost=explicitCost??(completeResultIntent?{source:"intent",value:"unbounded"}:{source:"default",value:budget.default_max_estimated_tokens_by_format[resolvedOutputFormat]});return{command:normalizedCommand,include,amount,cost,encoding,canonical_options_used:canonicalReadOutputOptionsUsed({include,amount,cost,encoding},invocationProvenance),legacy_aliases_used:legacyAliasesUsed,migration_hints:migrationHints,precedence:READ_OUTPUT_PRECEDENCE}}function isRecord(value){return value!==null&&typeof value=="object"&&!Array.isArray(value)}const ENVELOPE_KEYS=new Set(["applied_bound","applied_limit","completeness","continuation_kind","continuation_path","continuation_contract","count","filters","has_more","next_cursor","now","omission_receipt","projection","budget_retention_policy","row_contract","sorting","total","truncated"]),GET_STABLE_DERIVED_ITEM_SELECTORS=["collection_counts","notes_count","tests_count"];function projectRecordFields(value,selectors){const selected=new Set(selectors.map(selector=>selector.split(".")[0]));return Object.fromEntries(Object.entries(value).filter(([key])=>selected.has(key)))}function getProjectionVocabulary(result){const item=isRecord(result.item)?result.item:{},itemFields=[...new Set([...Object.keys(item),...GET_STABLE_DERIVED_ITEM_SELECTORS.filter(key=>Object.hasOwn(item,key))])].sort((left,right)=>left.localeCompare(right)),sections=Object.keys(result).filter(key=>key!=="item"&&key!=="read_output"&&!ENVELOPE_KEYS.has(key)).sort((left,right)=>left.localeCompare(right));return{item,itemFields,sections,valid:[...itemFields,"item",...itemFields.map(field=>`item.${field}`),...sections]}}function applyGetIncludeProjection(result,selectors){const vocabulary=getProjectionVocabulary(result),unknown=selectors.filter(selector=>!vocabulary.valid.includes(selector));if(unknown.length>0)throw new PmCliError(`Unknown --output-include selector(s) for get: ${unknown.join(", ")}. Valid selectors: ${vocabulary.valid.join(", ")}.`,EXIT_CODE.USAGE);const fullItem=selectors.includes("item"),itemSelectors=selectors.flatMap(selector=>selector.startsWith("item.")?[selector.slice(5)]:vocabulary.itemFields.includes(selector)?[selector]:[]).filter((selector,index,values)=>values.indexOf(selector)===index);if(fullItem&&itemSelectors.length>0)throw new PmCliError("--output-include cannot mix a full item with projected item fields; use item or item.<field>, not both.",EXIT_CODE.USAGE);const selectedSections=new Set(selectors.filter(selector=>vocabulary.sections.includes(selector))),projected=Object.fromEntries(Object.entries(result).filter(([key])=>ENVELOPE_KEYS.has(key)||selectedSections.has(key)));fullItem?projected.item=vocabulary.item:itemSelectors.length>0&&(projected.item=projectRecordFields(vocabulary.item,itemSelectors));const omittedFieldGroups=[...fullItem?[]:itemSelectors.length>0?vocabulary.itemFields.filter(field=>!itemSelectors.includes(field)).map(field=>({name:`item.${field}`,restore_with:`--output-include item.${field}`})):[{name:"item",restore_with:"--output-include item"}],...vocabulary.sections.filter(section=>!selectedSections.has(section)).map(section=>({name:section,restore_with:`--output-include ${section}`}))],combinedOmittedFieldGroups=[...isRecord(projected.omission_receipt)&&Array.isArray(projected.omission_receipt.omitted_field_groups)?projected.omission_receipt.omitted_field_groups:[],...omittedFieldGroups];return projected.omission_receipt={has_omissions:combinedOmittedFieldGroups.length>0,omitted_field_group_count:combinedOmittedFieldGroups.length,omitted_field_groups:combinedOmittedFieldGroups},projected}function countPopulatedRows(result){let populated=0;return mapReadOutputRows({...result},entry=>(isRecord(entry)&&Object.keys(entry).length>0&&(populated+=1),entry)),populated}function rejectEmptyIncludeProjection(command,original,shaped,selectors){if(countPopulatedRows(original)===0||countPopulatedRows(shaped)>0)return;const modes=[...readOutputIncludeModeOptions(command).keys()],domain=modes.length>0?` Declared ${command} projection modes: ${modes.join(", ")}.`:` The ${command} surface declares no projection modes; name row fields instead.`;throw new PmCliError(`Unknown --output-include selector(s) for ${command}: ${selectors.join(", ")}. No selector matched any returned row field.${domain}`,EXIT_CODE.USAGE)}function applyIncludeProjection(command,result,selectors){if(command==="get")return applyGetIncludeProjection(result,selectors);const rows=readOutputRowPaths(result),qualifiedRowSelectors=selectors.flatMap(selector=>rows.flatMap(rowPath=>selector.startsWith(`${rowPath}.`)?[selector.slice(rowPath.length+1)]:[])),selectedRoot=selectors.some(selector=>Object.hasOwn(result,selector.split(".")[0])&&!rows.some(rowPath=>selector.startsWith(`${rowPath}.`)));if(rows.length>0&&(!selectedRoot||qualifiedRowSelectors.length>0)){const projected={...result},rowSelectors=qualifiedRowSelectors.length>0?qualifiedRowSelectors:selectors,shaped=mapReadOutputRows(projected,entry=>isRecord(entry)?projectRecordFields(entry,rowSelectors):entry);return rejectEmptyIncludeProjection(command,result,shaped,rowSelectors),shaped}return Object.fromEntries(Object.entries(result).filter(([key])=>selectors.some(selector=>selector.split(".")[0]===key)||ENVELOPE_KEYS.has(key)))}function applyAmountBound(result,amount){if(amount==="unbounded")return result;const{result:bounded,truncated}=boundReadOutputRows(result,amount);if(!truncated)return bounded;if(bounded.has_more=!0,bounded.truncated=!0,typeof bounded.count=="number"){const activeRowKey=isRecord(bounded.projection)?bounded.projection.row_key:void 0;bounded.count=typeof activeRowKey=="string"&&Array.isArray(bounded[activeRowKey])?bounded[activeRowKey].length:countReadOutputRows(bounded)}return bounded.applied_bound={kind:"output_limit",source:"explicit",value:amount},bounded}function requestedDimensions(resolved){return PM_READ_OUTPUT_DIMENSIONS.filter(dimension=>resolved[dimension]!==void 0&&resolved[dimension]?.source!=="default"||resolved.canonical_options_used.includes(CANONICAL_OPTIONS[dimension]))}function readOutputMeasurementFormat(options){const format=options.resolvedOutputFormat??options.outputFormat??options.output_format??options.format;return format==="json"||format==="toon"?format:void 0}function attachReadOutputSessionContracts(result,state,receipt,format){let withSession=attachReadOutputSessionReceipt(result,state,format);preserveReadOutputRowContract(result,withSession);for(let iteration=0;iteration<8;iteration+=1){const previousReadEstimate=receipt.estimated_tokens,previousSessionEstimate=withSession.read_session.spent_this_call_tokens;updateReadOutputReceiptEstimate(withSession,receipt,format);const previous=withSession;withSession=attachReadOutputSessionReceipt(withSession,state,format),preserveReadOutputRowContract(previous,withSession);const sessionEstimate=withSession.read_session.spent_this_call_tokens;if(receipt.estimated_tokens===previousReadEstimate&&sessionEstimate===previousSessionEstimate)return withSession}return withSession}function stabilizeReadOutputReceiptEstimates(result,options){if(!isRecord(result.read_output))return result;const format=readOutputMeasurementFormat(options),receipt=result.read_output,session=parseReadOutputSession(options.outputSession??options.output_session);return session===void 0?(updateReadOutputReceiptEstimate(result,receipt,format),result):attachReadOutputSessionContracts(result,session,receipt,format)}function attachValidateDiagnosticRowContract(command,result){if(command!=="validate")return result;const projection=isRecord(result.projection)?result.projection:void 0;if(!(Array.isArray(projection?.declared_field_groups)?projection.declared_field_groups:[]).some(group=>isRecord(group)&&group.name==="diagnostic_rows"))return result;const diagnosticCollectionPaths=[...new Set(readOutputBudgetCollections(result).map(({path})=>path).filter(path=>/^checks\.\d+\.details\./u.test(path)))],diagnosticRowKeys=diagnosticCollectionPaths.filter(path=>!diagnosticCollectionPaths.some(candidate=>candidate!==path&&path.startsWith(`${candidate}.`)));if(diagnosticRowKeys.length===0)return result;const existingContract=isRecord(result.row_contract)?result.row_contract:{},existingRowKeys=Array.isArray(existingContract.row_keys)?existingContract.row_keys.filter(entry=>typeof entry=="string"):[],existingContinuationRowKeys=Array.isArray(existingContract.continuation_row_keys)?existingContract.continuation_row_keys.filter(entry=>typeof entry=="string"):[],rowKeys=existingRowKeys.length>0?existingRowKeys:diagnosticRowKeys,continuationRowKeys=[...new Set(diagnosticRowKeys)];return JSON.stringify(rowKeys)===JSON.stringify(existingRowKeys)&&JSON.stringify(continuationRowKeys)===JSON.stringify(existingContinuationRowKeys)?result:{...result,row_contract:{...existingContract,row_keys:rowKeys,continuation_row_keys:continuationRowKeys,jq_selector:typeof existingContract.jq_selector=="string"?existingContract.jq_selector:".checks[].details"}}}function projectReadOutputRows(result,resolved,session,cursor){let projected={...result};if(resolved.include?.source==="canonical"&&(projected=applyIncludeProjection(resolved.command,projected,resolved.include.value)),resolved.command==="assurance"&&(projected=prioritizeAssuranceAssertions(projected)),refreshReadOutputDeliveredCounts(projected,result),projected=applyReadOutputContinuation(projected,resolved.command,cursor),resolved.command==="history"&&cursor){const historyRowKeys=["compact_history","provenance_history","history","diff"];if(projected=Object.fromEntries(Object.entries(projected).filter(([key])=>!historyRowKeys.includes(key)||key===cursor.path)),isRecord(projected.projection)&&(projected.projection={...projected.projection,row_key:cursor.path}),isRecord(projected.row_contract)){const rowContract=projected.row_contract;projected.row_contract={...rowContract,row_keys:[cursor.path],...Array.isArray(rowContract.continuation_row_keys)?{continuation_row_keys:[cursor.path]}:{}}}projected.count=Object.keys(projected[cursor.path]).length}const continuationSource=result.count_only===!0?{...projected,count_only:!0,count:result.count}:projected;return resolved.amount?.source==="canonical"&&(projected=applyAmountBound(projected,resolved.amount.value)),refreshReadOutputDeliveredCounts(projected,continuationSource),session===void 0?projected:applyReadOutputSessionReferences(projected,session)}function resolveBindingReadOutputBudget(resolved,session){return[...resolved.cost!==void 0&&resolved.cost.value!=="unbounded"&&(resolved.cost.source==="canonical"||resolved.cost.source==="default")?[{source:resolved.cost.source,tokens:resolved.cost.value}]:[],...session===void 0?[]:[{source:"session",tokens:readOutputSessionRemainingTokens(session)}]].sort((left,right)=>left.tokens-right.tokens)[0]}function canonicalReadOutputReceiptFields(resolved){const canonicalOptions=resolved.canonical_options_used;return canonicalOptions&&canonicalOptions.length>0?{canonical_options_used:canonicalOptions}:{}}function omitReadOutputForBudget(resolved,requested,session,bindingBudget,omittedResultEstimatedTokens,format){const minimalReceipt={contract_version:1,command:resolved.command,requested_dimensions:requested,...bindingBudget.source==="default"?{budget_source:bindingBudget.source,budget_tokens:bindingBudget.tokens}:{},precedence:resolved.precedence,...canonicalReadOutputReceiptFields(resolved),legacy_aliases_used:[],migration_hints:[],estimated_tokens:0,within_budget:!1,strings_compacted:!1,rows_compacted:!1,result_omitted:!0,...session===void 0?{omitted_result_estimated_tokens:omittedResultEstimatedTokens}:{}},omitted={output_budget_exceeded:{omitted_result:!0,reason:"requested_budget_infeasible",restore_with:"Unbounded",recovery:{outputBudget:"unbounded"}},read_output:minimalReceipt},boundedOmission=session===void 0?omitted:attachReadOutputSessionContracts(omitted,session,minimalReceipt,format);if(session===void 0&&updateReadOutputReceiptEstimate(boundedOmission,minimalReceipt,format),session!==void 0&&minimalReceipt.estimated_tokens>bindingBudget.tokens)throw new PmCliError("The remaining output-session budget cannot fit its mandatory receipts; start a new session with a larger token_budget.",EXIT_CODE.USAGE);return boundedOmission}function requiresReadOutputAudit(resolved,options){return options.outputRowContract===!0||options.output_row_contract===!0||resolved.canonical_options_used.includes("--output-include")||resolved.command==="list"&&resolved.canonical_options_used.length>0&&resolved.include?.value.includes("full")===!0}function canReturnReadOutputUnchanged(resolved,session,result,format,options){if(session!==void 0||requiresReadOutputAudit(resolved,options))return!1;if(resolved.amount?.source==="canonical"&&resolved.amount.value!=="unbounded"){const limit=resolved.amount.value;if(readOutputRowCollections(result).some(({value})=>(Array.isArray(value)?value.length:Object.keys(value).length)>limit))return!1}return resolved.cost===void 0||resolved.cost.value==="unbounded"||resolved.cost.source==="legacy"||estimateReadOutputTokens(options.outputRowContract===!1?Object.fromEntries(Object.entries(result).filter(([key])=>key!=="row_contract")):result,format)<=resolved.cost.value}function attachReadOutputTruncationDisclosure(projected,resolved,receipt,bindingBudget,continuationCursorRebased,measuredResultTokens,collectionsBeforeBudget){if(!receipt.rows_compacted)return;const overridden=resolved.amount?.value==="unbounded"?["amount"]:[],afterByPath=new Map(readOutputContinuationRowCollections(projected).map(collection=>[collection.path,Array.isArray(collection.value)?collection.value.length:Object.keys(collection.value).length])),continuations=[...collectionsBeforeBudget.entries()].flatMap(([path,before])=>{const retainedRows=afterByPath.get(path);if(retainedRows>=before.rows)return[];const offset=before.baseOffset+retainedRows;return[{path,cursor:encodeReadOutputContinuationCursor({command:resolved.command,path,offset,total_rows:before.totalRows,fingerprint:before.fingerprint}),retained_rows:retainedRows,remaining_rows:before.totalRows-offset,total_rows:before.totalRows}]}),primary=continuations[0],continuationHint=primary?"; page --output-cursor":"",budgetHint=bindingBudget.source==="session"?`Truncated by the remaining ${bindingBudget.tokens}-token session budget; start a new output session with a larger token_budget${continuationHint}.`:`${bindingBudget.tokens}-token: raise --output-budget${continuationHint}`;receipt.migration_hints=[budgetHint,...resolved.migration_hints];const recoveryBudget=resolveReadOutputRecoveryBudget({effective_budget_tokens:bindingBudget.tokens,measured_result_tokens:measuredResultTokens});primary&&!continuationCursorRebased&&(typeof projected.next_cursor!="string"||projected.continuation_kind==="output_cursor")&&(projected.next_cursor=primary.cursor),projected.continuation_kind=continuationCursorRebased?"producer_cursor":primary?"output_cursor":"none",projected.output_budget_truncation={reason:"output_budget_reached",budget_source:bindingBudget.source,budget_tokens:bindingBudget.tokens,overridden_dimensions:overridden,compacted_row_paths:receipt.compacted_row_paths,continuation_cursor_rebased:continuationCursorRebased,continuation_available:continuations.length>0,recovery_budget_multiplier:primary?1:recoveryBudget.recovery_budget_multiplier,continuations,restore_with:primary?"recovery":`Retry with --output-budget ${recoveryBudget.output_budget} because no declared row collection can be continued.`,recovery:primary?{cursor:primary.cursor,cli:"--output-cursor",sdk:"outputCursor",mcp:"outputCursor"}:{cli:`--output-budget ${recoveryBudget.output_budget}`,sdk:{outputBudget:recoveryBudget.output_budget},mcp:{outputBudget:recoveryBudget.output_budget}}}}function rebaseBudgetCompactedCursor(projected,originalItemCount,cursorSource,cursorContinuesExistingPage){if(typeof cursorSource!="string"||!Array.isArray(projected.items))return!1;const retainedCount=projected.items.length;if(retainedCount===0||retainedCount>=originalItemCount)return!1;let cursor;try{cursor=decodeQueryCursorEnvelope(cursorSource)}catch{return!1}const sourceIndex=cursor.after_index;if(sourceIndex===void 0)return!1;const last=projected.items.at(-1);if(Object.prototype.toString.call(last)!=="[object Object]")return!1;const lastId=Reflect.get(last,"id");if(typeof lastId!="string"||lastId.length===0)return!1;const afterIndex=cursorContinuesExistingPage?sourceIndex-(originalItemCount-retainedCount):sourceIndex+retainedCount;return afterIndex<0?!1:(projected.next_cursor=encodeQueryCursor(cursor.fingerprint,lastId,afterIndex,cursor.snapshot),!0)}function captureReadOutputContinuationState(projected,command,cursor,options){const collectionsBeforeBudget=new Map(readOutputContinuationRowCollections(projected).map(collection=>{const rows=Array.isArray(collection.value)?collection.value.length:Object.keys(collection.value).length,continued=cursor?.path===collection.path;return[collection.path,{rows,totalRows:continued?cursor.total_rows:rows,baseOffset:continued?cursor.offset:0,fingerprint:continued?cursor.fingerprint:readOutputCollectionFingerprint(collection.path,collection.value,command)}]})),cursorContinuesExistingPage=typeof projected.next_cursor=="string";return{collectionsBeforeBudget,originalItemCount:Array.isArray(projected.items)?projected.items.length:0,cursorContinuesExistingPage,cursorSource:cursorContinuesExistingPage?projected.next_cursor:options.after}}function compactReadOutputProjection(projected,source,countOnly,resolved,receipt,bindingBudget,session,continuationState,measuredResultTokens,format){const deliveredSource={...source,count_only:countOnly},assuranceMinimumRows=resolved.command==="assurance"&&Array.isArray(projected.assertions)?projected.assertions.filter(row=>isRecord(row)&&row.verdict!=="pass").length:0,minimumRowsByPath=new Map;if(assuranceMinimumRows>0&&minimumRowsByPath.set("assertions",assuranceMinimumRows),resolved.command==="history"&&Array.isArray(projected.diff))for(const collection of readOutputBudgetCollections(projected))collection.path.startsWith("diff.")&&minimumRowsByPath.set(collection.path,Object.keys(collection.value).length);return compactReadOutputToBudget(projected,receipt,bindingBudget.tokens,minimumRowsByPath,format,compacted=>{refreshReadOutputDeliveredCounts(compacted,deliveredSource);const continuationCursorRebased=rebaseBudgetCompactedCursor(compacted,continuationState.originalItemCount,continuationState.cursorSource,continuationState.cursorContinuesExistingPage);if(attachReadOutputTruncationDisclosure(compacted,resolved,receipt,bindingBudget,continuationCursorRebased,measuredResultTokens,continuationState.collectionsBeforeBudget),resolved.command==="history"&&isRecord(compacted.projection)){compacted.has_more=typeof compacted.next_cursor=="string"||compacted.applied_bound?.kind==="output_limit";const rowKey=compacted.projection.row_key;typeof rowKey=="string"&&Array.isArray(compacted[rowKey])&&(compacted.count=compacted[rowKey].length)}session!==void 0&&Object.assign(compacted,attachReadOutputSessionContracts(compacted,session,receipt,format))},resolved.command==="history"&&Array.isArray(projected.diff))}function applyReadOutputDimensions(command,options,result){const resolved=resolveReadOutputDimensions(command,options);if(!resolved)return result;const format=readOutputMeasurementFormat(options),session=parseReadOutputSession(options.outputSession??options.output_session),rawCursor=options.outputCursor??options.output_cursor,cursor=typeof rawCursor=="string"?decodeReadOutputContinuationCursor(rawCursor):void 0,requested=requestedDimensions(resolved),continuationReadyResult=attachValidateDiagnosticRowContract(resolved.command,result);if(cursor===void 0&&canReturnReadOutputUnchanged(resolved,session,continuationReadyResult,format,options))return continuationReadyResult;const bindingBudget=resolveBindingReadOutputBudget(resolved,session);let projected=projectReadOutputRows(continuationReadyResult,resolved,session,cursor);preserveReadOutputRowContract(projected,projected,options.outputRowContract===!1);const receipt={contract_version:1,command:resolved.command,requested_dimensions:requested,...bindingBudget?.source==="default"?{budget_source:bindingBudget.source,budget_tokens:bindingBudget.tokens}:{},precedence:resolved.precedence,...canonicalReadOutputReceiptFields(resolved),legacy_aliases_used:resolved.legacy_aliases_used,migration_hints:resolved.migration_hints,estimated_tokens:0,within_budget:!0,strings_compacted:!1,rows_compacted:!1,result_omitted:!1};if(projected.read_output=receipt,projected=session===void 0?projected:attachReadOutputSessionContracts(projected,session,receipt,format),updateReadOutputReceiptEstimate(projected,receipt,format),bindingBudget!==void 0&&receipt.estimated_tokens>bindingBudget.tokens){const brief=projectReadOutputItemToBrief(resolved.command,options,projected);brief!==void 0&&(receipt.applied_depth="brief",receipt.degradation_reason="output_budget_reached",preserveReadOutputRowContract(projected,brief),projected=stabilizeReadOutputReceiptEstimates(brief,options)),receipt.estimated_tokens>bindingBudget.tokens&&(projected=compactReadOutputProjection(projected,projected,continuationReadyResult.count_only===!0,resolved,receipt,bindingBudget,session,captureReadOutputContinuationState(projected,resolved.command,cursor,options),receipt.estimated_tokens,format))}return bindingBudget!==void 0&&receipt.estimated_tokens>bindingBudget.tokens?omitReadOutputForBudget(resolved,requested,session,bindingBudget,receipt.estimated_tokens,format):projected}function isReadOutputBudgetExceeded(result){return isRecord(result)&&isRecord(result.output_budget_exceeded)&&result.output_budget_exceeded.omitted_result===!0&&result.output_budget_exceeded.reason==="requested_budget_infeasible"}function resolveReadOutputEncoding(command,options){const canonical=options.outputFormat??options.output_format;if(canonical==="json"||canonical==="toon")return canonical;const encoding=resolveReadOutputDimensions(command,options)?.encoding;return encoding?.value==="json"||encoding?.value==="toon"?encoding.value:void 0}export{PM_READ_OUTPUT_COMPOSITION_OPTION_FLAGS,PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES,PM_READ_OUTPUT_DIMENSIONS,PM_READ_OUTPUT_OPTION_FLAGS,PM_READ_OUTPUT_SURFACES,PM_READ_OUTPUT_SURFACE_CONTRACTS,applyReadOutputDimensions,applyReadOutputIncludeModes,decodeReadOutputContinuationCursor2 as decodeReadOutputContinuationCursor,encodeReadOutputContinuationCursor2 as encodeReadOutputContinuationCursor,isReadOutputBudgetExceeded,normalizeReadOutputIncludeModeOptions,readOutputCollectionFingerprint2 as readOutputCollectionFingerprint,readOutputIncludeModeOptions,resolveReadOutputDimensions,resolveReadOutputEncoding,resolveReadOutputRecoveryBudget2 as resolveReadOutputRecoveryBudget,resolveReadOutputSurface,stabilizeReadOutputReceiptEstimates,validateReadOutputOptions};
 //# sourceMappingURL=read-output-contracts.js.map

package/dist/sdk/read-output-rows.js

@@ -1,2 +1,2 @@
-!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d8631828-9fb8-5cdf-b448-43787147b44e")}catch(e2){}})();const BUDGET_METADATA_ROOT_KEYS=new Set(["applied_bound","completeness","budget_retention_policy","continuation_contract","continuation_kind","continuation_path","filters","omission_receipt","output_budget_truncation","projection","read_output","read_session","row_contract","sorting"]);function isRecord(value){return value!==null&&typeof value==="object"&&!Array.isArray(value)}function valueAtPath(result,rowPath){let value=result;for(const segment of rowPath.split(".")){if(Array.isArray(value)){if(!/^\d+$/u.test(segment))return void 0;value=value[Number(segment)]}else{if(!isRecord(value))return void 0;value=value[segment]}}return value}function replaceValueAtPath(result,rowPath,replacement){const segments=rowPath.split(".");const replace=(value,offset)=>{if(offset===segments.length)return replacement;const segment=segments[offset];if(Array.isArray(value)){const index=Number(segment);const cloned=[...value];cloned[index]=replace(value[index],offset+1);return cloned}const record=value;return{...record,[segment]:replace(record[segment],offset+1)}};return replace(result,0)}function sliceReadOutputRowCollection(result,rowPath,offset){const collection=readOutputContinuationRowCollections(result).find(entry=>entry.path===rowPath);if(!collection)return result;const replacement=Array.isArray(collection.value)?collection.value.slice(offset):Object.fromEntries(Object.entries(collection.value).slice(offset));const sliced=replaceValueAtPath(result,rowPath,replacement);if(isRecord(sliced.summary)&&isRecord(sliced.summary.focus_row_states)&&typeof sliced.summary.focus_row_states[rowPath]==="string"){sliced.summary={...sliced.summary,focus_row_states:{...sliced.summary.focus_row_states,[rowPath]:sliced.summary.focus_row_states[rowPath].slice(offset)}}}refreshReadOutputDeliveredCounts(sliced);return sliced}function readOutputRowPaths(result){const contract=result.row_contract;if(isRecord(contract)&&Array.isArray(contract.row_keys)){return contract.row_keys.filter(entry=>typeof entry==="string"&&entry.trim().length>0)}return Object.entries(result).filter(([,value])=>Array.isArray(value)).map(([key])=>key)}function readOutputContinuationRowPaths(result){const contract=result.row_contract;if(isRecord(contract)&&Array.isArray(contract.continuation_row_keys)){return contract.continuation_row_keys.filter(entry=>typeof entry==="string"&&entry.trim().length>0)}return readOutputRowPaths(result)}function readOutputRowCollections(result){return readOutputRowPaths(result).flatMap(rowPath=>{const value=valueAtPath(result,rowPath);return Array.isArray(value)||isRecord(value)?[{path:rowPath,value}]:[]})}function readOutputContinuationRowCollections(result){return readOutputContinuationRowPaths(result).flatMap(rowPath=>{const value=valueAtPath(result,rowPath);return Array.isArray(value)||isRecord(value)?[{path:rowPath,value}]:[]})}function readOutputBudgetCollections(result){const collections=readOutputRowCollections(result);const declaredPaths=new Set(collections.map(collection=>collection.path));const visit=(value,path)=>{if(Array.isArray(value)){if(!declaredPaths.has(path)){collections.push({path,value})}value.forEach((entry,index)=>visit(entry,`${path}.${index}`));return}if(!isRecord(value))return;for(const[key,entry]of Object.entries(value)){if(path.length===0&&BUDGET_METADATA_ROOT_KEYS.has(key))continue;visit(entry,path.length===0?key:`${path}.${key}`)}};visit(result,"");return collections}function countReadOutputRows(result){return readOutputRowCollections(result).reduce((total,collection)=>total+(Array.isArray(collection.value)?collection.value.length:Object.keys(collection.value).length),0)}function mapReadOutputRows(result,transform){let projected=result;for(const collection of readOutputRowCollections(projected)){const replacement=Array.isArray(collection.value)?collection.value.map((row,index)=>transform(row,collection.path,index)):Object.fromEntries(Object.entries(collection.value).map(([key,row],index)=>[key,transform(row,collection.path,index)]));projected=replaceValueAtPath(projected,collection.path,replacement)}return projected}function boundReadOutputRows(result,amount){let projected=result;let truncated=false;for(const collection of readOutputRowCollections(projected)){const entries=Array.isArray(collection.value)?collection.value:Object.entries(collection.value);if(entries.length<=amount)continue;truncated=true;const replacement=Array.isArray(collection.value)?entries.slice(0,amount):Object.fromEntries(entries.slice(0,amount));projected=replaceValueAtPath(projected,collection.path,replacement)}return{result:projected,truncated}}const FOCUS_KEYS=["high_level","low_level","blocked_fallback"];function focusRowState(row){const state=row.status==="in_progress"?"i":"o";return row.blocked===true?state.toUpperCase():state}function rememberReadOutputFocusRows(result,rows){if(!isRecord(result.summary)||!isRecord(result.summary.returned_focus))return;const byId=new Map(rows.map(row=>[row.id,row]));result.summary={...result.summary,focus_row_states:Object.fromEntries(FOCUS_KEYS.map(key=>[key,Array.isArray(result[key])?result[key].filter(isRecord).map(row=>focusRowState(byId.get(row.id)??row)).join(""):""]))}}function validatedFocusStates(value,rows){if(value===void 0)return void 0;if(typeof value!=="string"||value.length!==rows||!/^[iIoO]*$/u.test(value)){throw new TypeError("Context focus classification receipt must contain one i/I/o/O code per delivered record")}return value}function deliveredFocusSectionStates(result,source,key,sourceStates){const original=Array.isArray(source[key])?source[key].filter(isRecord):[];const originalStates=validatedFocusStates(sourceStates[key],original.length)??original.map(focusRowState).join("");const byId=new Map(original.flatMap((row,index)=>row.id===void 0?[]:[[row.id,originalStates[index]]]));const delivered=Array.isArray(result[key])?result[key].filter(isRecord):[];let needsStates=false;const states=delivered.map((row,index)=>{const state=byId.get(row.id)??(row.id===void 0?originalStates[index]:void 0)??focusRowState(row);if(state!==focusRowState(row))needsStates=true;return state}).join("");return{states,needsStates}}function refreshItemCount(result,source){if(typeof result.count!=="number")return;if(result.count_only===true||source.count_only===true){if(typeof source.count==="number")result.count=source.count}else if(Array.isArray(result.items)){result.count=result.items.length}}function refreshReadOutputDeliveredCounts(result,source=result){refreshItemCount(result,source);if(!isRecord(result.summary)||!isRecord(result.summary.returned_focus))return;const summary={...result.summary};const sourceStates=isRecord(source.summary)&&isRecord(source.summary.focus_row_states)?source.summary.focus_row_states:{};const sections=FOCUS_KEYS.map(key=>({key,...deliveredFocusSectionStates(result,source,key,sourceStates)}));const states=Object.fromEntries(sections.map(({key,states:states2})=>[key,states2]));const needsStates=sections.some(section=>section.needsStates);const deliveredStates=Object.values(states).join("");if(typeof summary.high_level==="number")summary.high_level=Array.isArray(result.high_level)?result.high_level.length:0;if(typeof summary.low_level==="number")summary.low_level=Array.isArray(result.low_level)?result.low_level.length:0;summary.returned_focus={active_items:deliveredStates.length,in_progress:[...deliveredStates].filter(state=>state.toLowerCase()==="i").length,open:[...deliveredStates].filter(state=>state.toLowerCase()==="o").length,blocked:[...deliveredStates].filter(state=>state===state.toUpperCase()).length};if(needsStates)summary.focus_row_states=states;else delete summary.focus_row_states;result.summary=summary}export{boundReadOutputRows,countReadOutputRows,mapReadOutputRows,readOutputBudgetCollections,readOutputContinuationRowCollections,readOutputContinuationRowPaths,readOutputRowCollections,readOutputRowPaths,refreshReadOutputDeliveredCounts,rememberReadOutputFocusRows,sliceReadOutputRowCollection};
+(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]="b6db58d1-5d89-56b2-adee-13e985ebc675")}catch{}})();const BUDGET_METADATA_ROOT_KEYS=new Set(["applied_bound","completeness","budget_retention_policy","continuation_contract","continuation_kind","continuation_path","filters","omission_receipt","output_budget_truncation","projection","read_output","read_session","row_contract","sorting"]);function isRecord(value){return value!==null&&typeof value=="object"&&!Array.isArray(value)}function valueAtPath(result,rowPath){let value=result;for(const segment of rowPath.split("."))if(Array.isArray(value)){if(!/^\d+$/u.test(segment))return;value=value[Number(segment)]}else{if(!isRecord(value))return;value=value[segment]}return value}function replaceValueAtPath(result,rowPath,replacement){const segments=rowPath.split("."),replace=(value,offset)=>{if(offset===segments.length)return replacement;const segment=segments[offset];if(Array.isArray(value)){const index=Number(segment),cloned=[...value];return cloned[index]=replace(value[index],offset+1),cloned}const record=value;return{...record,[segment]:replace(record[segment],offset+1)}};return replace(result,0)}function sliceReadOutputRowCollection(result,rowPath,offset){const collection=readOutputContinuationRowCollections(result).find(entry=>entry.path===rowPath);if(!collection)return result;const replacement=Array.isArray(collection.value)?collection.value.slice(offset):Object.fromEntries(Object.entries(collection.value).slice(offset)),sliced=replaceValueAtPath(result,rowPath,replacement);return isRecord(sliced.summary)&&isRecord(sliced.summary.focus_row_states)&&typeof sliced.summary.focus_row_states[rowPath]=="string"&&(sliced.summary={...sliced.summary,focus_row_states:{...sliced.summary.focus_row_states,[rowPath]:sliced.summary.focus_row_states[rowPath].slice(offset)}}),refreshReadOutputDeliveredCounts(sliced),sliced}function readOutputRowPaths(result){const contract=result.row_contract;return isRecord(contract)&&Array.isArray(contract.row_keys)?contract.row_keys.filter(entry=>typeof entry=="string"&&entry.trim().length>0):Object.entries(result).filter(([,value])=>Array.isArray(value)).map(([key])=>key)}function readOutputContinuationRowPaths(result){const contract=result.row_contract;return isRecord(contract)&&Array.isArray(contract.continuation_row_keys)?contract.continuation_row_keys.filter(entry=>typeof entry=="string"&&entry.trim().length>0):readOutputRowPaths(result)}function readOutputRowCollections(result){return readOutputRowPaths(result).flatMap(rowPath=>{const value=valueAtPath(result,rowPath);return Array.isArray(value)||isRecord(value)?[{path:rowPath,value}]:[]})}function readOutputContinuationRowCollections(result){return readOutputContinuationRowPaths(result).flatMap(rowPath=>{const value=valueAtPath(result,rowPath);return Array.isArray(value)||isRecord(value)?[{path:rowPath,value}]:[]})}function readOutputBudgetCollections(result){const collections=readOutputRowCollections(result),declaredPaths=new Set(collections.map(collection=>collection.path)),visit=(value,path)=>{if(Array.isArray(value)){declaredPaths.has(path)||collections.push({path,value}),value.forEach((entry,index)=>visit(entry,`${path}.${index}`));return}if(isRecord(value))for(const[key,entry]of Object.entries(value))path.length===0&&BUDGET_METADATA_ROOT_KEYS.has(key)||visit(entry,path.length===0?key:`${path}.${key}`)};return visit(result,""),collections}function countReadOutputRows(result){return readOutputRowCollections(result).reduce((total,collection)=>total+(Array.isArray(collection.value)?collection.value.length:Object.keys(collection.value).length),0)}function mapReadOutputRows(result,transform){let projected=result;for(const collection of readOutputRowCollections(projected)){const replacement=Array.isArray(collection.value)?collection.value.map((row,index)=>transform(row,collection.path,index)):Object.fromEntries(Object.entries(collection.value).map(([key,row],index)=>[key,transform(row,collection.path,index)]));projected=replaceValueAtPath(projected,collection.path,replacement)}return projected}function boundReadOutputRows(result,amount){let projected=result,truncated=!1;for(const collection of readOutputRowCollections(projected)){const entries=Array.isArray(collection.value)?collection.value:Object.entries(collection.value);if(entries.length<=amount)continue;truncated=!0;const replacement=Array.isArray(collection.value)?entries.slice(0,amount):Object.fromEntries(entries.slice(0,amount));projected=replaceValueAtPath(projected,collection.path,replacement)}return{result:projected,truncated}}const FOCUS_KEYS=["high_level","low_level","blocked_fallback"];function focusRowState(row){const state=row.status==="in_progress"?"i":"o";return row.blocked===!0?state.toUpperCase():state}function rememberReadOutputFocusRows(result,rows){if(!isRecord(result.summary)||!isRecord(result.summary.returned_focus))return;const byId=new Map(rows.map(row=>[row.id,row]));result.summary={...result.summary,focus_row_states:Object.fromEntries(FOCUS_KEYS.map(key=>[key,Array.isArray(result[key])?result[key].filter(isRecord).map(row=>focusRowState(byId.get(row.id)??row)).join(""):""]))}}function validatedFocusStates(value,rows){if(value!==void 0){if(typeof value!="string"||value.length!==rows||!/^[iIoO]*$/u.test(value))throw new TypeError("Context focus classification receipt must contain one i/I/o/O code per delivered record");return value}}function deliveredFocusSectionStates(result,source,key,sourceStates){const original=Array.isArray(source[key])?source[key].filter(isRecord):[],originalStates=validatedFocusStates(sourceStates[key],original.length)??original.map(focusRowState).join(""),byId=new Map(original.flatMap((row,index)=>row.id===void 0?[]:[[row.id,originalStates[index]]])),delivered=Array.isArray(result[key])?result[key].filter(isRecord):[];let needsStates=!1;return{states:delivered.map((row,index)=>{const state=byId.get(row.id)??(row.id===void 0?originalStates[index]:void 0)??focusRowState(row);return state!==focusRowState(row)&&(needsStates=!0),state}).join(""),needsStates}}function refreshItemCount(result,source){typeof result.count=="number"&&(result.count_only===!0||source.count_only===!0?typeof source.count=="number"&&(result.count=source.count):Array.isArray(result.items)&&(result.count=result.items.length))}function refreshReadOutputDeliveredCounts(result,source=result){if(refreshItemCount(result,source),!isRecord(result.summary)||!isRecord(result.summary.returned_focus))return;const summary={...result.summary},sourceStates=isRecord(source.summary)&&isRecord(source.summary.focus_row_states)?source.summary.focus_row_states:{},sections=FOCUS_KEYS.map(key=>({key,...deliveredFocusSectionStates(result,source,key,sourceStates)})),states=Object.fromEntries(sections.map(({key,states:states2})=>[key,states2])),needsStates=sections.some(section=>section.needsStates),deliveredStates=Object.values(states).join("");typeof summary.high_level=="number"&&(summary.high_level=Array.isArray(result.high_level)?result.high_level.length:0),typeof summary.low_level=="number"&&(summary.low_level=Array.isArray(result.low_level)?result.low_level.length:0),summary.returned_focus={active_items:deliveredStates.length,in_progress:[...deliveredStates].filter(state=>state.toLowerCase()==="i").length,open:[...deliveredStates].filter(state=>state.toLowerCase()==="o").length,blocked:[...deliveredStates].filter(state=>state===state.toUpperCase()).length},needsStates?summary.focus_row_states=states:delete summary.focus_row_states,result.summary=summary}export{boundReadOutputRows,countReadOutputRows,mapReadOutputRows,readOutputBudgetCollections,readOutputContinuationRowCollections,readOutputContinuationRowPaths,readOutputRowCollections,readOutputRowPaths,refreshReadOutputDeliveredCounts,rememberReadOutputFocusRows,sliceReadOutputRowCollection};
 //# sourceMappingURL=read-output-rows.js.map

package/dist/sdk/read-output-session.js

@@ -1,2 +1,2 @@
-!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="999accf0-d4e1-5dc4-92a0-4ea7d745ac48")}catch(e2){}})();import{estimateReadOutputTokens}from"./read-output-budget.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{mapReadOutputRows,readOutputRowCollections}from"./read-output-rows.js";const PM_READ_OUTPUT_SESSION_MIN_TOKENS=256;const PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS=1e4;const SESSION_ID_PATTERN=/^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/u;const ITEM_ID_PATTERN=/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;const SESSION_KEYS=new Set(["version","id","token_budget","spent_tokens","seen_item_ids"]);const SESSION_FIELD_VALIDATIONS=[{valid:state=>state.version===1,reason:"version must equal 1."},{valid:state=>typeof state.id==="string"&&SESSION_ID_PATTERN.test(state.id),reason:"id must be 1-64 portable identifier characters."},{valid:state=>Number.isSafeInteger(state.token_budget)&&state.token_budget>=PM_READ_OUTPUT_SESSION_MIN_TOKENS,reason:`token_budget must be a safe integer of at least ${PM_READ_OUTPUT_SESSION_MIN_TOKENS}.`},{valid:state=>Number.isSafeInteger(state.spent_tokens)&&state.spent_tokens>=0&&state.spent_tokens<=state.token_budget,reason:"spent_tokens must be a non-negative safe integer no larger than token_budget."},{valid:state=>Array.isArray(state.seen_item_ids)&&state.seen_item_ids.length<=PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS&&state.seen_item_ids.every(id=>typeof id==="string"&&ITEM_ID_PATTERN.test(id)),reason:`seen_item_ids must contain at most ${PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS} portable item identifiers.`}];function isRecord(value){return value!==null&&typeof value==="object"&&!Array.isArray(value)}function invalidSession(reason){throw new PmCliError(`--output-session ${reason}`,EXIT_CODE.USAGE,{code:"invalid_read_output_session",field:"outputSession"})}function parseReadOutputSession(value){if(value===void 0)return void 0;let parsed=value;if(typeof value==="string"){try{parsed=JSON.parse(value)}catch{invalidSession("must be a valid JSON object.")}}if(!isRecord(parsed))invalidSession("must be a JSON object.");const unknownKeys=Object.keys(parsed).filter(key=>!SESSION_KEYS.has(key));if(unknownKeys.length>0){invalidSession(`contains unknown field "${unknownKeys.sort()[0]}".`)}const invalidField=SESSION_FIELD_VALIDATIONS.find(validation=>!validation.valid(parsed));if(invalidField!==void 0)invalidSession(invalidField.reason);const seenItemIds=[...new Set(parsed.seen_item_ids)].sort();return{version:1,id:parsed.id,token_budget:parsed.token_budget,spent_tokens:parsed.spent_tokens,seen_item_ids:seenItemIds}}function itemIdFromRow(row){if(!isRecord(row))return void 0;if(typeof row.id==="string")return row.id;if(typeof row.item_id==="string")return row.item_id;return isRecord(row.item)&&typeof row.item.id==="string"?row.item.id:void 0}function summarizeReadOutputSessionRows(result){const deliveredIds=new Set;let suppressedRepeatCount=0;const collections=readOutputRowCollections(result);const declaredPaths=new Set(collections.map(({path})=>path));const additionalCollections=Object.entries(result).flatMap(([path,value])=>Array.isArray(value)&&!declaredPaths.has(path)?[{path,value}]:[]);for(const collection of[...collections,...additionalCollections]){const rows=Array.isArray(collection.value)?collection.value:Object.values(collection.value);for(const row of rows){if(!isRecord(row))continue;if(typeof row.context_ref==="string"){suppressedRepeatCount+=1;continue}const itemId=itemIdFromRow(row);if(itemId!==void 0&&ITEM_ID_PATTERN.test(itemId))deliveredIds.add(itemId)}}return{deliveredIds,suppressedRepeatCount}}function applyReadOutputSessionReferences(result,state){const seen=new Set(state.seen_item_ids);return mapReadOutputRows(result,row=>{const itemId=itemIdFromRow(row);return itemId!==void 0&&seen.has(itemId)?{id:itemId,context_ref:`session:${state.id}:${itemId}`}:row})}function attachReadOutputSessionReceipt(result,state,format){const{deliveredIds,suppressedRepeatCount}=summarizeReadOutputSessionRows(result);const alreadySeen=new Set(state.seen_item_ids);const newlySeen=[...deliveredIds].filter(id=>!alreadySeen.has(id)).sort();const retainedNewIds=newlySeen.slice(0,PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS-state.seen_item_ids.length);const nextSeen=[...state.seen_item_ids,...retainedNewIds].sort();const seenItemOverflowCount=newlySeen.length-retainedNewIds.length;const receipt={contract_version:1,id:state.id,measurement_scope:"complete_read_envelope",estimator:"ceil(utf8_bytes / 4)",token_budget:state.token_budget,spent_before_tokens:state.spent_tokens,spent_this_call_tokens:0,charged_this_call_tokens:0,spent_total_tokens:state.spent_tokens,remaining_tokens:state.token_budget-state.spent_tokens,exhausted:false,seen_before_count:state.seen_item_ids.length,new_item_count:deliveredIds.size,...seenItemOverflowCount===0?{}:{seen_item_overflow_count:seenItemOverflowCount},suppressed_repeat_count:suppressedRepeatCount,reference_format:"session:<session-id>:<item-id>",restore_reference_with:"pm get <item-id> --brief",next_state:{version:1,id:state.id,token_budget:state.token_budget,spent_tokens:state.spent_tokens,seen_item_ids:nextSeen}};const withReceipt={...result,read_session:receipt};const applyEstimate=estimate2=>{receipt.spent_this_call_tokens=estimate2;receipt.charged_this_call_tokens=Math.min(state.token_budget-state.spent_tokens,estimate2);receipt.spent_total_tokens=Math.min(state.token_budget,state.spent_tokens+receipt.charged_this_call_tokens);receipt.remaining_tokens=Math.max(0,state.token_budget-receipt.spent_total_tokens);receipt.exhausted=receipt.remaining_tokens<PM_READ_OUTPUT_SESSION_MIN_TOKENS;receipt.next_state.spent_tokens=receipt.spent_total_tokens};let estimate=0;let highestMeasuredEstimate=0;for(let iteration=0;iteration<8;iteration+=1){applyEstimate(estimate);const measured=estimateReadOutputTokens(withReceipt,format);if(measured===estimate)return withReceipt;highestMeasuredEstimate=Math.max(highestMeasuredEstimate,measured);estimate=measured}applyEstimate(highestMeasuredEstimate);return withReceipt}function readOutputSessionRemainingTokens(state){return Math.max(0,state.token_budget-state.spent_tokens)}export{PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS,PM_READ_OUTPUT_SESSION_MIN_TOKENS,applyReadOutputSessionReferences,attachReadOutputSessionReceipt,parseReadOutputSession,readOutputSessionRemainingTokens};
+(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]="f7d00f9c-6e95-5426-971d-9b30e2ec1652")}catch{}})();import{estimateReadOutputTokens}from"./read-output-budget.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{mapReadOutputRows,readOutputRowCollections}from"./read-output-rows.js";const PM_READ_OUTPUT_SESSION_MIN_TOKENS=256,PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS=1e4,SESSION_ID_PATTERN=/^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/u,ITEM_ID_PATTERN=/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u,SESSION_KEYS=new Set(["version","id","token_budget","spent_tokens","seen_item_ids"]),SESSION_FIELD_VALIDATIONS=[{valid:state=>state.version===1,reason:"version must equal 1."},{valid:state=>typeof state.id=="string"&&SESSION_ID_PATTERN.test(state.id),reason:"id must be 1-64 portable identifier characters."},{valid:state=>Number.isSafeInteger(state.token_budget)&&state.token_budget>=PM_READ_OUTPUT_SESSION_MIN_TOKENS,reason:`token_budget must be a safe integer of at least ${PM_READ_OUTPUT_SESSION_MIN_TOKENS}.`},{valid:state=>Number.isSafeInteger(state.spent_tokens)&&state.spent_tokens>=0&&state.spent_tokens<=state.token_budget,reason:"spent_tokens must be a non-negative safe integer no larger than token_budget."},{valid:state=>Array.isArray(state.seen_item_ids)&&state.seen_item_ids.length<=PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS&&state.seen_item_ids.every(id=>typeof id=="string"&&ITEM_ID_PATTERN.test(id)),reason:`seen_item_ids must contain at most ${PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS} portable item identifiers.`}];function isRecord(value){return value!==null&&typeof value=="object"&&!Array.isArray(value)}function invalidSession(reason){throw new PmCliError(`--output-session ${reason}`,EXIT_CODE.USAGE,{code:"invalid_read_output_session",field:"outputSession"})}function parseReadOutputSession(value){if(value===void 0)return;let parsed=value;if(typeof value=="string")try{parsed=JSON.parse(value)}catch{invalidSession("must be a valid JSON object.")}isRecord(parsed)||invalidSession("must be a JSON object.");const unknownKeys=Object.keys(parsed).filter(key=>!SESSION_KEYS.has(key));unknownKeys.length>0&&invalidSession(`contains unknown field "${unknownKeys.sort()[0]}".`);const invalidField=SESSION_FIELD_VALIDATIONS.find(validation=>!validation.valid(parsed));invalidField!==void 0&&invalidSession(invalidField.reason);const seenItemIds=[...new Set(parsed.seen_item_ids)].sort();return{version:1,id:parsed.id,token_budget:parsed.token_budget,spent_tokens:parsed.spent_tokens,seen_item_ids:seenItemIds}}function itemIdFromRow(row){if(isRecord(row))return typeof row.id=="string"?row.id:typeof row.item_id=="string"?row.item_id:isRecord(row.item)&&typeof row.item.id=="string"?row.item.id:void 0}function summarizeReadOutputSessionRows(result){const deliveredIds=new Set;let suppressedRepeatCount=0;const collections=readOutputRowCollections(result),declaredPaths=new Set(collections.map(({path})=>path)),additionalCollections=Object.entries(result).flatMap(([path,value])=>Array.isArray(value)&&!declaredPaths.has(path)?[{path,value}]:[]);for(const collection of[...collections,...additionalCollections]){const rows=Array.isArray(collection.value)?collection.value:Object.values(collection.value);for(const row of rows){if(!isRecord(row))continue;if(typeof row.context_ref=="string"){suppressedRepeatCount+=1;continue}const itemId=itemIdFromRow(row);itemId!==void 0&&ITEM_ID_PATTERN.test(itemId)&&deliveredIds.add(itemId)}}return{deliveredIds,suppressedRepeatCount}}function applyReadOutputSessionReferences(result,state){const seen=new Set(state.seen_item_ids);return mapReadOutputRows(result,row=>{const itemId=itemIdFromRow(row);return itemId!==void 0&&seen.has(itemId)?{id:itemId,context_ref:`session:${state.id}:${itemId}`}:row})}function attachReadOutputSessionReceipt(result,state,format){const{deliveredIds,suppressedRepeatCount}=summarizeReadOutputSessionRows(result),alreadySeen=new Set(state.seen_item_ids),newlySeen=[...deliveredIds].filter(id=>!alreadySeen.has(id)).sort(),retainedNewIds=newlySeen.slice(0,PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS-state.seen_item_ids.length),nextSeen=[...state.seen_item_ids,...retainedNewIds].sort(),seenItemOverflowCount=newlySeen.length-retainedNewIds.length,receipt={contract_version:1,id:state.id,measurement_scope:"complete_read_envelope",estimator:"ceil(utf8_bytes / 4)",token_budget:state.token_budget,spent_before_tokens:state.spent_tokens,spent_this_call_tokens:0,charged_this_call_tokens:0,spent_total_tokens:state.spent_tokens,remaining_tokens:state.token_budget-state.spent_tokens,exhausted:!1,seen_before_count:state.seen_item_ids.length,new_item_count:deliveredIds.size,...seenItemOverflowCount===0?{}:{seen_item_overflow_count:seenItemOverflowCount},suppressed_repeat_count:suppressedRepeatCount,reference_format:"session:<session-id>:<item-id>",restore_reference_with:"pm get <item-id> --brief",next_state:{version:1,id:state.id,token_budget:state.token_budget,spent_tokens:state.spent_tokens,seen_item_ids:nextSeen}},withReceipt={...result,read_session:receipt},applyEstimate=estimate2=>{receipt.spent_this_call_tokens=estimate2,receipt.charged_this_call_tokens=Math.min(state.token_budget-state.spent_tokens,estimate2),receipt.spent_total_tokens=Math.min(state.token_budget,state.spent_tokens+receipt.charged_this_call_tokens),receipt.remaining_tokens=Math.max(0,state.token_budget-receipt.spent_total_tokens),receipt.exhausted=receipt.remaining_tokens<PM_READ_OUTPUT_SESSION_MIN_TOKENS,receipt.next_state.spent_tokens=receipt.spent_total_tokens};let estimate=0,highestMeasuredEstimate=0;for(let iteration=0;iteration<8;iteration+=1){applyEstimate(estimate);const measured=estimateReadOutputTokens(withReceipt,format);if(measured===estimate)return withReceipt;highestMeasuredEstimate=Math.max(highestMeasuredEstimate,measured),estimate=measured}return applyEstimate(highestMeasuredEstimate),withReceipt}function readOutputSessionRemainingTokens(state){return Math.max(0,state.token_budget-state.spent_tokens)}export{PM_READ_OUTPUT_SESSION_MAX_SEEN_ITEM_IDS,PM_READ_OUTPUT_SESSION_MIN_TOKENS,applyReadOutputSessionReferences,attachReadOutputSessionReceipt,parseReadOutputSession,readOutputSessionRemainingTokens};
 //# sourceMappingURL=read-output-session.js.map

package/dist/sdk/relationship-analytics.js

@@ -1,2 +1,2 @@
-!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b3394526-5a20-5881-9a03-411ada32bd49")}catch(e2){}})();import{createQueryFingerprint,decodeQueryCursor,encodeQueryCursor}from"./pagination.js";import{createRelationshipKindRegistry}from"./relationships.js";function visitImpactNeighbor(state,id,parent,root,after,limit){if(state.seen.has(id))return"skip";if(state.cursorFound&&state.affected.length>=limit)return"truncate";state.seen.add(id);state.parents.set(id,parent.id);const depth=parent.depth+1;state.queue.push({id,depth});if(!state.cursorFound){state.cursorFound=id===after;return"skip"}state.affected.push({id,distance:depth,path:reconstructImpactPath(root,id,state.parents)});return"continue"}function resolveImpactCursor(root,options,direction,maxDepth){const fingerprint=createQueryFingerprint("graph impact",{root,direction,kinds:[...options.kinds??[]].sort(),max_depth:Number.isFinite(maxDepth)?maxDepth:"unbounded"});return{fingerprint,after:options.after===void 0?void 0:decodeQueryCursor(options.after,fingerprint)}}function appendNeighbor(adjacency,source,target){adjacency.get(source).add(target)}function createAdjacency(nodes){return new Map(nodes.map(node=>[node,new Set]))}function sortComponents(components){for(const component of components)component.sort();return components.sort((left,right)=>right.length-left.length||left[0].localeCompare(right[0]))}function stableJsonValue(value){if(Array.isArray(value))return value.map(entry=>stableJsonValue(entry));if(value===null||typeof value!=="object")return value;const toJSON=value.toJSON;if(typeof toJSON==="function")return stableJsonValue(toJSON.call(value));return Object.fromEntries(Object.entries(value).sort(([left],[right])=>left.localeCompare(right)).map(([key,entry])=>[key,stableJsonValue(entry)]))}function relationshipEdgeKey(edge){return JSON.stringify(stableJsonValue(edge))}function appendFinishingOrder(start,adjacency,visited,order){const stack=[{id:start,expanded:false}];while(stack.length>0){const current=stack.pop();if(current.expanded){order.push(current.id);continue}if(visited.has(current.id))continue;visited.add(current.id);stack.push({id:current.id,expanded:true});const neighbors=[...adjacency.get(current.id)].sort().reverse();for(const neighbor of neighbors)if(!visited.has(neighbor))stack.push({id:neighbor,expanded:false})}}function computeFinishingOrder(nodes,adjacency){const visited=new Set;const order=[];for(const start of nodes)if(!visited.has(start))appendFinishingOrder(start,adjacency,visited,order);return order}function collectReverseComponents(order,reverse){const visited=new Set;const components=[];for(const start of[...order].reverse()){if(visited.has(start))continue;const component=[];const stack=[start];visited.add(start);while(stack.length>0){const current=stack.pop();component.push(current);for(const neighbor of reverse.get(current)){if(visited.has(neighbor))continue;visited.add(neighbor);stack.push(neighbor)}}components.push(component)}return sortComponents(components)}function stronglyConnectedComponents(nodes,adjacency){const reverse=createAdjacency(nodes);for(const[source,targets]of adjacency)for(const target of targets)appendNeighbor(reverse,target,source);return collectReverseComponents(computeFinishingOrder(nodes,adjacency),reverse)}function buildExecutionAdjacency(graph,registry){const adjacency=createAdjacency(graph.nodes());for(const edge of graph.edges()){const definition=registry.require(edge.kind);if(!definition.ordering)continue;const sourceFirst=(definition.precedence??"source_before_target")==="source_before_target";appendNeighbor(adjacency,sourceFirst?edge.source:edge.target,sourceFirst?edge.target:edge.source)}return adjacency}function topologicalLayers(nodes,adjacency){const indegree=new Map(nodes.map(node=>[node,0]));for(const targets of adjacency.values())for(const target of targets)indegree.set(target,indegree.get(target)+1);let frontier=nodes.filter(node=>indegree.get(node)===0).sort();const layers=[];while(frontier.length>0){layers.push(frontier);const next=[];for(const source of frontier){for(const target of adjacency.get(source)){const remaining=indegree.get(target)-1;indegree.set(target,remaining);if(remaining===0)next.push(target)}}frontier=next.sort()}return layers}function longestPath(order,adjacency){const depth=new Map(order.map(node=>[node,0]));const parent=new Map;for(const source of order){for(const target of adjacency.get(source)){if(!depth.has(target))continue;const candidate=depth.get(source)+1;const currentParent=parent.get(target);if(candidate>depth.get(target)||candidate===depth.get(target)&&(currentParent===void 0||source.localeCompare(currentParent)<0)){depth.set(target,candidate);parent.set(target,source)}}}const end=[...order].sort((left,right)=>depth.get(right)-depth.get(left)||left.localeCompare(right))[0];const path=end===void 0?[]:[end];while(path[0]!==void 0&&parent.has(path[0]))path.unshift(parent.get(path[0]));return{depth:Object.fromEntries(depth),path}}function reconstructImpactPath(root,target,parents){const path=[target];let cursor=target;while(cursor!==root){cursor=parents.get(cursor);path.push(cursor)}return path.reverse()}function analyzeRelationshipExecution(graph,options={}){const registry=options.registry??createRelationshipKindRegistry();const nodes=[...graph.nodes()];const adjacency=buildExecutionAdjacency(graph,registry);const layers=topologicalLayers(nodes,adjacency);const order=layers.flat();const acyclic=order.length===nodes.length;const cycles=acyclic?[]:stronglyConnectedComponents(nodes,adjacency).filter(component=>component.length>1||adjacency.get(component[0]).has(component[0]));const longest=longestPath(order,adjacency);return{exact:true,acyclic,order,layers,frontier:layers[0]??[],depth:longest.depth,criticalPath:longest.path,criticalPathLength:Math.max(0,longest.path.length-1),cycles,provenance:{algorithm:"kahn-longest-path",edgeFamily:"ordering"}}}function buildImpactAdjacency(graph,direction,kinds){const adjacency=createAdjacency(graph.nodes());const selectedKinds=kinds===void 0?void 0:new Set(kinds.map(kind=>graph.registry().require(kind).kind));const edges=graph.edges();for(const edge of edges){const definition=graph.registry().require(edge.kind);if(selectedKinds!==void 0&&!selectedKinds.has(edge.kind)&&(definition.inverse===void 0||!selectedKinds.has(definition.inverse))){continue}appendNeighbor(adjacency,direction==="incoming"?edge.target:edge.source,direction==="incoming"?edge.source:edge.target)}return{adjacency,inspectedEdges:edges.length}}function analyzeBidirectionalGraphImpact(graph,root,options,after,limit,cursorFingerprint){const incoming=analyzeGraphImpact(graph,root,{...options,after:void 0,direction:"incoming",limit:void 0});const outgoing=analyzeGraphImpact(graph,root,{...options,after:void 0,direction:"outgoing",limit:void 0});const rows=new Map;const candidates=[...incoming.affected,...outgoing.affected].sort((left,right)=>left.distance-right.distance||left.id.localeCompare(right.id)||left.path.join("\0").localeCompare(right.path.join("\0")));for(const row of candidates){if(!rows.has(row.id)){rows.set(row.id,row)}}const ordered=[...rows.values()].sort((left,right)=>left.distance-right.distance||left.id.localeCompare(right.id));const afterIndex=after===void 0||after===root?-1:ordered.findIndex(row=>row.id===after);if(after!==void 0&&after!==root&&afterIndex<0){throw new TypeError(`Unknown impact cursor item: ${after}`)}const affected=ordered.slice(afterIndex+1,afterIndex+1+limit);const rowLimitTruncated=afterIndex+1+affected.length<ordered.length;return{root,affected,exact:true,truncated:incoming.truncated||outgoing.truncated||rowLimitTruncated,...rowLimitTruncated?{nextCursor:encodeQueryCursor(cursorFingerprint,affected.at(-1)?.id??root)}:{},cost:{visitedNodes:incoming.cost.visitedNodes+outgoing.cost.visitedNodes,inspectedEdges:incoming.cost.inspectedEdges+outgoing.cost.inspectedEdges}}}function analyzeUnidirectionalGraphImpact(graph,root,options){const direction=options.direction;const maxDepth=options.maxDepth??Number.POSITIVE_INFINITY;const limit=options.limit??Number.POSITIVE_INFINITY;const{fingerprint:cursorFingerprint,after}=resolveImpactCursor(root,options,direction,maxDepth);const{adjacency,inspectedEdges}=buildImpactAdjacency(graph,direction,options.kinds);const state={queue:[{id:root,depth:0}],seen:new Set([root]),parents:new Map,affected:[],cursorFound:after===void 0||after===root};let visitedNodes=0;let truncated=false;let rowLimitTruncated=false;traversal:for(let index=0;index<state.queue.length;index+=1){options.signal?.throwIfAborted();const current=state.queue[index];visitedNodes+=1;const adjacent=[...adjacency.get(current.id)].sort();if(current.depth>=maxDepth){if(adjacent.some(id=>!state.seen.has(id)))truncated=true;continue}for(const id of adjacent){const outcome=visitImpactNeighbor(state,id,current,root,after,limit);if(outcome==="truncate"){truncated=true;rowLimitTruncated=true;break traversal}}}if(!state.cursorFound){throw new TypeError(`Unknown impact cursor item: ${after}`)}return{root,affected:state.affected,exact:true,truncated,...rowLimitTruncated?{nextCursor:encodeQueryCursor(cursorFingerprint,state.affected.at(-1)?.id??root)}:{},cost:{visitedNodes,inspectedEdges}}}function analyzeGraphImpact(graph,root,options={}){const direction=options.direction??"outgoing";if(direction!=="both"){return analyzeUnidirectionalGraphImpact(graph,root,{...options,direction})}const maxDepth=options.maxDepth??Number.POSITIVE_INFINITY;const limit=options.limit??Number.POSITIVE_INFINITY;const{fingerprint,after}=resolveImpactCursor(root,options,direction,maxDepth);return analyzeBidirectionalGraphImpact(graph,root,options,after,limit,fingerprint)}function analyzeKnowledgeGraph(graph){const nodes=[...graph.nodes()];const weak=createAdjacency(nodes);const directed=createAdjacency(nodes);for(const edge of graph.edges()){appendNeighbor(weak,edge.source,edge.target);appendNeighbor(weak,edge.target,edge.source);appendNeighbor(directed,edge.source,edge.target)}const components=[];const visited=new Set;for(const start of nodes){if(visited.has(start))continue;const component=[];const stack=[start];visited.add(start);while(stack.length>0){const current=stack.pop();component.push(current);for(const neighbor of weak.get(current)){if(visited.has(neighbor))continue;visited.add(neighbor);stack.push(neighbor)}}components.push(component)}const degrees=nodes.map(id=>({id,degree:weak.get(id).size}));const maximum=Math.max(0,...degrees.map(({degree})=>degree));return{components:sortComponents(components),stronglyConnected:stronglyConnectedComponents(nodes,directed),orphans:degrees.filter(({degree})=>degree===0).map(({id})=>id),hubs:degrees.filter(({degree})=>degree>0&&degree===maximum),exact:true,provenance:{algorithm:"component-degree",edgeFamily:"all"}}}function compareRelationshipSnapshots(before,after){const earlier=new Map(before.edges.map(edge=>[relationshipEdgeKey(edge),edge]));const later=new Map(after.edges.map(edge=>[relationshipEdgeKey(edge),edge]));return{fromVersion:before.version,toVersion:after.version,added:[...later].filter(([key])=>!earlier.has(key)).map(([,edge])=>edge),removed:[...earlier].filter(([key])=>!later.has(key)).map(([,edge])=>edge),unchangedCount:[...earlier.keys()].filter(key=>later.has(key)).length,exact:true}}export{analyzeGraphImpact,analyzeKnowledgeGraph,analyzeRelationshipExecution,compareRelationshipSnapshots};
+(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]="403706c5-987d-5db1-95d2-b0eaded98e92")}catch{}})();import{createQueryFingerprint,decodeQueryCursor,encodeQueryCursor}from"./pagination.js";import{createRelationshipKindRegistry}from"./relationships.js";function visitImpactNeighbor(state,id,parent,root,after,limit){if(state.seen.has(id))return"skip";if(state.cursorFound&&state.affected.length>=limit)return"truncate";state.seen.add(id),state.parents.set(id,parent.id);const depth=parent.depth+1;return state.queue.push({id,depth}),state.cursorFound?(state.affected.push({id,distance:depth,path:reconstructImpactPath(root,id,state.parents)}),"continue"):(state.cursorFound=id===after,"skip")}function resolveImpactCursor(root,options,direction,maxDepth){const fingerprint=createQueryFingerprint("graph impact",{root,direction,kinds:[...options.kinds??[]].sort(),max_depth:Number.isFinite(maxDepth)?maxDepth:"unbounded"});return{fingerprint,after:options.after===void 0?void 0:decodeQueryCursor(options.after,fingerprint)}}function appendNeighbor(adjacency,source,target){adjacency.get(source).add(target)}function createAdjacency(nodes){return new Map(nodes.map(node=>[node,new Set]))}function sortComponents(components){for(const component of components)component.sort();return components.sort((left,right)=>right.length-left.length||left[0].localeCompare(right[0]))}function stableJsonValue(value){if(Array.isArray(value))return value.map(entry=>stableJsonValue(entry));if(value===null||typeof value!="object")return value;const toJSON=value.toJSON;return typeof toJSON=="function"?stableJsonValue(toJSON.call(value)):Object.fromEntries(Object.entries(value).sort(([left],[right])=>left.localeCompare(right)).map(([key,entry])=>[key,stableJsonValue(entry)]))}function relationshipEdgeKey(edge){return JSON.stringify(stableJsonValue(edge))}function appendFinishingOrder(start,adjacency,visited,order){const stack=[{id:start,expanded:!1}];for(;stack.length>0;){const current=stack.pop();if(current.expanded){order.push(current.id);continue}if(visited.has(current.id))continue;visited.add(current.id),stack.push({id:current.id,expanded:!0});const neighbors=[...adjacency.get(current.id)].sort().reverse();for(const neighbor of neighbors)visited.has(neighbor)||stack.push({id:neighbor,expanded:!1})}}function computeFinishingOrder(nodes,adjacency){const visited=new Set,order=[];for(const start of nodes)visited.has(start)||appendFinishingOrder(start,adjacency,visited,order);return order}function collectReverseComponents(order,reverse){const visited=new Set,components=[];for(const start of[...order].reverse()){if(visited.has(start))continue;const component=[],stack=[start];for(visited.add(start);stack.length>0;){const current=stack.pop();component.push(current);for(const neighbor of reverse.get(current))visited.has(neighbor)||(visited.add(neighbor),stack.push(neighbor))}components.push(component)}return sortComponents(components)}function stronglyConnectedComponents(nodes,adjacency){const reverse=createAdjacency(nodes);for(const[source,targets]of adjacency)for(const target of targets)appendNeighbor(reverse,target,source);return collectReverseComponents(computeFinishingOrder(nodes,adjacency),reverse)}function buildExecutionAdjacency(graph,registry){const adjacency=createAdjacency(graph.nodes());for(const edge of graph.edges()){const definition=registry.require(edge.kind);if(!definition.ordering)continue;const sourceFirst=(definition.precedence??"source_before_target")==="source_before_target";appendNeighbor(adjacency,sourceFirst?edge.source:edge.target,sourceFirst?edge.target:edge.source)}return adjacency}function topologicalLayers(nodes,adjacency){const indegree=new Map(nodes.map(node=>[node,0]));for(const targets of adjacency.values())for(const target of targets)indegree.set(target,indegree.get(target)+1);let frontier=nodes.filter(node=>indegree.get(node)===0).sort();const layers=[];for(;frontier.length>0;){layers.push(frontier);const next=[];for(const source of frontier)for(const target of adjacency.get(source)){const remaining=indegree.get(target)-1;indegree.set(target,remaining),remaining===0&&next.push(target)}frontier=next.sort()}return layers}function longestPath(order,adjacency){const depth=new Map(order.map(node=>[node,0])),parent=new Map;for(const source of order)for(const target of adjacency.get(source)){if(!depth.has(target))continue;const candidate=depth.get(source)+1,currentParent=parent.get(target);(candidate>depth.get(target)||candidate===depth.get(target)&&(currentParent===void 0||source.localeCompare(currentParent)<0))&&(depth.set(target,candidate),parent.set(target,source))}const end=[...order].sort((left,right)=>depth.get(right)-depth.get(left)||left.localeCompare(right))[0],path=end===void 0?[]:[end];for(;path[0]!==void 0&&parent.has(path[0]);)path.unshift(parent.get(path[0]));return{depth:Object.fromEntries(depth),path}}function reconstructImpactPath(root,target,parents){const path=[target];let cursor=target;for(;cursor!==root;)cursor=parents.get(cursor),path.push(cursor);return path.reverse()}function analyzeRelationshipExecution(graph,options={}){const registry=options.registry??createRelationshipKindRegistry(),nodes=[...graph.nodes()],adjacency=buildExecutionAdjacency(graph,registry),layers=topologicalLayers(nodes,adjacency),order=layers.flat(),acyclic=order.length===nodes.length,cycles=acyclic?[]:stronglyConnectedComponents(nodes,adjacency).filter(component=>component.length>1||adjacency.get(component[0]).has(component[0])),longest=longestPath(order,adjacency);return{exact:!0,acyclic,order,layers,frontier:layers[0]??[],depth:longest.depth,criticalPath:longest.path,criticalPathLength:Math.max(0,longest.path.length-1),cycles,provenance:{algorithm:"kahn-longest-path",edgeFamily:"ordering"}}}function buildImpactAdjacency(graph,direction,kinds){const adjacency=createAdjacency(graph.nodes()),selectedKinds=kinds===void 0?void 0:new Set(kinds.map(kind=>graph.registry().require(kind).kind)),edges=graph.edges();for(const edge of edges){const definition=graph.registry().require(edge.kind);selectedKinds!==void 0&&!selectedKinds.has(edge.kind)&&(definition.inverse===void 0||!selectedKinds.has(definition.inverse))||appendNeighbor(adjacency,direction==="incoming"?edge.target:edge.source,direction==="incoming"?edge.source:edge.target)}return{adjacency,inspectedEdges:edges.length}}function analyzeBidirectionalGraphImpact(graph,root,options,after,limit,cursorFingerprint){const incoming=analyzeGraphImpact(graph,root,{...options,after:void 0,direction:"incoming",limit:void 0}),outgoing=analyzeGraphImpact(graph,root,{...options,after:void 0,direction:"outgoing",limit:void 0}),rows=new Map,candidates=[...incoming.affected,...outgoing.affected].sort((left,right)=>left.distance-right.distance||left.id.localeCompare(right.id)||left.path.join("\0").localeCompare(right.path.join("\0")));for(const row of candidates)rows.has(row.id)||rows.set(row.id,row);const ordered=[...rows.values()].sort((left,right)=>left.distance-right.distance||left.id.localeCompare(right.id)),afterIndex=after===void 0||after===root?-1:ordered.findIndex(row=>row.id===after);if(after!==void 0&&after!==root&&afterIndex<0)throw new TypeError(`Unknown impact cursor item: ${after}`);const affected=ordered.slice(afterIndex+1,afterIndex+1+limit),rowLimitTruncated=afterIndex+1+affected.length<ordered.length;return{root,affected,exact:!0,truncated:incoming.truncated||outgoing.truncated||rowLimitTruncated,...rowLimitTruncated?{nextCursor:encodeQueryCursor(cursorFingerprint,affected.at(-1)?.id??root)}:{},cost:{visitedNodes:incoming.cost.visitedNodes+outgoing.cost.visitedNodes,inspectedEdges:incoming.cost.inspectedEdges+outgoing.cost.inspectedEdges}}}function analyzeUnidirectionalGraphImpact(graph,root,options){const direction=options.direction,maxDepth=options.maxDepth??Number.POSITIVE_INFINITY,limit=options.limit??Number.POSITIVE_INFINITY,{fingerprint:cursorFingerprint,after}=resolveImpactCursor(root,options,direction,maxDepth),{adjacency,inspectedEdges}=buildImpactAdjacency(graph,direction,options.kinds),state={queue:[{id:root,depth:0}],seen:new Set([root]),parents:new Map,affected:[],cursorFound:after===void 0||after===root};let visitedNodes=0,truncated=!1,rowLimitTruncated=!1;traversal:for(let index=0;index<state.queue.length;index+=1){options.signal?.throwIfAborted();const current=state.queue[index];visitedNodes+=1;const adjacent=[...adjacency.get(current.id)].sort();if(current.depth>=maxDepth){adjacent.some(id=>!state.seen.has(id))&&(truncated=!0);continue}for(const id of adjacent)if(visitImpactNeighbor(state,id,current,root,after,limit)==="truncate"){truncated=!0,rowLimitTruncated=!0;break traversal}}if(!state.cursorFound)throw new TypeError(`Unknown impact cursor item: ${after}`);return{root,affected:state.affected,exact:!0,truncated,...rowLimitTruncated?{nextCursor:encodeQueryCursor(cursorFingerprint,state.affected.at(-1)?.id??root)}:{},cost:{visitedNodes,inspectedEdges}}}function analyzeGraphImpact(graph,root,options={}){const direction=options.direction??"outgoing";if(direction!=="both")return analyzeUnidirectionalGraphImpact(graph,root,{...options,direction});const maxDepth=options.maxDepth??Number.POSITIVE_INFINITY,limit=options.limit??Number.POSITIVE_INFINITY,{fingerprint,after}=resolveImpactCursor(root,options,direction,maxDepth);return analyzeBidirectionalGraphImpact(graph,root,options,after,limit,fingerprint)}function analyzeKnowledgeGraph(graph){const nodes=[...graph.nodes()],weak=createAdjacency(nodes),directed=createAdjacency(nodes);for(const edge of graph.edges())appendNeighbor(weak,edge.source,edge.target),appendNeighbor(weak,edge.target,edge.source),appendNeighbor(directed,edge.source,edge.target);const components=[],visited=new Set;for(const start of nodes){if(visited.has(start))continue;const component=[],stack=[start];for(visited.add(start);stack.length>0;){const current=stack.pop();component.push(current);for(const neighbor of weak.get(current))visited.has(neighbor)||(visited.add(neighbor),stack.push(neighbor))}components.push(component)}const degrees=nodes.map(id=>({id,degree:weak.get(id).size})),maximum=Math.max(0,...degrees.map(({degree})=>degree));return{components:sortComponents(components),stronglyConnected:stronglyConnectedComponents(nodes,directed),orphans:degrees.filter(({degree})=>degree===0).map(({id})=>id),hubs:degrees.filter(({degree})=>degree>0&&degree===maximum),exact:!0,provenance:{algorithm:"component-degree",edgeFamily:"all"}}}function compareRelationshipSnapshots(before,after){const earlier=new Map(before.edges.map(edge=>[relationshipEdgeKey(edge),edge])),later=new Map(after.edges.map(edge=>[relationshipEdgeKey(edge),edge]));return{fromVersion:before.version,toVersion:after.version,added:[...later].filter(([key])=>!earlier.has(key)).map(([,edge])=>edge),removed:[...earlier].filter(([key])=>!later.has(key)).map(([,edge])=>edge),unchangedCount:[...earlier.keys()].filter(key=>later.has(key)).length,exact:!0}}export{analyzeGraphImpact,analyzeKnowledgeGraph,analyzeRelationshipExecution,compareRelationshipSnapshots};
 //# sourceMappingURL=relationship-analytics.js.map

package/dist/sdk/relationship-context.js

@@ -1,2 +1,2 @@
-!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="47b3091f-a1a8-503c-83e9-46b85adf4207")}catch(e2){}})();import{createQueryFingerprint,encodeQueryCursor,resolveQueryCursorStart}from"./pagination.js";import{createRelationshipKindRegistry}from"./relationships.js";const RELATIONSHIP_CONTEXT_ROLE_PRIORITY=["prerequisite","dependent","ancestor","descendant","provenance","related"];const 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 sourceFirst=(definition.precedence??"source_before_target")==="source_before_target";const before=sourceFirst?edge.source:edge.target;return node===before?"prerequisite":"dependent"}if(definition?.hierarchy){const sourceIsParent=definition.hierarchyDirection==="source_parent";const parent=sourceIsParent?edge.source:edge.target;return node===parent?"ancestor":"descendant"}if(edge.kind==="discovered_from"||edge.kind==="incident_from")return"provenance";return"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";const 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]);const queue=[{id:root,distance:0}];const rows=[];let inspectedEdges=0;let depthTruncated=false;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});inspectedEdges+=adjacent.meta.inspectedEdges;if(current.distance>=maxDepth){if(adjacent.value.some(row=>!seen.has(row.id)))depthTruncated=true;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)}}rows.sort((left,right)=>left.distance-right.distance||left.id.localeCompare(right.id));return{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};const 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):[];const 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})`]};const 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;const candidates=params.graph.edges().filter(edge=>{if(!params.included.has(edge.source)||!params.included.has(edge.target))return false;if(kinds===void 0||kinds.has(edge.kind))return true;const inverse=params.registry.resolve(edge.kind)?.inverse;return inverse!==void 0&&kinds.has(inverse)});const 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");const edgeLimit=positiveInteger(options.edgeLimit,40,"edgeLimit");const tokenBudget=positiveInteger(options.tokenBudget,1200,"tokenBudget");const registry=options.registry??createRelationshipKindRegistry();const byId=new Map(details.map(detail=>[detail.id,detail]));const rootDetails=byId.get(rootId)??{id:rootId};const{evidence:rootEvidence=[],...root}=rootDetails;const evidence=[...rootEvidence];const discovery=discoverNodes(graph,rootId,registry,options);const{rootEdges,...directSummary}=summarizeDirectEdges(graph,rootId,registry,options);const fingerprint=createQueryFingerprint("relationship-context",{rootId,direction:options.direction??"both",kinds:[...options.kinds??[]].sort(),maxDepth:options.maxDepth??3});const pageStart=resolveQueryCursorStart(discovery.rows,options.cursor,fingerprint,({id})=>id);const candidates=discovery.rows.slice(pageStart);const 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});const{nodes}=nodeSelection;const included=new Set([rootId,...nodes.map(({id})=>id)]);const edgeSelection=selectContextEdges({graph,included,options,registry,edgeLimit,tokenBudget,initialTokens:nodeSelection.usedTokens});const{edges,usedTokens}=edgeSelection;const consumed=pageStart+nodes.length;const hasMoreNodes=consumed<discovery.rows.length;const lastNode=nodes.at(-1);const omittedEdges=edgeSelection.candidateCount-edges.length;const truncated=discovery.depthTruncated||hasMoreNodes||omittedEdges>0;const 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:true,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]="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};
 //# sourceMappingURL=relationship-context.js.map

package/dist/sdk/relationship-history.js

@@ -1,5 +1,8 @@
-!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e57a9bca-1190-5ffd-bb7d-d76a22fc9e57")}catch(e2){}})();import{createQueryFingerprint,decodeQueryCursorState,paginateQueryRows}from"./pagination.js";import{constants}from"node:fs";import{lstat,mkdir,open}from"node:fs/promises";import path from"node:path";import{acquireLock}from"../core/lock/lock.js";import{isFileMissingError,writeFileAtomic}from"../core/fs/fs-utils.js";import{stableStringify}from"../core/shared/serialization.js";import{RelationshipGraph,createRelationshipKindRegistry}from"./relationships.js";function requiredText(value,field){if(typeof value!=="string"||value.trim().length===0)throw new TypeError(`Relationship event ${field} must be non-empty`);return value.trim()}function edgeIdentity(edge,registry){const definition=registry.require(edge.kind);const endpoints=definition.direction==="undirected"?[edge.source,edge.target].sort().join("\0"):`${edge.source}\0${edge.target}`;return`${definition.kind}\0${endpoints}`}function freezeEdge(edge){return Object.freeze({...edge,...edge.payload===void 0?{}:{payload:Object.freeze(structuredClone(edge.payload))}})}function assertCardinality(candidate,excludeRelationshipId,registry,indexes){const definition=registry.require(candidate.kind);const outgoingOwner=indexes.outgoingOne.get(`${definition.kind}\0${candidate.source}`);if(outgoingOwner!==void 0&&outgoingOwner!==excludeRelationshipId)throw new TypeError(`Relationship outgoing cardinality exceeded for ${definition.kind}`);const incomingOwner=indexes.incomingOne.get(`${definition.kind}\0${candidate.target}`);if(incomingOwner!==void 0&&incomingOwner!==excludeRelationshipId)throw new TypeError(`Relationship incoming cardinality exceeded for ${definition.kind}`);const identity=edgeIdentity(candidate,registry);const identityOwner=indexes.identities.get(identity);if(identityOwner!==void 0&&identityOwner!==excludeRelationshipId)throw new TypeError(`Relationship edge already active: ${identity}`)}function replayEvents(events){const active=new Map;for(const event of events){if(event.action==="remove")active.delete(event.relationshipId);else active.set(event.relationshipId,event.edge)}return active}function normalizeEventHeader(input,currentVersion,eventIds){if(input.expectedVersion!==void 0&&input.expectedVersion!==currentVersion)throw new TypeError(`Relationship event version conflict: expected ${input.expectedVersion}, current ${currentVersion}`);const eventId=requiredText(input.eventId,"eventId");if(eventIds.has(eventId))throw new TypeError(`Relationship event already exists: ${eventId}`);if(input.action!=="add"&&input.action!=="remove"&&input.action!=="supersede")throw new TypeError(`Unknown relationship event action: ${input.action}`);if(!Number.isFinite(Date.parse(input.timestamp)))throw new TypeError("Relationship event timestamp must be valid");return{eventId,relationshipId:requiredText(input.relationshipId,"relationshipId"),author:requiredText(input.author,"author"),timestamp:new Date(input.timestamp).toISOString()}}function resolveMutationEdge(input,relationshipId,active,nodes,registry,indexes){const isActive=active.has(relationshipId);if(input.action==="add"&&isActive)throw new TypeError(`Relationship is already active: ${relationshipId}`);if(input.action!=="add"&&!isActive)throw new TypeError(`Relationship is not active: ${relationshipId}`);if(input.action==="remove")return void 0;if(!input.edge)throw new TypeError(`Relationship ${input.action} event requires an edge`);const source=typeof input.edge.source==="string"?input.edge.source.trim():"";const target=typeof input.edge.target==="string"?input.edge.target.trim():"";if(!nodes.has(source)||!nodes.has(target))throw new TypeError(`Relationship endpoint not found: ${source} -> ${target}`);const canonical=new RelationshipGraph([source,target],[input.edge],registry).edges()[0];assertCardinality(canonical,relationshipId,registry,indexes);return freezeEdge(canonical)}class RelationshipEventLog{#nodes;#registry;#events=[];#eventIds=new Set;#active=new Map;#cardinalityIndexes={identities:new Map,outgoingOne:new Map,incomingOne:new Map};constructor(nodes,options={}){this.#nodes=new Set([...nodes].filter(node=>typeof node==="string").map(node=>node.trim()).filter(Boolean));this.#registry=options.registry??createRelationshipKindRegistry()}get version(){return this.#events.length}events(){return Object.freeze([...this.#events])}*stream(options={}){const fromVersion=options.fromVersion??1;const toVersion=options.toVersion??this.version;const batchSize=options.batchSize??100;if(!Number.isInteger(fromVersion)||fromVersion<1)throw new TypeError("Relationship event stream fromVersion must be positive");if(!Number.isInteger(toVersion)||toVersion<0||toVersion>this.version)throw new TypeError(`Relationship event stream toVersion out of range: ${toVersion}`);if(!Number.isInteger(batchSize)||batchSize<1)throw new TypeError("Relationship event stream batchSize must be positive");if(fromVersion>toVersion+1)throw new TypeError("Relationship event stream fromVersion exceeds the selected prefix");for(let offset=fromVersion-1;offset<toVersion;offset+=batchSize){yield Object.freeze(this.#events.slice(offset,Math.min(offset+batchSize,toVersion)))}}project(initialState,reducer,options={}){if(typeof reducer!=="function")throw new TypeError("Relationship event projection requires a reducer");let state=initialState;let processed=0;let finalEvent;for(const batch of this.stream({...options,batchSize:256})){for(const event of batch){state=reducer(state,event);processed+=1;finalEvent=event}}return Object.freeze({state,version:finalEvent?.sequence??Math.max(0,(options.fromVersion??1)-1),processed,...finalEvent===void 0?{}:{asOf:finalEvent.timestamp}})}#indexActive(relationshipId,edge){const definition=this.#registry.require(edge.kind);this.#cardinalityIndexes.identities.set(edgeIdentity(edge,this.#registry),relationshipId);if(definition.outgoing==="one")this.#cardinalityIndexes.outgoingOne.set(`${definition.kind}\0${edge.source}`,relationshipId);if(definition.incoming==="one")this.#cardinalityIndexes.incomingOne.set(`${definition.kind}\0${edge.target}`,relationshipId)}#unindexActive(edge){const definition=this.#registry.require(edge.kind);this.#cardinalityIndexes.identities.delete(edgeIdentity(edge,this.#registry));if(definition.outgoing==="one")this.#cardinalityIndexes.outgoingOne.delete(`${definition.kind}\0${edge.source}`);if(definition.incoming==="one")this.#cardinalityIndexes.incomingOne.delete(`${definition.kind}\0${edge.target}`)}append(input){const header=normalizeEventHeader(input,this.version,this.#eventIds);const previous=this.#active.get(header.relationshipId);const edge=resolveMutationEdge(input,header.relationshipId,this.#active,this.#nodes,this.#registry,this.#cardinalityIndexes);const event=Object.freeze({eventId:header.eventId,relationshipId:header.relationshipId,action:input.action,...edge===void 0?{}:{edge},author:header.author,timestamp:header.timestamp,...input.reason?.trim()?{reason:input.reason.trim()}:{},sequence:this.version+1});this.#events.push(event);this.#eventIds.add(header.eventId);if(previous)this.#unindexActive(previous);if(input.action==="remove")this.#active.delete(header.relationshipId);else{this.#active.set(header.relationshipId,edge);this.#indexActive(header.relationshipId,edge)}return event}snapshot(options={}){if(options.atVersion!==void 0&&options.atTimestamp!==void 0)throw new TypeError("Relationship snapshot accepts one target");let included;if(options.atTimestamp!==void 0){const timestamp=Date.parse(options.atTimestamp);if(!Number.isFinite(timestamp))throw new TypeError("Relationship snapshot timestamp must be valid");included=this.#events.filter(event=>Date.parse(event.timestamp)<=timestamp)}else{const version=options.atVersion??this.version;if(!Number.isInteger(version)||version<0||version>this.version)throw new TypeError(`Relationship snapshot version out of range: ${version}`);included=this.#events.slice(0,version)}const active=replayEvents(included);const graph=new RelationshipGraph(this.#nodes,active.values(),this.#registry);return Object.freeze({version:included.at(-1)?.sequence??0,...included.at(-1)?{asOf:included.at(-1).timestamp}:{},edges:graph.edges(),graph})}page(options){if(!Number.isInteger(options.limit)||options.limit<1)throw new TypeError("Relationship event page limit must be positive");const fingerprint=createQueryFingerprint("relationship-events",{order:"append-sequence"});const snapshot=options.cursor===void 0?this.version:Number(decodeQueryCursorState(options.cursor,fingerprint).snapshot);if(!Number.isSafeInteger(snapshot)||snapshot<0||snapshot>this.version)throw new TypeError("Relationship event cursor snapshot version is invalid");const page=paginateQueryRows(this.#events.slice(0,snapshot),{cursor:options.cursor,fingerprint,limit:options.limit,readId:event=>event.eventId,snapshot:String(snapshot)});return{version:snapshot,events:page.rows,hasMore:page.has_more,...page.next_cursor?{nextCursor:page.next_cursor}:{}}}}const RELATIONSHIP_STORE_LOCK_ID="relationship-event-store";const RELATIONSHIP_NOFOLLOW_FLAG=constants.O_NOFOLLOW;function acquireRelationshipStoreLock(pmRoot){return acquireLock(pmRoot,RELATIONSHIP_STORE_LOCK_ID,30,`relationship-store:${process.pid}`,false,false,3e3)}async function resolveRelationshipEventStorePath(pmRoot,relativePath="relationships/events.jsonl"){const root=path.resolve(pmRoot);const target=path.resolve(root,relativePath);const relative=path.relative(root,target);if(relative.length===0)throw new TypeError("Relationship event path must name a file within the tracker root");if(relative===".."||relative.startsWith(`..${path.sep}`)||path.isAbsolute(relative))throw new TypeError("Relationship event path must stay within the tracker root");await mkdir(root,{recursive:true});const rootStats=await lstat(root);if(rootStats.isSymbolicLink())throw new TypeError("Relationship event tracker root must not be a symbolic link");let current=root;for(const segment of relative.split(path.sep)){current=path.join(current,segment);try{if((await lstat(current)).isSymbolicLink())throw new TypeError("Relationship event path must not contain symbolic links")}catch(error){if(isFileMissingError(error))break;throw error}}return target}async function loadRelationshipEventLog(target,nodes,registry){const log=new RelationshipEventLog(nodes,{registry});let raw;let handle;try{handle=await open(target,constants.O_RDONLY|RELATIONSHIP_NOFOLLOW_FLAG);raw=await handle.readFile("utf8")}catch(error){if(isFileMissingError(error))return{log,raw:""};throw error}finally{await handle?.close()}const lines=raw.split("\n");for(let index=0;index<lines.length;index+=1){const line=lines[index].trim();if(!line)continue;let stored;try{stored=JSON.parse(line)}catch{throw new TypeError(`Invalid relationship event JSONL at line ${index+1}`)}if(stored.sequence!==log.version+1)throw new TypeError(`Invalid relationship event sequence at line ${index+1}`);log.append({eventId:stored.eventId,relationshipId:stored.relationshipId,action:stored.action,...stored.edge===void 0?{}:{edge:stored.edge},author:stored.author,timestamp:stored.timestamp,...stored.reason===void 0?{}:{reason:stored.reason},expectedVersion:log.version})}return{log,raw}}function relationshipEventMatchesInput(event,input,nodes,registry){const timestamp=Date.parse(input.timestamp);let edge;if(input.action!=="remove"&&input.edge!==void 0)edge=new RelationshipGraph(nodes,[input.edge],registry).edges()[0];return event.eventId===input.eventId.trim()&&event.relationshipId===input.relationshipId.trim()&&event.action===input.action&&event.author===input.author.trim()&&Number.isFinite(timestamp)&&event.timestamp===new Date(timestamp).toISOString()&&event.reason===(input.reason?.trim()||void 0)&&stableStringify(event.edge)===stableStringify(edge)}class RelationshipEventStore{#pmRoot;#nodes;#registry;#path;#log;constructor(options,nodes,target,log){this.#pmRoot=options.pmRoot;this.#nodes=nodes;this.#registry=options.registry;this.#path=target;this.#log=log}static async open(options){const nodes=Object.freeze([...options.nodes]);const target=await resolveRelationshipEventStorePath(options.pmRoot,options.relativePath);const release=await acquireRelationshipStoreLock(options.pmRoot);try{await resolveRelationshipEventStorePath(options.pmRoot,target);const{log}=await loadRelationshipEventLog(target,nodes,options.registry);return new RelationshipEventStore(options,nodes,target,log)}finally{await release()}}get path(){return this.#path}async currentVersion(){this.#log=await this.#refreshFromDurableHistory();return this.#log.version}async append(input){const release=await acquireRelationshipStoreLock(this.#pmRoot);try{const target=await resolveRelationshipEventStorePath(this.#pmRoot,this.#path);const{log:refreshed}=await loadRelationshipEventLog(target,this.#nodes,this.#registry);const event=refreshed.append(input);await mkdir(path.dirname(target),{recursive:true});await resolveRelationshipEventStorePath(this.#pmRoot,target);const handle=await open(target,constants.O_APPEND|constants.O_CREAT|constants.O_WRONLY|RELATIONSHIP_NOFOLLOW_FLAG);try{await handle.appendFile(`${JSON.stringify(event)}
-`,"utf8")}finally{await handle.close()}this.#log=refreshed;return event}finally{await release()}}async appendBatch(inputs,options={}){const release=await acquireRelationshipStoreLock(this.#pmRoot);try{const target=await resolveRelationshipEventStorePath(this.#pmRoot,this.#path);const{log:refreshed,raw}=await loadRelationshipEventLog(target,this.#nodes,this.#registry);const versionBefore=refreshed.version;const existing=new Map(refreshed.events().map(event=>[event.eventId,event]));const appended=[];const skippedEventIds=[];for(const input of inputs){const eventId=input.eventId.trim();const stored=existing.get(eventId);if(stored!==void 0){if(options.existingEventPolicy==="skip_identical"&&relationshipEventMatchesInput(stored,input,this.#nodes,this.#registry)){skippedEventIds.push(stored.eventId);continue}if(options.existingEventPolicy==="skip_identical")throw new TypeError(`Relationship event id collision with different content: ${eventId}`)}const event=refreshed.append(input);existing.set(event.eventId,event);appended.push(event)}if(appended.length>0){const prefix=raw.length===0||raw.endsWith("\n")?raw:`${raw}
-`;await mkdir(path.dirname(target),{recursive:true});await resolveRelationshipEventStorePath(this.#pmRoot,target);await writeFileAtomic(target,`${prefix}${appended.map(event=>JSON.stringify(event)).join("\n")}
-`)}this.#log=refreshed;return Object.freeze({version_before:versionBefore,version_after:refreshed.version,appended:Object.freeze(appended),skipped_event_ids:Object.freeze(skippedEventIds)})}finally{await release()}}async snapshot(options={}){this.#log=await this.#refreshFromDurableHistory();return this.#log.snapshot(options)}async page(options){this.#log=await this.#refreshFromDurableHistory();return this.#log.page(options)}async*stream(options={}){this.#log=await this.#refreshFromDurableHistory();yield*this.#log.stream(options)}async project(initialState,reducer,options={}){this.#log=await this.#refreshFromDurableHistory();return this.#log.project(initialState,reducer,options)}async#refreshFromDurableHistory(){const release=await acquireRelationshipStoreLock(this.#pmRoot);try{const target=await resolveRelationshipEventStorePath(this.#pmRoot,this.#path);return(await loadRelationshipEventLog(target,this.#nodes,this.#registry)).log}finally{await release()}}}export{RelationshipEventLog,RelationshipEventStore};
+(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]="5434ff6f-95af-5983-88cb-fd360d95cb9e")}catch{}})();import{createQueryFingerprint,decodeQueryCursorState,paginateQueryRows}from"./pagination.js";import{constants}from"node:fs";import{lstat,mkdir,open}from"node:fs/promises";import path from"node:path";import{acquireLock}from"../core/lock/lock.js";import{isFileMissingError,writeFileAtomic}from"../core/fs/fs-utils.js";import{stableStringify}from"../core/shared/serialization.js";import{RelationshipGraph,createRelationshipKindRegistry}from"./relationships.js";function requiredText(value,field){if(typeof value!="string"||value.trim().length===0)throw new TypeError(`Relationship event ${field} must be non-empty`);return value.trim()}function edgeIdentity(edge,registry){const definition=registry.require(edge.kind),endpoints=definition.direction==="undirected"?[edge.source,edge.target].sort().join("\0"):`${edge.source}\0${edge.target}`;return`${definition.kind}\0${endpoints}`}function freezeEdge(edge){return Object.freeze({...edge,...edge.payload===void 0?{}:{payload:Object.freeze(structuredClone(edge.payload))}})}function assertCardinality(candidate,excludeRelationshipId,registry,indexes){const definition=registry.require(candidate.kind),outgoingOwner=indexes.outgoingOne.get(`${definition.kind}\0${candidate.source}`);if(outgoingOwner!==void 0&&outgoingOwner!==excludeRelationshipId)throw new TypeError(`Relationship outgoing cardinality exceeded for ${definition.kind}`);const incomingOwner=indexes.incomingOne.get(`${definition.kind}\0${candidate.target}`);if(incomingOwner!==void 0&&incomingOwner!==excludeRelationshipId)throw new TypeError(`Relationship incoming cardinality exceeded for ${definition.kind}`);const identity=edgeIdentity(candidate,registry),identityOwner=indexes.identities.get(identity);if(identityOwner!==void 0&&identityOwner!==excludeRelationshipId)throw new TypeError(`Relationship edge already active: ${identity}`)}function replayEvents(events){const active=new Map;for(const event of events)event.action==="remove"?active.delete(event.relationshipId):active.set(event.relationshipId,event.edge);return active}function normalizeEventHeader(input,currentVersion,eventIds){if(input.expectedVersion!==void 0&&input.expectedVersion!==currentVersion)throw new TypeError(`Relationship event version conflict: expected ${input.expectedVersion}, current ${currentVersion}`);const eventId=requiredText(input.eventId,"eventId");if(eventIds.has(eventId))throw new TypeError(`Relationship event already exists: ${eventId}`);if(input.action!=="add"&&input.action!=="remove"&&input.action!=="supersede")throw new TypeError(`Unknown relationship event action: ${input.action}`);if(!Number.isFinite(Date.parse(input.timestamp)))throw new TypeError("Relationship event timestamp must be valid");return{eventId,relationshipId:requiredText(input.relationshipId,"relationshipId"),author:requiredText(input.author,"author"),timestamp:new Date(input.timestamp).toISOString()}}function resolveMutationEdge(input,relationshipId,active,nodes,registry,indexes){const isActive=active.has(relationshipId);if(input.action==="add"&&isActive)throw new TypeError(`Relationship is already active: ${relationshipId}`);if(input.action!=="add"&&!isActive)throw new TypeError(`Relationship is not active: ${relationshipId}`);if(input.action==="remove")return;if(!input.edge)throw new TypeError(`Relationship ${input.action} event requires an edge`);const source=typeof input.edge.source=="string"?input.edge.source.trim():"",target=typeof input.edge.target=="string"?input.edge.target.trim():"";if(!nodes.has(source)||!nodes.has(target))throw new TypeError(`Relationship endpoint not found: ${source} -> ${target}`);const canonical=new RelationshipGraph([source,target],[input.edge],registry).edges()[0];return assertCardinality(canonical,relationshipId,registry,indexes),freezeEdge(canonical)}class RelationshipEventLog{#nodes;#registry;#events=[];#eventIds=new Set;#active=new Map;#cardinalityIndexes={identities:new Map,outgoingOne:new Map,incomingOne:new Map};constructor(nodes,options={}){this.#nodes=new Set([...nodes].filter(node=>typeof node=="string").map(node=>node.trim()).filter(Boolean)),this.#registry=options.registry??createRelationshipKindRegistry()}get version(){return this.#events.length}events(){return Object.freeze([...this.#events])}*stream(options={}){const fromVersion=options.fromVersion??1,toVersion=options.toVersion??this.version,batchSize=options.batchSize??100;if(!Number.isInteger(fromVersion)||fromVersion<1)throw new TypeError("Relationship event stream fromVersion must be positive");if(!Number.isInteger(toVersion)||toVersion<0||toVersion>this.version)throw new TypeError(`Relationship event stream toVersion out of range: ${toVersion}`);if(!Number.isInteger(batchSize)||batchSize<1)throw new TypeError("Relationship event stream batchSize must be positive");if(fromVersion>toVersion+1)throw new TypeError("Relationship event stream fromVersion exceeds the selected prefix");for(let offset=fromVersion-1;offset<toVersion;offset+=batchSize)yield Object.freeze(this.#events.slice(offset,Math.min(offset+batchSize,toVersion)))}project(initialState,reducer,options={}){if(typeof reducer!="function")throw new TypeError("Relationship event projection requires a reducer");let state=initialState,processed=0,finalEvent;for(const batch of this.stream({...options,batchSize:256}))for(const event of batch)state=reducer(state,event),processed+=1,finalEvent=event;return Object.freeze({state,version:finalEvent?.sequence??Math.max(0,(options.fromVersion??1)-1),processed,...finalEvent===void 0?{}:{asOf:finalEvent.timestamp}})}#indexActive(relationshipId,edge){const definition=this.#registry.require(edge.kind);this.#cardinalityIndexes.identities.set(edgeIdentity(edge,this.#registry),relationshipId),definition.outgoing==="one"&&this.#cardinalityIndexes.outgoingOne.set(`${definition.kind}\0${edge.source}`,relationshipId),definition.incoming==="one"&&this.#cardinalityIndexes.incomingOne.set(`${definition.kind}\0${edge.target}`,relationshipId)}#unindexActive(edge){const definition=this.#registry.require(edge.kind);this.#cardinalityIndexes.identities.delete(edgeIdentity(edge,this.#registry)),definition.outgoing==="one"&&this.#cardinalityIndexes.outgoingOne.delete(`${definition.kind}\0${edge.source}`),definition.incoming==="one"&&this.#cardinalityIndexes.incomingOne.delete(`${definition.kind}\0${edge.target}`)}append(input){const header=normalizeEventHeader(input,this.version,this.#eventIds),previous=this.#active.get(header.relationshipId),edge=resolveMutationEdge(input,header.relationshipId,this.#active,this.#nodes,this.#registry,this.#cardinalityIndexes),event=Object.freeze({eventId:header.eventId,relationshipId:header.relationshipId,action:input.action,...edge===void 0?{}:{edge},author:header.author,timestamp:header.timestamp,...input.reason?.trim()?{reason:input.reason.trim()}:{},sequence:this.version+1});return this.#events.push(event),this.#eventIds.add(header.eventId),previous&&this.#unindexActive(previous),input.action==="remove"?this.#active.delete(header.relationshipId):(this.#active.set(header.relationshipId,edge),this.#indexActive(header.relationshipId,edge)),event}snapshot(options={}){if(options.atVersion!==void 0&&options.atTimestamp!==void 0)throw new TypeError("Relationship snapshot accepts one target");let included;if(options.atTimestamp!==void 0){const timestamp=Date.parse(options.atTimestamp);if(!Number.isFinite(timestamp))throw new TypeError("Relationship snapshot timestamp must be valid");included=this.#events.filter(event=>Date.parse(event.timestamp)<=timestamp)}else{const version=options.atVersion??this.version;if(!Number.isInteger(version)||version<0||version>this.version)throw new TypeError(`Relationship snapshot version out of range: ${version}`);included=this.#events.slice(0,version)}const active=replayEvents(included),graph=new RelationshipGraph(this.#nodes,active.values(),this.#registry);return Object.freeze({version:included.at(-1)?.sequence??0,...included.at(-1)?{asOf:included.at(-1).timestamp}:{},edges:graph.edges(),graph})}page(options){if(!Number.isInteger(options.limit)||options.limit<1)throw new TypeError("Relationship event page limit must be positive");const fingerprint=createQueryFingerprint("relationship-events",{order:"append-sequence"}),snapshot=options.cursor===void 0?this.version:Number(decodeQueryCursorState(options.cursor,fingerprint).snapshot);if(!Number.isSafeInteger(snapshot)||snapshot<0||snapshot>this.version)throw new TypeError("Relationship event cursor snapshot version is invalid");const page=paginateQueryRows(this.#events.slice(0,snapshot),{cursor:options.cursor,fingerprint,limit:options.limit,readId:event=>event.eventId,snapshot:String(snapshot)});return{version:snapshot,events:page.rows,hasMore:page.has_more,...page.next_cursor?{nextCursor:page.next_cursor}:{}}}}const RELATIONSHIP_STORE_LOCK_ID="relationship-event-store",RELATIONSHIP_NOFOLLOW_FLAG=constants.O_NOFOLLOW;function acquireRelationshipStoreLock(pmRoot){return acquireLock(pmRoot,RELATIONSHIP_STORE_LOCK_ID,30,`relationship-store:${process.pid}`,!1,!1,3e3)}async function resolveRelationshipEventStorePath(pmRoot,relativePath="relationships/events.jsonl"){const root=path.resolve(pmRoot),target=path.resolve(root,relativePath),relative=path.relative(root,target);if(relative.length===0)throw new TypeError("Relationship event path must name a file within the tracker root");if(relative===".."||relative.startsWith(`..${path.sep}`)||path.isAbsolute(relative))throw new TypeError("Relationship event path must stay within the tracker root");if(await mkdir(root,{recursive:!0}),(await lstat(root)).isSymbolicLink())throw new TypeError("Relationship event tracker root must not be a symbolic link");let current=root;for(const segment of relative.split(path.sep)){current=path.join(current,segment);try{if((await lstat(current)).isSymbolicLink())throw new TypeError("Relationship event path must not contain symbolic links")}catch(error){if(isFileMissingError(error))break;throw error}}return target}async function loadRelationshipEventLog(target,nodes,registry){const log=new RelationshipEventLog(nodes,{registry});let raw,handle;try{handle=await open(target,constants.O_RDONLY|RELATIONSHIP_NOFOLLOW_FLAG),raw=await handle.readFile("utf8")}catch(error){if(isFileMissingError(error))return{log,raw:""};throw error}finally{await handle?.close()}const lines=raw.split(`
+`);for(let index=0;index<lines.length;index+=1){const line=lines[index].trim();if(!line)continue;let stored;try{stored=JSON.parse(line)}catch{throw new TypeError(`Invalid relationship event JSONL at line ${index+1}`)}if(stored.sequence!==log.version+1)throw new TypeError(`Invalid relationship event sequence at line ${index+1}`);log.append({eventId:stored.eventId,relationshipId:stored.relationshipId,action:stored.action,...stored.edge===void 0?{}:{edge:stored.edge},author:stored.author,timestamp:stored.timestamp,...stored.reason===void 0?{}:{reason:stored.reason},expectedVersion:log.version})}return{log,raw}}function relationshipEventMatchesInput(event,input,nodes,registry){const timestamp=Date.parse(input.timestamp);let edge;return input.action!=="remove"&&input.edge!==void 0&&(edge=new RelationshipGraph(nodes,[input.edge],registry).edges()[0]),event.eventId===input.eventId.trim()&&event.relationshipId===input.relationshipId.trim()&&event.action===input.action&&event.author===input.author.trim()&&Number.isFinite(timestamp)&&event.timestamp===new Date(timestamp).toISOString()&&event.reason===(input.reason?.trim()||void 0)&&stableStringify(event.edge)===stableStringify(edge)}class RelationshipEventStore{#pmRoot;#nodes;#registry;#path;#log;constructor(options,nodes,target,log){this.#pmRoot=options.pmRoot,this.#nodes=nodes,this.#registry=options.registry,this.#path=target,this.#log=log}static async open(options){const nodes=Object.freeze([...options.nodes]),target=await resolveRelationshipEventStorePath(options.pmRoot,options.relativePath),release=await acquireRelationshipStoreLock(options.pmRoot);try{await resolveRelationshipEventStorePath(options.pmRoot,target);const{log}=await loadRelationshipEventLog(target,nodes,options.registry);return new RelationshipEventStore(options,nodes,target,log)}finally{await release()}}get path(){return this.#path}async currentVersion(){return this.#log=await this.#refreshFromDurableHistory(),this.#log.version}async append(input){const release=await acquireRelationshipStoreLock(this.#pmRoot);try{const target=await resolveRelationshipEventStorePath(this.#pmRoot,this.#path),{log:refreshed}=await loadRelationshipEventLog(target,this.#nodes,this.#registry),event=refreshed.append(input);await mkdir(path.dirname(target),{recursive:!0}),await resolveRelationshipEventStorePath(this.#pmRoot,target);const handle=await open(target,constants.O_APPEND|constants.O_CREAT|constants.O_WRONLY|RELATIONSHIP_NOFOLLOW_FLAG);try{await handle.appendFile(`${JSON.stringify(event)}
+`,"utf8")}finally{await handle.close()}return this.#log=refreshed,event}finally{await release()}}async appendBatch(inputs,options={}){const release=await acquireRelationshipStoreLock(this.#pmRoot);try{const target=await resolveRelationshipEventStorePath(this.#pmRoot,this.#path),{log:refreshed,raw}=await loadRelationshipEventLog(target,this.#nodes,this.#registry),versionBefore=refreshed.version,existing=new Map(refreshed.events().map(event=>[event.eventId,event])),appended=[],skippedEventIds=[];for(const input of inputs){const eventId=input.eventId.trim(),stored=existing.get(eventId);if(stored!==void 0){if(options.existingEventPolicy==="skip_identical"&&relationshipEventMatchesInput(stored,input,this.#nodes,this.#registry)){skippedEventIds.push(stored.eventId);continue}if(options.existingEventPolicy==="skip_identical")throw new TypeError(`Relationship event id collision with different content: ${eventId}`)}const event=refreshed.append(input);existing.set(event.eventId,event),appended.push(event)}if(appended.length>0){const prefix=raw.length===0||raw.endsWith(`
+`)?raw:`${raw}
+`;await mkdir(path.dirname(target),{recursive:!0}),await resolveRelationshipEventStorePath(this.#pmRoot,target),await writeFileAtomic(target,`${prefix}${appended.map(event=>JSON.stringify(event)).join(`
+`)}
+`)}return this.#log=refreshed,Object.freeze({version_before:versionBefore,version_after:refreshed.version,appended:Object.freeze(appended),skipped_event_ids:Object.freeze(skippedEventIds)})}finally{await release()}}async snapshot(options={}){return this.#log=await this.#refreshFromDurableHistory(),this.#log.snapshot(options)}async page(options){return this.#log=await this.#refreshFromDurableHistory(),this.#log.page(options)}async*stream(options={}){this.#log=await this.#refreshFromDurableHistory(),yield*this.#log.stream(options)}async project(initialState,reducer,options={}){return this.#log=await this.#refreshFromDurableHistory(),this.#log.project(initialState,reducer,options)}async#refreshFromDurableHistory(){const release=await acquireRelationshipStoreLock(this.#pmRoot);try{const target=await resolveRelationshipEventStorePath(this.#pmRoot,this.#path);return(await loadRelationshipEventLog(target,this.#nodes,this.#registry)).log}finally{await release()}}}export{RelationshipEventLog,RelationshipEventStore};
 //# sourceMappingURL=relationship-history.js.map

package/dist/sdk/relationship-kinds/contract.js

@@ -1,2 +1,2 @@
-!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="4c00e38a-27df-5315-91e8-d35c03ed6bf3")}catch(e2){}})();const BUILTIN_RELATIONSHIP_KINDS=[{kind:"blocked_by",direction:"directed",traversal:"ordering",inverse:"blocks",ordering:true,precedence:"target_before_source",hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",aliases:["depends_on"],compatibilityVersion:1,allowSelf:false},{kind:"blocks",direction:"directed",traversal:"ordering",inverse:"blocked_by",ordering:true,precedence:"source_before_target",hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:false},{kind:"parent",direction:"directed",traversal:"hierarchy",outcomeTraversal:"source_to_target",inverse:"child",ordering:false,hierarchy:true,hierarchyDirection:"target_parent",outgoing:"one",incoming:"many",lifecycle:"supersedable",aliases:["child_of","epic"],compatibilityVersion:1,allowSelf:false},{kind:"child",direction:"directed",traversal:"hierarchy",outcomeTraversal:"target_to_source",inverse:"parent",ordering:false,hierarchy:true,hierarchyDirection:"source_parent",outgoing:"many",incoming:"one",lifecycle:"supersedable",aliases:["parent_child","task"],compatibilityVersion:1,allowSelf:false},{kind:"related",direction:"undirected",traversal:"association",ordering:false,hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",aliases:["related_to"],compatibilityVersion:1,allowSelf:false},{kind:"discovered_from",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:false,hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:false},{kind:"incident_from",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:false,hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:false},{kind:"implements",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:false,hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:false},{kind:"recurs_from",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:false,temporalOrder:"source_after_target",hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:false},{kind:"verifies",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:false,hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:false},{kind:"supersedes",direction:"directed",traversal:"semantic",outcomeTraversal:"both",ordering:false,hierarchy:false,outgoing:"many",incoming:"many",lifecycle:"supersedable",compatibilityVersion:1,allowSelf:false}];export{BUILTIN_RELATIONSHIP_KINDS};
+(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]="2ea7934f-4751-5245-a5ba-492681aa3794")}catch{}})();const BUILTIN_RELATIONSHIP_KINDS=[{kind:"blocked_by",direction:"directed",traversal:"ordering",inverse:"blocks",ordering:!0,precedence:"target_before_source",hierarchy:!1,outgoing:"many",incoming:"many",lifecycle:"persistent",aliases:["depends_on"],compatibilityVersion:1,allowSelf:!1},{kind:"blocks",direction:"directed",traversal:"ordering",inverse:"blocked_by",ordering:!0,precedence:"source_before_target",hierarchy:!1,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:!1},{kind:"parent",direction:"directed",traversal:"hierarchy",outcomeTraversal:"source_to_target",inverse:"child",ordering:!1,hierarchy:!0,hierarchyDirection:"target_parent",outgoing:"one",incoming:"many",lifecycle:"supersedable",aliases:["child_of","epic"],compatibilityVersion:1,allowSelf:!1},{kind:"child",direction:"directed",traversal:"hierarchy",outcomeTraversal:"target_to_source",inverse:"parent",ordering:!1,hierarchy:!0,hierarchyDirection:"source_parent",outgoing:"many",incoming:"one",lifecycle:"supersedable",aliases:["parent_child","task"],compatibilityVersion:1,allowSelf:!1},{kind:"related",direction:"undirected",traversal:"association",ordering:!1,hierarchy:!1,outgoing:"many",incoming:"many",lifecycle:"persistent",aliases:["related_to"],compatibilityVersion:1,allowSelf:!1},{kind:"discovered_from",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:!1,hierarchy:!1,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:!1},{kind:"incident_from",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:!1,hierarchy:!1,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:!1},{kind:"implements",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:!1,hierarchy:!1,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:!1},{kind:"recurs_from",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:!1,temporalOrder:"source_after_target",hierarchy:!1,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:!1},{kind:"verifies",direction:"directed",traversal:"semantic",outcomeTraversal:"source_to_target",ordering:!1,hierarchy:!1,outgoing:"many",incoming:"many",lifecycle:"persistent",compatibilityVersion:1,allowSelf:!1},{kind:"supersedes",direction:"directed",traversal:"semantic",outcomeTraversal:"both",ordering:!1,hierarchy:!1,outgoing:"many",incoming:"many",lifecycle:"supersedable",compatibilityVersion:1,allowSelf:!1}];export{BUILTIN_RELATIONSHIP_KINDS};
 //# sourceMappingURL=contract.js.map

package/dist/sdk/relationship-migration.js

@@ -1,2 +1,2 @@
-!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="41ef1735-c534-5b84-8367-1278007cb7c6")}catch(e2){}})();import{createHash}from"node:crypto";import{assembleWorkspaceRelationshipGraph}from"./graph/assembly.js";function requiredMigrationText(value,field){if(typeof value!=="string"||value.trim().length===0)throw new TypeError(`Relationship backfill ${field} must be non-empty`);return value.trim()}function planRelationshipEventBackfill(items,options){const migrationId=requiredMigrationText(options.migrationId,"migrationId");const author=requiredMigrationText(options.author,"author");const parsedTimestamp=Date.parse(options.timestamp);if(!Number.isFinite(parsedTimestamp))throw new TypeError("Relationship backfill timestamp must be valid");const timestamp=new Date(parsedTimestamp).toISOString();const assembly=assembleWorkspaceRelationshipGraph(items,void 0,options.registry);const nodes=assembly.graph.nodes();const completeEvents=assembly.graph.edges().map(edge=>{const digest=createHash("sha256").update(JSON.stringify([migrationId,edge.kind,edge.source,edge.target,edge.createdAt??null,edge.author??null,edge.payload??null])).digest("hex").slice(0,24);return Object.freeze({eventId:`backfill:${migrationId}:${digest}`,relationshipId:`migration:${migrationId}:${digest}`,action:"add",edge,author,timestamp,reason:`Backfill ${migrationId} from legacy item metadata`})});const fingerprint=createHash("sha256").update(JSON.stringify({migrationId,nodes,events:completeEvents})).digest("hex");const existingEventIds=new Set([...options.existingEventIds??[]].filter(id=>typeof id==="string").map(id=>id.trim()).filter(Boolean));const events=completeEvents.filter(event=>!existingEventIds.has(event.eventId));return Object.freeze({migration_id:migrationId,fingerprint,nodes,events:Object.freeze(events),edge_count:completeEvents.length,skipped_existing_count:completeEvents.length-events.length,duplicate_dependency_rows:assembly.duplicateRows.length,dangling_reference_count:assembly.dangling.active.length+assembly.dangling.legacy_terminal.length})}export{planRelationshipEventBackfill};
+(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]="7163a078-d8be-5bca-813f-c941fcb8e406")}catch{}})();import{createHash}from"node:crypto";import{assembleWorkspaceRelationshipGraph}from"./graph/assembly.js";function requiredMigrationText(value,field){if(typeof value!="string"||value.trim().length===0)throw new TypeError(`Relationship backfill ${field} must be non-empty`);return value.trim()}function planRelationshipEventBackfill(items,options){const migrationId=requiredMigrationText(options.migrationId,"migrationId"),author=requiredMigrationText(options.author,"author"),parsedTimestamp=Date.parse(options.timestamp);if(!Number.isFinite(parsedTimestamp))throw new TypeError("Relationship backfill timestamp must be valid");const timestamp=new Date(parsedTimestamp).toISOString(),assembly=assembleWorkspaceRelationshipGraph(items,void 0,options.registry),nodes=assembly.graph.nodes(),completeEvents=assembly.graph.edges().map(edge=>{const digest=createHash("sha256").update(JSON.stringify([migrationId,edge.kind,edge.source,edge.target,edge.createdAt??null,edge.author??null,edge.payload??null])).digest("hex").slice(0,24);return Object.freeze({eventId:`backfill:${migrationId}:${digest}`,relationshipId:`migration:${migrationId}:${digest}`,action:"add",edge,author,timestamp,reason:`Backfill ${migrationId} from legacy item metadata`})}),fingerprint=createHash("sha256").update(JSON.stringify({migrationId,nodes,events:completeEvents})).digest("hex"),existingEventIds=new Set([...options.existingEventIds??[]].filter(id=>typeof id=="string").map(id=>id.trim()).filter(Boolean)),events=completeEvents.filter(event=>!existingEventIds.has(event.eventId));return Object.freeze({migration_id:migrationId,fingerprint,nodes,events:Object.freeze(events),edge_count:completeEvents.length,skipped_existing_count:completeEvents.length-events.length,duplicate_dependency_rows:assembly.duplicateRows.length,dangling_reference_count:assembly.dangling.active.length+assembly.dangling.legacy_terminal.length})}export{planRelationshipEventBackfill};
 //# sourceMappingURL=relationship-migration.js.map