@unbrained/pm-cli 2026.10.11 → 2026.10.13

package/dist/sdk/config.d.ts

@@ -18,119 +18,119 @@ type GovernanceForceRequiredForStaleLockPolicy = "enabled" | "disabled";
 type GovernanceRequireCloseReasonPolicy = "enabled" | "disabled";
 type ConfigValue = string | string[] | ItemFormat | HistoryMissingStreamPolicy | SprintReleaseFormatPolicy | ParentReferencePolicy | ValidateMetadataProfile | GovernancePreset | GovernanceOwnershipEnforcement | GovernanceCreateModeDefault | GovernanceCloseValidationDefault | GovernanceRequireCloseReasonPolicy | GovernanceWorkflowEnforcement | GovernanceForceRequiredForStaleLockPolicy | TestResultTrackingPolicy | TelemetryTrackingPolicy | AgentIdentityVocabularySummary | ContextConfigValue;
 interface ContextConfigValue {
-    default_depth: string;
-    activity_limit: number;
-    stale_threshold_days: number;
-    sections: Record<string, boolean>;
+default_depth: string;
+activity_limit: number;
+stale_threshold_days: number;
+sections: Record<string, boolean>;
 }
 interface ConfigKeyDescriptor {
-    key: ConfigKey;
-    aliases: string[];
-    value_kind: "string_array" | "enum" | "object";
-    set_flags: string[];
-    summary: string;
-    value: ConfigValue;
+key: ConfigKey;
+aliases: string[];
+value_kind: "string_array" | "enum" | "object";
+set_flags: string[];
+summary: string;
+value: ConfigValue;
 }
 /** Documents the config command options payload exchanged by command, SDK, and package integrations. */
 export interface ConfigCommandOptions {
-    /** Value that configures or reports criterion for this contract. */
-    criterion?: string[];
-    /** Value that configures or reports format for this contract. */
-    format?: string;
-    /** Value that configures or reports policy for this contract. */
-    policy?: string;
-    /** Value that configures or reports value for this contract. */
-    value?: string;
-    /** Value that configures or reports clear criteria for this contract. */
-    clearCriteria?: boolean;
-    /** Fallback depth used when callers do not provide an override. */
-    defaultDepth?: string;
-    /** Value that configures or reports activity limit for this contract. */
-    activityLimit?: string;
-    /** Value that configures or reports stale threshold days for this contract. */
-    staleThresholdDays?: string;
-    /** Value that configures or reports section hierarchy for this contract. */
-    sectionHierarchy?: string;
-    /** Value that configures or reports section activity for this contract. */
-    sectionActivity?: string;
-    /** Value that configures or reports section progress for this contract. */
-    sectionProgress?: string;
-    /** Value that configures or reports section blockers for this contract. */
-    sectionBlockers?: string;
-    /** Value that configures or reports section files for this contract. */
-    sectionFiles?: string;
-    /** Value that configures or reports section workload for this contract. */
-    sectionWorkload?: string;
-    /** Value that configures or reports section staleness for this contract. */
-    sectionStaleness?: string;
-    /** Value that configures or reports section tests for this contract. */
-    sectionTests?: string;
+/** Value that configures or reports criterion for this contract. */
+criterion?: string[];
+/** Value that configures or reports format for this contract. */
+format?: string;
+/** Value that configures or reports policy for this contract. */
+policy?: string;
+/** Value that configures or reports value for this contract. */
+value?: string;
+/** Value that configures or reports clear criteria for this contract. */
+clearCriteria?: boolean;
+/** Fallback depth used when callers do not provide an override. */
+defaultDepth?: string;
+/** Value that configures or reports activity limit for this contract. */
+activityLimit?: string;
+/** Value that configures or reports stale threshold days for this contract. */
+staleThresholdDays?: string;
+/** Value that configures or reports section hierarchy for this contract. */
+sectionHierarchy?: string;
+/** Value that configures or reports section activity for this contract. */
+sectionActivity?: string;
+/** Value that configures or reports section progress for this contract. */
+sectionProgress?: string;
+/** Value that configures or reports section blockers for this contract. */
+sectionBlockers?: string;
+/** Value that configures or reports section files for this contract. */
+sectionFiles?: string;
+/** Value that configures or reports section workload for this contract. */
+sectionWorkload?: string;
+/** Value that configures or reports section staleness for this contract. */
+sectionStaleness?: string;
+/** Value that configures or reports section tests for this contract. */
+sectionTests?: string;
 }
 /** Documents the nested setting result value payload exchanged by command, SDK, and package integrations. */
 export interface NestedSettingResultValue {
-    /** Value that configures or reports key for this contract. */
-    key: string;
-    /** Preferred kebab-case CLI spelling for copy/paste-safe configuration. */
-    canonical_key?: string;
-    /** Filesystem path used for path resolution. */
-    path: string;
-    /** Value that configures or reports kind for this contract. */
-    kind: NestedSettingDescriptor["kind"];
-    /** Value that configures or reports value for this contract. */
-    value: string | number | boolean | null;
-    /** Short operator-facing explanation of the setting. */
-    summary?: string;
-    /** Closed value domain when the setting accepts a fixed vocabulary. */
-    choices?: string[];
-    /** Inclusive numeric lower bound when one is declared. */
-    min?: number;
-    /** Inclusive numeric upper bound when one is declared. */
-    max?: number;
+/** Value that configures or reports key for this contract. */
+key: string;
+/** Preferred kebab-case CLI spelling for copy/paste-safe configuration. */
+canonical_key?: string;
+/** Filesystem path used for path resolution. */
+path: string;
+/** Value that configures or reports kind for this contract. */
+kind: NestedSettingDescriptor["kind"];
+/** Value that configures or reports value for this contract. */
+value: string | number | boolean | null;
+/** Short operator-facing explanation of the setting. */
+summary?: string;
+/** Closed value domain when the setting accepts a fixed vocabulary. */
+choices?: string[];
+/** Inclusive numeric lower bound when one is declared. */
+min?: number;
+/** Inclusive numeric upper bound when one is declared. */
+max?: number;
 }
 /** Documents the config result payload exchanged by command, SDK, and package integrations. */
 export interface ConfigResult {
-    /** Value that configures or reports scope for this contract. */
-    scope: ConfigScope;
-    /** Value that configures or reports key for this contract. */
-    key?: ConfigKey | string;
-    /** Value that configures or reports criteria for this contract. */
-    criteria?: string[];
-    /** Value that configures or reports format for this contract. */
-    format?: ItemFormat;
-    /** Value that configures or reports policy for this contract. */
-    policy?: HistoryMissingStreamPolicy | SprintReleaseFormatPolicy | ParentReferencePolicy | ValidateMetadataProfile | GovernancePreset | GovernanceOwnershipEnforcement | GovernanceCreateModeDefault | GovernanceCloseValidationDefault | GovernanceRequireCloseReasonPolicy | GovernanceWorkflowEnforcement | GovernanceForceRequiredForStaleLockPolicy | TestResultTrackingPolicy | TelemetryTrackingPolicy | string;
-    /** Value that configures or reports nested setting for this contract. */
-    nested_setting?: NestedSettingResultValue;
-    /** Configuration controlling nested behavior. */
-    nested_settings?: NestedSettingResultValue[];
-    /** Value that configures or reports keys for this contract. */
-    keys?: ConfigKeyDescriptor[];
-    /** Value that configures or reports values for this contract. */
-    values?: Record<ConfigKey, ConfigValue>;
-    /** Value that configures or reports count for this contract. */
-    count?: number;
-    /** Configuration controlling context behavior. */
-    context_settings?: ContextConfigValue;
-    /** Privacy-safe revision/count projection for legacy author interpretation. */
-    identity_vocabulary?: AgentIdentityVocabularySummary;
-    /** Dry-run or committed vocabulary mutation receipt without alias spellings. */
-    vocabulary_mutation?: AgentIdentityVocabularyMutationPreview;
-    /** Whether explicit item format applies to this operation. */
-    has_explicit_item_format?: boolean;
-    /** Value that configures or reports migration for this contract. */
-    migration?: {
-        target_format: ItemFormat;
-        scanned: number;
-        migrated: string[];
-        removed: string[];
-        warnings: string[];
-    };
-    /** Filesystem path used for settings resolution. */
-    settings_path: string;
-    /** Value that configures or reports changed for this contract. */
-    changed: boolean;
-    /** Value that configures or reports warnings for this contract. */
-    warnings?: string[];
+/** Value that configures or reports scope for this contract. */
+scope: ConfigScope;
+/** Value that configures or reports key for this contract. */
+key?: ConfigKey | string;
+/** Value that configures or reports criteria for this contract. */
+criteria?: string[];
+/** Value that configures or reports format for this contract. */
+format?: ItemFormat;
+/** Value that configures or reports policy for this contract. */
+policy?: HistoryMissingStreamPolicy | SprintReleaseFormatPolicy | ParentReferencePolicy | ValidateMetadataProfile | GovernancePreset | GovernanceOwnershipEnforcement | GovernanceCreateModeDefault | GovernanceCloseValidationDefault | GovernanceRequireCloseReasonPolicy | GovernanceWorkflowEnforcement | GovernanceForceRequiredForStaleLockPolicy | TestResultTrackingPolicy | TelemetryTrackingPolicy | string;
+/** Value that configures or reports nested setting for this contract. */
+nested_setting?: NestedSettingResultValue;
+/** Configuration controlling nested behavior. */
+nested_settings?: NestedSettingResultValue[];
+/** Value that configures or reports keys for this contract. */
+keys?: ConfigKeyDescriptor[];
+/** Value that configures or reports values for this contract. */
+values?: Record<ConfigKey, ConfigValue>;
+/** Value that configures or reports count for this contract. */
+count?: number;
+/** Configuration controlling context behavior. */
+context_settings?: ContextConfigValue;
+/** Privacy-safe revision/count projection for legacy author interpretation. */
+identity_vocabulary?: AgentIdentityVocabularySummary;
+/** Dry-run or committed vocabulary mutation receipt without alias spellings. */
+vocabulary_mutation?: AgentIdentityVocabularyMutationPreview;
+/** Whether explicit item format applies to this operation. */
+has_explicit_item_format?: boolean;
+/** Value that configures or reports migration for this contract. */
+migration?: {
+target_format: ItemFormat;
+scanned: number;
+migrated: string[];
+removed: string[];
+warnings: string[];
+};
+/** Filesystem path used for settings resolution. */
+settings_path: string;
+/** Value that configures or reports changed for this contract. */
+changed: boolean;
+/** Value that configures or reports warnings for this contract. */
+warnings?: string[];
 }
 declare function normalizeScope(value: string): ConfigScope;
 declare function normalizeAction(value: string): ConfigAction;
@@ -158,26 +158,26 @@ declare function hasGovernanceValidationMirrorChange<T extends ParentReferencePo
 export declare function runConfig(scopeValue: string, actionValue: string, keyValue: string | undefined, options: ConfigCommandOptions, global: GlobalOptions, valueValue?: string): Promise<ConfigResult>;
 /** Public contract for test only config command, shared by SDK and presentation-layer consumers. */
 export declare const _testOnlyConfigCommand: {
-    hasGovernanceValidationMirrorChange: typeof hasGovernanceValidationMirrorChange;
-    applyPositionalValue: typeof applyPositionalValue;
-    normalizeAction: typeof normalizeAction;
-    normalizeCriteria: typeof normalizeCriteria;
-    normalizeGovernanceCloseValidationDefault: typeof normalizeGovernanceCloseValidationDefault;
-    normalizeGovernanceCreateModeDefault: typeof normalizeGovernanceCreateModeDefault;
-    normalizeGovernanceForceRequiredForStaleLockPolicy: typeof normalizeGovernanceForceRequiredForStaleLockPolicy;
-    normalizeGovernanceOwnershipEnforcement: typeof normalizeGovernanceOwnershipEnforcement;
-    normalizeGovernancePreset: typeof normalizeGovernancePreset;
-    normalizeGovernanceRequireCloseReasonPolicy: typeof normalizeGovernanceRequireCloseReasonPolicy;
-    normalizeGovernanceWorkflowEnforcement: typeof normalizeGovernanceWorkflowEnforcement;
-    normalizeHistoryMissingStreamPolicy: typeof normalizeHistoryMissingStreamPolicy;
-    normalizeItemFormat: typeof normalizeItemFormat;
-    normalizeKey: typeof normalizeKey;
-    normalizeMetadataRequiredFields: typeof normalizeMetadataRequiredFields;
-    normalizePolicyForConflict: typeof normalizePolicyForConflict;
-    normalizeScope: typeof normalizeScope;
-    normalizeTelemetryTrackingPolicy: typeof normalizeTelemetryTrackingPolicy;
-    normalizeTestResultTrackingPolicy: typeof normalizeTestResultTrackingPolicy;
-    normalizeValidateMetadataProfile: typeof normalizeValidateMetadataProfile;
-    normalizeWarnings: typeof normalizeWarnings;
+hasGovernanceValidationMirrorChange: typeof hasGovernanceValidationMirrorChange;
+applyPositionalValue: typeof applyPositionalValue;
+normalizeAction: typeof normalizeAction;
+normalizeCriteria: typeof normalizeCriteria;
+normalizeGovernanceCloseValidationDefault: typeof normalizeGovernanceCloseValidationDefault;
+normalizeGovernanceCreateModeDefault: typeof normalizeGovernanceCreateModeDefault;
+normalizeGovernanceForceRequiredForStaleLockPolicy: typeof normalizeGovernanceForceRequiredForStaleLockPolicy;
+normalizeGovernanceOwnershipEnforcement: typeof normalizeGovernanceOwnershipEnforcement;
+normalizeGovernancePreset: typeof normalizeGovernancePreset;
+normalizeGovernanceRequireCloseReasonPolicy: typeof normalizeGovernanceRequireCloseReasonPolicy;
+normalizeGovernanceWorkflowEnforcement: typeof normalizeGovernanceWorkflowEnforcement;
+normalizeHistoryMissingStreamPolicy: typeof normalizeHistoryMissingStreamPolicy;
+normalizeItemFormat: typeof normalizeItemFormat;
+normalizeKey: typeof normalizeKey;
+normalizeMetadataRequiredFields: typeof normalizeMetadataRequiredFields;
+normalizePolicyForConflict: typeof normalizePolicyForConflict;
+normalizeScope: typeof normalizeScope;
+normalizeTelemetryTrackingPolicy: typeof normalizeTelemetryTrackingPolicy;
+normalizeTestResultTrackingPolicy: typeof normalizeTestResultTrackingPolicy;
+normalizeValidateMetadataProfile: typeof normalizeValidateMetadataProfile;
+normalizeWarnings: typeof normalizeWarnings;
 };
 export {};

package/dist/sdk/context/semantic-session-attribution.d.ts

@@ -4,29 +4,29 @@ import { readSettings } from "../../core/store/settings.js";
 export declare function resolveSemanticLineageIds(pmRoot: string, settings: Awaited<ReturnType<typeof readSettings>>, itemId: string): Promise<string[]>;
 /** Record one successful claim and its bounded canonical lineage. */
 export declare function recordClaimSemanticAttribution(params: {
-    pmRoot: string;
-    settings: Awaited<ReturnType<typeof readSettings>>;
-    principal: string;
-    itemId: string;
+pmRoot: string;
+settings: Awaited<ReturnType<typeof readSettings>>;
+principal: string;
+itemId: string;
 }): Promise<void>;
 /** Remove one released claim from the active semantic workset. */
 export declare function recordReleaseSemanticAttribution(params: {
-    pmRoot: string;
-    principal: string;
-    itemId: string;
+pmRoot: string;
+principal: string;
+itemId: string;
 }): Promise<void>;
 /** Set or clear focused semantic work with canonical lineage evidence. */
 export declare function recordFocusSemanticAttribution(params: {
-    pmRoot: string;
-    settings: Awaited<ReturnType<typeof readSettings>>;
-    principal: string;
-    itemId?: string;
+pmRoot: string;
+settings: Awaited<ReturnType<typeof readSettings>>;
+principal: string;
+itemId?: string;
 }): Promise<void>;
 /** Public constants used by scale and negative-control tests. */
 export declare const SEMANTIC_ATTRIBUTION_LIMITS: {
-    readonly lineage_depth: 16;
-    readonly active_items: 64;
-    readonly evidence_rows: 32;
+readonly lineage_depth: 16;
+readonly active_items: 64;
+readonly evidence_rows: 32;
 };
 /** Convert bounded claim/focus evidence into normalized context affinity. */
 export declare function semanticAttributionAffinity(attribution: AgentSemanticAttribution | undefined): Readonly<Record<string, number>> | undefined;

package/dist/sdk/context/usage-ledger.d.ts

@@ -1,35 +1,35 @@
 import type { ContextUsageEvent, ContextUsageLedgerOptions } from "../context-usage.js";
 /** Public storage and sampling ceilings shared by every feedback producer. */
 export declare const CONTEXT_USAGE_LIMITS: {
-    readonly max_serving_rows: 256;
-    readonly max_bytes: 262144;
-    readonly max_event_bytes: 32768;
-    readonly retained_byte_fraction: 0.5;
-    readonly max_events: 2048;
-    readonly retention_days: 30;
+readonly max_serving_rows: 256;
+readonly max_bytes: 262144;
+readonly max_event_bytes: 32768;
+readonly retained_byte_fraction: 0.5;
+readonly max_events: 2048;
+readonly retention_days: 30;
 };
 /** Measured persistence work for one lock-protected feedback write. */
 export interface ContextUsageWriteReceipt {
-    /** Bytes written to the append or replacement file; excludes lock metadata. */
-    written_bytes: number;
-    /** Physical ledger size at the end of the protected write. */
-    ledger_bytes: number;
-    /** Whether this write replaced the ledger with a retained suffix. */
-    compacted: boolean;
-    /** Wall-clock time waiting to acquire the cross-process ledger lock. */
-    lock_wait_ms: number;
+/** Bytes written to the append or replacement file; excludes lock metadata. */
+written_bytes: number;
+/** Physical ledger size at the end of the protected write. */
+ledger_bytes: number;
+/** Whether this write replaced the ledger with a retained suffix. */
+compacted: boolean;
+/** Wall-clock time waiting to acquire the cross-process ledger lock. */
+lock_wait_ms: number;
 }
 /** Named validation failure emitted by context-usage SDK inputs. */
 export declare class ContextUsageValidationError extends TypeError {
-    /** Stable code for package and CLI hosts. */
-    readonly code = "context_usage_validation_failed";
-    /** Reject invalid feedback controls without exposing ledger contents. */
-    constructor(message: string);
+/** Stable code for package and CLI hosts. */
+readonly code = "context_usage_validation_failed";
+/** Reject invalid feedback controls without exposing ledger contents. */
+constructor(message: string);
 }
 /** Normalize one timestamp so filtering and serialization share the same clock. */
 export declare function resolveNow(options: ContextUsageLedgerOptions): {
-    iso: string;
-    ms: number;
+iso: string;
+ms: number;
 };
 /** Read only a bounded file suffix, dropping a partial first JSONL row. */
 export declare function readEvents(options: ContextUsageLedgerOptions): Promise<ContextUsageEvent[]>;

package/dist/sdk/context-intent-contracts.d.ts

@@ -4,60 +4,60 @@ export type PmContextIntentCommand = "context" | "get" | "list" | "next" | "sear
 export type PmContextIntentSource = "core" | "package" | "workspace";
 /** One named, bounded projection of a command's context. */
 export interface PmContextIntentContract {
-    /** Command that accepts the intent. */
-    command: PmContextIntentCommand;
-    /** Stable intent identifier used by CLI, SDK, and MCP callers. */
-    intent: string;
-    /** Agent-facing explanation of the projection's purpose. */
-    description: string;
-    /** Declared output field groups retained by the projection. */
-    included_field_groups: string[];
-    /** Default maximum estimated tokens before normal degradation applies. */
-    token_budget: number;
-    /** Layer that supplied the resolved declaration. */
-    source?: PmContextIntentSource;
+/** Command that accepts the intent. */
+command: PmContextIntentCommand;
+/** Stable intent identifier used by CLI, SDK, and MCP callers. */
+intent: string;
+/** Agent-facing explanation of the projection's purpose. */
+description: string;
+/** Declared output field groups retained by the projection. */
+included_field_groups: string[];
+/** Default maximum estimated tokens before normal degradation applies. */
+token_budget: number;
+/** Layer that supplied the resolved declaration. */
+source?: PmContextIntentSource;
 }
 /** Machine-readable proof of the intent projection resolved for one read result. */
 export interface PmContextIntentReceipt {
-    /** Canonical read command that resolved the intent. */
-    command: string;
-    /** Stable selected intent name. */
-    intent: string;
-    /** Layer that supplied the resolved declaration. */
-    source: PmContextIntentSource;
-    /** Field groups the selected intent promises to retain. */
-    included_field_groups: string[];
-    /** Effective token ceiling after an explicit caller override is applied. */
-    token_budget: number;
-    /** Ceiling declared by the selected intent before caller overrides. */
-    declared_token_budget: number;
-    /** Signed difference between the effective and declared ceilings. */
-    token_budget_override: number;
-    /** Deterministic JSON-size estimate for the useful result before any receipt-only omission. */
-    estimated_tokens: number;
-    /** Whether the measured result fits the effective ceiling after caller overrides. */
-    within_budget: boolean;
-    /** Projection strategy applied before the result was measured. */
-    degradation: "bounded_fields_and_rows" | "bounded_ranked_rows" | "bounded_sections" | "budget_row_compaction" | "recursive_budget_compaction" | "budget_receipt_only" | "standard_item" | "none";
-    /** Whether the declared ceiling can carry the measured useful projection, independent of an override. */
-    declaration_feasible: boolean;
-    /** True only when no useful result survived the effective ceiling. */
-    result_omitted: boolean;
-    /** Row ceiling calculated from the selected intent's effective token budget. */
-    budget_derived_limit?: number;
-    /** Constraint that selected the effective page size for row-oriented reads. */
-    binding_constraint?: "explicit_limit" | "token_budget";
-    /** Machine-readable explanation for the selected row ceiling. */
-    limit_reason?: string;
+/** Canonical read command that resolved the intent. */
+command: string;
+/** Stable selected intent name. */
+intent: string;
+/** Layer that supplied the resolved declaration. */
+source: PmContextIntentSource;
+/** Field groups the selected intent promises to retain. */
+included_field_groups: string[];
+/** Effective token ceiling after an explicit caller override is applied. */
+token_budget: number;
+/** Ceiling declared by the selected intent before caller overrides. */
+declared_token_budget: number;
+/** Signed difference between the effective and declared ceilings. */
+token_budget_override: number;
+/** Deterministic JSON-size estimate for the useful result before any receipt-only omission. */
+estimated_tokens: number;
+/** Whether the measured result fits the effective ceiling after caller overrides. */
+within_budget: boolean;
+/** Projection strategy applied before the result was measured. */
+degradation: "bounded_fields_and_rows" | "bounded_ranked_rows" | "bounded_sections" | "budget_row_compaction" | "recursive_budget_compaction" | "budget_receipt_only" | "standard_item" | "none";
+/** Whether the declared ceiling can carry the measured useful projection, independent of an override. */
+declaration_feasible: boolean;
+/** True only when no useful result survived the effective ceiling. */
+result_omitted: boolean;
+/** Row ceiling calculated from the selected intent's effective token budget. */
+budget_derived_limit?: number;
+/** Constraint that selected the effective page size for row-oriented reads. */
+binding_constraint?: "explicit_limit" | "token_budget";
+/** Machine-readable explanation for the selected row ceiling. */
+limit_reason?: string;
 }
 /** Built-in intent projections shared by CLI, SDK, MCP, and package authors. */
 export declare const PM_CONTEXT_INTENT_CONTRACTS: readonly PmContextIntentContract[];
 /** Runtime declaration layers applied to one asynchronous SDK or CLI execution. */
 export interface PmContextIntentRuntimeLayers {
-    /** Workspace declarations, which may override a core or package declaration. */
-    workspaceContracts?: readonly PmContextIntentContract[];
-    /** Package declarations, which may add but not replace earlier declarations. */
-    packageContracts?: readonly PmContextIntentContract[];
+/** Workspace declarations, which may override a core or package declaration. */
+workspaceContracts?: readonly PmContextIntentContract[];
+/** Package declarations, which may add but not replace earlier declarations. */
+packageContracts?: readonly PmContextIntentContract[];
 }
 /** Return the request-scoped intent registry, or the immutable built-in registry outside a configured scope. */
 export declare function getActiveContextIntentContracts(): readonly PmContextIntentContract[];
@@ -70,9 +70,9 @@ export declare function resolveContextIntentContract(command: string, intent: st
 /** Apply one declared read intent's defaults while preserving explicit caller options. */
 export declare function applyContextIntentProjection(command: "context" | "get" | "list" | "next" | "search", options: Record<string, unknown>, positionalArguments?: readonly string[]): Record<string, unknown>;
 interface ContextIntentCursorEnvelope {
-    fingerprint: string;
-    after_index: number;
-    snapshot?: string;
+fingerprint: string;
+after_index: number;
+snapshot?: string;
 }
 /** Decode the cursor fields required to preserve a row-compacted continuation. */
 export declare function decodeContextIntentCursor(cursor: string): ContextIntentCursorEnvelope | undefined;
@@ -80,7 +80,7 @@ export declare function decodeContextIntentCursor(cursor: string): ContextIntent
 export declare function contextIntentRowId(row: unknown): string | undefined;
 /** Attach budget and degradation evidence for a selected built-in read intent. */
 export declare function attachContextIntentReceipt<Result extends Record<string, unknown>>(command: string, options: Record<string, unknown>, result: Result): Result & {
-    context_intent?: PmContextIntentReceipt;
+context_intent?: PmContextIntentReceipt;
 };
 /** Attach universal row, omission, and optional intent-budget contracts in rendering order. */
 export declare function attachReadOutputContracts(command: string | undefined, options: Record<string, unknown>, result: unknown): unknown;

package/dist/sdk/context-intent-contracts.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]="e834062a-97f7-51d7-b934-1e4b43e3d6b2")}catch{}})();import{AsyncLocalStorage}from"node:async_hooks";import{renderPmCommand}from"./command-line.js";import{attachOutputOmissionReceipt}from"./output-projection.js";import{encodeQueryCursor}from"./pagination.js";import{applyReadOutputDimensions,stabilizeReadOutputReceiptEstimates}from"./read-output-contracts.js";import{propagateContextUsageServingReceipt}from"./context-usage.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";const PM_CONTEXT_INTENT_CONTRACTS=Object.freeze([{command:"context",intent:"orient",description:"Bounded active hierarchy, ownership, blockers, and recent progress.",included_field_groups:["summary","focus","hierarchy","blockers","activity"],token_budget:3e3,source:"core"},{command:"context",intent:"handoff",description:"Active ownership, evidence, decisions, and immediate continuation context.",included_field_groups:["summary","focus","in_progress","decisions","activity"],token_budget:2200,source:"core"},{command:"get",intent:"inspect",description:"Standard-depth item metadata, relationships, evidence, and lifecycle state.",included_field_groups:["item","children","claim_state","linked"],token_budget:3200,source:"core"},{command:"list",intent:"triage",description:"A budget-derived page of compact governance, ownership, priority, and blocker rows for triage.",included_field_groups:["identity","governance","ownership","dependencies"],token_budget:3200,source:"core"},{command:"next",intent:"execute",description:"The highest-ranked actionable work with concise ranking evidence.",included_field_groups:["recommended"],token_budget:1200,source:"core"},{command:"search",intent:"discover",description:"A budget-derived page of ranked canonical lineage candidates with compact match evidence.",included_field_groups:["identity","status","lineage","match"],token_budget:1800,source:"core"}]),activeContextIntentContracts=new AsyncLocalStorage;function getActiveContextIntentContracts(){return activeContextIntentContracts.getStore()??PM_CONTEXT_INTENT_CONTRACTS}function runWithContextIntentContracts(layers,run){return activeContextIntentContracts.run(composeContextIntentContracts(layers.workspaceContracts,layers.packageContracts),run)}function normalizeContextIntentDeclaration(declaration,source){const command=declaration.command.trim().toLowerCase(),intent=declaration.intent.trim().toLowerCase(),key=`${command}:${intent}`;if(!/^[a-z0-9][a-z0-9-]*$/.test(command)||!/^[a-z0-9][a-z0-9-]*$/.test(intent))throw new TypeError(`Invalid context intent command or name: ${key}`);if(declaration.description.trim().length===0)throw new TypeError(`Context intent ${key} requires a non-empty description`);if(!Number.isSafeInteger(declaration.token_budget)||declaration.token_budget<=0)throw new TypeError(`Context intent ${key} requires a positive integer token_budget`);const includedFieldGroups=[...new Set(declaration.included_field_groups.map(field=>field.trim()).filter(Boolean))];if(includedFieldGroups.length===0)throw new TypeError(`Context intent ${key} requires included_field_groups`);return{command,intent,description:declaration.description.trim(),included_field_groups:includedFieldGroups,token_budget:declaration.token_budget,source}}function composeContextIntentContracts(workspaceContracts=[],packageContracts=[]){const layers=[{source:"core",contracts:PM_CONTEXT_INTENT_CONTRACTS,allowOverride:!1},{source:"package",contracts:packageContracts,allowOverride:!1},{source:"workspace",contracts:workspaceContracts,allowOverride:!0}],composed=new Map,keysSeenWithinLayer=new Set;for(const layer of layers){keysSeenWithinLayer.clear();for(const declaration of layer.contracts){const normalized=normalizeContextIntentDeclaration(declaration,layer.source),key=`${normalized.command}:${normalized.intent}`;if(keysSeenWithinLayer.has(key))throw new TypeError(`Duplicate context intent declaration: ${key}`);if(keysSeenWithinLayer.add(key),!layer.allowOverride&&composed.has(key))throw new TypeError(`Duplicate context intent declaration: ${key}`);composed.set(key,normalized)}}return[...composed.values()].sort((left,right)=>left.command.localeCompare(right.command)||left.intent.localeCompare(right.intent))}function resolveContextIntentContract(command,intent,contracts=getActiveContextIntentContracts(),positionalArguments=[]){const normalizedCommand=command.trim().toLowerCase(),normalizedIntent=intent.trim().toLowerCase(),exact=contracts.find(entry=>entry.command===normalizedCommand&&entry.intent===normalizedIntent);if(exact)return{...exact,source:exact.source??"core"};const candidates=contracts.filter(entry=>entry.command===normalizedCommand).map(entry=>entry.intent);if(candidates.length===0)return;const suggestion=candidates.map(candidate=>{const rows=Array.from({length:normalizedIntent.length+1},(_,index)=>index);for(let candidateIndex=1;candidateIndex<=candidate.length;candidateIndex+=1){let previous=rows[0];rows[0]=candidateIndex;for(let intentIndex=1;intentIndex<=normalizedIntent.length;intentIndex+=1){const prior=rows[intentIndex];rows[intentIndex]=Math.min(rows[intentIndex]+1,rows[intentIndex-1]+1,previous+(candidate[candidateIndex-1]===normalizedIntent[intentIndex-1]?0:1)),previous=prior}}return{candidate,distance:rows[normalizedIntent.length]}}).sort((left,right)=>left.distance-right.distance||left.candidate.localeCompare(right.candidate))[0].candidate,attemptedArguments=[normalizedCommand,...positionalArguments,"--for",normalizedIntent],suggestedRetryArguments=[normalizedCommand,...positionalArguments,"--for",suggestion],suggestedCommand=renderPmCommand(suggestedRetryArguments);throw new PmCliError(`Unknown context intent "${normalizedIntent}" for ${normalizedCommand}. Did you mean "${suggestion}"?`,EXIT_CODE.USAGE,{code:"unknown_context_intent",reason:"unknown_intent",field:"for",flag:"--for",value:normalizedIntent,required:`Use a declared ${normalizedCommand} intent.`,why:"Intent names are command-local contracts and cannot be inferred from output section names.",nextSteps:[suggestedCommand],recovery:{recovery_mode:"compact",attempted_command:renderPmCommand(attemptedArguments),allowed_values:[...candidates].sort(),suggested_retry:suggestedCommand,suggested_retry_args:suggestedRetryArguments}})}const CONTEXT_INTENT_DEFAULT_APPLIERS={context:(projected,contract,explicitTokenBudget)=>{projected.section===void 0&&projected.depth===void 0&&(projected.section=contract.intent==="handoff"?["activity","progress","blockers"]:["hierarchy","blockers","activity"]),projected.depth===void 0&&(projected.depth=contract.intent==="handoff"?"deep":"standard");const tokenBudget=resolveIntentTokenBudget(projected.tokenBudget,contract.token_budget),budgetDerivedLimit=resolveIntentRowBudget("context",contract.intent,tokenBudget,explicitTokenBudget),requestedLimit=parsePositiveIntentTokenBudget(projected.limit),derivedLimit=String(requestedLimit===void 0?budgetDerivedLimit:Math.min(requestedLimit,budgetDerivedLimit));(projected.limit===void 0||requestedLimit!==void 0)&&(projected.limit=derivedLimit),projected.activityLimit===void 0&&(projected.activityLimit=derivedLimit)},get:projected=>{projected.depth===void 0&&projected.fields===void 0&&(projected.depth="standard")},list:(projected,contract,explicitTokenBudget)=>{projected.brief===void 0&&projected.compact===void 0&&projected.full===void 0&&projected.fields===void 0&&(projected.fields="id,title,status,type,priority,parent,assignee,risk,blocked_by");const tokenBudget=resolveIntentTokenBudget(projected.tokenBudget,contract.token_budget),budgetDerivedLimit=resolveIntentRowBudget("list",contract.intent,tokenBudget,explicitTokenBudget),requestedLimit=parsePositiveIntentTokenBudget(projected.limit);(projected.limit===void 0||requestedLimit!==void 0)&&(projected.limit=String(requestedLimit===void 0?budgetDerivedLimit:Math.min(requestedLimit,budgetDerivedLimit)))},next:projected=>{projected.readyOnly===void 0&&(projected.readyOnly=!0)},search:(projected,contract,explicitTokenBudget)=>{projected.compact===void 0&&projected.full===void 0&&projected.fields===void 0&&(projected.compact=!0);const tokenBudget=resolveIntentTokenBudget(projected.tokenBudget,contract.token_budget),budgetDerivedLimit=resolveIntentRowBudget("search",contract.intent,tokenBudget,explicitTokenBudget),requestedLimit=parsePositiveIntentTokenBudget(projected.limit);(projected.limit===void 0||requestedLimit!==void 0)&&(projected.limit=String(requestedLimit===void 0?budgetDerivedLimit:Math.min(requestedLimit,budgetDerivedLimit)))}};function applyContextIntentProjection(command,options,positionalArguments=[]){const tokenBudget=options.tokenBudget??options.token_budget;if(typeof options.for!="string"){if(tokenBudget!==void 0&&(command==="get"||command==="list"||command==="search"))throw new PmCliError("--token-budget requires a declared context intent selected with --for",EXIT_CODE.USAGE,{code:"missing_required_option",field:"for",required:"Select a context intent with --for when setting --token-budget.",why:"A token-budget override has no projection contract to constrain without a selected intent.",nextSteps:["Retry with --for <intent> --token-budget <n>, or omit --token-budget."]});if(options.tokenBudget!==void 0||options.token_budget===void 0)return options;const projected2={...options,tokenBudget};return delete projected2.token_budget,projected2}const contract=resolveContextIntentContract(command,options.for,void 0,positionalArguments),explicitTokenBudget=parsePositiveIntentTokenBudget(tokenBudget)!==void 0,projected={...options};return projected.tokenBudget===void 0&&tokenBudget!==void 0&&(projected.tokenBudget=tokenBudget),delete projected.token_budget,projected.tokenBudget===void 0&&(projected.tokenBudget=String(contract.token_budget)),CONTEXT_INTENT_DEFAULT_APPLIERS[command](projected,contract,explicitTokenBudget),projected}const CONTEXT_INTENT_DEGRADATIONS={context:"bounded_sections",get:"standard_item",list:"bounded_fields_and_rows",next:"bounded_ranked_rows",search:"bounded_ranked_rows"},MINIMUM_CONTEXT_INTENT_TOKEN_BUDGET=256;function compactContextIntentValue(value){return Array.isArray(value)?value.map(compactContextIntentValue):value!==null&&typeof value=="object"?Object.fromEntries(Object.entries(value).map(([key,entry])=>[key,compactContextIntentValue(entry)])):typeof value=="string"&&value.length>240?`${value.slice(0,240)}\u2026`:value}function parsePositiveIntentTokenBudget(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 resolveIntentTokenBudget(value,declaredBudget){const parsed=parsePositiveIntentTokenBudget(value);if(parsed===void 0)return declaredBudget;if(parsed<MINIMUM_CONTEXT_INTENT_TOKEN_BUDGET)throw new PmCliError(`Context intent token budget must be at least ${MINIMUM_CONTEXT_INTENT_TOKEN_BUDGET}`,EXIT_CODE.USAGE,{code:"invalid_argument_value",reason:"below_minimum",field:"tokenBudget",value:String(value),required:`Use an integer token budget of at least ${MINIMUM_CONTEXT_INTENT_TOKEN_BUDGET}.`,why:"Smaller ceilings cannot contain the minimum machine-readable intent receipt.",nextSteps:[`Retry with --token-budget ${MINIMUM_CONTEXT_INTENT_TOKEN_BUDGET} or omit the override.`]});return parsed}function resolveIntentRowBudget(command,intent,tokenBudget,explicitTokenBudget){if(command==="get"||command==="next")return;const contextOrient=command==="context"&&intent==="orient",overhead=command==="context"?contextOrient?1200:800:command==="list"?520:480,rowCost=command==="context"?contextOrient?600:500:16,calculatedLimit=Math.max(command==="context"?1:2,Math.floor((tokenBudget-overhead)/rowCost));return explicitTokenBudget?calculatedLimit:Math.min(command==="context"?20:100,calculatedLimit)}function updateContextIntentEstimate(projected,receipt){let measuredTokens=receipt.estimated_tokens;for(;;){receipt.estimated_tokens=measuredTokens;const nextMeasurement=Math.ceil(Buffer.byteLength(JSON.stringify(projected),"utf8")/4);if(nextMeasurement===measuredTokens)return;measuredTokens=nextMeasurement}}const CONTEXT_INTENT_ROW_KEYS={context:["high_level","low_level","blocked_fallback","recently_created","unparented","hierarchy","activity","blockers"],get:["children"],list:["items"],next:["ready","decision_needed","gate_needed","containers","blocked","held_by_others"],search:["items"]};function decodeContextIntentCursor(cursor){try{const parsed=JSON.parse(Buffer.from(cursor,"base64url").toString("utf8"));return typeof parsed.fingerprint!="string"||!Number.isSafeInteger(parsed.after_index)?void 0:{fingerprint:parsed.fingerprint,after_index:parsed.after_index,...typeof parsed.snapshot=="string"?{snapshot:parsed.snapshot}:{}}}catch{return}}function contextIntentRowId(row){if(row===null||typeof row!="object")return;if(typeof row.id=="string")return row.id;const nestedId=row.item?.id;return typeof nestedId=="string"?nestedId:void 0}function shrinkContextIntentRowsToBudget(projected,receipt,rows){let compacted=!1;for(;;){if(updateContextIntentEstimate(projected,receipt),receipt.estimated_tokens<=receipt.token_budget||rows.length<=1)return compacted;const rowBytes=Buffer.byteLength(JSON.stringify(rows),"utf8"),excessBytes=(receipt.estimated_tokens-receipt.token_budget)*4;rows.splice(-Math.min(rows.length-1,Math.max(1,Math.ceil(excessBytes/Math.max(1,Math.ceil(rowBytes/rows.length)))))),compacted=!0}}function compactPaginatedContextIntentRows(projected,receipt,options){const rows=projected.items,cursorContinuesExistingPage=typeof projected.next_cursor=="string",cursorSource=cursorContinuesExistingPage?projected.next_cursor:options.after;if(!Array.isArray(rows)||typeof cursorSource!="string")return!1;const cursorEnvelope=decodeContextIntentCursor(cursorSource);if(cursorEnvelope===void 0)return!1;const originalRowCount=rows.length,originalRows=[...rows];let compacted=!1;for(;;){if(compacted=shrinkContextIntentRowsToBudget(projected,receipt,rows)||compacted,!compacted)return!1;const lastId=contextIntentRowId(rows.at(-1));if(lastId===void 0)return rows.splice(0,rows.length,...originalRows),updateContextIntentEstimate(projected,receipt),!1;if(projected.next_cursor=encodeQueryCursor(cursorEnvelope.fingerprint,lastId,cursorContinuesExistingPage?cursorEnvelope.after_index-(originalRowCount-rows.length):cursorEnvelope.after_index+rows.length,cursorEnvelope.snapshot),updateContextIntentEstimate(projected,receipt),receipt.estimated_tokens<=receipt.token_budget||rows.length<=1)break}return typeof projected.count=="number"&&(projected.count=rows.length),typeof projected.applied_limit=="number"&&(projected.applied_limit=rows.length),!0}function compactContextIntentRows(command,projected,receipt,options){if(command==="list"||command==="search")return compactPaginatedContextIntentRows(projected,receipt,options);if(command!=="next"||typeof projected.next_cursor=="string")return!1;let compacted=!1;for(;;){if(updateContextIntentEstimate(projected,receipt),receipt.estimated_tokens<=receipt.token_budget)return compacted;const candidate=CONTEXT_INTENT_ROW_KEYS[command].map(key=>({key,rows:Array.isArray(projected[key])?projected[key]:[]})).filter(({rows})=>rows.length>0).sort((left,right)=>right.rows.length-left.rows.length||left.key.localeCompare(right.key))[0];if(candidate===void 0)return compacted;const retainedTotal=CONTEXT_INTENT_ROW_KEYS[command].reduce((total,key)=>total+(Array.isArray(projected[key])?projected[key].length:0),0);if(retainedTotal<=1)return compacted;const removableRows=Math.min(candidate.rows.length,retainedTotal-1),candidateBytes=Buffer.byteLength(JSON.stringify(candidate.rows),"utf8"),estimatedBytesPerRow=Math.max(1,Math.ceil(candidateBytes/candidate.rows.length)),excessBytes=(receipt.estimated_tokens-receipt.token_budget)*4,removalCount=Math.min(removableRows,Math.max(1,Math.ceil(excessBytes/estimatedBytesPerRow)));candidate.rows.splice(-removalCount,removalCount),compacted=!0}}function attachContextIntentReceipt(command,options,result){if(typeof options.for!="string")return result;const normalizedCommand=command.startsWith("list-")?"list":command;if(!(normalizedCommand in CONTEXT_INTENT_DEFAULT_APPLIERS))return result;const builtInCommand=normalizedCommand,contract=resolveContextIntentContract(builtInCommand,options.for),effectiveTokenBudget=resolveIntentTokenBudget(options.tokenBudget??options.token_budget,contract.token_budget),receipt={command:builtInCommand,intent:contract.intent,source:contract.source,included_field_groups:[...contract.included_field_groups],token_budget:effectiveTokenBudget,declared_token_budget:contract.token_budget,token_budget_override:effectiveTokenBudget-contract.token_budget,estimated_tokens:0,within_budget:!0,degradation:CONTEXT_INTENT_DEGRADATIONS[builtInCommand],declaration_feasible:!0,result_omitted:!1},resultWithDiagnostics={...result},budgetDerivedLimit=resolveIntentRowBudget(builtInCommand,contract.intent,receipt.token_budget,parsePositiveIntentTokenBudget(options.tokenBudget??options.token_budget)!==void 0);if(budgetDerivedLimit!==void 0){const effectiveLimit=parsePositiveIntentTokenBudget(options.limit),explicitLimitBinds=effectiveLimit!==void 0&&effectiveLimit<budgetDerivedLimit;receipt.budget_derived_limit=budgetDerivedLimit,receipt.binding_constraint=explicitLimitBinds?"explicit_limit":"token_budget",receipt.limit_reason=explicitLimitBinds?"The caller supplied a smaller row limit than the budget-derived ceiling.":"The selected intent token budget constrains the effective row ceiling.",resultWithDiagnostics.budget_derived_limit=budgetDerivedLimit}let projected={...resultWithDiagnostics,context_intent:receipt};return updateContextIntentEstimate(projected,receipt),receipt.estimated_tokens>receipt.token_budget&&(receipt.degradation="recursive_budget_compaction",projected={...compactContextIntentValue(resultWithDiagnostics),context_intent:receipt},updateContextIntentEstimate(projected,receipt)),receipt.estimated_tokens>receipt.token_budget&&compactContextIntentRows(builtInCommand,projected,receipt,options)&&(receipt.degradation="budget_row_compaction",updateContextIntentEstimate(projected,receipt)),receipt.declaration_feasible=receipt.estimated_tokens<=receipt.declared_token_budget,receipt.estimated_tokens>receipt.token_budget&&(receipt.degradation="budget_receipt_only",receipt.result_omitted=!0,receipt.within_budget=!1,projected={budget_exceeded:{omitted_result:!0,reason:receipt.token_budget_override===0?"declared_budget_infeasible":"effective_budget_infeasible",restore_with:buildContextIntentRecoveryCommand(command,builtInCommand,contract.intent,receipt,resultWithDiagnostics)},context_intent:receipt}),projected}function collapseContinuationMetadata(options,result){if(typeof options.after!="string"||options.after.length===0)return result;const fingerprint=decodeContextIntentCursor(options.after)?.fingerprint??"opaque_cursor",projected={...result};for(const key of["applied_limit","completeness","context_intent","count","filters","has_more","now","omission_receipt","projection","row_contract","sorting","total","truncated"])delete projected[key];return projected.continuation_contract={fingerprint,metadata:"reference",restore_with:"omit --after"},projected}function isOutputRecord(value){return value!==null&&typeof value=="object"&&!Array.isArray(value)}function buildContextIntentRecoveryCommand(command,builtInCommand,intent,receipt,result){const recoveryTarget=builtInCommand==="get"&&isOutputRecord(result.item)&&typeof result.item.id=="string"?result.item.id:builtInCommand==="search"&&typeof result.query=="string"?result.query:void 0,recoveryPositional=recoveryTarget===void 0?"":` '${recoveryTarget.replaceAll("'",`'"'"'`)}'`,boundedRowLimit=builtInCommand==="get"?"":` --limit ${receipt.budget_derived_limit??1}`;return`pm ${command}${recoveryPositional} --for ${intent} --token-budget ${Math.ceil(receipt.estimated_tokens/100)*100}${boundedRowLimit}`}function receiptEstimate(value,field){if(isOutputRecord(value))return typeof value[field]=="number"?value[field]:void 0}function stabilizeSuppressedRowContractReceipts(result,options){let finalized=result;for(let iteration=0;iteration<8;iteration+=1){const previousContextEstimate=receiptEstimate(finalized.context_intent,"estimated_tokens"),previousReadEstimate=receiptEstimate(finalized.read_output,"estimated_tokens"),previousSessionEstimate=receiptEstimate(finalized.read_session,"spent_this_call_tokens");if(isOutputRecord(finalized.context_intent)&&updateContextIntentEstimate(finalized,finalized.context_intent),finalized=stabilizeReadOutputReceiptEstimates(finalized,options),receiptEstimate(finalized.context_intent,"estimated_tokens")===previousContextEstimate&&receiptEstimate(finalized.read_output,"estimated_tokens")===previousReadEstimate&&receiptEstimate(finalized.read_session,"spent_this_call_tokens")===previousSessionEstimate)break}return finalized}function attachReadOutputContracts(command,options,result){const disclosedResult=attachOutputOmissionReceipt(command,result),projected=typeof disclosedResult=="object"&&disclosedResult!==null&&!Array.isArray(disclosedResult)?applyReadOutputDimensions(command??"",{...options,outputRowContract:options.outputRowContract===!0||options.output_row_contract===!0},collapseContinuationMetadata(options,attachContextIntentReceipt(command??"",options,disclosedResult))):disclosedResult;if(propagateContextUsageServingReceipt(result,projected),options.outputRowContract===!0||options.output_row_contract===!0||typeof projected!="object"||projected===null||Array.isArray(projected)||!Object.hasOwn(projected,"row_contract"))return projected;const withoutDiscoveryMetadata=Object.fromEntries(Object.entries(projected).filter(([key])=>key!=="row_contract"));Object.defineProperty(withoutDiscoveryMetadata,"row_contract",{value:projected.row_contract,enumerable:!1,configurable:!0});const suppressed=stabilizeSuppressedRowContractReceipts(withoutDiscoveryMetadata,options);return delete suppressed.row_contract,propagateContextUsageServingReceipt(projected,suppressed),suppressed}export{PM_CONTEXT_INTENT_CONTRACTS,applyContextIntentProjection,attachContextIntentReceipt,attachReadOutputContracts,composeContextIntentContracts,contextIntentRowId,decodeContextIntentCursor,getActiveContextIntentContracts,resolveContextIntentContract,runWithContextIntentContracts};
+(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]="5470b8b4-c584-50fb-bd09-0feb81bd8184")}catch{}})();import{AsyncLocalStorage}from"node:async_hooks";import{attachExtensionReadOutputRows}from"./read-output/extension.js";import{renderPmCommand}from"./command-line.js";import{attachOutputOmissionReceipt}from"./output-projection.js";import{encodeQueryCursor}from"./pagination.js";import{applyReadOutputDimensions,stabilizeReadOutputReceiptEstimates}from"./read-output-contracts.js";import{propagateContextUsageServingReceipt}from"./context-usage.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";const PM_CONTEXT_INTENT_CONTRACTS=Object.freeze([{command:"context",intent:"orient",description:"Bounded active hierarchy, ownership, blockers, and recent progress.",included_field_groups:["summary","focus","hierarchy","blockers","activity"],token_budget:3e3,source:"core"},{command:"context",intent:"handoff",description:"Active ownership, evidence, decisions, and immediate continuation context.",included_field_groups:["summary","focus","in_progress","decisions","activity"],token_budget:2200,source:"core"},{command:"get",intent:"inspect",description:"Standard-depth item metadata, relationships, evidence, and lifecycle state.",included_field_groups:["item","children","claim_state","linked"],token_budget:3200,source:"core"},{command:"list",intent:"triage",description:"A budget-derived page of compact governance, ownership, priority, and blocker rows for triage.",included_field_groups:["identity","governance","ownership","dependencies"],token_budget:3200,source:"core"},{command:"next",intent:"execute",description:"The highest-ranked actionable work with concise ranking evidence.",included_field_groups:["recommended"],token_budget:1200,source:"core"},{command:"search",intent:"discover",description:"A budget-derived page of ranked canonical lineage candidates with compact match evidence.",included_field_groups:["identity","status","lineage","match"],token_budget:1800,source:"core"}]),activeContextIntentContracts=new AsyncLocalStorage;function getActiveContextIntentContracts(){return activeContextIntentContracts.getStore()??PM_CONTEXT_INTENT_CONTRACTS}function runWithContextIntentContracts(layers,run){return activeContextIntentContracts.run(composeContextIntentContracts(layers.workspaceContracts,layers.packageContracts),run)}function normalizeContextIntentDeclaration(declaration,source){const command=declaration.command.trim().toLowerCase(),intent=declaration.intent.trim().toLowerCase(),key=`${command}:${intent}`;if(!/^[a-z0-9][a-z0-9-]*$/.test(command)||!/^[a-z0-9][a-z0-9-]*$/.test(intent))throw new TypeError(`Invalid context intent command or name: ${key}`);if(declaration.description.trim().length===0)throw new TypeError(`Context intent ${key} requires a non-empty description`);if(!Number.isSafeInteger(declaration.token_budget)||declaration.token_budget<=0)throw new TypeError(`Context intent ${key} requires a positive integer token_budget`);const includedFieldGroups=[...new Set(declaration.included_field_groups.map(field=>field.trim()).filter(Boolean))];if(includedFieldGroups.length===0)throw new TypeError(`Context intent ${key} requires included_field_groups`);return{command,intent,description:declaration.description.trim(),included_field_groups:includedFieldGroups,token_budget:declaration.token_budget,source}}function composeContextIntentContracts(workspaceContracts=[],packageContracts=[]){const layers=[{source:"core",contracts:PM_CONTEXT_INTENT_CONTRACTS,allowOverride:!1},{source:"package",contracts:packageContracts,allowOverride:!1},{source:"workspace",contracts:workspaceContracts,allowOverride:!0}],composed=new Map,keysSeenWithinLayer=new Set;for(const layer of layers){keysSeenWithinLayer.clear();for(const declaration of layer.contracts){const normalized=normalizeContextIntentDeclaration(declaration,layer.source),key=`${normalized.command}:${normalized.intent}`;if(keysSeenWithinLayer.has(key))throw new TypeError(`Duplicate context intent declaration: ${key}`);if(keysSeenWithinLayer.add(key),!layer.allowOverride&&composed.has(key))throw new TypeError(`Duplicate context intent declaration: ${key}`);composed.set(key,normalized)}}return[...composed.values()].sort((left,right)=>left.command.localeCompare(right.command)||left.intent.localeCompare(right.intent))}function resolveContextIntentContract(command,intent,contracts=getActiveContextIntentContracts(),positionalArguments=[]){const normalizedCommand=command.trim().toLowerCase(),normalizedIntent=intent.trim().toLowerCase(),exact=contracts.find(entry=>entry.command===normalizedCommand&&entry.intent===normalizedIntent);if(exact)return{...exact,source:exact.source??"core"};const candidates=contracts.filter(entry=>entry.command===normalizedCommand).map(entry=>entry.intent);if(candidates.length===0)return;const suggestion=candidates.map(candidate=>{const rows=Array.from({length:normalizedIntent.length+1},(_,index)=>index);for(let candidateIndex=1;candidateIndex<=candidate.length;candidateIndex+=1){let previous=rows[0];rows[0]=candidateIndex;for(let intentIndex=1;intentIndex<=normalizedIntent.length;intentIndex+=1){const prior=rows[intentIndex];rows[intentIndex]=Math.min(rows[intentIndex]+1,rows[intentIndex-1]+1,previous+(candidate[candidateIndex-1]===normalizedIntent[intentIndex-1]?0:1)),previous=prior}}return{candidate,distance:rows[normalizedIntent.length]}}).sort((left,right)=>left.distance-right.distance||left.candidate.localeCompare(right.candidate))[0].candidate,attemptedArguments=[normalizedCommand,...positionalArguments,"--for",normalizedIntent],suggestedRetryArguments=[normalizedCommand,...positionalArguments,"--for",suggestion],suggestedCommand=renderPmCommand(suggestedRetryArguments);throw new PmCliError(`Unknown context intent "${normalizedIntent}" for ${normalizedCommand}. Did you mean "${suggestion}"?`,EXIT_CODE.USAGE,{code:"unknown_context_intent",reason:"unknown_intent",field:"for",flag:"--for",value:normalizedIntent,required:`Use a declared ${normalizedCommand} intent.`,why:"Intent names are command-local contracts and cannot be inferred from output section names.",nextSteps:[suggestedCommand],recovery:{recovery_mode:"compact",attempted_command:renderPmCommand(attemptedArguments),allowed_values:[...candidates].sort(),suggested_retry:suggestedCommand,suggested_retry_args:suggestedRetryArguments}})}const CONTEXT_INTENT_DEFAULT_APPLIERS={context:(projected,contract,explicitTokenBudget)=>{projected.section===void 0&&projected.depth===void 0&&(projected.section=contract.intent==="handoff"?["activity","progress","blockers"]:["hierarchy","blockers","activity"]),projected.depth===void 0&&(projected.depth=contract.intent==="handoff"?"deep":"standard");const tokenBudget=resolveIntentTokenBudget(projected.tokenBudget,contract.token_budget),budgetDerivedLimit=resolveIntentRowBudget("context",contract.intent,tokenBudget,explicitTokenBudget),requestedLimit=parsePositiveIntentTokenBudget(projected.limit),derivedLimit=String(requestedLimit===void 0?budgetDerivedLimit:Math.min(requestedLimit,budgetDerivedLimit));(projected.limit===void 0||requestedLimit!==void 0)&&(projected.limit=derivedLimit),projected.activityLimit===void 0&&(projected.activityLimit=derivedLimit)},get:projected=>{projected.depth===void 0&&projected.fields===void 0&&(projected.depth="standard")},list:(projected,contract,explicitTokenBudget)=>{projected.brief===void 0&&projected.compact===void 0&&projected.full===void 0&&projected.fields===void 0&&(projected.fields="id,title,status,type,priority,parent,assignee,risk,blocked_by");const tokenBudget=resolveIntentTokenBudget(projected.tokenBudget,contract.token_budget),budgetDerivedLimit=resolveIntentRowBudget("list",contract.intent,tokenBudget,explicitTokenBudget),requestedLimit=parsePositiveIntentTokenBudget(projected.limit);(projected.limit===void 0||requestedLimit!==void 0)&&(projected.limit=String(requestedLimit===void 0?budgetDerivedLimit:Math.min(requestedLimit,budgetDerivedLimit)))},next:projected=>{projected.readyOnly===void 0&&(projected.readyOnly=!0)},search:(projected,contract,explicitTokenBudget)=>{projected.compact===void 0&&projected.full===void 0&&projected.fields===void 0&&(projected.compact=!0);const tokenBudget=resolveIntentTokenBudget(projected.tokenBudget,contract.token_budget),budgetDerivedLimit=resolveIntentRowBudget("search",contract.intent,tokenBudget,explicitTokenBudget),requestedLimit=parsePositiveIntentTokenBudget(projected.limit);(projected.limit===void 0||requestedLimit!==void 0)&&(projected.limit=String(requestedLimit===void 0?budgetDerivedLimit:Math.min(requestedLimit,budgetDerivedLimit)))}};function applyContextIntentProjection(command,options,positionalArguments=[]){const tokenBudget=options.tokenBudget??options.token_budget;if(typeof options.for!="string"){if(tokenBudget!==void 0&&(command==="get"||command==="list"||command==="search"))throw new PmCliError("--token-budget requires a declared context intent selected with --for",EXIT_CODE.USAGE,{code:"missing_required_option",field:"for",required:"Select a context intent with --for when setting --token-budget.",why:"A token-budget override has no projection contract to constrain without a selected intent.",nextSteps:["Retry with --for <intent> --token-budget <n>, or omit --token-budget."]});if(options.tokenBudget!==void 0||options.token_budget===void 0)return options;const projected2={...options,tokenBudget};return delete projected2.token_budget,projected2}const contract=resolveContextIntentContract(command,options.for,void 0,positionalArguments),explicitTokenBudget=parsePositiveIntentTokenBudget(tokenBudget)!==void 0,projected={...options};return projected.tokenBudget===void 0&&tokenBudget!==void 0&&(projected.tokenBudget=tokenBudget),delete projected.token_budget,projected.tokenBudget===void 0&&(projected.tokenBudget=String(contract.token_budget)),CONTEXT_INTENT_DEFAULT_APPLIERS[command](projected,contract,explicitTokenBudget),projected}const CONTEXT_INTENT_DEGRADATIONS={context:"bounded_sections",get:"standard_item",list:"bounded_fields_and_rows",next:"bounded_ranked_rows",search:"bounded_ranked_rows"},MINIMUM_CONTEXT_INTENT_TOKEN_BUDGET=256;function compactContextIntentValue(value){return Array.isArray(value)?value.map(compactContextIntentValue):value!==null&&typeof value=="object"?Object.fromEntries(Object.entries(value).map(([key,entry])=>[key,compactContextIntentValue(entry)])):typeof value=="string"&&value.length>240?`${value.slice(0,240)}\u2026`:value}function parsePositiveIntentTokenBudget(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 resolveIntentTokenBudget(value,declaredBudget){const parsed=parsePositiveIntentTokenBudget(value);if(parsed===void 0)return declaredBudget;if(parsed<MINIMUM_CONTEXT_INTENT_TOKEN_BUDGET)throw new PmCliError(`Context intent token budget must be at least ${MINIMUM_CONTEXT_INTENT_TOKEN_BUDGET}`,EXIT_CODE.USAGE,{code:"invalid_argument_value",reason:"below_minimum",field:"tokenBudget",value:String(value),required:`Use an integer token budget of at least ${MINIMUM_CONTEXT_INTENT_TOKEN_BUDGET}.`,why:"Smaller ceilings cannot contain the minimum machine-readable intent receipt.",nextSteps:[`Retry with --token-budget ${MINIMUM_CONTEXT_INTENT_TOKEN_BUDGET} or omit the override.`]});return parsed}function resolveIntentRowBudget(command,intent,tokenBudget,explicitTokenBudget){if(command==="get"||command==="next")return;const contextOrient=command==="context"&&intent==="orient",overhead=command==="context"?contextOrient?1200:800:command==="list"?520:480,rowCost=command==="context"?contextOrient?600:500:16,calculatedLimit=Math.max(command==="context"?1:2,Math.floor((tokenBudget-overhead)/rowCost));return explicitTokenBudget?calculatedLimit:Math.min(command==="context"?20:100,calculatedLimit)}function updateContextIntentEstimate(projected,receipt){let measuredTokens=receipt.estimated_tokens;for(;;){receipt.estimated_tokens=measuredTokens;const nextMeasurement=Math.ceil(Buffer.byteLength(JSON.stringify(projected),"utf8")/4);if(nextMeasurement===measuredTokens)return;measuredTokens=nextMeasurement}}const CONTEXT_INTENT_ROW_KEYS={context:["high_level","low_level","blocked_fallback","recently_created","unparented","hierarchy","activity","blockers"],get:["children"],list:["items"],next:["ready","decision_needed","gate_needed","containers","blocked","held_by_others"],search:["items"]};function decodeContextIntentCursor(cursor){try{const parsed=JSON.parse(Buffer.from(cursor,"base64url").toString("utf8"));return typeof parsed.fingerprint!="string"||!Number.isSafeInteger(parsed.after_index)?void 0:{fingerprint:parsed.fingerprint,after_index:parsed.after_index,...typeof parsed.snapshot=="string"?{snapshot:parsed.snapshot}:{}}}catch{return}}function contextIntentRowId(row){if(row===null||typeof row!="object")return;if(typeof row.id=="string")return row.id;const nestedId=row.item?.id;return typeof nestedId=="string"?nestedId:void 0}function shrinkContextIntentRowsToBudget(projected,receipt,rows){let compacted=!1;for(;;){if(updateContextIntentEstimate(projected,receipt),receipt.estimated_tokens<=receipt.token_budget||rows.length<=1)return compacted;const rowBytes=Buffer.byteLength(JSON.stringify(rows),"utf8"),excessBytes=(receipt.estimated_tokens-receipt.token_budget)*4;rows.splice(-Math.min(rows.length-1,Math.max(1,Math.ceil(excessBytes/Math.max(1,Math.ceil(rowBytes/rows.length)))))),compacted=!0}}function compactPaginatedContextIntentRows(projected,receipt,options){const rows=projected.items,cursorContinuesExistingPage=typeof projected.next_cursor=="string",cursorSource=cursorContinuesExistingPage?projected.next_cursor:options.after;if(!Array.isArray(rows)||typeof cursorSource!="string")return!1;const cursorEnvelope=decodeContextIntentCursor(cursorSource);if(cursorEnvelope===void 0)return!1;const originalRowCount=rows.length,originalRows=[...rows];let compacted=!1;for(;;){if(compacted=shrinkContextIntentRowsToBudget(projected,receipt,rows)||compacted,!compacted)return!1;const lastId=contextIntentRowId(rows.at(-1));if(lastId===void 0)return rows.splice(0,rows.length,...originalRows),updateContextIntentEstimate(projected,receipt),!1;if(projected.next_cursor=encodeQueryCursor(cursorEnvelope.fingerprint,lastId,cursorContinuesExistingPage?cursorEnvelope.after_index-(originalRowCount-rows.length):cursorEnvelope.after_index+rows.length,cursorEnvelope.snapshot),updateContextIntentEstimate(projected,receipt),receipt.estimated_tokens<=receipt.token_budget||rows.length<=1)break}return typeof projected.count=="number"&&(projected.count=rows.length),typeof projected.applied_limit=="number"&&(projected.applied_limit=rows.length),!0}function compactContextIntentRows(command,projected,receipt,options){if(command==="list"||command==="search")return compactPaginatedContextIntentRows(projected,receipt,options);if(command!=="next"||typeof projected.next_cursor=="string")return!1;let compacted=!1;for(;;){if(updateContextIntentEstimate(projected,receipt),receipt.estimated_tokens<=receipt.token_budget)return compacted;const candidate=CONTEXT_INTENT_ROW_KEYS[command].map(key=>({key,rows:Array.isArray(projected[key])?projected[key]:[]})).filter(({rows})=>rows.length>0).sort((left,right)=>right.rows.length-left.rows.length||left.key.localeCompare(right.key))[0];if(candidate===void 0)return compacted;const retainedTotal=CONTEXT_INTENT_ROW_KEYS[command].reduce((total,key)=>total+(Array.isArray(projected[key])?projected[key].length:0),0);if(retainedTotal<=1)return compacted;const removableRows=Math.min(candidate.rows.length,retainedTotal-1),candidateBytes=Buffer.byteLength(JSON.stringify(candidate.rows),"utf8"),estimatedBytesPerRow=Math.max(1,Math.ceil(candidateBytes/candidate.rows.length)),excessBytes=(receipt.estimated_tokens-receipt.token_budget)*4,removalCount=Math.min(removableRows,Math.max(1,Math.ceil(excessBytes/estimatedBytesPerRow)));candidate.rows.splice(-removalCount,removalCount),compacted=!0}}function attachContextIntentReceipt(command,options,result){if(typeof options.for!="string")return result;const normalizedCommand=command.startsWith("list-")?"list":command;if(!(normalizedCommand in CONTEXT_INTENT_DEFAULT_APPLIERS))return result;const builtInCommand=normalizedCommand,contract=resolveContextIntentContract(builtInCommand,options.for),effectiveTokenBudget=resolveIntentTokenBudget(options.tokenBudget??options.token_budget,contract.token_budget),receipt={command:builtInCommand,intent:contract.intent,source:contract.source,included_field_groups:[...contract.included_field_groups],token_budget:effectiveTokenBudget,declared_token_budget:contract.token_budget,token_budget_override:effectiveTokenBudget-contract.token_budget,estimated_tokens:0,within_budget:!0,degradation:CONTEXT_INTENT_DEGRADATIONS[builtInCommand],declaration_feasible:!0,result_omitted:!1},resultWithDiagnostics={...result},budgetDerivedLimit=resolveIntentRowBudget(builtInCommand,contract.intent,receipt.token_budget,parsePositiveIntentTokenBudget(options.tokenBudget??options.token_budget)!==void 0);if(budgetDerivedLimit!==void 0){const effectiveLimit=parsePositiveIntentTokenBudget(options.limit),explicitLimitBinds=effectiveLimit!==void 0&&effectiveLimit<budgetDerivedLimit;receipt.budget_derived_limit=budgetDerivedLimit,receipt.binding_constraint=explicitLimitBinds?"explicit_limit":"token_budget",receipt.limit_reason=explicitLimitBinds?"The caller supplied a smaller row limit than the budget-derived ceiling.":"The selected intent token budget constrains the effective row ceiling.",resultWithDiagnostics.budget_derived_limit=budgetDerivedLimit}let projected={...resultWithDiagnostics,context_intent:receipt};return updateContextIntentEstimate(projected,receipt),receipt.estimated_tokens>receipt.token_budget&&(receipt.degradation="recursive_budget_compaction",projected={...compactContextIntentValue(resultWithDiagnostics),context_intent:receipt},updateContextIntentEstimate(projected,receipt)),receipt.estimated_tokens>receipt.token_budget&&compactContextIntentRows(builtInCommand,projected,receipt,options)&&(receipt.degradation="budget_row_compaction",updateContextIntentEstimate(projected,receipt)),receipt.declaration_feasible=receipt.estimated_tokens<=receipt.declared_token_budget,receipt.estimated_tokens>receipt.token_budget&&(receipt.degradation="budget_receipt_only",receipt.result_omitted=!0,receipt.within_budget=!1,projected={budget_exceeded:{omitted_result:!0,reason:receipt.token_budget_override===0?"declared_budget_infeasible":"effective_budget_infeasible",restore_with:buildContextIntentRecoveryCommand(command,builtInCommand,contract.intent,receipt,resultWithDiagnostics)},context_intent:receipt}),projected}function collapseContinuationMetadata(options,result){if(typeof options.after!="string"||options.after.length===0)return result;const fingerprint=decodeContextIntentCursor(options.after)?.fingerprint??"opaque_cursor",projected={...result};for(const key of["applied_limit","completeness","context_intent","count","filters","has_more","now","omission_receipt","projection","row_contract","sorting","total","truncated"])delete projected[key];return projected.continuation_contract={fingerprint,metadata:"reference",restore_with:"omit --after"},projected}function isOutputRecord(value){return value!==null&&typeof value=="object"&&!Array.isArray(value)}function buildContextIntentRecoveryCommand(command,builtInCommand,intent,receipt,result){const recoveryTarget=builtInCommand==="get"&&isOutputRecord(result.item)&&typeof result.item.id=="string"?result.item.id:builtInCommand==="search"&&typeof result.query=="string"?result.query:void 0,recoveryPositional=recoveryTarget===void 0?"":` '${recoveryTarget.replaceAll("'",`'"'"'`)}'`,boundedRowLimit=builtInCommand==="get"?"":` --limit ${receipt.budget_derived_limit??1}`;return`pm ${command}${recoveryPositional} --for ${intent} --token-budget ${Math.ceil(receipt.estimated_tokens/100)*100}${boundedRowLimit}`}function receiptEstimate(value,field){if(isOutputRecord(value))return typeof value[field]=="number"?value[field]:void 0}function stabilizeSuppressedRowContractReceipts(result,options){let finalized=result;for(let iteration=0;iteration<8;iteration+=1){const previousContextEstimate=receiptEstimate(finalized.context_intent,"estimated_tokens"),previousReadEstimate=receiptEstimate(finalized.read_output,"estimated_tokens"),previousSessionEstimate=receiptEstimate(finalized.read_session,"spent_this_call_tokens");if(isOutputRecord(finalized.context_intent)&&updateContextIntentEstimate(finalized,finalized.context_intent),finalized=stabilizeReadOutputReceiptEstimates(finalized,options),receiptEstimate(finalized.context_intent,"estimated_tokens")===previousContextEstimate&&receiptEstimate(finalized.read_output,"estimated_tokens")===previousReadEstimate&&receiptEstimate(finalized.read_session,"spent_this_call_tokens")===previousSessionEstimate)break}return finalized}function attachReadOutputContracts(command,options,result){const disclosedResult=attachOutputOmissionReceipt(command,attachExtensionReadOutputRows(command??"",result)),projected=typeof disclosedResult=="object"&&disclosedResult!==null&&!Array.isArray(disclosedResult)?applyReadOutputDimensions(command??"",{...options,outputRowContract:options.outputRowContract===!0||options.output_row_contract===!0},collapseContinuationMetadata(options,attachContextIntentReceipt(command??"",options,disclosedResult))):disclosedResult;if(propagateContextUsageServingReceipt(result,projected),options.outputRowContract===!0||options.output_row_contract===!0||typeof projected!="object"||projected===null||Array.isArray(projected)||!Object.hasOwn(projected,"row_contract"))return projected;const withoutDiscoveryMetadata=Object.fromEntries(Object.entries(projected).filter(([key])=>key!=="row_contract"));Object.defineProperty(withoutDiscoveryMetadata,"row_contract",{value:projected.row_contract,enumerable:!1,configurable:!0});const suppressed=stabilizeSuppressedRowContractReceipts(withoutDiscoveryMetadata,options);return delete suppressed.row_contract,propagateContextUsageServingReceipt(projected,suppressed),suppressed}export{PM_CONTEXT_INTENT_CONTRACTS,applyContextIntentProjection,attachContextIntentReceipt,attachReadOutputContracts,composeContextIntentContracts,contextIntentRowId,decodeContextIntentCursor,getActiveContextIntentContracts,resolveContextIntentContract,runWithContextIntentContracts};
 //# sourceMappingURL=context-intent-contracts.js.map