@unbrained/pm-cli 2026.10.12 → 2026.10.14

package/dist/sdk/query/search-contracts.d.ts

@@ -3,34 +3,34 @@ import type { SharedItemFilterOptions } from "./item-filter-options.js";
 import type { SearchMode } from "./search-rendering.js";
 /** Documents the search options payload exchanged by command, SDK, and package integrations. */
 export interface SearchOptions extends SharedItemFilterOptions {
-    /** Value that configures or reports mode for this contract. */
-    mode?: string;
-    /** Strategy used to control match behavior. */
-    matchMode?: string;
-    /** Value that configures or reports min score for this contract. */
-    minScore?: string | number;
-    /** Value that configures or reports count for this contract. */
-    count?: boolean;
-    /** Value that configures or reports semantic weight for this contract. */
-    semanticWeight?: string | number;
-    /** Value that configures or reports include linked for this contract. */
-    includeLinked?: boolean;
-    /** Value that configures or reports title exact for this contract. */
-    titleExact?: boolean;
-    /** Value that configures or reports phrase exact for this contract. */
-    phraseExact?: boolean;
-    /** Value that configures or reports limit for this contract. */
-    limit?: string;
-    /** Opaque cursor returned by a previous search page. */
-    after?: string;
-    /** Value that configures or reports compact for this contract. */
-    compact?: boolean;
-    /** Value that configures or reports full for this contract. */
-    full?: boolean;
-    /** Value that configures or reports fields for this contract. */
-    fields?: string;
-    /** Whether matched-text snippets are included on each hit. */
-    highlight?: boolean;
+/** Value that configures or reports mode for this contract. */
+mode?: string;
+/** Strategy used to control match behavior. */
+matchMode?: string;
+/** Value that configures or reports min score for this contract. */
+minScore?: string | number;
+/** Value that configures or reports count for this contract. */
+count?: boolean;
+/** Value that configures or reports semantic weight for this contract. */
+semanticWeight?: string | number;
+/** Value that configures or reports include linked for this contract. */
+includeLinked?: boolean;
+/** Value that configures or reports title exact for this contract. */
+titleExact?: boolean;
+/** Value that configures or reports phrase exact for this contract. */
+phraseExact?: boolean;
+/** Value that configures or reports limit for this contract. */
+limit?: string;
+/** Opaque cursor returned by a previous search page. */
+after?: string;
+/** Value that configures or reports compact for this contract. */
+compact?: boolean;
+/** Value that configures or reports full for this contract. */
+full?: boolean;
+/** Value that configures or reports fields for this contract. */
+fields?: string;
+/** Whether matched-text snippets are included on each hit. */
+highlight?: boolean;
 }
 /** Restricts search match mode values accepted by command, SDK, and storage contracts. */
 export type SearchMatchMode = "and" | "or" | "exact";
@@ -38,10 +38,10 @@ export type SearchMatchMode = "and" | "or" | "exact";
 export type SearchProjectionMode = "compact" | "full" | "fields";
 /** Validated search result projection. */
 export interface SearchProjectionConfig {
-    /** Selected projection mode. */
-    mode: SearchProjectionMode;
-    /** Explicit fields for compact or fields mode. */
-    fields: string[];
+/** Selected projection mode. */
+mode: SearchProjectionMode;
+/** Explicit fields for compact or fields mode. */
+fields: string[];
 }
 /** Parse the configured search execution mode. */
 export declare function parseSearchMode(raw: string | undefined): SearchMode;
@@ -67,32 +67,32 @@ export declare function validateSearchProjectionFields(projection: SearchProject
 export declare function parseSearchTokens(query: string): string[];
 /** Documents the search tuning payload exchanged by command, SDK, and package integrations. */
 export interface SearchTuning {
-    /** Exact-title ranking bonus. */
-    title_exact_bonus: number;
-    /** Title field weight. */
-    title_weight: number;
-    /** Description field weight. */
-    description_weight: number;
-    /** Tag field weight. */
-    tags_weight: number;
-    /** Status field weight. */
-    status_weight: number;
-    /** Body field weight. */
-    body_weight: number;
-    /** Comment field weight. */
-    comments_weight: number;
-    /** Note field weight. */
-    notes_weight: number;
-    /** Learning field weight. */
-    learnings_weight: number;
-    /** Reminder field weight. */
-    reminders_weight: number;
-    /** Event field weight. */
-    events_weight: number;
-    /** Dependency field weight. */
-    dependencies_weight: number;
-    /** Linked-content field weight. */
-    linked_content_weight: number;
+/** Exact-title ranking bonus. */
+title_exact_bonus: number;
+/** Title field weight. */
+title_weight: number;
+/** Description field weight. */
+description_weight: number;
+/** Tag field weight. */
+tags_weight: number;
+/** Status field weight. */
+status_weight: number;
+/** Body field weight. */
+body_weight: number;
+/** Comment field weight. */
+comments_weight: number;
+/** Note field weight. */
+notes_weight: number;
+/** Learning field weight. */
+learnings_weight: number;
+/** Reminder field weight. */
+reminders_weight: number;
+/** Event field weight. */
+events_weight: number;
+/** Dependency field weight. */
+dependencies_weight: number;
+/** Linked-content field weight. */
+linked_content_weight: number;
 }
 /** Resolve the bounded default maximum result count. */
 export declare function resolveSearchMaxResults(settings: unknown): number;
@@ -104,10 +104,10 @@ export declare const SEARCH_DEFAULT_MODE_VALUES: readonly SearchDefaultMode[];
 export type SearchModeSource = "explicit" | "settings" | "auto";
 /** Documents the effective search mode together with the layer that chose it. */
 export interface SearchModeResolution {
-    /** The mode the query will execute in before any runtime fallback. */
-    mode: SearchMode;
-    /** `explicit` when the caller passed a mode, `settings` when `search.default_mode` pins one, `auto` when derived from workspace state. */
-    source: SearchModeSource;
+/** The mode the query will execute in before any runtime fallback. */
+mode: SearchMode;
+/** `explicit` when the caller passed a mode, `settings` when `search.default_mode` pins one, `auto` when derived from workspace state. */
+source: SearchModeSource;
 }
 /** Resolve the declared `search.default_mode` setting, falling back to `auto` for absent or invalid values. */
 export declare function resolveSearchDefaultModeSetting(settings: unknown): SearchDefaultMode;
@@ -119,9 +119,9 @@ export declare function resolveSearchDefaultModeSetting(settings: unknown): Sear
  * workspace that built a vector index is searched with it without any flag.
  */
 export declare function resolveEffectiveSearchMode(params: {
-    requested: unknown;
-    settings: unknown;
-    semanticRunnable: boolean;
+requested: unknown;
+settings: unknown;
+semanticRunnable: boolean;
 }): SearchModeResolution;
 /** Resolve the configured minimum result score. */
 export declare function resolveSearchScoreThreshold(settings: unknown): number;

package/dist/sdk/query/search-pagination.d.ts

@@ -2,27 +2,27 @@ import type { SearchHit, SearchOptions } from "./search.js";
 import type { SearchMode } from "./search-rendering.js";
 /** Build the query-only fingerprint shared by search retrieval and paging. */
 export declare function createSearchCursorFingerprint(options: {
-    query: string;
-    mode: SearchMode;
-    searchOptions: SearchOptions;
-    /** Tracker scope, resolved before hashing so callers share native path identity. */
-    pmRoot?: string;
+query: string;
+mode: SearchMode;
+searchOptions: SearchOptions;
+/** Tracker scope, resolved before hashing so callers share native path identity. */
+pmRoot?: string;
 }): string;
 /** Page ranked search hits without coupling cursor mechanics to search scoring. */
 export declare function resolveSearchPage(options: {
-    sorted: SearchHit[];
-    query: string;
-    mode: SearchMode;
-    searchOptions: SearchOptions;
-    limit: number;
-    /** Resolved tracker scope when invoked by the query runtime. */
-    pmRoot?: string;
+sorted: SearchHit[];
+query: string;
+mode: SearchMode;
+searchOptions: SearchOptions;
+limit: number;
+/** Resolved tracker scope when invoked by the query runtime. */
+pmRoot?: string;
 }): {
-    limited: SearchHit[];
-    pageExtras: {
-        has_more?: boolean;
-        next_cursor?: string;
-        applied_limit: number;
-        truncated?: true;
-    };
+limited: SearchHit[];
+pageExtras: {
+has_more?: boolean;
+next_cursor?: string;
+applied_limit: number;
+truncated?: true;
+};
 };

package/dist/sdk/query/search-rendering.d.ts

@@ -2,38 +2,38 @@ import type { SearchMatchMode, SearchOptions } from "./search.js";
 /** Search execution modes represented in response metadata. */
 export type SearchMode = "keyword" | "semantic" | "hybrid";
 interface SearchRenderingQueryExpansion {
-    enabled: boolean;
-    provider: string | null;
+enabled: boolean;
+provider: string | null;
 }
 interface SearchRenderingRerank {
-    enabled: boolean;
-    model: string;
-    top_k: number;
+enabled: boolean;
+model: string;
+top_k: number;
 }
 /** Builds the token-efficient filter echo used by compact search results. */
 export declare function buildCompactSearchFilterSummary(params: {
-    mode: SearchMode;
-    matchMode: SearchMatchMode;
-    options: SearchOptions;
-    includeLinked: boolean;
-    titleExact: boolean;
-    phraseExact: boolean;
-    scoreThreshold: number;
-    hybridSemanticWeight: number;
-    runtimeFieldFilters?: Record<string, unknown>;
+mode: SearchMode;
+matchMode: SearchMatchMode;
+options: SearchOptions;
+includeLinked: boolean;
+titleExact: boolean;
+phraseExact: boolean;
+scoreThreshold: number;
+hybridSemanticWeight: number;
+runtimeFieldFilters?: Record<string, unknown>;
 }): Record<string, unknown>;
 /** Builds the complete filter echo shared by verbose search response paths. */
 export declare function buildVerboseSearchFilters(params: {
-    effectiveMode: SearchMode;
-    matchMode: SearchMatchMode;
-    options: SearchOptions;
-    includeLinked: boolean;
-    titleExact: boolean;
-    phraseExact: boolean;
-    scoreThreshold: number;
-    hybridSemanticWeight: number;
-    queryExpansion: SearchRenderingQueryExpansion;
-    rerank: SearchRenderingRerank;
-    runtimeFieldFilters: Record<string, unknown>;
+effectiveMode: SearchMode;
+matchMode: SearchMatchMode;
+options: SearchOptions;
+includeLinked: boolean;
+titleExact: boolean;
+phraseExact: boolean;
+scoreThreshold: number;
+hybridSemanticWeight: number;
+queryExpansion: SearchRenderingQueryExpansion;
+rerank: SearchRenderingRerank;
+runtimeFieldFilters: Record<string, unknown>;
 }): Record<string, unknown>;
 export {};

package/dist/sdk/query/search.d.ts

@@ -14,52 +14,52 @@ export { classifyImplicitSemanticFallbackReason, collectErrorCauseCodes, formatV
 export type { SearchCompactResult, SearchHit, SearchHitHighlight, SearchResult, SearchResultItem, SearchVerboseResult } from "./search/types.js";
 /** Public contract for test only search command, shared by SDK and presentation-layer consumers. */
 export declare const _testOnlySearchCommand: {
-    applyFilters: typeof applyFilters;
-    applyExactQueryFilters: typeof applyExactQueryFilters;
-    applyInlineQueryFilters: typeof applyInlineQueryFilters;
-    buildHitHighlights: typeof buildHitHighlights;
-    buildVerboseSearchFilters: typeof buildVerboseSearchFilters;
-    buildExplicitSemanticFallbackWarning: typeof buildExplicitSemanticFallbackWarning;
-    buildCompactSearchFilterSummary: typeof buildCompactSearchFilterSummary;
-    buildHybridLexicalScore: typeof buildHybridLexicalScore;
-    buildRerankCorpus: typeof buildRerankCorpus;
-    buildSemanticHits: typeof buildSemanticHits;
-    classifyImplicitSemanticFallbackReason: typeof classifyImplicitSemanticFallbackReason;
-    collectErrorCauseCodes: typeof collectErrorCauseCodes;
-    collectExactPhraseFields: typeof collectExactPhraseFields;
-    collectLinkedPaths: typeof collectLinkedPaths;
-    combineHybridHits: typeof combineHybridHits;
-    computeBuiltInBm25Hits: typeof computeBuiltInBm25Hits;
-    computeSemanticOrHybridHits: typeof computeSemanticOrHybridHits;
-    resolveBuiltInBm25Mode: typeof resolveBuiltInBm25Mode;
-    countOccurrences: typeof countOccurrences;
-    dependencyEntries: typeof dependencyEntries;
-    documentContainsExactPhrase: typeof documentContainsExactPhrase;
-    emptySearchResult: typeof emptySearchResult;
-    highlightFieldSnippet: typeof highlightFieldSnippet;
-    loadDocuments: typeof loadDocuments;
-    markTokenRuns: typeof markTokenRuns;
-    parseInlineQueryFilters: typeof parseInlineQueryFilters;
-    maybeEmitVectorIndexStaleWarning: typeof maybeEmitVectorIndexStaleWarning;
-    loadLinkedCorpus: typeof loadLinkedCorpus;
-    mergeVectorHitsById: typeof mergeVectorHitsById;
-    normalizeExtensionProviderHits: typeof normalizeExtensionProviderHits;
-    normalizeScoreMap: typeof normalizeScoreMap;
-    parseProjectionConfig: typeof parseSearchProjection;
-    parseTimestampWindow: typeof parseTimestampWindow;
-    parseTokens: typeof parseSearchTokens;
-    projectSearchHits: typeof projectSearchHits;
-    readSearchFieldValue: typeof readSearchFieldValue;
-    requireSemanticDependencies: typeof requireSemanticDependencies;
-    resolveExtensionSearchProvider: typeof resolveExtensionSearchProvider;
-    resolveExtensionSearchProviderByName: typeof resolveExtensionSearchProviderByName;
-    resolveExtensionVectorAdapter: typeof resolveExtensionVectorAdapter;
-    resolveLinkedCorpusRoots: typeof resolveLinkedCorpusRoots;
-    scoreDocument: typeof scoreDocument;
-    sortHits: typeof sortHits;
-    stringArray: typeof stringArray;
-    textEntries: typeof textEntries;
-    validateSearchProjectionFields: typeof validateSearchProjectionFields;
+applyFilters: typeof applyFilters;
+applyExactQueryFilters: typeof applyExactQueryFilters;
+applyInlineQueryFilters: typeof applyInlineQueryFilters;
+buildHitHighlights: typeof buildHitHighlights;
+buildVerboseSearchFilters: typeof buildVerboseSearchFilters;
+buildExplicitSemanticFallbackWarning: typeof buildExplicitSemanticFallbackWarning;
+buildCompactSearchFilterSummary: typeof buildCompactSearchFilterSummary;
+buildHybridLexicalScore: typeof buildHybridLexicalScore;
+buildRerankCorpus: typeof buildRerankCorpus;
+buildSemanticHits: typeof buildSemanticHits;
+classifyImplicitSemanticFallbackReason: typeof classifyImplicitSemanticFallbackReason;
+collectErrorCauseCodes: typeof collectErrorCauseCodes;
+collectExactPhraseFields: typeof collectExactPhraseFields;
+collectLinkedPaths: typeof collectLinkedPaths;
+combineHybridHits: typeof combineHybridHits;
+computeBuiltInBm25Hits: typeof computeBuiltInBm25Hits;
+computeSemanticOrHybridHits: typeof computeSemanticOrHybridHits;
+resolveBuiltInBm25Mode: typeof resolveBuiltInBm25Mode;
+countOccurrences: typeof countOccurrences;
+dependencyEntries: typeof dependencyEntries;
+documentContainsExactPhrase: typeof documentContainsExactPhrase;
+emptySearchResult: typeof emptySearchResult;
+highlightFieldSnippet: typeof highlightFieldSnippet;
+loadDocuments: typeof loadDocuments;
+markTokenRuns: typeof markTokenRuns;
+parseInlineQueryFilters: typeof parseInlineQueryFilters;
+maybeEmitVectorIndexStaleWarning: typeof maybeEmitVectorIndexStaleWarning;
+loadLinkedCorpus: typeof loadLinkedCorpus;
+mergeVectorHitsById: typeof mergeVectorHitsById;
+normalizeExtensionProviderHits: typeof normalizeExtensionProviderHits;
+normalizeScoreMap: typeof normalizeScoreMap;
+parseProjectionConfig: typeof parseSearchProjection;
+parseTimestampWindow: typeof parseTimestampWindow;
+parseTokens: typeof parseSearchTokens;
+projectSearchHits: typeof projectSearchHits;
+readSearchFieldValue: typeof readSearchFieldValue;
+requireSemanticDependencies: typeof requireSemanticDependencies;
+resolveExtensionSearchProvider: typeof resolveExtensionSearchProvider;
+resolveExtensionSearchProviderByName: typeof resolveExtensionSearchProviderByName;
+resolveExtensionVectorAdapter: typeof resolveExtensionVectorAdapter;
+resolveLinkedCorpusRoots: typeof resolveLinkedCorpusRoots;
+scoreDocument: typeof scoreDocument;
+sortHits: typeof sortHits;
+stringArray: typeof stringArray;
+textEntries: typeof textEntries;
+validateSearchProjectionFields: typeof validateSearchProjectionFields;
 };
 /** Implements run search for the public runtime surface of this module. */
 export declare function runSearch(rawQuery: string, rawOptions: SearchOptions, global: GlobalOptions): Promise<SearchResult>;

package/dist/sdk/read-output/continuation.d.ts

@@ -1,14 +1,14 @@
 import type { PmReadOutputCursorEnvelope, PmReadOutputSurface } from "../read-output-contracts.js";
 /** Stable snapshot policy for a read surface whose probes refresh observation metadata. */
 export interface PmReadOutputContinuationFingerprintPolicy {
-    /** Version included in fingerprints so policy changes invalidate older cursors. */
-    version: 3;
-    /** Declared continuation row paths governed by this policy. */
-    paths: readonly string[];
-    /** Exact direct detail fields excluded for each named dynamic row. */
-    ignored_detail_field_names_by_row: Readonly<Record<string, readonly string[]>>;
-    /** Promise that verdicts, stable configuration, and nonvolatile evidence remain bound. */
-    guarantee: "nonvolatile_snapshot_and_stable_configuration";
+/** Version included in fingerprints so policy changes invalidate older cursors. */
+version: 3;
+/** Declared continuation row paths governed by this policy. */
+paths: readonly string[];
+/** Exact direct detail fields excluded for each named dynamic row. */
+ignored_detail_field_names_by_row: Readonly<Record<string, readonly string[]>>;
+/** Promise that verdicts, stable configuration, and nonvolatile evidence remain bound. */
+guarantee: "nonvolatile_snapshot_and_stable_configuration";
 }
 /** Command-specific exceptions to complete-row continuation fingerprinting. */
 export declare const PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES: Readonly<Partial<Record<PmReadOutputSurface, PmReadOutputContinuationFingerprintPolicy>>>;

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

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ddc50fa6-a983-5d61-bc06-673c9b4a483e")}catch{}})();import{createHash}from"node:crypto";import{EXIT_CODE}from"../../core/shared/constants.js";import{PmCliError}from"../../core/shared/errors.js";import{stableStringify}from"../../core/shared/serialization.js";import{resolveReadOutputSurface}from"../read-output-contracts.js";import{readOutputContinuationRowCollections,sliceReadOutputRowCollection}from"../read-output-rows.js";const MAX_READ_OUTPUT_CURSOR_LENGTH=4096,HEALTH_TELEMETRY_VOLATILE_DETAIL_FIELDS=Object.freeze(["queue_draining","queue_entries","queue_exists","queue_high_retry_entries","queue_invalid_rows","queue_max_attempts","queue_rows_total","queue_size_bytes","pending_otel_spans","last_attempted_flush_at","last_failed_flush_at","last_otel_attempt_at","last_otel_failure_at","last_otel_success_at","last_successful_flush_at"]),PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES=Object.freeze({health:Object.freeze({version:3,paths:Object.freeze(["checks"]),ignored_detail_field_names_by_row:Object.freeze({telemetry:HEALTH_TELEMETRY_VOLATILE_DETAIL_FIELDS}),guarantee:"nonvolatile_snapshot_and_stable_configuration"})});function isRecord(value){return value!==null&&typeof value=="object"&&!Array.isArray(value)}function normalizeReadOutputFingerprintValue(value){return Array.isArray(value)?value.map(normalizeReadOutputFingerprintValue):isRecord(value)?Object.fromEntries(Object.entries(value).map(([key,entry])=>[key,normalizeReadOutputFingerprintValue(entry)])):value}function normalizeReadOutputFingerprintRow(value,policy){if(!isRecord(value))return normalizeReadOutputFingerprintValue(value);const rowName=typeof value.name=="string"?value.name:void 0,ignoredDetailFields=rowName!==void 0&&Object.hasOwn(policy.ignored_detail_field_names_by_row,rowName)?policy.ignored_detail_field_names_by_row[rowName]:void 0;return Object.fromEntries(Object.entries(value).map(([key,entry])=>key!=="details"||!ignoredDetailFields||!isRecord(entry)?[key,normalizeReadOutputFingerprintValue(entry)]:[key,Object.fromEntries(Object.entries(entry).filter(([detailKey])=>!ignoredDetailFields.includes(detailKey)).map(([detailKey,detailValue])=>[detailKey,normalizeReadOutputFingerprintValue(detailValue)]))]))}function normalizeReadOutputFingerprintSnapshot(value,policy){return Array.isArray(value)?value.map(row=>normalizeReadOutputFingerprintRow(row,policy)):normalizeReadOutputFingerprintRow(value,policy)}function readOutputCollectionFingerprint(path,value,command){const policy=command?PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES[command]:void 0,policyApplies=policy?.paths.includes(path)===!0;return createHash("sha256").update(stableStringify({path,value:policyApplies?normalizeReadOutputFingerprintSnapshot(value,policy):value,...policyApplies?{fingerprint_policy_version:policy.version}:{}})).digest("base64url").slice(0,16)}function encodeReadOutputContinuationCursor(cursor){return Buffer.from(JSON.stringify({v:1,c:cursor.command,p:cursor.path,o:cursor.offset,n:cursor.total_rows,f:cursor.fingerprint}),"utf8").toString("base64url")}function decodeReadOutputContinuationCursor(raw){if(raw.length>MAX_READ_OUTPUT_CURSOR_LENGTH)throw new PmCliError("The read-output continuation cursor is malformed or unsupported.",EXIT_CODE.USAGE,{code:"read_output_cursor_invalid"});let candidate;try{candidate=JSON.parse(Buffer.from(raw,"base64url").toString("utf8"))}catch{candidate=null}if(!isRecord(candidate)||candidate.v!==1||resolveReadOutputSurface(String(candidate.c??""))!==candidate.c||typeof candidate.p!="string"||candidate.p.length===0||!Number.isSafeInteger(candidate.o)||candidate.o<0||!Number.isSafeInteger(candidate.n)||candidate.n<1||typeof candidate.f!="string"||candidate.f.length===0)throw new PmCliError("The read-output continuation cursor is malformed or unsupported.",EXIT_CODE.USAGE,{code:"read_output_cursor_invalid"});return{version:1,command:candidate.c,path:candidate.p,offset:candidate.o,total_rows:candidate.n,fingerprint:candidate.f}}function prioritizeAssuranceAssertions(result){if(!Array.isArray(result.assertions))return result;const priority=row=>!isRecord(row)||row.verdict==="pass"?4:row.verdict==="retired"?3:row.enforcement==="block"?0:row.enforcement==="warn"?1:2;return{...result,assertions:result.assertions.map((row,index)=>({row,index})).sort((left,right)=>priority(left.row)-priority(right.row)||left.index-right.index).map(({row})=>row),budget_retention_policy:"verdict_priority"}}function applyReadOutputContinuation(result,command,cursor){if(!cursor)return result;if(cursor.command!==command)throw new PmCliError(`The read-output cursor belongs to ${cursor.command}, not ${command}.`,EXIT_CODE.USAGE,{code:"read_output_cursor_command_mismatch"});const collection=readOutputContinuationRowCollections(result).find(entry=>entry.path===cursor.path),totalRows=collection?Array.isArray(collection.value)?collection.value.length:Object.keys(collection.value).length:0;if(!collection||totalRows!==cursor.total_rows||cursor.offset>totalRows||readOutputCollectionFingerprint(cursor.path,collection.value,command)!==cursor.fingerprint)throw new PmCliError("The read-output continuation no longer matches the declared row collection; restart the bounded read.",EXIT_CODE.USAGE,{code:"read_output_cursor_stale"});return sliceReadOutputRowCollection(result,cursor.path,cursor.offset)}export{PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES,applyReadOutputContinuation,decodeReadOutputContinuationCursor,encodeReadOutputContinuationCursor,prioritizeAssuranceAssertions,readOutputCollectionFingerprint};
+(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]="f7f59eaa-9d5d-5797-99de-e672fdfba99d")}catch{}})();import{createHash}from"node:crypto";import{EXIT_CODE}from"../../core/shared/constants.js";import{PmCliError}from"../../core/shared/errors.js";import{stableStringify}from"../../core/shared/serialization.js";import{resolveReadOutputSurface}from"../read-output-contracts.js";import{readOutputContinuationRowCollections,sliceReadOutputRowCollection}from"../read-output-rows.js";const MAX_READ_OUTPUT_CURSOR_LENGTH=4096,HEALTH_TELEMETRY_VOLATILE_DETAIL_FIELDS=Object.freeze(["queue_draining","queue_entries","queue_exists","queue_high_retry_entries","queue_invalid_rows","queue_max_attempts","queue_rows_total","queue_size_bytes","pending_otel_spans","last_attempted_flush_at","last_failed_flush_at","last_otel_attempt_at","last_otel_failure_at","last_otel_success_at","last_successful_flush_at"]),PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES=Object.freeze({health:Object.freeze({version:3,paths:Object.freeze(["checks"]),ignored_detail_field_names_by_row:Object.freeze({telemetry:HEALTH_TELEMETRY_VOLATILE_DETAIL_FIELDS}),guarantee:"nonvolatile_snapshot_and_stable_configuration"})});function isRecord(value){return value!==null&&typeof value=="object"&&!Array.isArray(value)}function normalizeReadOutputFingerprintValue(value){return Array.isArray(value)?value.map(normalizeReadOutputFingerprintValue):isRecord(value)?Object.fromEntries(Object.entries(value).map(([key,entry])=>[key,normalizeReadOutputFingerprintValue(entry)])):value}function normalizeReadOutputFingerprintRow(value,policy){if(!isRecord(value))return normalizeReadOutputFingerprintValue(value);const rowName=typeof value.name=="string"?value.name:void 0,ignoredDetailFields=rowName!==void 0&&Object.hasOwn(policy.ignored_detail_field_names_by_row,rowName)?policy.ignored_detail_field_names_by_row[rowName]:void 0;return Object.fromEntries(Object.entries(value).map(([key,entry])=>key!=="details"||!ignoredDetailFields||!isRecord(entry)?[key,normalizeReadOutputFingerprintValue(entry)]:[key,Object.fromEntries(Object.entries(entry).filter(([detailKey])=>!ignoredDetailFields.includes(detailKey)).map(([detailKey,detailValue])=>[detailKey,normalizeReadOutputFingerprintValue(detailValue)]))]))}function normalizeReadOutputFingerprintSnapshot(value,policy){return Array.isArray(value)?value.map(row=>normalizeReadOutputFingerprintRow(row,policy)):normalizeReadOutputFingerprintRow(value,policy)}function readOutputCollectionFingerprint(path,value,command){const policy=command?PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES[command]:void 0,policyApplies=policy?.paths.includes(path)===!0;return createHash("sha256").update(stableStringify({path,value:policyApplies?normalizeReadOutputFingerprintSnapshot(value,policy):value,...policyApplies?{fingerprint_policy_version:policy.version}:{}})).digest("base64url").slice(0,16)}function encodeReadOutputContinuationCursor(cursor){return Buffer.from(JSON.stringify({v:1,c:cursor.command,p:cursor.path,o:cursor.offset,n:cursor.total_rows,f:cursor.fingerprint}),"utf8").toString("base64url")}function isReadOutputCursorCommand(value){return typeof value=="string"&&(resolveReadOutputSurface(value)===value||/^extension:\S(?:[^\r\n]*\S)?$/u.test(value))}function decodeReadOutputContinuationCursor(raw){if(raw.length>MAX_READ_OUTPUT_CURSOR_LENGTH)throw new PmCliError("The read-output continuation cursor is malformed or unsupported.",EXIT_CODE.USAGE,{code:"read_output_cursor_invalid"});let candidate;try{candidate=JSON.parse(Buffer.from(raw,"base64url").toString("utf8"))}catch{candidate=null}if(!isRecord(candidate)||candidate.v!==1||!isReadOutputCursorCommand(candidate.c)||typeof candidate.p!="string"||candidate.p.length===0||!Number.isSafeInteger(candidate.o)||candidate.o<0||!Number.isSafeInteger(candidate.n)||candidate.n<1||typeof candidate.f!="string"||candidate.f.length===0)throw new PmCliError("The read-output continuation cursor is malformed or unsupported.",EXIT_CODE.USAGE,{code:"read_output_cursor_invalid"});return{version:1,command:candidate.c,path:candidate.p,offset:candidate.o,total_rows:candidate.n,fingerprint:candidate.f}}function prioritizeAssuranceAssertions(result){if(!Array.isArray(result.assertions))return result;const priority=row=>!isRecord(row)||row.verdict==="pass"?4:row.verdict==="retired"?3:row.enforcement==="block"?0:row.enforcement==="warn"?1:2;return{...result,assertions:result.assertions.map((row,index)=>({row,index})).sort((left,right)=>priority(left.row)-priority(right.row)||left.index-right.index).map(({row})=>row),budget_retention_policy:"verdict_priority"}}function applyReadOutputContinuation(result,command,cursor){if(!cursor)return result;if(cursor.command!==command)throw new PmCliError(`The read-output cursor belongs to ${cursor.command}, not ${command}.`,EXIT_CODE.USAGE,{code:"read_output_cursor_command_mismatch"});const collection=readOutputContinuationRowCollections(result).find(entry=>entry.path===cursor.path),totalRows=collection?Array.isArray(collection.value)?collection.value.length:Object.keys(collection.value).length:0;if(!collection||totalRows!==cursor.total_rows||cursor.offset>totalRows||readOutputCollectionFingerprint(cursor.path,collection.value,command)!==cursor.fingerprint)throw new PmCliError("The read-output continuation no longer matches the declared row collection; restart the bounded read.",EXIT_CODE.USAGE,{code:"read_output_cursor_stale"});return sliceReadOutputRowCollection(result,cursor.path,cursor.offset)}export{PM_READ_OUTPUT_CONTINUATION_FINGERPRINT_POLICIES,applyReadOutputContinuation,decodeReadOutputContinuationCursor,encodeReadOutputContinuationCursor,prioritizeAssuranceAssertions,readOutputCollectionFingerprint};
 //# sourceMappingURL=continuation.js.map

package/dist/sdk/read-output/extension.d.ts

@@ -0,0 +1,7 @@
+import type { RegisteredExtensionCommandDefinition } from "../../core/extensions/extension-types.js";
+/** Find the winning command declaration by CLI path, SDK action or receipt identity. */
+export declare function resolveExtensionOutputCommand(command: string): RegisteredExtensionCommandDefinition | undefined;
+/** Resolve read permission only from the winning command registration. */
+export declare function resolveExtensionReadOutput(command: string): RegisteredExtensionCommandDefinition | undefined;
+/** Validate declared rows before projection and attach the host-owned row contract. */
+export declare function attachExtensionReadOutputRows(command: string, result: unknown): unknown;

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

@@ -0,0 +1,2 @@
+(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1b67272d-8924-5b1b-97cd-74a6a10493be")}catch{}})();import{getActiveExtensionRegistrations}from"../../core/extensions/index.js";import{PmCliError}from"../../core/shared/errors.js";import{EXIT_CODE}from"../../core/shared/constants.js";import{isNativeExtensionOutputCommand}from"../../core/extensions/read-output-contract.js";import{PM_READ_ROW_JQ_SELECTOR}from"../output-projection.js";function resolveExtensionOutputCommand(command){const canonicalPath=command.trim().toLowerCase().startsWith("extension:"),normalized=command.trim().toLowerCase().replace(/^extension:/u,"");if(isNativeExtensionOutputCommand(normalized))return;const commands=getActiveExtensionRegistrations()?.commands??[],commandPath=[...commands].reverse().find(entry=>entry.command===normalized)?.command??(canonicalPath?void 0:commands.find(entry=>entry.action===normalized)?.command),registration=[...commands].reverse().find(entry=>entry.command===commandPath);return registration===void 0||isNativeExtensionOutputCommand(registration.command)||isNativeExtensionOutputCommand(registration.action)?void 0:registration}function resolveExtensionReadOutput(command){const registration=resolveExtensionOutputCommand(command);return registration?.read_output===void 0?void 0:registration}function attachExtensionReadOutputRows(command,result){const registration=resolveExtensionReadOutput(command),definition=registration?.read_output;if(definition===void 0)return result;if(typeof result!="object"||result===null||Array.isArray(result))throw new PmCliError("Read-only extension commands must return a structured object.",EXIT_CODE.USAGE,{code:"extension_read_output_invalid"});for(const rowPath of definition.row_keys){let value=result;for(const segment of rowPath.split("."))value=typeof value=="object"&&value!==null&&Object.hasOwn(value,segment)?Reflect.get(value,segment):void 0;if(value===null||typeof value!="object")throw new PmCliError(`Read-only extension result is missing declared row collection ${rowPath}.`,EXIT_CODE.USAGE,{code:"extension_read_output_invalid"})}return{...result,row_contract:{command:`extension:${registration.command}`,row_kind:definition.row_keys.length>0?"collection":"none",row_keys:[...definition.row_keys],fields:"supported",...definition.row_keys.length>0?{jq_selector:PM_READ_ROW_JQ_SELECTOR}:{},toon_encoding:"tabular_when_uniform"}}}export{attachExtensionReadOutputRows,resolveExtensionOutputCommand,resolveExtensionReadOutput};
+//# sourceMappingURL=extension.js.map

package/dist/sdk/read-output/options.d.ts

@@ -5,10 +5,12 @@
  */
 /** Canonical field, amount, cost and encoding controls for every read surface. */
 export declare const READ_OUTPUT_DIMENSION_FLAGS: {
-    readonly include: "--output-include";
-    readonly amount: "--output-limit";
-    readonly cost: "--output-budget";
-    readonly encoding: "--output-format";
+readonly include: "--output-include";
+readonly amount: "--output-limit";
+readonly cost: "--output-budget";
+readonly encoding: "--output-format";
 };
 /** Presentation-only controls composing universal output shaping across calls. */
 export declare const READ_OUTPUT_COMPOSITION_FLAGS: readonly ["--output-session", "--output-cursor", "--output-row-contract"];
+/** Built-in command roots whose primary operation is a read. */
+export declare const PM_READ_OUTPUT_SURFACES: readonly ["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"];

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

@@ -1,2 +1,2 @@
-(function(){try{var e=typeof window<"u"?window:typeof global<"u"?global:typeof globalThis<"u"?globalThis:typeof self<"u"?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="ddd492ec-2482-5047-8d7f-8c40e18b60e3")}catch{}})();const READ_OUTPUT_DIMENSION_FLAGS={include:"--output-include",amount:"--output-limit",cost:"--output-budget",encoding:"--output-format"},READ_OUTPUT_COMPOSITION_FLAGS=Object.freeze(["--output-session","--output-cursor","--output-row-contract"]);export{READ_OUTPUT_COMPOSITION_FLAGS,READ_OUTPUT_DIMENSION_FLAGS};
+(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]="53865a81-4c96-51e2-a378-ae0e2781a50f")}catch{}})();const READ_OUTPUT_DIMENSION_FLAGS={include:"--output-include",amount:"--output-limit",cost:"--output-budget",encoding:"--output-format"},READ_OUTPUT_COMPOSITION_FLAGS=Object.freeze(["--output-session","--output-cursor","--output-row-contract"]),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"];export{PM_READ_OUTPUT_SURFACES,READ_OUTPUT_COMPOSITION_FLAGS,READ_OUTPUT_DIMENSION_FLAGS};
 //# sourceMappingURL=options.js.map

package/dist/sdk/read-output/provenance.d.ts

@@ -7,14 +7,14 @@
 export declare const READ_OUTPUT_INVOCATION_PROVENANCE: unique symbol;
 /** Internal evidence that distinguishes caller aliases from forwarded command options. */
 export interface PmReadOutputInvocationProvenance {
-    /** Canonical include modes forwarded through command-local option keys. */
-    canonical_include_modes: string[];
-    /** Compatibility aliases observed before defaults or canonical forwarding. */
-    explicit_legacy_aliases: string[];
-    /** Whether the CLI captured the complete set of caller-supplied aliases. */
-    cli_invocation_observed?: boolean;
-    /** Whether an SDK helper constructed every command-local option itself. */
-    sdk_invocation_observed?: boolean;
+/** Canonical include modes forwarded through command-local option keys. */
+canonical_include_modes: string[];
+/** Compatibility aliases observed before defaults or canonical forwarding. */
+explicit_legacy_aliases: string[];
+/** Whether the CLI captured the complete set of caller-supplied aliases. */
+cli_invocation_observed?: boolean;
+/** Whether an SDK helper constructed every command-local option itself. */
+sdk_invocation_observed?: boolean;
 }
 /** Mark a complete SDK helper request so internal command options are not reported as caller aliases. */
 export declare function markCanonicalSdkReadOutputOptions<Options extends object>(options: Options, canonicalIncludeModes: readonly string[]): Options;

package/dist/sdk/read-output-budget.d.ts

@@ -3,19 +3,19 @@ import type { PmReadOutputReceipt } from "./read-output-contracts.js";
 export declare function projectReadOutputItemToBrief(command: string, options: Record<string, unknown>, result: Record<string, unknown>): Record<string, unknown> | undefined;
 /** Input to the deterministic finite-retry recommendation contract. */
 export interface PmReadOutputRecoveryBudgetInput {
-    /** Ceiling that already bound and truncated the response. */
-    effective_budget_tokens: number;
-    /** Measured cost of the useful result before row compaction. */
-    measured_result_tokens: number;
+/** Ceiling that already bound and truncated the response. */
+effective_budget_tokens: number;
+/** Measured cost of the useful result before row compaction. */
+measured_result_tokens: number;
 }
 /** Executable next-budget recommendation shared by CLI, SDK, and MCP. */
 export interface PmReadOutputRecoveryBudget {
-    /** Rounded finite retry ceiling, or the only truthful safe fallback. */
-    output_budget: number | "unbounded";
-    /** Ratio to the binding request, absent when finite arithmetic is unsafe. */
-    recovery_budget_multiplier: number | null;
-    /** Stable algorithm revision for consumers and fixtures. */
-    rule_version: "v1";
+/** Rounded finite retry ceiling, or the only truthful safe fallback. */
+output_budget: number | "unbounded";
+/** Ratio to the binding request, absent when finite arithmetic is unsafe. */
+recovery_budget_multiplier: number | null;
+/** Stable algorithm revision for consumers and fixtures. */
+rule_version: "v1";
 }
 /**
  * Recommend a retry that is strictly larger than both the binding request and