@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/dist/sdk/context-relevance.js

@@ -1,504 +1,2 @@
-/**
- * @module sdk/context-relevance
- *
- * Public, deterministic context-ranking and evaluation primitives. The scorer
- * accepts already-derived signals so package authors can reuse the same model
- * with core, extension, or project-specific feature stores.
- */
-
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="80a03884-711e-5170-a3c1-f05ccb065702")}catch(e){}}();
-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";
-/** Canonical signal keys understood by the built-in relevance model. */
-export 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",
-];
-const NO_CONTEXT_AUTHOR = Symbol("no-context-author");
-const 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 undefined;
-    const match = /^v?(\d{4})\.(\d{1,2})\.(\d{1,2})(?:$|[-+])/u.exec(value.trim());
-    if (!match)
-        return undefined;
-    const year = Number(match[1]);
-    const month = Number(match[2]);
-    const day = Number(match[3]);
-    const date = new Date(Date.UTC(year, month - 1, day));
-    return date.getUTCFullYear() === year &&
-        date.getUTCMonth() === month - 1 &&
-        date.getUTCDate() === day
-        ? date.toISOString()
-        : undefined;
-}
-function fallbackRecencyEvidence(item) {
-    const releaseCoordinate = releaseCohortCoordinate(item.release);
-    if (releaseCoordinate !== undefined) {
-        return { source: "release_cohort", coordinate: releaseCoordinate };
-    }
-    return {
-        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 !== undefined &&
-                typeof evidence.history_op !== "string") ||
-                (evidence.event_class !== undefined &&
-                    evidence.event_class !== "substantive")
-            : evidence.history_op !== undefined || evidence.event_class !== undefined)) {
-        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) / 86_400_000;
-    return days <= 0 ? 1 : 1 / (1 + days / 30);
-}
-function riskPressure(risk) {
-    const normalized = typeof risk === "string" ? risk.trim().toLowerCase() : undefined;
-    if (normalized === "critical" || normalized === "high")
-        return 1;
-    if (normalized === "medium")
-        return 0.5;
-    return normalized === "low" ? 0.1 : 0;
-}
-function derivedSignalOrFallback(values, id, fallback) {
-    return values?.[id] ?? fallback;
-}
-/**
- * Derive the canonical metadata signals consumed by `pm context` and `pm next`.
- * Extensions can pair this with {@link scoreContextCandidatesWithActiveExtensions}
- * to reproduce built-in ranking without private imports or subprocesses.
- */
-export function buildItemContextRelevanceCandidates(items, options) {
-    const recencyEvidence = new Map(items.map((item) => {
-        const suppliedEvidence = options.recencyEvidence?.[item.id];
-        return [
-            item.id,
-            suppliedEvidence === undefined
-                ? fallbackRecencyEvidence(item)
-                : canonicalizeRecencyEvidence(suppliedEvidence),
-        ];
-    }));
-    const recencyOrder = [...items].sort((left, right) => {
-        const leftTime = recencyEvidence.get(left.id)
-            .coordinate;
-        const rightTime = recencyEvidence.get(right.id)
-            .coordinate;
-        return (compareTimestampStrings(rightTime, leftTime) ||
-            left.id.localeCompare(right.id));
-    });
-    const recencyRank = new Map(recencyOrder.map((item, index) => [item.id, index]));
-    const denominator = Math.max(items.length - 1, 1);
-    const normalizedAuthor = normalizeContextActor(options.author, NO_CONTEXT_AUTHOR);
-    const inProgressStatus = normalizeStatusInput("in_progress", options.statusRegistry);
-    const nowMs = Date.parse(options.now);
-    return items.map((item) => {
-        const assigned = normalizeContextActor(item.assignee, NO_ITEM_ASSIGNEE) ===
-            normalizedAuthor;
-        const 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 ? 0.3 : 0),
-                claim_focus: derivedSignalOrFallback(options.claimFocus, item.id, normalizeStatusForRegistry(item.status, options.statusRegistry) ===
-                    inProgressStatus
-                    ? 1
-                    : assigned
-                        ? 0.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],
-            },
-        };
-    });
-}
-/** Governed extension service used to replace or wrap context ranking. */
-export const CONTEXT_RELEVANCE_SERVICE = "context_relevance";
-const DEFAULT_CONTEXT_RELEVANCE_WEIGHTS = {
-    structural: 0.4,
-    recency: 0.35,
-    activity_density: 0.25,
-    graph_proximity: 0.15,
-    claim_focus: 0.6,
-    priority_pressure: 0.35,
-    risk_pressure: 0.2,
-    deadline_pressure: 0.45,
-    knowledge_density: 0.25,
-    author_affinity: 0.2,
-    usage_affinity: 0.3,
-    semantic_similarity: 0.5,
-};
-const 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 === undefined)
-                continue;
-            if (!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 ?? {})) {
-        if (weight !== undefined &&
-            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;
-}
-/** Score candidates with pm's deterministic weighted model. Candidate order is the structural baseline and remains unchanged when no advanced signals exist. */
-export function defaultScoreContextCandidates(candidates, options = {}) {
-    assertCandidates(candidates);
-    const weights = resolveWeights(options.weights);
-    const denominator = Math.max(candidates.length - 1, 1);
-    const available = new Set(["structural"]);
-    for (const candidate of candidates) {
-        for (const [signal, value] of Object.entries(candidate.signals ?? {})) {
-            if (value !== undefined)
-                available.add(signal);
-        }
-    }
-    const availableSignals = CONTEXT_RELEVANCE_SIGNAL_NAMES.filter((signal) => available.has(signal));
-    const scored = candidates.map((candidate, index) => {
-        const signalValues = {
-            structural: candidates.length === 1 ? 1 : 1 - index / denominator,
-            ...candidate.signals,
-        };
-        const contributions = {};
-        let weightedScore = 0;
-        let totalWeight = 0;
-        for (const signal of availableSignals) {
-            const value = signalValues[signal];
-            if (value === undefined)
-                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,
-        };
-    });
-    scored.sort((left, right) => right.score - left.score || left.baseline_rank - right.baseline_rank);
-    scored.forEach((entry, index) => {
-        entry.rank = index + 1;
-    });
-    return {
-        model: "default-weighted-v1",
-        available_signals: availableSignals,
-        ranked: scored,
-    };
-}
-/** Score candidates with the default model or a validated replacement/wrapper. */
-export async function scoreContextCandidates(candidates, options = {}) {
-    const defaultReport = defaultScoreContextCandidates(candidates, options);
-    if (!options.scorer)
-        return defaultReport;
-    const customScores = await options.scorer({
-        candidates,
-        default_report: defaultReport,
-    });
-    const 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 } };
-    });
-    ranked.sort((left, right) => right.score - left.score || left.baseline_rank - right.baseline_rank);
-    ranked.forEach((entry, index) => {
-        entry.rank = index + 1;
-    });
-    return {
-        model: "custom",
-        available_signals: defaultReport.available_signals,
-        ranked,
-    };
-}
-/** Score command candidates through the public default model and then the active governed `context_relevance` service override, when one is registered. */
-export async function scoreContextCandidatesWithActiveExtensions(surface, candidates, options = {}) {
-    const defaultReport = defaultScoreContextCandidates(candidates, options);
-    const 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",
-            ],
-        };
-    }
-}
-/** Canonical aggregate metrics required by every context evaluation corpus. */
-export const CONTEXT_EVALUATION_METRIC_NAMES = [
-    "ndcg",
-    "reciprocal_rank",
-    "required_recall",
-    "continuity_coverage",
-    "token_budget_adherence",
-];
-function ratioOfPresent(expected, actual) {
-    if (expected.length === 0)
-        return 1;
-    return expected.filter((id) => actual.has(id)).length / expected.length;
-}
-/** Evaluate one ranked context packet against graded human judgments. */
-export 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 ?? {};
-    const gains = input.ranked_ids.map((id) => Math.max(0, judgments[id] ?? 0));
-    const idealGains = Object.values(judgments)
-        .map((grade) => Math.max(0, grade))
-        .sort((left, right) => right - left)
-        .slice(0, gains.length || 1);
-    const discountedGain = (values) => values.reduce((total, grade, index) => total + (2 ** grade - 1) / Math.log2(index + 2), 0);
-    const ideal = discountedGain(idealGains);
-    const firstRelevant = gains.findIndex((grade) => grade > 0);
-    const actualIds = new Set(input.ranked_ids);
-    const 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 * 10_000) / 10_000;
-}
-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);
-    const servedIds = new Set(rankedIds);
-    const attribution = (result.ranking?.items ?? [])
-        .filter((item) => servedIds.has(item.id))
-        .map((item) => ({ id: item.id, contributions: item.contributions }));
-    return { rankedIds, attribution };
-}
-/** Execute one graded scenario through public SDK context/next read primitives. */
-export 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: true,
-            outputBudget: "unbounded",
-        })
-        : await reader.next({
-            ...scenario.options,
-            explainRanking: true,
-            outputBudget: "unbounded",
-        });
-    const { rankedIds, attribution } = rankingPayloadForScenario(result, scenario.surface);
-    const packet = { ...result, ranking: undefined };
-    const 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,
-    };
-}
-/** Aggregate scenario reports and evaluate every metric against explicit thresholds. */
-export 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),
-    ]));
-    const 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,
-    };
-}
-/** Execute a same-workspace scenario corpus through public SDK read primitives. */
-export async function runContextEvaluationCorpus(scenarios, reader, thresholds) {
-    const reports = [];
-    for (const scenario of scenarios) {
-        reports.push(await runContextEvaluationScenario(scenario, reader));
-    }
-    return summarizeContextEvaluationReports(reports, thresholds);
-}
+!(function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=new e.Error().stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="dffb5f26-d8b4-5861-a7ea-0436bd4a22a6")}catch(e2){}})();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"];const NO_CONTEXT_AUTHOR=Symbol("no-context-author");const 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 void 0;const match=/^v?(\d{4})\.(\d{1,2})\.(\d{1,2})(?:$|[-+])/u.exec(value.trim());if(!match)return void 0;const year=Number(match[1]);const month=Number(match[2]);const day=Number(match[3]);const 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);if(releaseCoordinate!==void 0){return{source:"release_cohort",coordinate:releaseCoordinate}}return{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;if(normalized==="critical"||normalized==="high")return 1;if(normalized==="medium")return .5;return 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)]}));const recencyOrder=[...items].sort((left,right)=>{const leftTime=recencyEvidence.get(left.id).coordinate;const rightTime=recencyEvidence.get(right.id).coordinate;return compareTimestampStrings(rightTime,leftTime)||left.id.localeCompare(right.id)});const recencyRank=new Map(recencyOrder.map((item,index)=>[item.id,index]));const denominator=Math.max(items.length-1,1);const normalizedAuthor=normalizeContextActor(options.author,NO_CONTEXT_AUTHOR);const inProgressStatus=normalizeStatusInput("in_progress",options.statusRegistry);const nowMs=Date.parse(options.now);return items.map(item=>{const assigned=normalizeContextActor(item.assignee,NO_ITEM_ASSIGNEE)===normalizedAuthor;const 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";const 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};const 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)continue;if(!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??{})){if(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);const denominator=Math.max(candidates.length-1,1);const available=new Set(["structural"]);for(const candidate of candidates){for(const[signal,value]of Object.entries(candidate.signals??{})){if(value!==void 0)available.add(signal)}}const availableSignals=CONTEXT_RELEVANCE_SIGNAL_NAMES.filter(signal=>available.has(signal));const scored=candidates.map((candidate,index)=>{const signalValues={structural:candidates.length===1?1:1-index/denominator,...candidate.signals};const contributions={};let weightedScore=0;let 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}});scored.sort((left,right)=>right.score-left.score||left.baseline_rank-right.baseline_rank);scored.forEach((entry,index)=>{entry.rank=index+1});return{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});const 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}}});ranked.sort((left,right)=>right.score-left.score||left.baseline_rank-right.baseline_rank);ranked.forEach((entry,index)=>{entry.rank=index+1});return{model:"custom",available_signals:defaultReport.available_signals,ranked}}async function scoreContextCandidatesWithActiveExtensions(surface,candidates,options={}){const defaultReport=defaultScoreContextCandidates(candidates,options);const 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){if(expected.length===0)return 1;return 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??{};const gains=input.ranked_ids.map(id=>Math.max(0,judgments[id]??0));const idealGains=Object.values(judgments).map(grade=>Math.max(0,grade)).sort((left,right)=>right-left).slice(0,gains.length||1);const discountedGain=values=>values.reduce((total,grade,index)=>total+(2**grade-1)/Math.log2(index+2),0);const ideal=discountedGain(idealGains);const firstRelevant=gains.findIndex(grade=>grade>0);const actualIds=new Set(input.ranked_ids);const 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);const servedIds=new Set(rankedIds);const 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:true,outputBudget:"unbounded"}):await reader.next({...scenario.options,explainRanking:true,outputBudget:"unbounded"});const{rankedIds,attribution}=rankingPayloadForScenario(result,scenario.surface);const packet={...result,ranking:void 0};const 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)]));const 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
-//# debugId=80a03884-711e-5170-a3c1-f05ccb065702