@unbrained/pm-cli 2026.10.12 → 2026.10.13

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

@@ -1,6 +1,8 @@
 import type { RuntimeStatusRegistry } from "../core/schema/runtime-schema.js";
 import type { ItemMetadata } from "../types/index.js";
 import type { HistoryEventClass } from "../core/history/event-classification.js";
+import { type PmReadOutputResult } from "./read-output-contracts.js";
+import type { PmContextIntentReceipt } from "./context-intent-contracts.js";
 /** Canonical signal keys understood by the built-in relevance model. */
 export declare const CONTEXT_RELEVANCE_SIGNAL_NAMES: readonly ["structural", "recency", "activity_density", "graph_proximity", "claim_focus", "priority_pressure", "risk_pressure", "deadline_pressure", "knowledge_density", "author_affinity", "usage_affinity", "semantic_similarity"];
 /** A normalized signal consumed by the built-in context relevance scorer. */
@@ -9,62 +11,62 @@ export type ContextRelevanceSignalName = (typeof CONTEXT_RELEVANCE_SIGNAL_NAMES)
 export type ContextRelevanceSignals = Partial<Record<Exclude<ContextRelevanceSignalName, "structural">, number>>;
 /** Authoritative coordinate and fallback that produced an item's recency. */
 export interface ContextRecencyEvidence {
-    /** Source selected by the canonical fallback ladder. */
-    source: "substantive_history" | "release_cohort" | "created_at";
-    /** ISO coordinate used for deterministic recency ordering. */
-    coordinate: string;
-    /** Immutable operation selected from history when source is substantive_history. */
-    history_op?: string;
-    /** Declared class selected from history when source is substantive_history. */
-    event_class?: HistoryEventClass;
+/** Source selected by the canonical fallback ladder. */
+source: "substantive_history" | "release_cohort" | "created_at";
+/** ISO coordinate used for deterministic recency ordering. */
+coordinate: string;
+/** Immutable operation selected from history when source is substantive_history. */
+history_op?: string;
+/** Declared class selected from history when source is substantive_history. */
+event_class?: HistoryEventClass;
 }
 /** Per-signal provenance exposed by explained relevance results. */
 export interface ContextSignalProvenance {
-    /** Evidence for the canonical temporal component. */
-    recency: ContextRecencyEvidence;
+/** Evidence for the canonical temporal component. */
+recency: ContextRecencyEvidence;
 }
 /** A project-management object and its derived relevance signals. */
 export interface ContextRelevanceCandidate<TItem> {
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
-    /** Value that configures or reports item for this contract. */
-    item: TItem;
-    /** Value that configures or reports signals for this contract. */
-    signals?: ContextRelevanceSignals;
-    /** Authoritative source details for explainable derived signals. */
-    signal_provenance?: ContextSignalProvenance;
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** Value that configures or reports item for this contract. */
+item: TItem;
+/** Value that configures or reports signals for this contract. */
+signals?: ContextRelevanceSignals;
+/** Authoritative source details for explainable derived signals. */
+signal_provenance?: ContextSignalProvenance;
 }
 /** Item candidate whose built-in metadata derivation always supplies signals. */
 export interface ItemContextRelevanceCandidate extends ContextRelevanceCandidate<ItemMetadata> {
-    /** Complete built-in derivation result, with unavailable signals omitted by value. */
-    signals: ContextRelevanceSignals;
-    /** Built-in recency derivation always discloses its source. */
-    signal_provenance: ContextSignalProvenance;
+/** Complete built-in derivation result, with unavailable signals omitted by value. */
+signals: ContextRelevanceSignals;
+/** Built-in recency derivation always discloses its source. */
+signal_provenance: ContextSignalProvenance;
 }
 /** Inputs that make item-signal derivation deterministic and host-configurable. */
 export interface BuildItemContextRelevanceCandidatesOptions {
-    /** Workspace lifecycle registry, including custom in-progress aliases. */
-    statusRegistry: RuntimeStatusRegistry;
-    /** Stable clock used for deadline pressure. */
-    now: string;
-    /** Optional caller identity used for assignment affinity. */
-    author?: string;
-    /** Optional derived served-then-used affinity by item id. */
-    usageAffinity?: Readonly<Record<string, number>>;
-    /** Optional caller-derived semantic similarity by item id. */
-    semanticSimilarity?: Readonly<Record<string, number>>;
-    /** Optional index-derived activity density by item id. */
-    activityDensity?: Readonly<Record<string, number>>;
-    /** Optional index-derived graph proximity by item id. */
-    graphProximity?: Readonly<Record<string, number>>;
-    /** Optional host-derived claim or focus affinity by item id. */
-    claimFocus?: Readonly<Record<string, number>>;
-    /** Optional index-derived knowledge density by item id. */
-    knowledgeDensity?: Readonly<Record<string, number>>;
-    /** Optional history-derived author affinity by item id. */
-    authorAffinity?: Readonly<Record<string, number>>;
-    /** Latest substantive history evidence keyed by item id. */
-    recencyEvidence?: Readonly<Record<string, ContextRecencyEvidence>>;
+/** Workspace lifecycle registry, including custom in-progress aliases. */
+statusRegistry: RuntimeStatusRegistry;
+/** Stable clock used for deadline pressure. */
+now: string;
+/** Optional caller identity used for assignment affinity. */
+author?: string;
+/** Optional derived served-then-used affinity by item id. */
+usageAffinity?: Readonly<Record<string, number>>;
+/** Optional caller-derived semantic similarity by item id. */
+semanticSimilarity?: Readonly<Record<string, number>>;
+/** Optional index-derived activity density by item id. */
+activityDensity?: Readonly<Record<string, number>>;
+/** Optional index-derived graph proximity by item id. */
+graphProximity?: Readonly<Record<string, number>>;
+/** Optional host-derived claim or focus affinity by item id. */
+claimFocus?: Readonly<Record<string, number>>;
+/** Optional index-derived knowledge density by item id. */
+knowledgeDensity?: Readonly<Record<string, number>>;
+/** Optional history-derived author affinity by item id. */
+authorAffinity?: Readonly<Record<string, number>>;
+/** Latest substantive history evidence keyed by item id. */
+recencyEvidence?: Readonly<Record<string, ContextRecencyEvidence>>;
 }
 /**
  * Derive the canonical metadata signals consumed by `pm context` and `pm next`.
@@ -76,48 +78,48 @@ export declare function buildItemContextRelevanceCandidates(items: readonly Item
 export type ContextRelevanceContributions = Record<string, number>;
 /** One ranked candidate with deterministic score and explanation metadata. */
 export interface RankedContextCandidate<TItem> extends ContextRelevanceCandidate<TItem> {
-    /** Value that configures or reports baseline rank for this contract. */
-    baseline_rank: number;
-    /** Value that configures or reports rank for this contract. */
-    rank: number;
-    /** Value that configures or reports score for this contract. */
-    score: number;
-    /** Value that configures or reports contributions for this contract. */
-    contributions: ContextRelevanceContributions;
+/** Value that configures or reports baseline rank for this contract. */
+baseline_rank: number;
+/** Value that configures or reports rank for this contract. */
+rank: number;
+/** Value that configures or reports score for this contract. */
+score: number;
+/** Value that configures or reports contributions for this contract. */
+contributions: ContextRelevanceContributions;
 }
 /** Complete output from a context relevance scorer. */
 export interface ContextRelevanceReport<TItem> {
-    /** Value that configures or reports model for this contract. */
-    model: string;
-    /** Value that configures or reports available signals for this contract. */
-    available_signals: ContextRelevanceSignalName[];
-    /** Value that configures or reports ranked for this contract. */
-    ranked: RankedContextCandidate<TItem>[];
-    /** Value that configures or reports warnings for this contract. */
-    warnings?: string[];
+/** Value that configures or reports model for this contract. */
+model: string;
+/** Value that configures or reports available signals for this contract. */
+available_signals: ContextRelevanceSignalName[];
+/** Value that configures or reports ranked for this contract. */
+ranked: RankedContextCandidate<TItem>[];
+/** Value that configures or reports warnings for this contract. */
+warnings?: string[];
 }
 /** Minimal custom score returned by a replacement or wrapper scorer. */
 export interface ContextRelevanceCustomScore {
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
-    /** Value that configures or reports score for this contract. */
-    score: number;
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** Value that configures or reports score for this contract. */
+score: number;
 }
 /** Input provided to a custom scorer, including the deterministic default. */
 export interface ContextRelevanceScorerInput<TItem> {
-    /** Value that configures or reports candidates for this contract. */
-    candidates: readonly ContextRelevanceCandidate<TItem>[];
-    /** Fallback report used when callers do not provide an override. */
-    default_report: ContextRelevanceReport<TItem>;
+/** Value that configures or reports candidates for this contract. */
+candidates: readonly ContextRelevanceCandidate<TItem>[];
+/** Fallback report used when callers do not provide an override. */
+default_report: ContextRelevanceReport<TItem>;
 }
 /** Replaceable package/extension scorer contract. */
 export type ContextRelevanceScorer<TItem> = (input: ContextRelevanceScorerInput<TItem>) => readonly ContextRelevanceCustomScore[] | Promise<readonly ContextRelevanceCustomScore[]>;
 /** Options for the built-in or replaceable context relevance scorer. */
 export interface ScoreContextCandidatesOptions<TItem> {
-    /** Value that configures or reports weights for this contract. */
-    weights?: Partial<Record<ContextRelevanceSignalName, number>>;
-    /** Value that configures or reports scorer for this contract. */
-    scorer?: ContextRelevanceScorer<TItem>;
+/** Value that configures or reports weights for this contract. */
+weights?: Partial<Record<ContextRelevanceSignalName, number>>;
+/** Value that configures or reports scorer for this contract. */
+scorer?: ContextRelevanceScorer<TItem>;
 }
 /** Governed extension service used to replace or wrap context ranking. */
 export declare const CONTEXT_RELEVANCE_SERVICE: "context_relevance";
@@ -131,152 +133,158 @@ export declare function scoreContextCandidates<TItem>(candidates: readonly Conte
 export declare function scoreContextCandidatesWithActiveExtensions<TItem>(surface: ContextRelevanceSurface, candidates: readonly ContextRelevanceCandidate<TItem>[], options?: Pick<ScoreContextCandidatesOptions<TItem>, "weights">): Promise<ContextRelevanceReport<TItem>>;
 /** Input for rank-aware context/next quality evaluation. */
 export interface ContextRankingEvaluationInput {
-    /** Value that configures or reports ranked ids for this contract. */
-    ranked_ids: string[];
-    /** Value that configures or reports judgments for this contract. */
-    judgments: Record<string, number>;
-    /** Value that configures or reports required ids for this contract. */
-    required_ids?: string[];
-    /** Value that configures or reports continuity ids for this contract. */
-    continuity_ids?: string[];
-    /** Value that configures or reports actual tokens for this contract. */
-    actual_tokens: number;
-    /** Value that configures or reports token budget for this contract. */
-    token_budget: number;
+/** Value that configures or reports ranked ids for this contract. */
+ranked_ids: string[];
+/** Value that configures or reports judgments for this contract. */
+judgments: Record<string, number>;
+/** Value that configures or reports required ids for this contract. */
+required_ids?: string[];
+/** Value that configures or reports continuity ids for this contract. */
+continuity_ids?: string[];
+/** Value that configures or reports actual tokens for this contract. */
+actual_tokens: number;
+/** Value that configures or reports token budget for this contract. */
+token_budget: number;
 }
 /** Rank-quality, continuity, recall, and token-budget metrics for one scenario. */
 export interface ContextRankingEvaluation {
-    /** Value that configures or reports ndcg for this contract. */
-    ndcg: number;
-    /** Value that configures or reports reciprocal rank for this contract. */
-    reciprocal_rank: number;
-    /** Value that configures or reports required recall for this contract. */
-    required_recall: number;
-    /** Value that configures or reports continuity coverage for this contract. */
-    continuity_coverage: number;
-    /** Value that configures or reports token budget adherence for this contract. */
-    token_budget_adherence: number;
-    /** Value that configures or reports within token budget for this contract. */
-    within_token_budget: boolean;
+/** Value that configures or reports ndcg for this contract. */
+ndcg: number;
+/** Value that configures or reports reciprocal rank for this contract. */
+reciprocal_rank: number;
+/** Value that configures or reports required recall for this contract. */
+required_recall: number;
+/** Value that configures or reports continuity coverage for this contract. */
+continuity_coverage: number;
+/** Value that configures or reports token budget adherence for this contract. */
+token_budget_adherence: number;
+/** Value that configures or reports within token budget for this contract. */
+within_token_budget: boolean;
 }
 /** Flexible read options accepted by context evaluation scenarios. */
 export interface ContextEvaluationReadOptions {
-    /** Value that configures or reports explain ranking for this contract. */
-    explainRanking?: boolean;
-    [key: string]: unknown;
+/** Value that configures or reports explain ranking for this contract. */
+explainRanking?: boolean;
+[key: string]: unknown;
 }
 /** Minimal item identity consumed by the context evaluation runner. */
 export interface ContextEvaluationResultItem {
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
 }
 /** Optional scorer attribution returned by an evaluated read primitive. */
 export interface ContextEvaluationResultRanking {
-    /** Value that configures or reports items for this contract. */
-    items?: Array<{
-        id: string;
-        contributions: ContextRelevanceContributions;
-    }>;
+/** Value that configures or reports items for this contract. */
+items?: Array<{
+id: string;
+contributions: ContextRelevanceContributions;
+}>;
 }
 /** Structural context result consumed by the evaluation runner. */
 export interface ContextEvaluationContextResult {
-    /** Value that configures or reports high level for this contract. */
-    high_level?: ContextEvaluationResultItem[];
-    /** Value that configures or reports low level for this contract. */
-    low_level?: ContextEvaluationResultItem[];
-    /** Value that configures or reports blocked fallback for this contract. */
-    blocked_fallback?: ContextEvaluationResultItem[];
-    /** Value that configures or reports ranking for this contract. */
-    ranking?: ContextEvaluationResultRanking;
-    [key: string]: unknown;
+/** Value that configures or reports high level for this contract. */
+high_level?: ContextEvaluationResultItem[];
+/** Value that configures or reports low level for this contract. */
+low_level?: ContextEvaluationResultItem[];
+/** Value that configures or reports blocked fallback for this contract. */
+blocked_fallback?: ContextEvaluationResultItem[];
+/** Value that configures or reports ranking for this contract. */
+ranking?: ContextEvaluationResultRanking;
+/** Intent receipt retained so whole-result omissions cannot be graded. */
+context_intent?: Pick<PmContextIntentReceipt, "result_omitted">;
+[key: string]: unknown;
 }
 /** Structural next result consumed by the evaluation runner. */
 export interface ContextEvaluationNextResult {
-    /** Value that configures or reports recommended for this contract. */
-    recommended?: ContextEvaluationResultItem | null;
-    /** Value that configures or reports ready for this contract. */
-    ready?: ContextEvaluationResultItem[];
-    /** Value that configures or reports ranking for this contract. */
-    ranking?: ContextEvaluationResultRanking;
-    [key: string]: unknown;
+/** Value that configures or reports recommended for this contract. */
+recommended?: ContextEvaluationResultItem | null;
+/** Value that configures or reports ready for this contract. */
+ready?: ContextEvaluationResultItem[];
+/** Value that configures or reports ranking for this contract. */
+ranking?: ContextEvaluationResultRanking;
+/** Intent receipt retained so whole-result omissions cannot be graded. */
+context_intent?: Pick<PmContextIntentReceipt, "result_omitted">;
+[key: string]: unknown;
 }
+type ContextEvaluationContextFields = Pick<ContextEvaluationContextResult, "high_level" | "low_level" | "blocked_fallback" | "ranking" | "context_intent">;
+type ContextEvaluationNextFields = Pick<ContextEvaluationNextResult, "recommended" | "ready" | "ranking" | "context_intent">;
 /** Read-only SDK surface required by the context evaluation runner. */
 export interface ContextEvaluationReader {
-    /** Value that configures or reports context for this contract. */
-    context(options?: ContextEvaluationReadOptions): Promise<ContextEvaluationContextResult>;
-    /** Value that configures or reports next for this contract. */
-    next(options?: ContextEvaluationReadOptions): Promise<ContextEvaluationNextResult>;
+/** Value that configures or reports context for this contract. */
+context(options?: ContextEvaluationReadOptions): Promise<PmReadOutputResult<ContextEvaluationContextFields>>;
+/** Value that configures or reports next for this contract. */
+next(options?: ContextEvaluationReadOptions): Promise<PmReadOutputResult<ContextEvaluationNextFields>>;
 }
 /** One graded context or next scenario evaluated against a real SDK reader. */
 export interface ContextEvaluationScenario {
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
-    /** Value that configures or reports surface for this contract. */
-    surface: ContextRelevanceSurface;
-    /** Value that configures or reports options for this contract. */
-    options?: ContextEvaluationReadOptions;
-    /** Value that configures or reports judgments for this contract. */
-    judgments: Record<string, number>;
-    /** Value that configures or reports required ids for this contract. */
-    required_ids?: string[];
-    /** Value that configures or reports continuity ids for this contract. */
-    continuity_ids?: string[];
-    /** Value that configures or reports token budget for this contract. */
-    token_budget: number;
-    /** Value that configures or reports rationale for this contract. */
-    rationale: string;
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** Value that configures or reports surface for this contract. */
+surface: ContextRelevanceSurface;
+/** Value that configures or reports options for this contract. */
+options?: ContextEvaluationReadOptions;
+/** Value that configures or reports judgments for this contract. */
+judgments: Record<string, number>;
+/** Value that configures or reports required ids for this contract. */
+required_ids?: string[];
+/** Value that configures or reports continuity ids for this contract. */
+continuity_ids?: string[];
+/** Value that configures or reports token budget for this contract. */
+token_budget: number;
+/** Value that configures or reports rationale for this contract. */
+rationale: string;
 }
 /** Per-item signal attribution retained by a context evaluation report. */
 export interface ContextEvaluationAttribution {
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
-    /** Value that configures or reports contributions for this contract. */
-    contributions: ContextRelevanceContributions;
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** Value that configures or reports contributions for this contract. */
+contributions: ContextRelevanceContributions;
 }
 /** Result of executing and grading one context evaluation scenario. */
 export interface ContextEvaluationScenarioReport {
-    /** Stable identifier used to reference this record across commands and storage. */
-    id: string;
-    /** Value that configures or reports surface for this contract. */
-    surface: ContextRelevanceSurface;
-    /** Value that configures or reports rationale for this contract. */
-    rationale: string;
-    /** Value that configures or reports ranked ids for this contract. */
-    ranked_ids: string[];
-    /** Value that configures or reports actual tokens for this contract. */
-    actual_tokens: number;
-    /** Value that configures or reports metrics for this contract. */
-    metrics: ContextRankingEvaluation;
-    /** Value that configures or reports attribution for this contract. */
-    attribution: ContextEvaluationAttribution[];
+/** Stable identifier used to reference this record across commands and storage. */
+id: string;
+/** Value that configures or reports surface for this contract. */
+surface: ContextRelevanceSurface;
+/** Value that configures or reports rationale for this contract. */
+rationale: string;
+/** Value that configures or reports ranked ids for this contract. */
+ranked_ids: string[];
+/** Value that configures or reports actual tokens for this contract. */
+actual_tokens: number;
+/** Value that configures or reports metrics for this contract. */
+metrics: ContextRankingEvaluation;
+/** Value that configures or reports attribution for this contract. */
+attribution: ContextEvaluationAttribution[];
 }
 /** Minimum acceptable aggregate metrics for a context evaluation corpus. */
 export interface ContextEvaluationThresholds {
-    /** Value that configures or reports ndcg for this contract. */
-    ndcg: number;
-    /** Value that configures or reports reciprocal rank for this contract. */
-    reciprocal_rank: number;
-    /** Value that configures or reports required recall for this contract. */
-    required_recall: number;
-    /** Value that configures or reports continuity coverage for this contract. */
-    continuity_coverage: number;
-    /** Value that configures or reports token budget adherence for this contract. */
-    token_budget_adherence: number;
+/** Value that configures or reports ndcg for this contract. */
+ndcg: number;
+/** Value that configures or reports reciprocal rank for this contract. */
+reciprocal_rank: number;
+/** Value that configures or reports required recall for this contract. */
+required_recall: number;
+/** Value that configures or reports continuity coverage for this contract. */
+continuity_coverage: number;
+/** Value that configures or reports token budget adherence for this contract. */
+token_budget_adherence: number;
 }
 /** Canonical aggregate metrics required by every context evaluation corpus. */
 export declare const CONTEXT_EVALUATION_METRIC_NAMES: readonly ["ndcg", "reciprocal_rank", "required_recall", "continuity_coverage", "token_budget_adherence"];
 /** Aggregate context evaluation report suitable for a CI quality gate. */
 export interface ContextEvaluationCorpusReport {
-    /** Number of scenario entries represented by this result. */
-    scenario_count: number;
-    /** Value that configures or reports aggregate for this contract. */
-    aggregate: ContextEvaluationThresholds;
-    /** Value that configures or reports scenarios for this contract. */
-    scenarios: ContextEvaluationScenarioReport[];
-    /** Value that configures or reports passed for this contract. */
-    passed: boolean;
-    /** Value that configures or reports failures for this contract. */
-    failures: string[];
+/** Number of scenario entries represented by this result. */
+scenario_count: number;
+/** Value that configures or reports aggregate for this contract. */
+aggregate: ContextEvaluationThresholds;
+/** Value that configures or reports scenarios for this contract. */
+scenarios: ContextEvaluationScenarioReport[];
+/** Value that configures or reports passed for this contract. */
+passed: boolean;
+/** Value that configures or reports failures for this contract. */
+failures: string[];
 }
 /** Evaluate one ranked context packet against graded human judgments. */
 export declare function evaluateContextRanking(input: ContextRankingEvaluationInput): ContextRankingEvaluation;
@@ -286,3 +294,4 @@ export declare function runContextEvaluationScenario(scenario: ContextEvaluation
 export declare function summarizeContextEvaluationReports(reports: readonly ContextEvaluationScenarioReport[], thresholds: ContextEvaluationThresholds): ContextEvaluationCorpusReport;
 /** Execute a same-workspace scenario corpus through public SDK read primitives. */
 export declare function runContextEvaluationCorpus(scenarios: readonly ContextEvaluationScenario[], reader: ContextEvaluationReader, thresholds: ContextEvaluationThresholds): Promise<ContextEvaluationCorpusReport>;
+export {};

package/dist/sdk/context-relevance.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]="e750a203-8bef-5bfd-85a5-a584c2105472")}catch{}})();import{runActiveServiceOverride}from"../core/extensions/index.js";import{normalizeStatusForRegistry,normalizeStatusInput}from"../core/item/status.js";import{compareTimestampStrings}from"../core/shared/time.js";import{canonicalizeContextRecencyCoordinate,CONTEXT_RECENCY_EPOCH}from"./context/recency.js";const CONTEXT_RELEVANCE_SIGNAL_NAMES=["structural","recency","activity_density","graph_proximity","claim_focus","priority_pressure","risk_pressure","deadline_pressure","knowledge_density","author_affinity","usage_affinity","semantic_similarity"],NO_CONTEXT_AUTHOR=Symbol("no-context-author"),NO_ITEM_ASSIGNEE=Symbol("no-item-assignee");function normalizeContextActor(value,missingValue){if(typeof value!="string")return missingValue;const normalized=value.trim().toLowerCase();return normalized.length>0?normalized:missingValue}function releaseCohortCoordinate(value){if(typeof value!="string")return;const match=/^v?(\d{4})\.(\d{1,2})\.(\d{1,2})(?:$|[-+])/u.exec(value.trim());if(!match)return;const year=Number(match[1]),month=Number(match[2]),day=Number(match[3]),date=new Date(Date.UTC(year,month-1,day));return date.getUTCFullYear()===year&&date.getUTCMonth()===month-1&&date.getUTCDate()===day?date.toISOString():void 0}function fallbackRecencyEvidence(item){const releaseCoordinate=releaseCohortCoordinate(item.release);return releaseCoordinate!==void 0?{source:"release_cohort",coordinate:releaseCoordinate}:{source:"created_at",coordinate:canonicalizeContextRecencyCoordinate(item.created_at)??CONTEXT_RECENCY_EPOCH}}function canonicalizeRecencyEvidence(evidence){if(!["substantive_history","release_cohort","created_at"].includes(evidence.source)||(evidence.source==="substantive_history"?evidence.history_op!==void 0&&typeof evidence.history_op!="string"||evidence.event_class!==void 0&&evidence.event_class!=="substantive":evidence.history_op!==void 0||evidence.event_class!==void 0))throw new TypeError("Context signal recency provenance must match its source");const coordinate=canonicalizeContextRecencyCoordinate(evidence.coordinate);if(coordinate===null)throw new TypeError("Context signal recency coordinate must be a valid absolute timestamp with millisecond precision");return{...evidence,coordinate}}function normalizedPressure(value,maximum){const parsed=typeof value=="number"?value:typeof value=="string"?Number.parseFloat(value):Number.NaN;return Number.isFinite(parsed)?1-Math.min(Math.max(parsed,0),maximum)/maximum:0}function deadlinePressure(deadline,nowMs){const deadlineMs=typeof deadline=="string"?Date.parse(deadline):deadline instanceof Date?deadline.getTime():typeof deadline=="number"?deadline:Number.NaN;if(!Number.isFinite(deadlineMs)||!Number.isFinite(nowMs))return 0;const days=(deadlineMs-nowMs)/864e5;return days<=0?1:1/(1+days/30)}function riskPressure(risk){const normalized=typeof risk=="string"?risk.trim().toLowerCase():void 0;return normalized==="critical"||normalized==="high"?1:normalized==="medium"?.5:normalized==="low"?.1:0}function derivedSignalOrFallback(values,id,fallback){return values?.[id]??fallback}function buildItemContextRelevanceCandidates(items,options){const recencyEvidence=new Map(items.map(item=>{const suppliedEvidence=options.recencyEvidence?.[item.id];return[item.id,suppliedEvidence===void 0?fallbackRecencyEvidence(item):canonicalizeRecencyEvidence(suppliedEvidence)]})),recencyOrder=[...items].sort((left,right)=>{const leftTime=recencyEvidence.get(left.id).coordinate,rightTime=recencyEvidence.get(right.id).coordinate;return compareTimestampStrings(rightTime,leftTime)||left.id.localeCompare(right.id)}),recencyRank=new Map(recencyOrder.map((item,index)=>[item.id,index])),denominator=Math.max(items.length-1,1),normalizedAuthor=normalizeContextActor(options.author,NO_CONTEXT_AUTHOR),inProgressStatus=normalizeStatusInput("in_progress",options.statusRegistry),nowMs=Date.parse(options.now);return items.map(item=>{const assigned=normalizeContextActor(item.assignee,NO_ITEM_ASSIGNEE)===normalizedAuthor,knowledgeEntries=(item.comments?.length??0)+(item.notes?.length??0)+(item.learnings?.length??0);return{id:item.id,item,signal_provenance:{recency:recencyEvidence.get(item.id)},signals:{recency:items.length===1?1:1-recencyRank.get(item.id)/denominator,activity_density:options.activityDensity?.[item.id],graph_proximity:derivedSignalOrFallback(options.graphProximity,item.id,item.parent?.3:0),claim_focus:derivedSignalOrFallback(options.claimFocus,item.id,normalizeStatusForRegistry(item.status,options.statusRegistry)===inProgressStatus?1:assigned?.75:0),priority_pressure:normalizedPressure(item.priority,4),risk_pressure:riskPressure(item.risk),deadline_pressure:deadlinePressure(item.deadline,nowMs),knowledge_density:derivedSignalOrFallback(options.knowledgeDensity,item.id,Math.min(knowledgeEntries/5,1)),author_affinity:derivedSignalOrFallback(options.authorAffinity,item.id,assigned?1:0),usage_affinity:options.usageAffinity?.[item.id],semantic_similarity:options.semanticSimilarity?.[item.id]}}})}const CONTEXT_RELEVANCE_SERVICE="context_relevance",DEFAULT_CONTEXT_RELEVANCE_WEIGHTS={structural:.4,recency:.35,activity_density:.25,graph_proximity:.15,claim_focus:.6,priority_pressure:.35,risk_pressure:.2,deadline_pressure:.45,knowledge_density:.25,author_affinity:.2,usage_affinity:.3,semantic_similarity:.5},JSON_TOKEN_ENCODER=new TextEncoder;function assertCandidates(candidates){const ids=new Set;for(const candidate of candidates){if(typeof candidate.id!="string"||candidate.id.trim().length===0||ids.has(candidate.id))throw new TypeError("Context relevance candidates require unique non-empty ids");ids.add(candidate.id);for(const[signal,value]of Object.entries(candidate.signals??{})){if(signal==="structural"||!CONTEXT_RELEVANCE_SIGNAL_NAMES.includes(signal))throw new TypeError(`Unknown context relevance signal: ${signal}`);if(value!==void 0&&(!Number.isFinite(value)||value<0||value>1))throw new TypeError(`Context relevance signal ${signal} must be a finite number from 0 to 1`)}}}function resolveWeights(overrides){const weights={...DEFAULT_CONTEXT_RELEVANCE_WEIGHTS};for(const[signal,weight]of Object.entries(overrides??{}))weight!==void 0&&CONTEXT_RELEVANCE_SIGNAL_NAMES.includes(signal)&&(weights[signal]=weight);for(const[signal,weight]of Object.entries(weights))if(!Number.isFinite(weight)||weight<0)throw new TypeError(`Context relevance weight ${signal} must be a finite non-negative number`);return weights}function defaultScoreContextCandidates(candidates,options={}){assertCandidates(candidates);const weights=resolveWeights(options.weights),denominator=Math.max(candidates.length-1,1),available=new Set(["structural"]);for(const candidate of candidates)for(const[signal,value]of Object.entries(candidate.signals??{}))value!==void 0&&available.add(signal);const availableSignals=CONTEXT_RELEVANCE_SIGNAL_NAMES.filter(signal=>available.has(signal)),scored=candidates.map((candidate,index)=>{const signalValues={structural:candidates.length===1?1:1-index/denominator,...candidate.signals},contributions={};let weightedScore=0,totalWeight=0;for(const signal of availableSignals){const value=signalValues[signal];if(value===void 0)continue;const contribution=value*weights[signal];contributions[signal]=contribution,weightedScore+=contribution,totalWeight+=weights[signal]}return{...candidate,baseline_rank:index+1,rank:0,score:totalWeight===0?0:weightedScore/totalWeight,contributions}});return scored.sort((left,right)=>right.score-left.score||left.baseline_rank-right.baseline_rank),scored.forEach((entry,index)=>{entry.rank=index+1}),{model:"default-weighted-v1",available_signals:availableSignals,ranked:scored}}async function scoreContextCandidates(candidates,options={}){const defaultReport=defaultScoreContextCandidates(candidates,options);if(!options.scorer)return defaultReport;const customScores=await options.scorer({candidates,default_report:defaultReport}),scoreById=new Map;for(const entry of customScores){if(scoreById.has(entry.id)||!Number.isFinite(entry.score))throw new TypeError("Context relevance scorer must return one finite score for every candidate");scoreById.set(entry.id,entry.score)}if(scoreById.size!==candidates.length||candidates.some(candidate=>!scoreById.has(candidate.id)))throw new TypeError("Context relevance scorer must return one finite score for every candidate");const ranked=defaultReport.ranked.map(entry=>{const score=scoreById.get(entry.id);return{...entry,score,contributions:{custom:score}}});return ranked.sort((left,right)=>right.score-left.score||left.baseline_rank-right.baseline_rank),ranked.forEach((entry,index)=>{entry.rank=index+1}),{model:"custom",available_signals:defaultReport.available_signals,ranked}}async function scoreContextCandidatesWithActiveExtensions(surface,candidates,options={}){const defaultReport=defaultScoreContextCandidates(candidates,options),override=await runActiveServiceOverride(CONTEXT_RELEVANCE_SERVICE,{surface,candidates,default_report:defaultReport});if(!override.handled)return override.warnings.length>0?{...defaultReport,warnings:override.warnings}:defaultReport;if(!Array.isArray(override.result)||!override.result.every(entry=>typeof entry=="object"&&entry!==null&&typeof entry.id=="string"&&typeof entry.score=="number"&&Number.isFinite(entry.score)))return{...defaultReport,warnings:[...override.warnings,"extension_context_relevance_invalid_result"]};try{const report=await scoreContextCandidates(candidates,{...options,scorer:()=>override.result});return override.warnings.length>0?{...report,warnings:override.warnings}:report}catch{return{...defaultReport,warnings:[...override.warnings,"extension_context_relevance_invalid_result"]}}}const CONTEXT_EVALUATION_METRIC_NAMES=["ndcg","reciprocal_rank","required_recall","continuity_coverage","token_budget_adherence"];function ratioOfPresent(expected,actual){return expected.length===0?1:expected.filter(id=>actual.has(id)).length/expected.length}function evaluateContextRanking(input){if(!Number.isFinite(input.actual_tokens)||input.actual_tokens<0||!Number.isFinite(input.token_budget)||input.token_budget<=0)throw new TypeError("Context ranking token counts require actual_tokens >= 0 and token_budget > 0");const judgments=input.judgments??{},gains=input.ranked_ids.map(id=>Math.max(0,judgments[id]??0)),idealGains=Object.values(judgments).map(grade=>Math.max(0,grade)).sort((left,right)=>right-left).slice(0,gains.length||1),discountedGain=values=>values.reduce((total,grade,index)=>total+(2**grade-1)/Math.log2(index+2),0),ideal=discountedGain(idealGains),firstRelevant=gains.findIndex(grade=>grade>0),actualIds=new Set(input.ranked_ids),withinBudget=input.actual_tokens<=input.token_budget;return{ndcg:ideal===0?1:discountedGain(gains)/ideal,reciprocal_rank:firstRelevant<0?0:1/(firstRelevant+1),required_recall:ratioOfPresent(input.required_ids??[],actualIds),continuity_coverage:ratioOfPresent(input.continuity_ids??[],actualIds),token_budget_adherence:withinBudget?1:input.token_budget/input.actual_tokens,within_token_budget:withinBudget}}function estimateJsonTokens(value){return Math.ceil(JSON_TOKEN_ENCODER.encode(JSON.stringify(value)).byteLength/4)}function roundEvaluationMetric(value){return Math.round(value*1e4)/1e4}function rankingPayloadForScenario(result,surface){const rankedIds=surface==="context"?[...result.high_level??[],...result.low_level??[],...result.blocked_fallback??[]].map(item=>item.id):[...result.recommended?[result.recommended]:[],...result.ready??[]].map(item=>item.id),servedIds=new Set(rankedIds),attribution=(result.ranking?.items??[]).filter(item=>servedIds.has(item.id)).map(item=>({id:item.id,contributions:item.contributions}));return{rankedIds,attribution}}async function runContextEvaluationScenario(scenario,reader){if(scenario.id.trim().length===0||scenario.rationale.trim().length===0)throw new TypeError("Context evaluation scenarios require non-empty id and rationale values");const result=scenario.surface==="context"?await reader.context({...scenario.options,explainRanking:!0,outputBudget:scenario.options?.outputBudget??"unbounded"}):await reader.next({...scenario.options,explainRanking:!0,outputBudget:scenario.options?.outputBudget??"unbounded"}),{rankedIds,attribution}=rankingPayloadForScenario(result,scenario.surface),packet={...result,ranking:void 0},actualTokens=estimateJsonTokens(packet);return{id:scenario.id,surface:scenario.surface,rationale:scenario.rationale,ranked_ids:rankedIds,actual_tokens:actualTokens,metrics:evaluateContextRanking({ranked_ids:rankedIds,judgments:scenario.judgments,required_ids:scenario.required_ids,continuity_ids:scenario.continuity_ids,actual_tokens:actualTokens,token_budget:scenario.token_budget}),attribution}}function summarizeContextEvaluationReports(reports,thresholds){if(reports.length===0)throw new TypeError("Context evaluation requires at least one scenario report");const metrics=CONTEXT_EVALUATION_METRIC_NAMES;for(const metric of metrics)if(!Number.isFinite(thresholds[metric]))throw new TypeError(`Context evaluation threshold ${metric} must be a finite number`);const aggregate=Object.fromEntries(metrics.map(metric=>[metric,roundEvaluationMetric(reports.reduce((total,report)=>total+report.metrics[metric],0)/reports.length)])),failures=metrics.filter(metric=>aggregate[metric]<thresholds[metric]).map(metric=>`${metric}:${aggregate[metric]}<${thresholds[metric]}`);return{scenario_count:reports.length,aggregate,scenarios:[...reports],passed:failures.length===0,failures}}async function runContextEvaluationCorpus(scenarios,reader,thresholds){const reports=[];for(const scenario of scenarios)reports.push(await runContextEvaluationScenario(scenario,reader));return summarizeContextEvaluationReports(reports,thresholds)}export{CONTEXT_EVALUATION_METRIC_NAMES,CONTEXT_RELEVANCE_SERVICE,CONTEXT_RELEVANCE_SIGNAL_NAMES,buildItemContextRelevanceCandidates,defaultScoreContextCandidates,evaluateContextRanking,runContextEvaluationCorpus,runContextEvaluationScenario,scoreContextCandidates,scoreContextCandidatesWithActiveExtensions,summarizeContextEvaluationReports};
+(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]="74b476d9-5f30-5135-9539-5fe3e864c60f")}catch{}})();import{runActiveServiceOverride}from"../core/extensions/index.js";import{normalizeStatusForRegistry,normalizeStatusInput}from"../core/item/status.js";import{compareTimestampStrings}from"../core/shared/time.js";import{EXIT_CODE}from"../core/shared/constants.js";import{PmCliError}from"../core/shared/errors.js";import{isReadOutputBudgetExceeded}from"./read-output-contracts.js";import{canonicalizeContextRecencyCoordinate,CONTEXT_RECENCY_EPOCH}from"./context/recency.js";const CONTEXT_RELEVANCE_SIGNAL_NAMES=["structural","recency","activity_density","graph_proximity","claim_focus","priority_pressure","risk_pressure","deadline_pressure","knowledge_density","author_affinity","usage_affinity","semantic_similarity"],NO_CONTEXT_AUTHOR=Symbol("no-context-author"),NO_ITEM_ASSIGNEE=Symbol("no-item-assignee");function normalizeContextActor(value,missingValue){if(typeof value!="string")return missingValue;const normalized=value.trim().toLowerCase();return normalized.length>0?normalized:missingValue}function releaseCohortCoordinate(value){if(typeof value!="string")return;const match=/^v?(\d{4})\.(\d{1,2})\.(\d{1,2})(?:$|[-+])/u.exec(value.trim());if(!match)return;const year=Number(match[1]),month=Number(match[2]),day=Number(match[3]),date=new Date(Date.UTC(year,month-1,day));return date.getUTCFullYear()===year&&date.getUTCMonth()===month-1&&date.getUTCDate()===day?date.toISOString():void 0}function fallbackRecencyEvidence(item){const releaseCoordinate=releaseCohortCoordinate(item.release);return releaseCoordinate!==void 0?{source:"release_cohort",coordinate:releaseCoordinate}:{source:"created_at",coordinate:canonicalizeContextRecencyCoordinate(item.created_at)??CONTEXT_RECENCY_EPOCH}}function canonicalizeRecencyEvidence(evidence){if(!["substantive_history","release_cohort","created_at"].includes(evidence.source)||(evidence.source==="substantive_history"?evidence.history_op!==void 0&&typeof evidence.history_op!="string"||evidence.event_class!==void 0&&evidence.event_class!=="substantive":evidence.history_op!==void 0||evidence.event_class!==void 0))throw new TypeError("Context signal recency provenance must match its source");const coordinate=canonicalizeContextRecencyCoordinate(evidence.coordinate);if(coordinate===null)throw new TypeError("Context signal recency coordinate must be a valid absolute timestamp with millisecond precision");return{...evidence,coordinate}}function normalizedPressure(value,maximum){const parsed=typeof value=="number"?value:typeof value=="string"?Number.parseFloat(value):Number.NaN;return Number.isFinite(parsed)?1-Math.min(Math.max(parsed,0),maximum)/maximum:0}function deadlinePressure(deadline,nowMs){const deadlineMs=typeof deadline=="string"?Date.parse(deadline):deadline instanceof Date?deadline.getTime():typeof deadline=="number"?deadline:Number.NaN;if(!Number.isFinite(deadlineMs)||!Number.isFinite(nowMs))return 0;const days=(deadlineMs-nowMs)/864e5;return days<=0?1:1/(1+days/30)}function riskPressure(risk){const normalized=typeof risk=="string"?risk.trim().toLowerCase():void 0;return normalized==="critical"||normalized==="high"?1:normalized==="medium"?.5:normalized==="low"?.1:0}function derivedSignalOrFallback(values,id,fallback){return values?.[id]??fallback}function buildItemContextRelevanceCandidates(items,options){const recencyEvidence=new Map(items.map(item=>{const suppliedEvidence=options.recencyEvidence?.[item.id];return[item.id,suppliedEvidence===void 0?fallbackRecencyEvidence(item):canonicalizeRecencyEvidence(suppliedEvidence)]})),recencyOrder=[...items].sort((left,right)=>{const leftTime=recencyEvidence.get(left.id).coordinate,rightTime=recencyEvidence.get(right.id).coordinate;return compareTimestampStrings(rightTime,leftTime)||left.id.localeCompare(right.id)}),recencyRank=new Map(recencyOrder.map((item,index)=>[item.id,index])),denominator=Math.max(items.length-1,1),normalizedAuthor=normalizeContextActor(options.author,NO_CONTEXT_AUTHOR),inProgressStatus=normalizeStatusInput("in_progress",options.statusRegistry),nowMs=Date.parse(options.now);return items.map(item=>{const assigned=normalizeContextActor(item.assignee,NO_ITEM_ASSIGNEE)===normalizedAuthor,knowledgeEntries=(item.comments?.length??0)+(item.notes?.length??0)+(item.learnings?.length??0);return{id:item.id,item,signal_provenance:{recency:recencyEvidence.get(item.id)},signals:{recency:items.length===1?1:1-recencyRank.get(item.id)/denominator,activity_density:options.activityDensity?.[item.id],graph_proximity:derivedSignalOrFallback(options.graphProximity,item.id,item.parent?.3:0),claim_focus:derivedSignalOrFallback(options.claimFocus,item.id,normalizeStatusForRegistry(item.status,options.statusRegistry)===inProgressStatus?1:assigned?.75:0),priority_pressure:normalizedPressure(item.priority,4),risk_pressure:riskPressure(item.risk),deadline_pressure:deadlinePressure(item.deadline,nowMs),knowledge_density:derivedSignalOrFallback(options.knowledgeDensity,item.id,Math.min(knowledgeEntries/5,1)),author_affinity:derivedSignalOrFallback(options.authorAffinity,item.id,assigned?1:0),usage_affinity:options.usageAffinity?.[item.id],semantic_similarity:options.semanticSimilarity?.[item.id]}}})}const CONTEXT_RELEVANCE_SERVICE="context_relevance",DEFAULT_CONTEXT_RELEVANCE_WEIGHTS={structural:.4,recency:.35,activity_density:.25,graph_proximity:.15,claim_focus:.6,priority_pressure:.35,risk_pressure:.2,deadline_pressure:.45,knowledge_density:.25,author_affinity:.2,usage_affinity:.3,semantic_similarity:.5},JSON_TOKEN_ENCODER=new TextEncoder;function assertCandidates(candidates){const ids=new Set;for(const candidate of candidates){if(typeof candidate.id!="string"||candidate.id.trim().length===0||ids.has(candidate.id))throw new TypeError("Context relevance candidates require unique non-empty ids");ids.add(candidate.id);for(const[signal,value]of Object.entries(candidate.signals??{})){if(signal==="structural"||!CONTEXT_RELEVANCE_SIGNAL_NAMES.includes(signal))throw new TypeError(`Unknown context relevance signal: ${signal}`);if(value!==void 0&&(!Number.isFinite(value)||value<0||value>1))throw new TypeError(`Context relevance signal ${signal} must be a finite number from 0 to 1`)}}}function resolveWeights(overrides){const weights={...DEFAULT_CONTEXT_RELEVANCE_WEIGHTS};for(const[signal,weight]of Object.entries(overrides??{}))weight!==void 0&&CONTEXT_RELEVANCE_SIGNAL_NAMES.includes(signal)&&(weights[signal]=weight);for(const[signal,weight]of Object.entries(weights))if(!Number.isFinite(weight)||weight<0)throw new TypeError(`Context relevance weight ${signal} must be a finite non-negative number`);return weights}function defaultScoreContextCandidates(candidates,options={}){assertCandidates(candidates);const weights=resolveWeights(options.weights),denominator=Math.max(candidates.length-1,1),available=new Set(["structural"]);for(const candidate of candidates)for(const[signal,value]of Object.entries(candidate.signals??{}))value!==void 0&&available.add(signal);const availableSignals=CONTEXT_RELEVANCE_SIGNAL_NAMES.filter(signal=>available.has(signal)),scored=candidates.map((candidate,index)=>{const signalValues={structural:candidates.length===1?1:1-index/denominator,...candidate.signals},contributions={};let weightedScore=0,totalWeight=0;for(const signal of availableSignals){const value=signalValues[signal];if(value===void 0)continue;const contribution=value*weights[signal];contributions[signal]=contribution,weightedScore+=contribution,totalWeight+=weights[signal]}return{...candidate,baseline_rank:index+1,rank:0,score:totalWeight===0?0:weightedScore/totalWeight,contributions}});return scored.sort((left,right)=>right.score-left.score||left.baseline_rank-right.baseline_rank),scored.forEach((entry,index)=>{entry.rank=index+1}),{model:"default-weighted-v1",available_signals:availableSignals,ranked:scored}}async function scoreContextCandidates(candidates,options={}){const defaultReport=defaultScoreContextCandidates(candidates,options);if(!options.scorer)return defaultReport;const customScores=await options.scorer({candidates,default_report:defaultReport}),scoreById=new Map;for(const entry of customScores){if(scoreById.has(entry.id)||!Number.isFinite(entry.score))throw new TypeError("Context relevance scorer must return one finite score for every candidate");scoreById.set(entry.id,entry.score)}if(scoreById.size!==candidates.length||candidates.some(candidate=>!scoreById.has(candidate.id)))throw new TypeError("Context relevance scorer must return one finite score for every candidate");const ranked=defaultReport.ranked.map(entry=>{const score=scoreById.get(entry.id);return{...entry,score,contributions:{custom:score}}});return ranked.sort((left,right)=>right.score-left.score||left.baseline_rank-right.baseline_rank),ranked.forEach((entry,index)=>{entry.rank=index+1}),{model:"custom",available_signals:defaultReport.available_signals,ranked}}async function scoreContextCandidatesWithActiveExtensions(surface,candidates,options={}){const defaultReport=defaultScoreContextCandidates(candidates,options),override=await runActiveServiceOverride(CONTEXT_RELEVANCE_SERVICE,{surface,candidates,default_report:defaultReport});if(!override.handled)return override.warnings.length>0?{...defaultReport,warnings:override.warnings}:defaultReport;if(!Array.isArray(override.result)||!override.result.every(entry=>typeof entry=="object"&&entry!==null&&typeof entry.id=="string"&&typeof entry.score=="number"&&Number.isFinite(entry.score)))return{...defaultReport,warnings:[...override.warnings,"extension_context_relevance_invalid_result"]};try{const report=await scoreContextCandidates(candidates,{...options,scorer:()=>override.result});return override.warnings.length>0?{...report,warnings:override.warnings}:report}catch{return{...defaultReport,warnings:[...override.warnings,"extension_context_relevance_invalid_result"]}}}const CONTEXT_EVALUATION_METRIC_NAMES=["ndcg","reciprocal_rank","required_recall","continuity_coverage","token_budget_adherence"];function ratioOfPresent(expected,actual){return expected.length===0?1:expected.filter(id=>actual.has(id)).length/expected.length}function evaluateContextRanking(input){if(!Number.isFinite(input.actual_tokens)||input.actual_tokens<0||!Number.isFinite(input.token_budget)||input.token_budget<=0)throw new TypeError("Context ranking token counts require actual_tokens >= 0 and token_budget > 0");const judgments=input.judgments??{},gains=input.ranked_ids.map(id=>Math.max(0,judgments[id]??0)),idealGains=Object.values(judgments).map(grade=>Math.max(0,grade)).sort((left,right)=>right-left).slice(0,gains.length||1),discountedGain=values=>values.reduce((total,grade,index)=>total+(2**grade-1)/Math.log2(index+2),0),ideal=discountedGain(idealGains),firstRelevant=gains.findIndex(grade=>grade>0),actualIds=new Set(input.ranked_ids),withinBudget=input.actual_tokens<=input.token_budget;return{ndcg:ideal===0?1:discountedGain(gains)/ideal,reciprocal_rank:firstRelevant<0?0:1/(firstRelevant+1),required_recall:ratioOfPresent(input.required_ids??[],actualIds),continuity_coverage:ratioOfPresent(input.continuity_ids??[],actualIds),token_budget_adherence:withinBudget?1:input.token_budget/input.actual_tokens,within_token_budget:withinBudget}}function estimateJsonTokens(value){return Math.ceil(JSON_TOKEN_ENCODER.encode(JSON.stringify(value)).byteLength/4)}function roundEvaluationMetric(value){return Math.round(value*1e4)/1e4}function rankingPayloadForScenario(result,surface){const rankedIds=surface==="context"?[...result.high_level??[],...result.low_level??[],...result.blocked_fallback??[]].map(item=>item.id):[...result.recommended?[result.recommended]:[],...result.ready??[]].map(item=>item.id),servedIds=new Set(rankedIds),attribution=(result.ranking?.items??[]).filter(item=>servedIds.has(item.id)).map(item=>({id:item.id,contributions:item.contributions}));return{rankedIds,attribution}}async function runContextEvaluationScenario(scenario,reader){if(scenario.id.trim().length===0||scenario.rationale.trim().length===0)throw new TypeError("Context evaluation scenarios require non-empty id and rationale values");const result=scenario.surface==="context"?await reader.context({...scenario.options,explainRanking:!0,outputBudget:scenario.options?.outputBudget??"unbounded"}):await reader.next({...scenario.options,explainRanking:!0,outputBudget:scenario.options?.outputBudget??"unbounded"});if(isReadOutputBudgetExceeded(result)||result.read_output?.result_omitted===!0||result.context_intent?.result_omitted===!0)throw new PmCliError(`Cannot evaluate ${scenario.surface} scenario "${scenario.id}": the read omitted its useful result.`,EXIT_CODE.USAGE,{code:"context_evaluation_read_incomplete",nextSteps:["Increase the read output budget or start a new shared output session, then rerun the scenario."]});const{rankedIds,attribution}=rankingPayloadForScenario(result,scenario.surface),packet={...result,ranking:void 0},actualTokens=estimateJsonTokens(packet);return{id:scenario.id,surface:scenario.surface,rationale:scenario.rationale,ranked_ids:rankedIds,actual_tokens:actualTokens,metrics:evaluateContextRanking({ranked_ids:rankedIds,judgments:scenario.judgments,required_ids:scenario.required_ids,continuity_ids:scenario.continuity_ids,actual_tokens:actualTokens,token_budget:scenario.token_budget}),attribution}}function summarizeContextEvaluationReports(reports,thresholds){if(reports.length===0)throw new TypeError("Context evaluation requires at least one scenario report");const metrics=CONTEXT_EVALUATION_METRIC_NAMES;for(const metric of metrics)if(!Number.isFinite(thresholds[metric]))throw new TypeError(`Context evaluation threshold ${metric} must be a finite number`);const aggregate=Object.fromEntries(metrics.map(metric=>[metric,roundEvaluationMetric(reports.reduce((total,report)=>total+report.metrics[metric],0)/reports.length)])),failures=metrics.filter(metric=>aggregate[metric]<thresholds[metric]).map(metric=>`${metric}:${aggregate[metric]}<${thresholds[metric]}`);return{scenario_count:reports.length,aggregate,scenarios:[...reports],passed:failures.length===0,failures}}async function runContextEvaluationCorpus(scenarios,reader,thresholds){const reports=[];for(const scenario of scenarios)reports.push(await runContextEvaluationScenario(scenario,reader));return summarizeContextEvaluationReports(reports,thresholds)}export{CONTEXT_EVALUATION_METRIC_NAMES,CONTEXT_RELEVANCE_SERVICE,CONTEXT_RELEVANCE_SIGNAL_NAMES,buildItemContextRelevanceCandidates,defaultScoreContextCandidates,evaluateContextRanking,runContextEvaluationCorpus,runContextEvaluationScenario,scoreContextCandidates,scoreContextCandidatesWithActiveExtensions,summarizeContextEvaluationReports};
 //# sourceMappingURL=context-relevance.js.map