open-multi-agent-kit 0.96.2 → 0.97.0

package/dist/core/context-budget-v2-planner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-v2-planner.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-planner.ts"],"names":[],"mappings":"AA2BA,OAAO,EAGN,KAAK,0BAA0B,EAE/B,KAAK,yBAAyB,EAK9B,MAAM,8BAA8B,CAAC;AAUtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,0BAA0B,GAAG,yBAAyB,CA6KtG","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextSourceRefV2,\n\tDEFAULT_HEADROOM_QUALITY_POLICY,\n} from \"./context-budget-headroom.ts\";\nimport {\n\tbuildContextBudgetPlanCacheKeyV2,\n\tcreateContextBudgetCacheKeyBaseV2,\n\tcreateContextBudgetSelectionCacheV2,\n\tfinalizeContextBudgetCacheTelemetryV2,\n\treadValidPlanCacheV2,\n\twritePlanCacheV2,\n} from \"./context-budget-v2-cache.ts\";\nimport { computePlanHash } from \"./context-budget-v2-plan-hash.ts\";\nimport { compareOptionalForSelection } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tapplyPlannerRedundancyPenalties,\n\tbuildTierAllocations,\n\tcreatePlannedItems,\n\tcreateTierUsage,\n\temitCoverageDiagnostics,\n\temitOmissionDiagnostics,\n\tselectHardItem,\n\tselectOptionalItem,\n} from \"./context-budget-v2-selection.ts\";\nimport { allocateTiers, computeTierDemand } from \"./context-budget-v2-tiers.ts\";\nimport {\n\tCONTEXT_BUDGET_POLICY_VERSION_V2,\n\tDEFAULT_TIER_POLICY_V2,\n\ttype PromptContextBudgetInputV2,\n\ttype PromptContextBudgetObservabilityV2,\n\ttype PromptContextBudgetPlanV2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetPolicyV2,\n\ttype TokenOptimizerRuntimeStatus,\n} from \"./context-budget-v2-types.ts\";\n\nconst TOKEN_OPTIMIZER_RUNTIME_STATUS: TokenOptimizerRuntimeStatus = {\n\toptimizerId: \"legacy-token-optimizer\",\n\tstatus: \"quarantined_compatibility\",\n\tactive: false,\n\tactiveContextBudgetOptimizer: \"context-budget-v2\",\n\tcompatibilityOnly: true,\n};\n\nexport function planPromptContextBudgetV2(input: PromptContextBudgetInputV2): PromptContextBudgetPlanV2 {\n\tconst modelId = input.modelId ?? \"unknown\";\n\tconst qualityPolicy = input.qualityPolicy ?? DEFAULT_HEADROOM_QUALITY_POLICY;\n\tconst policyVersion = input.policyVersion ?? CONTEXT_BUDGET_POLICY_VERSION_V2;\n\tconst diagnostics: QualityDiagnosticV2[] = [];\n\n\tconst maxTokens = normalizeBudgetTokens(\"maxTokens\", input.maxTokens, diagnostics);\n\tconst responseReserve = normalizeBudgetTokens(\n\t\t\"responseReserveTokens\",\n\t\tinput.responseReserveTokens ?? 0,\n\t\tdiagnostics,\n\t);\n\tconst safetyMargin = normalizeBudgetTokens(\n\t\t\"safetyMarginTokens\",\n\t\tinput.safetyMarginTokens ?? Math.ceil(maxTokens * 0.05),\n\t\tdiagnostics,\n\t);\n\tconst available = Math.max(0, maxTokens - responseReserve - safetyMargin);\n\tconst canUsePlanCache = !diagnostics.some((diagnostic) => diagnostic.reason === \"invalid_budget\");\n\n\tconst tierPolicy: Readonly<Record<ContextBudgetTierV2, TierBudgetPolicyV2>> = {\n\t\t...DEFAULT_TIER_POLICY_V2,\n\t\t...(input.tierPolicy ?? {}),\n\t};\n\tconst basePlanned = createPlannedItems(input.items, input.tokenCounter, modelId);\n\tapplyPlannerRedundancyPenalties(basePlanned);\n\tconst rawTokens = basePlanned.reduce((sum, planned) => sum + planned.fullTokens, 0);\n\n\tconst demand = computeTierDemand(basePlanned);\n\tconst allocation = allocateTiers(available, tierPolicy, demand);\n\tconst cacheKeyBase = createContextBudgetCacheKeyBaseV2({\n\t\tbudgetBucket: input.cacheBudgetBucket ?? String(available),\n\t\tcacheInvalidationSnapshot: input.cacheInvalidationSnapshot ?? input.cacheProvider?.getInvalidationSnapshot?.(),\n\t\tmodelId,\n\t\tnamespace: input.cacheNamespace,\n\t\tpolicyVersion,\n\t\tquery: input.query,\n\t\tqueryIntentHash: input.queryIntentHash,\n\t\tredactionPolicyHash: input.redactionPolicyHash,\n\t\tsafetyProfileHash: input.safetyProfileHash,\n\t\ttokenizerId: input.tokenizerId,\n\t});\n\tconst planCacheKey = buildContextBudgetPlanCacheKeyV2({\n\t\tavailableTokens: available,\n\t\tkeyBase: cacheKeyBase,\n\t\tmaxTokens,\n\t\tplanned: basePlanned,\n\t\tpromptHash: input.promptHash,\n\t\tqualityPolicy,\n\t\tresponseReserveTokens: responseReserve,\n\t\tsafetyMarginTokens: safetyMargin,\n\t\ttierPolicy,\n\t});\n\tconst cache = createContextBudgetSelectionCacheV2({\n\t\tkeyBase: cacheKeyBase,\n\t\tnowEpochMs: input.cacheNowEpochMs,\n\t\tplanCacheKey,\n\t\tprovider: input.cacheProvider,\n\t\tttlMs: input.cacheTtlMs,\n\t});\n\tconst cachedPlan = canUsePlanCache\n\t\t? readValidPlanCacheV2({\n\t\t\t\tavailableTokens: available,\n\t\t\t\tcache,\n\t\t\t\tkey: planCacheKey,\n\t\t\t\tplanned: basePlanned,\n\t\t\t})\n\t\t: undefined;\n\tif (cachedPlan) {\n\t\treturn cachedPlan;\n\t}\n\tconst selection = new Map<string, SelectedRepresentationV2>();\n\tconst tierUsed = createTierUsage();\n\tconst omitted: ContextBudgetItemV2[] = [];\n\tconst retrievalFallbacks: ContextSourceRefV2[] = [];\n\tlet usedTokens = 0;\n\n\tfor (const planned of basePlanned) {\n\t\tif (!planned.isHard) continue;\n\t\tusedTokens += selectHardItem(planned, selection, tierUsed);\n\t}\n\tif (usedTokens > available) {\n\t\tdiagnostics.push({\n\t\t\treason: \"hard_pin_over_capacity\",\n\t\t\tdetail: `hard-pinned context uses ${usedTokens} tokens against ${available} available tokens`,\n\t\t});\n\t}\n\n\tconst optionalPlanned = basePlanned.filter((planned) => !planned.isHard).sort(compareOptionalForSelection);\n\tfor (const planned of optionalPlanned) {\n\t\tusedTokens = selectOptionalItem(planned, {\n\t\t\tallocation,\n\t\t\tavailable,\n\t\t\tcache,\n\t\t\tdiagnostics,\n\t\t\tomitted,\n\t\t\tqualityPolicy,\n\t\t\tretrievalFallbacks,\n\t\t\tselection,\n\t\t\ttierUsed,\n\t\t\tusedTokens,\n\t\t});\n\t}\n\n\tconst omittedHighPriority = omitted.some((item) => item.priority === \"high\" || item.required === true);\n\temitOmissionDiagnostics(omitted, diagnostics, retrievalFallbacks);\n\temitCoverageDiagnostics(input.query, selection, diagnostics);\n\n\tconst tierAllocations = buildTierAllocations(allocation, demand, tierUsed);\n\tconst omittedTokens = omitted.reduce(\n\t\t(sum, item) => sum + (basePlanned.find((planned) => planned.item.id === item.id)?.fullTokens ?? 0),\n\t\t0,\n\t);\n\tconst omittedItemIds = omitted.map((item) => item.id);\n\tconst planHash = computePlanHash({\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanned: basePlanned,\n\t\tselection,\n\t\tallocations: tierAllocations,\n\t\tomittedItemIds,\n\t});\n\tconst observability = buildObservability({\n\t\tavailable,\n\t\tdiagnostics,\n\t\tomittedItemIds,\n\t\tomittedTokens,\n\t\tplanHash,\n\t\trawTokens,\n\t\tretrievalFallbacks,\n\t\tselection,\n\t\tusedTokens,\n\t\tcacheTelemetry: finalizeContextBudgetCacheTelemetryV2(cache.telemetry, {\n\t\t\tomittedTokens,\n\t\t\trawTokens,\n\t\t\tusedTokens,\n\t\t}),\n\t});\n\n\tconst plan: PromptContextBudgetPlanV2 = {\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanHash,\n\t\tmaxTokens,\n\t\tresponseReserveTokens: responseReserve,\n\t\tsafetyMarginTokens: safetyMargin,\n\t\tavailableTokens: available,\n\t\tusedTokens,\n\t\tomittedTokens,\n\t\trawTokens,\n\t\ttokenSavingsRatio: rawTokens > 0 ? Math.max(0, 1 - usedTokens / rawTokens) : 0,\n\t\temergency: usedTokens > available || diagnostics.some((diagnostic) => diagnostic.reason === \"invalid_budget\"),\n\t\tomittedHighPriority,\n\t\ttierAllocations,\n\t\tselectedRepresentations: [...selection.values()].sort((a, b) => a.itemId.localeCompare(b.itemId)),\n\t\tincludedItemIds: basePlanned\n\t\t\t.map((planned) => planned.item.id)\n\t\t\t.filter((id) => selection.has(id))\n\t\t\t.sort(),\n\t\tomittedItemIds,\n\t\tdiagnostics,\n\t\tretrievalFallbacks,\n\t\tobservability,\n\t};\n\tif (canUsePlanCache) {\n\t\twritePlanCacheV2({\n\t\t\tcache,\n\t\t\tkey: planCacheKey,\n\t\t\tplan,\n\t\t\tplanned: basePlanned,\n\t\t});\n\t}\n\treturn plan;\n}\n\nfunction normalizeBudgetTokens(field: string, value: number, diagnostics: QualityDiagnosticV2[]): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\tdiagnostics.push({\n\t\t\treason: \"invalid_budget\",\n\t\t\tdetail: `${field} must be a non-negative finite number, got ${value}`,\n\t\t});\n\t\treturn 0;\n\t}\n\treturn Math.floor(value);\n}\n\nfunction buildObservability(input: {\n\treadonly available: number;\n\treadonly diagnostics: readonly QualityDiagnosticV2[];\n\treadonly omittedItemIds: readonly string[];\n\treadonly omittedTokens: number;\n\treadonly planHash: string;\n\treadonly rawTokens: number;\n\treadonly retrievalFallbacks: readonly ContextSourceRefV2[];\n\treadonly selection: ReadonlyMap<string, SelectedRepresentationV2>;\n\treadonly usedTokens: number;\n\treadonly cacheTelemetry: PromptContextBudgetObservabilityV2[\"cache\"];\n}): PromptContextBudgetObservabilityV2 {\n\tconst selected = [...input.selection.values()];\n\treturn {\n\t\tcounts: {\n\t\t\tselected: selected.length,\n\t\t\tomitted: input.omittedItemIds.length,\n\t\t\tpointer: selected.filter((representation) => representation.kind === \"pointer\").length,\n\t\t\tcompressed: selected.filter((representation) => representation.kind === \"headroom-compressed\").length,\n\t\t\tfull: selected.filter((representation) => representation.kind === \"full\").length,\n\t\t\tretrievalFallback: countUniqueRetrievalFallbacks(input.retrievalFallbacks),\n\t\t},\n\t\tdiagnosticReasons: [...new Set(input.diagnostics.map((diagnostic) => diagnostic.reason))].sort(),\n\t\ttokens: {\n\t\t\tavailable: input.available,\n\t\t\tused: input.usedTokens,\n\t\t\traw: input.rawTokens,\n\t\t\tomitted: input.omittedTokens,\n\t\t\ttokenSavings: Math.max(0, input.rawTokens - input.usedTokens),\n\t\t},\n\t\tplanHash: input.planHash,\n\t\tcache: input.cacheTelemetry,\n\t\ttokenOptimizer: TOKEN_OPTIMIZER_RUNTIME_STATUS,\n\t};\n}\n\nfunction countUniqueRetrievalFallbacks(retrievalFallbacks: readonly ContextSourceRefV2[]): number {\n\treturn new Set(\n\t\tretrievalFallbacks.map((ref) =>\n\t\t\t[ref.uri, ref.contentHash, ref.symbol ?? \"\", ref.range?.startLine ?? \"\", ref.range?.endLine ?? \"\"].join(\"\\0\"),\n\t\t),\n\t).size;\n}\n"]}
+{"version":3,"file":"context-budget-v2-planner.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-planner.ts"],"names":[],"mappings":"AA2BA,OAAO,EAGN,KAAK,0BAA0B,EAE/B,KAAK,yBAAyB,EAK9B,MAAM,8BAA8B,CAAC;AAUtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,0BAA0B,GAAG,yBAAyB,CA8KtG","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextSourceRefV2,\n\tDEFAULT_HEADROOM_QUALITY_POLICY,\n} from \"./context-budget-headroom.ts\";\nimport {\n\tbuildContextBudgetPlanCacheKeyV2,\n\tcreateContextBudgetCacheKeyBaseV2,\n\tcreateContextBudgetSelectionCacheV2,\n\tfinalizeContextBudgetCacheTelemetryV2,\n\treadValidPlanCacheV2,\n\twritePlanCacheV2,\n} from \"./context-budget-v2-cache.ts\";\nimport { computePlanHash } from \"./context-budget-v2-plan-hash.ts\";\nimport { compareOptionalForSelection } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tapplyPlannerRedundancyPenalties,\n\tbuildTierAllocations,\n\tcreatePlannedItems,\n\tcreateTierUsage,\n\temitCoverageDiagnostics,\n\temitOmissionDiagnostics,\n\tselectHardItem,\n\tselectOptionalItem,\n} from \"./context-budget-v2-selection.ts\";\nimport { allocateTiers, computeTierDemand } from \"./context-budget-v2-tiers.ts\";\nimport {\n\tCONTEXT_BUDGET_POLICY_VERSION_V2,\n\tDEFAULT_TIER_POLICY_V2,\n\ttype PromptContextBudgetInputV2,\n\ttype PromptContextBudgetObservabilityV2,\n\ttype PromptContextBudgetPlanV2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetPolicyV2,\n\ttype TokenOptimizerRuntimeStatus,\n} from \"./context-budget-v2-types.ts\";\n\nconst TOKEN_OPTIMIZER_RUNTIME_STATUS: TokenOptimizerRuntimeStatus = {\n\toptimizerId: \"legacy-token-optimizer\",\n\tstatus: \"quarantined_compatibility\",\n\tactive: false,\n\tactiveContextBudgetOptimizer: \"context-budget-v2\",\n\tcompatibilityOnly: true,\n};\n\nexport function planPromptContextBudgetV2(input: PromptContextBudgetInputV2): PromptContextBudgetPlanV2 {\n\tconst modelId = input.modelId ?? \"unknown\";\n\tconst qualityPolicy = input.qualityPolicy ?? DEFAULT_HEADROOM_QUALITY_POLICY;\n\tconst policyVersion = input.policyVersion ?? CONTEXT_BUDGET_POLICY_VERSION_V2;\n\tconst diagnostics: QualityDiagnosticV2[] = [];\n\n\tconst maxTokens = normalizeBudgetTokens(\"maxTokens\", input.maxTokens, diagnostics);\n\tconst responseReserve = normalizeBudgetTokens(\n\t\t\"responseReserveTokens\",\n\t\tinput.responseReserveTokens ?? 0,\n\t\tdiagnostics,\n\t);\n\tconst safetyMargin = normalizeBudgetTokens(\n\t\t\"safetyMarginTokens\",\n\t\tinput.safetyMarginTokens ?? Math.ceil(maxTokens * 0.05),\n\t\tdiagnostics,\n\t);\n\tconst available = Math.max(0, maxTokens - responseReserve - safetyMargin);\n\tconst canUsePlanCache = !diagnostics.some((diagnostic) => diagnostic.reason === \"invalid_budget\");\n\n\tconst tierPolicy: Readonly<Record<ContextBudgetTierV2, TierBudgetPolicyV2>> = {\n\t\t...DEFAULT_TIER_POLICY_V2,\n\t\t...(input.tierPolicy ?? {}),\n\t};\n\tconst basePlanned = createPlannedItems(input.items, input.tokenCounter, modelId, qualityPolicy);\n\tapplyPlannerRedundancyPenalties(basePlanned);\n\tconst rawTokens = basePlanned.reduce((sum, planned) => sum + planned.fullTokens, 0);\n\n\tconst demand = computeTierDemand(basePlanned);\n\tconst allocation = allocateTiers(available, tierPolicy, demand);\n\tconst cacheKeyBase = createContextBudgetCacheKeyBaseV2({\n\t\tbudgetBucket: input.cacheBudgetBucket ?? String(available),\n\t\tcacheInvalidationSnapshot: input.cacheInvalidationSnapshot ?? input.cacheProvider?.getInvalidationSnapshot?.(),\n\t\tmodelId,\n\t\tnamespace: input.cacheNamespace,\n\t\tpolicyVersion,\n\t\tselectionPolicyVersion: input.selectionPolicyVersion,\n\t\tquery: input.query,\n\t\tqueryIntentHash: input.queryIntentHash,\n\t\tredactionPolicyHash: input.redactionPolicyHash,\n\t\tsafetyProfileHash: input.safetyProfileHash,\n\t\ttokenizerId: input.tokenizerId,\n\t});\n\tconst planCacheKey = buildContextBudgetPlanCacheKeyV2({\n\t\tavailableTokens: available,\n\t\tkeyBase: cacheKeyBase,\n\t\tmaxTokens,\n\t\tplanned: basePlanned,\n\t\tpromptHash: input.promptHash,\n\t\tqualityPolicy,\n\t\tresponseReserveTokens: responseReserve,\n\t\tsafetyMarginTokens: safetyMargin,\n\t\ttierPolicy,\n\t});\n\tconst cache = createContextBudgetSelectionCacheV2({\n\t\tkeyBase: cacheKeyBase,\n\t\tnowEpochMs: input.cacheNowEpochMs,\n\t\tplanCacheKey,\n\t\tprovider: input.cacheProvider,\n\t\tttlMs: input.cacheTtlMs,\n\t});\n\tconst cachedPlan = canUsePlanCache\n\t\t? readValidPlanCacheV2({\n\t\t\t\tavailableTokens: available,\n\t\t\t\tcache,\n\t\t\t\tkey: planCacheKey,\n\t\t\t\tplanned: basePlanned,\n\t\t\t})\n\t\t: undefined;\n\tif (cachedPlan) {\n\t\treturn cachedPlan;\n\t}\n\tconst selection = new Map<string, SelectedRepresentationV2>();\n\tconst tierUsed = createTierUsage();\n\tconst omitted: ContextBudgetItemV2[] = [];\n\tconst retrievalFallbacks: ContextSourceRefV2[] = [];\n\tlet usedTokens = 0;\n\n\tfor (const planned of basePlanned) {\n\t\tif (!planned.isHard) continue;\n\t\tusedTokens += selectHardItem(planned, selection, tierUsed);\n\t}\n\tif (usedTokens > available) {\n\t\tdiagnostics.push({\n\t\t\treason: \"hard_pin_over_capacity\",\n\t\t\tdetail: `hard-pinned context uses ${usedTokens} tokens against ${available} available tokens`,\n\t\t});\n\t}\n\n\tconst optionalPlanned = basePlanned.filter((planned) => !planned.isHard).sort(compareOptionalForSelection);\n\tfor (const planned of optionalPlanned) {\n\t\tusedTokens = selectOptionalItem(planned, {\n\t\t\tallocation,\n\t\t\tavailable,\n\t\t\tcache,\n\t\t\tdiagnostics,\n\t\t\tomitted,\n\t\t\tqualityPolicy,\n\t\t\tretrievalFallbacks,\n\t\t\tselection,\n\t\t\ttierUsed,\n\t\t\tusedTokens,\n\t\t});\n\t}\n\n\tconst omittedHighPriority = omitted.some((item) => item.priority === \"high\" || item.required === true);\n\temitOmissionDiagnostics(omitted, diagnostics, retrievalFallbacks);\n\temitCoverageDiagnostics(input.query, selection, diagnostics);\n\n\tconst tierAllocations = buildTierAllocations(allocation, demand, tierUsed);\n\tconst omittedTokens = omitted.reduce(\n\t\t(sum, item) => sum + (basePlanned.find((planned) => planned.item.id === item.id)?.fullTokens ?? 0),\n\t\t0,\n\t);\n\tconst omittedItemIds = omitted.map((item) => item.id);\n\tconst planHash = computePlanHash({\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanned: basePlanned,\n\t\tselection,\n\t\tallocations: tierAllocations,\n\t\tomittedItemIds,\n\t});\n\tconst observability = buildObservability({\n\t\tavailable,\n\t\tdiagnostics,\n\t\tomittedItemIds,\n\t\tomittedTokens,\n\t\tplanHash,\n\t\trawTokens,\n\t\tretrievalFallbacks,\n\t\tselection,\n\t\tusedTokens,\n\t\tcacheTelemetry: finalizeContextBudgetCacheTelemetryV2(cache.telemetry, {\n\t\t\tomittedTokens,\n\t\t\trawTokens,\n\t\t\tusedTokens,\n\t\t}),\n\t});\n\n\tconst plan: PromptContextBudgetPlanV2 = {\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanHash,\n\t\tmaxTokens,\n\t\tresponseReserveTokens: responseReserve,\n\t\tsafetyMarginTokens: safetyMargin,\n\t\tavailableTokens: available,\n\t\tusedTokens,\n\t\tomittedTokens,\n\t\trawTokens,\n\t\ttokenSavingsRatio: rawTokens > 0 ? Math.max(0, 1 - usedTokens / rawTokens) : 0,\n\t\temergency: usedTokens > available || diagnostics.some((diagnostic) => diagnostic.reason === \"invalid_budget\"),\n\t\tomittedHighPriority,\n\t\ttierAllocations,\n\t\tselectedRepresentations: [...selection.values()].sort((a, b) => a.itemId.localeCompare(b.itemId)),\n\t\tincludedItemIds: basePlanned\n\t\t\t.map((planned) => planned.item.id)\n\t\t\t.filter((id) => selection.has(id))\n\t\t\t.sort(),\n\t\tomittedItemIds,\n\t\tdiagnostics,\n\t\tretrievalFallbacks,\n\t\tobservability,\n\t};\n\tif (canUsePlanCache) {\n\t\twritePlanCacheV2({\n\t\t\tcache,\n\t\t\tkey: planCacheKey,\n\t\t\tplan,\n\t\t\tplanned: basePlanned,\n\t\t});\n\t}\n\treturn plan;\n}\n\nfunction normalizeBudgetTokens(field: string, value: number, diagnostics: QualityDiagnosticV2[]): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\tdiagnostics.push({\n\t\t\treason: \"invalid_budget\",\n\t\t\tdetail: `${field} must be a non-negative finite number, got ${value}`,\n\t\t});\n\t\treturn 0;\n\t}\n\treturn Math.floor(value);\n}\n\nfunction buildObservability(input: {\n\treadonly available: number;\n\treadonly diagnostics: readonly QualityDiagnosticV2[];\n\treadonly omittedItemIds: readonly string[];\n\treadonly omittedTokens: number;\n\treadonly planHash: string;\n\treadonly rawTokens: number;\n\treadonly retrievalFallbacks: readonly ContextSourceRefV2[];\n\treadonly selection: ReadonlyMap<string, SelectedRepresentationV2>;\n\treadonly usedTokens: number;\n\treadonly cacheTelemetry: PromptContextBudgetObservabilityV2[\"cache\"];\n}): PromptContextBudgetObservabilityV2 {\n\tconst selected = [...input.selection.values()];\n\treturn {\n\t\tcounts: {\n\t\t\tselected: selected.length,\n\t\t\tomitted: input.omittedItemIds.length,\n\t\t\tpointer: selected.filter((representation) => representation.kind === \"pointer\").length,\n\t\t\tcompressed: selected.filter((representation) => representation.kind === \"headroom-compressed\").length,\n\t\t\tfull: selected.filter((representation) => representation.kind === \"full\").length,\n\t\t\tretrievalFallback: countUniqueRetrievalFallbacks(input.retrievalFallbacks),\n\t\t},\n\t\tdiagnosticReasons: [...new Set(input.diagnostics.map((diagnostic) => diagnostic.reason))].sort(),\n\t\ttokens: {\n\t\t\tavailable: input.available,\n\t\t\tused: input.usedTokens,\n\t\t\traw: input.rawTokens,\n\t\t\tomitted: input.omittedTokens,\n\t\t\ttokenSavings: Math.max(0, input.rawTokens - input.usedTokens),\n\t\t},\n\t\tplanHash: input.planHash,\n\t\tcache: input.cacheTelemetry,\n\t\ttokenOptimizer: TOKEN_OPTIMIZER_RUNTIME_STATUS,\n\t};\n}\n\nfunction countUniqueRetrievalFallbacks(retrievalFallbacks: readonly ContextSourceRefV2[]): number {\n\treturn new Set(\n\t\tretrievalFallbacks.map((ref) =>\n\t\t\t[ref.uri, ref.contentHash, ref.symbol ?? \"\", ref.range?.startLine ?? \"\", ref.range?.endLine ?? \"\"].join(\"\\0\"),\n\t\t),\n\t).size;\n}\n"]}

package/dist/core/context-budget-v2-planner.js

@@ -26,7 +26,7 @@ export function planPromptContextBudgetV2(input) {
         ...DEFAULT_TIER_POLICY_V2,
         ...(input.tierPolicy ?? {}),
     };
-    const basePlanned = createPlannedItems(input.items, input.tokenCounter, modelId);
+    const basePlanned = createPlannedItems(input.items, input.tokenCounter, modelId, qualityPolicy);
     applyPlannerRedundancyPenalties(basePlanned);
     const rawTokens = basePlanned.reduce((sum, planned) => sum + planned.fullTokens, 0);
     const demand = computeTierDemand(basePlanned);
@@ -37,6 +37,7 @@ export function planPromptContextBudgetV2(input) {
         modelId,
         namespace: input.cacheNamespace,
         policyVersion,
+        selectionPolicyVersion: input.selectionPolicyVersion,
         query: input.query,
         queryIntentHash: input.queryIntentHash,
         redactionPolicyHash: input.redactionPolicyHash,

package/dist/core/context-budget-v2-planner.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-v2-planner.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-planner.ts"],"names":[],"mappings":"AAAA,OAAO,EAIN,+BAA+B,GAC/B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EACN,gCAAgC,EAChC,iCAAiC,EACjC,mCAAmC,EACnC,qCAAqC,EACrC,oBAAoB,EACpB,gBAAgB,GAChB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,2BAA2B,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,EACN,+BAA+B,EAC/B,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,cAAc,EACd,kBAAkB,GAClB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAChF,OAAO,EACN,gCAAgC,EAChC,sBAAsB,GAQtB,MAAM,8BAA8B,CAAC;AAEtC,MAAM,8BAA8B,GAAgC;IACnE,WAAW,EAAE,wBAAwB;IACrC,MAAM,EAAE,2BAA2B;IACnC,MAAM,EAAE,KAAK;IACb,4BAA4B,EAAE,mBAAmB;IACjD,iBAAiB,EAAE,IAAI;CACvB,CAAC;AAEF,MAAM,UAAU,yBAAyB,CAAC,KAAiC,EAA6B;IACvG,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,SAAS,CAAC;IAC3C,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,IAAI,+BAA+B,CAAC;IAC7E,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,IAAI,gCAAgC,CAAC;IAC9E,MAAM,WAAW,GAA0B,EAAE,CAAC;IAE9C,MAAM,SAAS,GAAG,qBAAqB,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACnF,MAAM,eAAe,GAAG,qBAAqB,CAC5C,uBAAuB,EACvB,KAAK,CAAC,qBAAqB,IAAI,CAAC,EAChC,WAAW,CACX,CAAC;IACF,MAAM,YAAY,GAAG,qBAAqB,CACzC,oBAAoB,EACpB,KAAK,CAAC,kBAAkB,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,EACvD,WAAW,CACX,CAAC;IACF,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,YAAY,CAAC,CAAC;IAC1E,MAAM,eAAe,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,KAAK,gBAAgB,CAAC,CAAC;IAElG,MAAM,UAAU,GAA8D;QAC7E,GAAG,sBAAsB;QACzB,GAAG,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC;KAC3B,CAAC;IACF,MAAM,WAAW,GAAG,kBAAkB,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IACjF,+BAA+B,CAAC,WAAW,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC,GAAG,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAEpF,MAAM,MAAM,GAAG,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC9C,MAAM,UAAU,GAAG,aAAa,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;IAChE,MAAM,YAAY,GAAG,iCAAiC,CAAC;QACtD,YAAY,EAAE,KAAK,CAAC,iBAAiB,IAAI,MAAM,CAAC,SAAS,CAAC;QAC1D,yBAAyB,EAAE,KAAK,CAAC,yBAAyB,IAAI,KAAK,CAAC,aAAa,EAAE,uBAAuB,EAAE,EAAE;QAC9G,OAAO;QACP,SAAS,EAAE,KAAK,CAAC,cAAc;QAC/B,aAAa;QACb,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,eAAe,EAAE,KAAK,CAAC,eAAe;QACtC,mBAAmB,EAAE,KAAK,CAAC,mBAAmB;QAC9C,iBAAiB,EAAE,KAAK,CAAC,iBAAiB;QAC1C,WAAW,EAAE,KAAK,CAAC,WAAW;KAC9B,CAAC,CAAC;IACH,MAAM,YAAY,GAAG,gCAAgC,CAAC;QACrD,eAAe,EAAE,SAAS;QAC1B,OAAO,EAAE,YAAY;QACrB,SAAS;QACT,OAAO,EAAE,WAAW;QACpB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,aAAa;QACb,qBAAqB,EAAE,eAAe;QACtC,kBAAkB,EAAE,YAAY;QAChC,UAAU;KACV,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,mCAAmC,CAAC;QACjD,OAAO,EAAE,YAAY;QACrB,UAAU,EAAE,KAAK,CAAC,eAAe;QACjC,YAAY;QACZ,QAAQ,EAAE,KAAK,CAAC,aAAa;QAC7B,KAAK,EAAE,KAAK,CAAC,UAAU;KACvB,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,eAAe;QACjC,CAAC,CAAC,oBAAoB,CAAC;YACrB,eAAe,EAAE,SAAS;YAC1B,KAAK;YACL,GAAG,EAAE,YAAY;YACjB,OAAO,EAAE,WAAW;SACpB,CAAC;QACH,CAAC,CAAC,SAAS,CAAC;IACb,IAAI,UAAU,EAAE,CAAC;QAChB,OAAO,UAAU,CAAC;IACnB,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,GAAG,EAAoC,CAAC;IAC9D,MAAM,QAAQ,GAAG,eAAe,EAAE,CAAC;IACnC,MAAM,OAAO,GAA0B,EAAE,CAAC;IAC1C,MAAM,kBAAkB,GAAyB,EAAE,CAAC;IACpD,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,KAAK,MAAM,OAAO,IAAI,WAAW,EAAE,CAAC;QACnC,IAAI,CAAC,OAAO,CAAC,MAAM;YAAE,SAAS;QAC9B,UAAU,IAAI,cAAc,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC5D,CAAC;IACD,IAAI,UAAU,GAAG,SAAS,EAAE,CAAC;QAC5B,WAAW,CAAC,IAAI,CAAC;YAChB,MAAM,EAAE,wBAAwB;YAChC,MAAM,EAAE,4BAA4B,UAAU,mBAAmB,SAAS,mBAAmB;SAC7F,CAAC,CAAC;IACJ,CAAC;IAED,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IAC3G,KAAK,MAAM,OAAO,IAAI,eAAe,EAAE,CAAC;QACvC,UAAU,GAAG,kBAAkB,CAAC,OAAO,EAAE;YACxC,UAAU;YACV,SAAS;YACT,KAAK;YACL,WAAW;YACX,OAAO;YACP,aAAa;YACb,kBAAkB;YAClB,SAAS;YACT,QAAQ;YACR,UAAU;SACV,CAAC,CAAC;IACJ,CAAC;IAED,MAAM,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,MAAM,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;IACvG,uBAAuB,CAAC,OAAO,EAAE,WAAW,EAAE,kBAAkB,CAAC,CAAC;IAClE,uBAAuB,CAAC,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC;IAE7D,MAAM,eAAe,GAAG,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC3E,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CACnC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC,EAAE,UAAU,IAAI,CAAC,CAAC,EAClG,CAAC,CACD,CAAC;IACF,MAAM,cAAc,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,eAAe,CAAC;QAChC,aAAa;QACb,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,OAAO,EAAE,WAAW;QACpB,SAAS;QACT,WAAW,EAAE,eAAe;QAC5B,cAAc;KACd,CAAC,CAAC;IACH,MAAM,aAAa,GAAG,kBAAkB,CAAC;QACxC,SAAS;QACT,WAAW;QACX,cAAc;QACd,aAAa;QACb,QAAQ;QACR,SAAS;QACT,kBAAkB;QAClB,SAAS;QACT,UAAU;QACV,cAAc,EAAE,qCAAqC,CAAC,KAAK,CAAC,SAAS,EAAE;YACtE,aAAa;YACb,SAAS;YACT,UAAU;SACV,CAAC;KACF,CAAC,CAAC;IAEH,MAAM,IAAI,GAA8B;QACvC,aAAa;QACb,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,QAAQ;QACR,SAAS;QACT,qBAAqB,EAAE,eAAe;QACtC,kBAAkB,EAAE,YAAY;QAChC,eAAe,EAAE,SAAS;QAC1B,UAAU;QACV,aAAa;QACb,SAAS;QACT,iBAAiB,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QAC9E,SAAS,EAAE,UAAU,GAAG,SAAS,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,KAAK,gBAAgB,CAAC;QAC7G,mBAAmB;QACnB,eAAe;QACf,uBAAuB,EAAE,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACjG,eAAe,EAAE,WAAW;aAC1B,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;aACjC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;aACjC,IAAI,EAAE;QACR,cAAc;QACd,WAAW;QACX,kBAAkB;QAClB,aAAa;KACb,CAAC;IACF,IAAI,eAAe,EAAE,CAAC;QACrB,gBAAgB,CAAC;YAChB,KAAK;YACL,GAAG,EAAE,YAAY;YACjB,IAAI;YACJ,OAAO,EAAE,WAAW;SACpB,CAAC,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AAAA,CACZ;AAED,SAAS,qBAAqB,CAAC,KAAa,EAAE,KAAa,EAAE,WAAkC,EAAU;IACxG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC1C,WAAW,CAAC,IAAI,CAAC;YAChB,MAAM,EAAE,gBAAgB;YACxB,MAAM,EAAE,GAAG,KAAK,8CAA8C,KAAK,EAAE;SACrE,CAAC,CAAC;QACH,OAAO,CAAC,CAAC;IACV,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAAA,CACzB;AAED,SAAS,kBAAkB,CAAC,KAW3B,EAAsC;IACtC,MAAM,QAAQ,GAAG,CAAC,GAAG,KAAK,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/C,OAAO;QACN,MAAM,EAAE;YACP,QAAQ,EAAE,QAAQ,CAAC,MAAM;YACzB,OAAO,EAAE,KAAK,CAAC,cAAc,CAAC,MAAM;YACpC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,MAAM;YACtF,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,KAAK,qBAAqB,CAAC,CAAC,MAAM;YACrG,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,cAAc,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,MAAM;YAChF,iBAAiB,EAAE,6BAA6B,CAAC,KAAK,CAAC,kBAAkB,CAAC;SAC1E;QACD,iBAAiB,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;QAChG,MAAM,EAAE;YACP,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,IAAI,EAAE,KAAK,CAAC,UAAU;YACtB,GAAG,EAAE,KAAK,CAAC,SAAS;YACpB,OAAO,EAAE,KAAK,CAAC,aAAa;YAC5B,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,SAAS,GAAG,KAAK,CAAC,UAAU,CAAC;SAC7D;QACD,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,KAAK,EAAE,KAAK,CAAC,cAAc;QAC3B,cAAc,EAAE,8BAA8B;KAC9C,CAAC;AAAA,CACF;AAED,SAAS,6BAA6B,CAAC,kBAAiD,EAAU;IACjG,OAAO,IAAI,GAAG,CACb,kBAAkB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAC9B,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE,GAAG,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,EAAE,GAAG,CAAC,KAAK,EAAE,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAC7G,CACD,CAAC,IAAI,CAAC;AAAA,CACP","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextSourceRefV2,\n\tDEFAULT_HEADROOM_QUALITY_POLICY,\n} from \"./context-budget-headroom.ts\";\nimport {\n\tbuildContextBudgetPlanCacheKeyV2,\n\tcreateContextBudgetCacheKeyBaseV2,\n\tcreateContextBudgetSelectionCacheV2,\n\tfinalizeContextBudgetCacheTelemetryV2,\n\treadValidPlanCacheV2,\n\twritePlanCacheV2,\n} from \"./context-budget-v2-cache.ts\";\nimport { computePlanHash } from \"./context-budget-v2-plan-hash.ts\";\nimport { compareOptionalForSelection } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tapplyPlannerRedundancyPenalties,\n\tbuildTierAllocations,\n\tcreatePlannedItems,\n\tcreateTierUsage,\n\temitCoverageDiagnostics,\n\temitOmissionDiagnostics,\n\tselectHardItem,\n\tselectOptionalItem,\n} from \"./context-budget-v2-selection.ts\";\nimport { allocateTiers, computeTierDemand } from \"./context-budget-v2-tiers.ts\";\nimport {\n\tCONTEXT_BUDGET_POLICY_VERSION_V2,\n\tDEFAULT_TIER_POLICY_V2,\n\ttype PromptContextBudgetInputV2,\n\ttype PromptContextBudgetObservabilityV2,\n\ttype PromptContextBudgetPlanV2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetPolicyV2,\n\ttype TokenOptimizerRuntimeStatus,\n} from \"./context-budget-v2-types.ts\";\n\nconst TOKEN_OPTIMIZER_RUNTIME_STATUS: TokenOptimizerRuntimeStatus = {\n\toptimizerId: \"legacy-token-optimizer\",\n\tstatus: \"quarantined_compatibility\",\n\tactive: false,\n\tactiveContextBudgetOptimizer: \"context-budget-v2\",\n\tcompatibilityOnly: true,\n};\n\nexport function planPromptContextBudgetV2(input: PromptContextBudgetInputV2): PromptContextBudgetPlanV2 {\n\tconst modelId = input.modelId ?? \"unknown\";\n\tconst qualityPolicy = input.qualityPolicy ?? DEFAULT_HEADROOM_QUALITY_POLICY;\n\tconst policyVersion = input.policyVersion ?? CONTEXT_BUDGET_POLICY_VERSION_V2;\n\tconst diagnostics: QualityDiagnosticV2[] = [];\n\n\tconst maxTokens = normalizeBudgetTokens(\"maxTokens\", input.maxTokens, diagnostics);\n\tconst responseReserve = normalizeBudgetTokens(\n\t\t\"responseReserveTokens\",\n\t\tinput.responseReserveTokens ?? 0,\n\t\tdiagnostics,\n\t);\n\tconst safetyMargin = normalizeBudgetTokens(\n\t\t\"safetyMarginTokens\",\n\t\tinput.safetyMarginTokens ?? Math.ceil(maxTokens * 0.05),\n\t\tdiagnostics,\n\t);\n\tconst available = Math.max(0, maxTokens - responseReserve - safetyMargin);\n\tconst canUsePlanCache = !diagnostics.some((diagnostic) => diagnostic.reason === \"invalid_budget\");\n\n\tconst tierPolicy: Readonly<Record<ContextBudgetTierV2, TierBudgetPolicyV2>> = {\n\t\t...DEFAULT_TIER_POLICY_V2,\n\t\t...(input.tierPolicy ?? {}),\n\t};\n\tconst basePlanned = createPlannedItems(input.items, input.tokenCounter, modelId);\n\tapplyPlannerRedundancyPenalties(basePlanned);\n\tconst rawTokens = basePlanned.reduce((sum, planned) => sum + planned.fullTokens, 0);\n\n\tconst demand = computeTierDemand(basePlanned);\n\tconst allocation = allocateTiers(available, tierPolicy, demand);\n\tconst cacheKeyBase = createContextBudgetCacheKeyBaseV2({\n\t\tbudgetBucket: input.cacheBudgetBucket ?? String(available),\n\t\tcacheInvalidationSnapshot: input.cacheInvalidationSnapshot ?? input.cacheProvider?.getInvalidationSnapshot?.(),\n\t\tmodelId,\n\t\tnamespace: input.cacheNamespace,\n\t\tpolicyVersion,\n\t\tquery: input.query,\n\t\tqueryIntentHash: input.queryIntentHash,\n\t\tredactionPolicyHash: input.redactionPolicyHash,\n\t\tsafetyProfileHash: input.safetyProfileHash,\n\t\ttokenizerId: input.tokenizerId,\n\t});\n\tconst planCacheKey = buildContextBudgetPlanCacheKeyV2({\n\t\tavailableTokens: available,\n\t\tkeyBase: cacheKeyBase,\n\t\tmaxTokens,\n\t\tplanned: basePlanned,\n\t\tpromptHash: input.promptHash,\n\t\tqualityPolicy,\n\t\tresponseReserveTokens: responseReserve,\n\t\tsafetyMarginTokens: safetyMargin,\n\t\ttierPolicy,\n\t});\n\tconst cache = createContextBudgetSelectionCacheV2({\n\t\tkeyBase: cacheKeyBase,\n\t\tnowEpochMs: input.cacheNowEpochMs,\n\t\tplanCacheKey,\n\t\tprovider: input.cacheProvider,\n\t\tttlMs: input.cacheTtlMs,\n\t});\n\tconst cachedPlan = canUsePlanCache\n\t\t? readValidPlanCacheV2({\n\t\t\t\tavailableTokens: available,\n\t\t\t\tcache,\n\t\t\t\tkey: planCacheKey,\n\t\t\t\tplanned: basePlanned,\n\t\t\t})\n\t\t: undefined;\n\tif (cachedPlan) {\n\t\treturn cachedPlan;\n\t}\n\tconst selection = new Map<string, SelectedRepresentationV2>();\n\tconst tierUsed = createTierUsage();\n\tconst omitted: ContextBudgetItemV2[] = [];\n\tconst retrievalFallbacks: ContextSourceRefV2[] = [];\n\tlet usedTokens = 0;\n\n\tfor (const planned of basePlanned) {\n\t\tif (!planned.isHard) continue;\n\t\tusedTokens += selectHardItem(planned, selection, tierUsed);\n\t}\n\tif (usedTokens > available) {\n\t\tdiagnostics.push({\n\t\t\treason: \"hard_pin_over_capacity\",\n\t\t\tdetail: `hard-pinned context uses ${usedTokens} tokens against ${available} available tokens`,\n\t\t});\n\t}\n\n\tconst optionalPlanned = basePlanned.filter((planned) => !planned.isHard).sort(compareOptionalForSelection);\n\tfor (const planned of optionalPlanned) {\n\t\tusedTokens = selectOptionalItem(planned, {\n\t\t\tallocation,\n\t\t\tavailable,\n\t\t\tcache,\n\t\t\tdiagnostics,\n\t\t\tomitted,\n\t\t\tqualityPolicy,\n\t\t\tretrievalFallbacks,\n\t\t\tselection,\n\t\t\ttierUsed,\n\t\t\tusedTokens,\n\t\t});\n\t}\n\n\tconst omittedHighPriority = omitted.some((item) => item.priority === \"high\" || item.required === true);\n\temitOmissionDiagnostics(omitted, diagnostics, retrievalFallbacks);\n\temitCoverageDiagnostics(input.query, selection, diagnostics);\n\n\tconst tierAllocations = buildTierAllocations(allocation, demand, tierUsed);\n\tconst omittedTokens = omitted.reduce(\n\t\t(sum, item) => sum + (basePlanned.find((planned) => planned.item.id === item.id)?.fullTokens ?? 0),\n\t\t0,\n\t);\n\tconst omittedItemIds = omitted.map((item) => item.id);\n\tconst planHash = computePlanHash({\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanned: basePlanned,\n\t\tselection,\n\t\tallocations: tierAllocations,\n\t\tomittedItemIds,\n\t});\n\tconst observability = buildObservability({\n\t\tavailable,\n\t\tdiagnostics,\n\t\tomittedItemIds,\n\t\tomittedTokens,\n\t\tplanHash,\n\t\trawTokens,\n\t\tretrievalFallbacks,\n\t\tselection,\n\t\tusedTokens,\n\t\tcacheTelemetry: finalizeContextBudgetCacheTelemetryV2(cache.telemetry, {\n\t\t\tomittedTokens,\n\t\t\trawTokens,\n\t\t\tusedTokens,\n\t\t}),\n\t});\n\n\tconst plan: PromptContextBudgetPlanV2 = {\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanHash,\n\t\tmaxTokens,\n\t\tresponseReserveTokens: responseReserve,\n\t\tsafetyMarginTokens: safetyMargin,\n\t\tavailableTokens: available,\n\t\tusedTokens,\n\t\tomittedTokens,\n\t\trawTokens,\n\t\ttokenSavingsRatio: rawTokens > 0 ? Math.max(0, 1 - usedTokens / rawTokens) : 0,\n\t\temergency: usedTokens > available || diagnostics.some((diagnostic) => diagnostic.reason === \"invalid_budget\"),\n\t\tomittedHighPriority,\n\t\ttierAllocations,\n\t\tselectedRepresentations: [...selection.values()].sort((a, b) => a.itemId.localeCompare(b.itemId)),\n\t\tincludedItemIds: basePlanned\n\t\t\t.map((planned) => planned.item.id)\n\t\t\t.filter((id) => selection.has(id))\n\t\t\t.sort(),\n\t\tomittedItemIds,\n\t\tdiagnostics,\n\t\tretrievalFallbacks,\n\t\tobservability,\n\t};\n\tif (canUsePlanCache) {\n\t\twritePlanCacheV2({\n\t\t\tcache,\n\t\t\tkey: planCacheKey,\n\t\t\tplan,\n\t\t\tplanned: basePlanned,\n\t\t});\n\t}\n\treturn plan;\n}\n\nfunction normalizeBudgetTokens(field: string, value: number, diagnostics: QualityDiagnosticV2[]): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\tdiagnostics.push({\n\t\t\treason: \"invalid_budget\",\n\t\t\tdetail: `${field} must be a non-negative finite number, got ${value}`,\n\t\t});\n\t\treturn 0;\n\t}\n\treturn Math.floor(value);\n}\n\nfunction buildObservability(input: {\n\treadonly available: number;\n\treadonly diagnostics: readonly QualityDiagnosticV2[];\n\treadonly omittedItemIds: readonly string[];\n\treadonly omittedTokens: number;\n\treadonly planHash: string;\n\treadonly rawTokens: number;\n\treadonly retrievalFallbacks: readonly ContextSourceRefV2[];\n\treadonly selection: ReadonlyMap<string, SelectedRepresentationV2>;\n\treadonly usedTokens: number;\n\treadonly cacheTelemetry: PromptContextBudgetObservabilityV2[\"cache\"];\n}): PromptContextBudgetObservabilityV2 {\n\tconst selected = [...input.selection.values()];\n\treturn {\n\t\tcounts: {\n\t\t\tselected: selected.length,\n\t\t\tomitted: input.omittedItemIds.length,\n\t\t\tpointer: selected.filter((representation) => representation.kind === \"pointer\").length,\n\t\t\tcompressed: selected.filter((representation) => representation.kind === \"headroom-compressed\").length,\n\t\t\tfull: selected.filter((representation) => representation.kind === \"full\").length,\n\t\t\tretrievalFallback: countUniqueRetrievalFallbacks(input.retrievalFallbacks),\n\t\t},\n\t\tdiagnosticReasons: [...new Set(input.diagnostics.map((diagnostic) => diagnostic.reason))].sort(),\n\t\ttokens: {\n\t\t\tavailable: input.available,\n\t\t\tused: input.usedTokens,\n\t\t\traw: input.rawTokens,\n\t\t\tomitted: input.omittedTokens,\n\t\t\ttokenSavings: Math.max(0, input.rawTokens - input.usedTokens),\n\t\t},\n\t\tplanHash: input.planHash,\n\t\tcache: input.cacheTelemetry,\n\t\ttokenOptimizer: TOKEN_OPTIMIZER_RUNTIME_STATUS,\n\t};\n}\n\nfunction countUniqueRetrievalFallbacks(retrievalFallbacks: readonly ContextSourceRefV2[]): number {\n\treturn new Set(\n\t\tretrievalFallbacks.map((ref) =>\n\t\t\t[ref.uri, ref.contentHash, ref.symbol ?? \"\", ref.range?.startLine ?? \"\", ref.range?.endLine ?? \"\"].join(\"\\0\"),\n\t\t),\n\t).size;\n}\n"]}
+{"version":3,"file":"context-budget-v2-planner.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-planner.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextSourceRefV2,\n\tDEFAULT_HEADROOM_QUALITY_POLICY,\n} from \"./context-budget-headroom.ts\";\nimport {\n\tbuildContextBudgetPlanCacheKeyV2,\n\tcreateContextBudgetCacheKeyBaseV2,\n\tcreateContextBudgetSelectionCacheV2,\n\tfinalizeContextBudgetCacheTelemetryV2,\n\treadValidPlanCacheV2,\n\twritePlanCacheV2,\n} from \"./context-budget-v2-cache.ts\";\nimport { computePlanHash } from \"./context-budget-v2-plan-hash.ts\";\nimport { compareOptionalForSelection } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tapplyPlannerRedundancyPenalties,\n\tbuildTierAllocations,\n\tcreatePlannedItems,\n\tcreateTierUsage,\n\temitCoverageDiagnostics,\n\temitOmissionDiagnostics,\n\tselectHardItem,\n\tselectOptionalItem,\n} from \"./context-budget-v2-selection.ts\";\nimport { allocateTiers, computeTierDemand } from \"./context-budget-v2-tiers.ts\";\nimport {\n\tCONTEXT_BUDGET_POLICY_VERSION_V2,\n\tDEFAULT_TIER_POLICY_V2,\n\ttype PromptContextBudgetInputV2,\n\ttype PromptContextBudgetObservabilityV2,\n\ttype PromptContextBudgetPlanV2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetPolicyV2,\n\ttype TokenOptimizerRuntimeStatus,\n} from \"./context-budget-v2-types.ts\";\n\nconst TOKEN_OPTIMIZER_RUNTIME_STATUS: TokenOptimizerRuntimeStatus = {\n\toptimizerId: \"legacy-token-optimizer\",\n\tstatus: \"quarantined_compatibility\",\n\tactive: false,\n\tactiveContextBudgetOptimizer: \"context-budget-v2\",\n\tcompatibilityOnly: true,\n};\n\nexport function planPromptContextBudgetV2(input: PromptContextBudgetInputV2): PromptContextBudgetPlanV2 {\n\tconst modelId = input.modelId ?? \"unknown\";\n\tconst qualityPolicy = input.qualityPolicy ?? DEFAULT_HEADROOM_QUALITY_POLICY;\n\tconst policyVersion = input.policyVersion ?? CONTEXT_BUDGET_POLICY_VERSION_V2;\n\tconst diagnostics: QualityDiagnosticV2[] = [];\n\n\tconst maxTokens = normalizeBudgetTokens(\"maxTokens\", input.maxTokens, diagnostics);\n\tconst responseReserve = normalizeBudgetTokens(\n\t\t\"responseReserveTokens\",\n\t\tinput.responseReserveTokens ?? 0,\n\t\tdiagnostics,\n\t);\n\tconst safetyMargin = normalizeBudgetTokens(\n\t\t\"safetyMarginTokens\",\n\t\tinput.safetyMarginTokens ?? Math.ceil(maxTokens * 0.05),\n\t\tdiagnostics,\n\t);\n\tconst available = Math.max(0, maxTokens - responseReserve - safetyMargin);\n\tconst canUsePlanCache = !diagnostics.some((diagnostic) => diagnostic.reason === \"invalid_budget\");\n\n\tconst tierPolicy: Readonly<Record<ContextBudgetTierV2, TierBudgetPolicyV2>> = {\n\t\t...DEFAULT_TIER_POLICY_V2,\n\t\t...(input.tierPolicy ?? {}),\n\t};\n\tconst basePlanned = createPlannedItems(input.items, input.tokenCounter, modelId, qualityPolicy);\n\tapplyPlannerRedundancyPenalties(basePlanned);\n\tconst rawTokens = basePlanned.reduce((sum, planned) => sum + planned.fullTokens, 0);\n\n\tconst demand = computeTierDemand(basePlanned);\n\tconst allocation = allocateTiers(available, tierPolicy, demand);\n\tconst cacheKeyBase = createContextBudgetCacheKeyBaseV2({\n\t\tbudgetBucket: input.cacheBudgetBucket ?? String(available),\n\t\tcacheInvalidationSnapshot: input.cacheInvalidationSnapshot ?? input.cacheProvider?.getInvalidationSnapshot?.(),\n\t\tmodelId,\n\t\tnamespace: input.cacheNamespace,\n\t\tpolicyVersion,\n\t\tselectionPolicyVersion: input.selectionPolicyVersion,\n\t\tquery: input.query,\n\t\tqueryIntentHash: input.queryIntentHash,\n\t\tredactionPolicyHash: input.redactionPolicyHash,\n\t\tsafetyProfileHash: input.safetyProfileHash,\n\t\ttokenizerId: input.tokenizerId,\n\t});\n\tconst planCacheKey = buildContextBudgetPlanCacheKeyV2({\n\t\tavailableTokens: available,\n\t\tkeyBase: cacheKeyBase,\n\t\tmaxTokens,\n\t\tplanned: basePlanned,\n\t\tpromptHash: input.promptHash,\n\t\tqualityPolicy,\n\t\tresponseReserveTokens: responseReserve,\n\t\tsafetyMarginTokens: safetyMargin,\n\t\ttierPolicy,\n\t});\n\tconst cache = createContextBudgetSelectionCacheV2({\n\t\tkeyBase: cacheKeyBase,\n\t\tnowEpochMs: input.cacheNowEpochMs,\n\t\tplanCacheKey,\n\t\tprovider: input.cacheProvider,\n\t\tttlMs: input.cacheTtlMs,\n\t});\n\tconst cachedPlan = canUsePlanCache\n\t\t? readValidPlanCacheV2({\n\t\t\t\tavailableTokens: available,\n\t\t\t\tcache,\n\t\t\t\tkey: planCacheKey,\n\t\t\t\tplanned: basePlanned,\n\t\t\t})\n\t\t: undefined;\n\tif (cachedPlan) {\n\t\treturn cachedPlan;\n\t}\n\tconst selection = new Map<string, SelectedRepresentationV2>();\n\tconst tierUsed = createTierUsage();\n\tconst omitted: ContextBudgetItemV2[] = [];\n\tconst retrievalFallbacks: ContextSourceRefV2[] = [];\n\tlet usedTokens = 0;\n\n\tfor (const planned of basePlanned) {\n\t\tif (!planned.isHard) continue;\n\t\tusedTokens += selectHardItem(planned, selection, tierUsed);\n\t}\n\tif (usedTokens > available) {\n\t\tdiagnostics.push({\n\t\t\treason: \"hard_pin_over_capacity\",\n\t\t\tdetail: `hard-pinned context uses ${usedTokens} tokens against ${available} available tokens`,\n\t\t});\n\t}\n\n\tconst optionalPlanned = basePlanned.filter((planned) => !planned.isHard).sort(compareOptionalForSelection);\n\tfor (const planned of optionalPlanned) {\n\t\tusedTokens = selectOptionalItem(planned, {\n\t\t\tallocation,\n\t\t\tavailable,\n\t\t\tcache,\n\t\t\tdiagnostics,\n\t\t\tomitted,\n\t\t\tqualityPolicy,\n\t\t\tretrievalFallbacks,\n\t\t\tselection,\n\t\t\ttierUsed,\n\t\t\tusedTokens,\n\t\t});\n\t}\n\n\tconst omittedHighPriority = omitted.some((item) => item.priority === \"high\" || item.required === true);\n\temitOmissionDiagnostics(omitted, diagnostics, retrievalFallbacks);\n\temitCoverageDiagnostics(input.query, selection, diagnostics);\n\n\tconst tierAllocations = buildTierAllocations(allocation, demand, tierUsed);\n\tconst omittedTokens = omitted.reduce(\n\t\t(sum, item) => sum + (basePlanned.find((planned) => planned.item.id === item.id)?.fullTokens ?? 0),\n\t\t0,\n\t);\n\tconst omittedItemIds = omitted.map((item) => item.id);\n\tconst planHash = computePlanHash({\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanned: basePlanned,\n\t\tselection,\n\t\tallocations: tierAllocations,\n\t\tomittedItemIds,\n\t});\n\tconst observability = buildObservability({\n\t\tavailable,\n\t\tdiagnostics,\n\t\tomittedItemIds,\n\t\tomittedTokens,\n\t\tplanHash,\n\t\trawTokens,\n\t\tretrievalFallbacks,\n\t\tselection,\n\t\tusedTokens,\n\t\tcacheTelemetry: finalizeContextBudgetCacheTelemetryV2(cache.telemetry, {\n\t\t\tomittedTokens,\n\t\t\trawTokens,\n\t\t\tusedTokens,\n\t\t}),\n\t});\n\n\tconst plan: PromptContextBudgetPlanV2 = {\n\t\tpolicyVersion,\n\t\tpromptHash: input.promptHash,\n\t\tplanHash,\n\t\tmaxTokens,\n\t\tresponseReserveTokens: responseReserve,\n\t\tsafetyMarginTokens: safetyMargin,\n\t\tavailableTokens: available,\n\t\tusedTokens,\n\t\tomittedTokens,\n\t\trawTokens,\n\t\ttokenSavingsRatio: rawTokens > 0 ? Math.max(0, 1 - usedTokens / rawTokens) : 0,\n\t\temergency: usedTokens > available || diagnostics.some((diagnostic) => diagnostic.reason === \"invalid_budget\"),\n\t\tomittedHighPriority,\n\t\ttierAllocations,\n\t\tselectedRepresentations: [...selection.values()].sort((a, b) => a.itemId.localeCompare(b.itemId)),\n\t\tincludedItemIds: basePlanned\n\t\t\t.map((planned) => planned.item.id)\n\t\t\t.filter((id) => selection.has(id))\n\t\t\t.sort(),\n\t\tomittedItemIds,\n\t\tdiagnostics,\n\t\tretrievalFallbacks,\n\t\tobservability,\n\t};\n\tif (canUsePlanCache) {\n\t\twritePlanCacheV2({\n\t\t\tcache,\n\t\t\tkey: planCacheKey,\n\t\t\tplan,\n\t\t\tplanned: basePlanned,\n\t\t});\n\t}\n\treturn plan;\n}\n\nfunction normalizeBudgetTokens(field: string, value: number, diagnostics: QualityDiagnosticV2[]): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\tdiagnostics.push({\n\t\t\treason: \"invalid_budget\",\n\t\t\tdetail: `${field} must be a non-negative finite number, got ${value}`,\n\t\t});\n\t\treturn 0;\n\t}\n\treturn Math.floor(value);\n}\n\nfunction buildObservability(input: {\n\treadonly available: number;\n\treadonly diagnostics: readonly QualityDiagnosticV2[];\n\treadonly omittedItemIds: readonly string[];\n\treadonly omittedTokens: number;\n\treadonly planHash: string;\n\treadonly rawTokens: number;\n\treadonly retrievalFallbacks: readonly ContextSourceRefV2[];\n\treadonly selection: ReadonlyMap<string, SelectedRepresentationV2>;\n\treadonly usedTokens: number;\n\treadonly cacheTelemetry: PromptContextBudgetObservabilityV2[\"cache\"];\n}): PromptContextBudgetObservabilityV2 {\n\tconst selected = [...input.selection.values()];\n\treturn {\n\t\tcounts: {\n\t\t\tselected: selected.length,\n\t\t\tomitted: input.omittedItemIds.length,\n\t\t\tpointer: selected.filter((representation) => representation.kind === \"pointer\").length,\n\t\t\tcompressed: selected.filter((representation) => representation.kind === \"headroom-compressed\").length,\n\t\t\tfull: selected.filter((representation) => representation.kind === \"full\").length,\n\t\t\tretrievalFallback: countUniqueRetrievalFallbacks(input.retrievalFallbacks),\n\t\t},\n\t\tdiagnosticReasons: [...new Set(input.diagnostics.map((diagnostic) => diagnostic.reason))].sort(),\n\t\ttokens: {\n\t\t\tavailable: input.available,\n\t\t\tused: input.usedTokens,\n\t\t\traw: input.rawTokens,\n\t\t\tomitted: input.omittedTokens,\n\t\t\ttokenSavings: Math.max(0, input.rawTokens - input.usedTokens),\n\t\t},\n\t\tplanHash: input.planHash,\n\t\tcache: input.cacheTelemetry,\n\t\ttokenOptimizer: TOKEN_OPTIMIZER_RUNTIME_STATUS,\n\t};\n}\n\nfunction countUniqueRetrievalFallbacks(retrievalFallbacks: readonly ContextSourceRefV2[]): number {\n\treturn new Set(\n\t\tretrievalFallbacks.map((ref) =>\n\t\t\t[ref.uri, ref.contentHash, ref.symbol ?? \"\", ref.range?.startLine ?? \"\", ref.range?.endLine ?? \"\"].join(\"\\0\"),\n\t\t),\n\t).size;\n}\n"]}

package/dist/core/context-budget-v2-scoring.d.ts

@@ -2,6 +2,12 @@ import type { ContextBudgetItemV2 } from "./context-budget-headroom.ts";
 export interface PlannedItemV2 {
     readonly item: ContextBudgetItemV2;
     readonly fullTokens: number;
+    /**
+     * Cheapest non-omit representation cost, i.e. the true marginal cost of
+     * admitting this item at all. Equals `fullTokens` when the item has no
+     * cheaper pointer/summary/headroom representation.
+     */
+    readonly admissibleTokens: number;
     readonly contentHash: string;
     readonly baseScore: number;
     redundancyPenalty: number;
@@ -10,5 +16,16 @@ export interface PlannedItemV2 {
 }
 export declare function scoreContextBudgetItemV2(item: ContextBudgetItemV2, estimatedTokens: number): number;
 export declare function applyRedundancyPenalties(items: readonly PlannedItemV2[]): Map<string, number>;
+/**
+ * Order optional items for the budgeted 0/1 knapsack the planner greedily fills.
+ *
+ * Value density (effective score per token) is the primary key. Ordering by
+ * priority class first would let a single expensive `high` item evict an
+ * arbitrary number of far denser `medium` items, which makes the greedy
+ * unbounded-bad against the optimal packing. Priority still shapes the outcome
+ * through `PRIORITY_WEIGHT_V2` in the score numerator, and non-negotiable
+ * context uses `hard`/`required`, which the planner pins before this ordering
+ * is consulted. Remaining keys break ties into a deterministic total order.
+ */
 export declare function compareOptionalForSelection(a: PlannedItemV2, b: PlannedItemV2): number;
 //# sourceMappingURL=context-budget-v2-scoring.d.ts.map

package/dist/core/context-budget-v2-scoring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-v2-scoring.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-scoring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAgD,MAAM,8BAA8B,CAAC;AAEtH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CACzB;AAqBD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAUnG;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA8B7F;AAED,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,MAAM,CAiBtF","sourcesContent":["import type { ContextBudgetItemV2, ContextBudgetPriorityV2, ContextBudgetTierV2 } from \"./context-budget-headroom.ts\";\n\nexport interface PlannedItemV2 {\n\treadonly item: ContextBudgetItemV2;\n\treadonly fullTokens: number;\n\treadonly contentHash: string;\n\treadonly baseScore: number;\n\tredundancyPenalty: number;\n\teffectiveScore: number;\n\treadonly isHard: boolean;\n}\n\nconst PRIORITY_WEIGHT_V2: Record<ContextBudgetPriorityV2, number> = {\n\thard: 1_000_000,\n\thigh: 120,\n\tmedium: 60,\n\tlow: 15,\n};\n\nconst RECENCY_HALF_LIFE_BY_TIER: Readonly<Record<ContextBudgetTierV2, number>> = {\n\tsystem: 999,\n\t\"active-goal\": 12,\n\t\"current-files\": 8,\n\ttools: 4,\n\tskills: 6,\n\tmcp: 6,\n\thistory: 3,\n\tevidence: 8,\n\tscratch: 2,\n};\n\nexport function scoreContextBudgetItemV2(item: ContextBudgetItemV2, estimatedTokens: number): number {\n\tif (item.priority === \"hard\") {\n\t\treturn Number.POSITIVE_INFINITY;\n\t}\n\tconst priority = PRIORITY_WEIGHT_V2[item.priority];\n\tconst relevance = clamp01(item.relevance) * 25;\n\tconst recency = deriveRecency(item) * 15;\n\tconst evidence = clamp01(item.evidenceValue) * 25;\n\tconst cost = Math.sqrt(Math.max(0, estimatedTokens)) * 0.55;\n\treturn priority + relevance + recency + evidence - cost;\n}\n\nexport function applyRedundancyPenalties(items: readonly PlannedItemV2[]): Map<string, number> {\n\tconst penalties = new Map<string, number>();\n\tconst groups = new Map<string, PlannedItemV2[]>();\n\tfor (const planned of items) {\n\t\tif (!planned.item.redundancyKey) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst group = groups.get(planned.item.redundancyKey);\n\t\tif (group) {\n\t\t\tgroup.push(planned);\n\t\t} else {\n\t\t\tgroups.set(planned.item.redundancyKey, [planned]);\n\t\t}\n\t}\n\tfor (const group of groups.values()) {\n\t\tif (group.length <= 1) {\n\t\t\tcontinue;\n\t\t}\n\t\tgroup.sort((a, b) => {\n\t\t\tif (b.baseScore !== a.baseScore) {\n\t\t\t\treturn b.baseScore - a.baseScore;\n\t\t\t}\n\t\t\treturn a.item.id.localeCompare(b.item.id);\n\t\t});\n\t\tfor (let index = 1; index < group.length; index++) {\n\t\t\tconst duplicate = group[index];\n\t\t\tpenalties.set(duplicate.item.id, redundancyPenalty(duplicate.fullTokens) * index);\n\t\t}\n\t}\n\treturn penalties;\n}\n\nexport function compareOptionalForSelection(a: PlannedItemV2, b: PlannedItemV2): number {\n\tconst priorityDelta = priorityRank(b.item.priority) - priorityRank(a.item.priority);\n\tif (priorityDelta !== 0) {\n\t\treturn priorityDelta;\n\t}\n\tif (b.effectiveScore !== a.effectiveScore) {\n\t\treturn b.effectiveScore - a.effectiveScore;\n\t}\n\tconst aDensity = density(a);\n\tconst bDensity = density(b);\n\tif (bDensity !== aDensity) {\n\t\treturn bDensity - aDensity;\n\t}\n\tif (a.fullTokens !== b.fullTokens) {\n\t\treturn a.fullTokens - b.fullTokens;\n\t}\n\treturn a.item.id.localeCompare(b.item.id);\n}\n\nfunction priorityRank(priority: ContextBudgetPriorityV2): number {\n\tswitch (priority) {\n\t\tcase \"hard\":\n\t\t\treturn 4;\n\t\tcase \"high\":\n\t\t\treturn 3;\n\t\tcase \"medium\":\n\t\t\treturn 2;\n\t\tcase \"low\":\n\t\t\treturn 1;\n\t}\n}\n\nfunction clamp01(value: number | undefined): number {\n\tif (value === undefined || !Number.isFinite(value)) {\n\t\treturn 0;\n\t}\n\treturn Math.max(0, Math.min(1, value));\n}\n\nfunction deriveRecency(item: ContextBudgetItemV2): number {\n\tif (item.recency !== undefined) {\n\t\treturn clamp01(item.recency);\n\t}\n\tconst age = item.ageTurns ?? 0;\n\tconst halfLife = RECENCY_HALF_LIFE_BY_TIER[item.tier] ?? 6;\n\treturn clamp01(Math.exp(-age / halfLife));\n}\n\nfunction redundancyPenalty(tokens: number): number {\n\treturn Math.max(10, Math.sqrt(Math.max(0, tokens)) * 0.8);\n}\n\nfunction density(planned: PlannedItemV2): number {\n\tif (!Number.isFinite(planned.effectiveScore) || planned.effectiveScore <= 0) {\n\t\treturn planned.effectiveScore > 0 ? planned.effectiveScore : 0;\n\t}\n\treturn planned.effectiveScore / Math.max(planned.fullTokens, 1);\n}\n"]}
+{"version":3,"file":"context-budget-v2-scoring.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-scoring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAgD,MAAM,8BAA8B,CAAC;AAEtH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CACzB;AAqBD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAUnG;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA8B7F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,MAAM,CAiBtF","sourcesContent":["import type { ContextBudgetItemV2, ContextBudgetPriorityV2, ContextBudgetTierV2 } from \"./context-budget-headroom.ts\";\n\nexport interface PlannedItemV2 {\n\treadonly item: ContextBudgetItemV2;\n\treadonly fullTokens: number;\n\t/**\n\t * Cheapest non-omit representation cost, i.e. the true marginal cost of\n\t * admitting this item at all. Equals `fullTokens` when the item has no\n\t * cheaper pointer/summary/headroom representation.\n\t */\n\treadonly admissibleTokens: number;\n\treadonly contentHash: string;\n\treadonly baseScore: number;\n\tredundancyPenalty: number;\n\teffectiveScore: number;\n\treadonly isHard: boolean;\n}\n\nconst PRIORITY_WEIGHT_V2: Record<ContextBudgetPriorityV2, number> = {\n\thard: 1_000_000,\n\thigh: 120,\n\tmedium: 60,\n\tlow: 15,\n};\n\nconst RECENCY_HALF_LIFE_BY_TIER: Readonly<Record<ContextBudgetTierV2, number>> = {\n\tsystem: 999,\n\t\"active-goal\": 12,\n\t\"current-files\": 8,\n\ttools: 4,\n\tskills: 6,\n\tmcp: 6,\n\thistory: 3,\n\tevidence: 8,\n\tscratch: 2,\n};\n\nexport function scoreContextBudgetItemV2(item: ContextBudgetItemV2, estimatedTokens: number): number {\n\tif (item.priority === \"hard\") {\n\t\treturn Number.POSITIVE_INFINITY;\n\t}\n\tconst priority = PRIORITY_WEIGHT_V2[item.priority];\n\tconst relevance = clamp01(item.relevance) * 25;\n\tconst recency = deriveRecency(item) * 15;\n\tconst evidence = clamp01(item.evidenceValue) * 25;\n\tconst cost = Math.sqrt(Math.max(0, estimatedTokens)) * 0.55;\n\treturn priority + relevance + recency + evidence - cost;\n}\n\nexport function applyRedundancyPenalties(items: readonly PlannedItemV2[]): Map<string, number> {\n\tconst penalties = new Map<string, number>();\n\tconst groups = new Map<string, PlannedItemV2[]>();\n\tfor (const planned of items) {\n\t\tif (!planned.item.redundancyKey) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst group = groups.get(planned.item.redundancyKey);\n\t\tif (group) {\n\t\t\tgroup.push(planned);\n\t\t} else {\n\t\t\tgroups.set(planned.item.redundancyKey, [planned]);\n\t\t}\n\t}\n\tfor (const group of groups.values()) {\n\t\tif (group.length <= 1) {\n\t\t\tcontinue;\n\t\t}\n\t\tgroup.sort((a, b) => {\n\t\t\tif (b.baseScore !== a.baseScore) {\n\t\t\t\treturn b.baseScore - a.baseScore;\n\t\t\t}\n\t\t\treturn a.item.id.localeCompare(b.item.id);\n\t\t});\n\t\tfor (let index = 1; index < group.length; index++) {\n\t\t\tconst duplicate = group[index];\n\t\t\tpenalties.set(duplicate.item.id, redundancyPenalty(duplicate.fullTokens) * index);\n\t\t}\n\t}\n\treturn penalties;\n}\n\n/**\n * Order optional items for the budgeted 0/1 knapsack the planner greedily fills.\n *\n * Value density (effective score per token) is the primary key. Ordering by\n * priority class first would let a single expensive `high` item evict an\n * arbitrary number of far denser `medium` items, which makes the greedy\n * unbounded-bad against the optimal packing. Priority still shapes the outcome\n * through `PRIORITY_WEIGHT_V2` in the score numerator, and non-negotiable\n * context uses `hard`/`required`, which the planner pins before this ordering\n * is consulted. Remaining keys break ties into a deterministic total order.\n */\nexport function compareOptionalForSelection(a: PlannedItemV2, b: PlannedItemV2): number {\n\tconst aDensity = density(a);\n\tconst bDensity = density(b);\n\tif (bDensity !== aDensity) {\n\t\treturn bDensity - aDensity;\n\t}\n\tif (b.effectiveScore !== a.effectiveScore) {\n\t\treturn b.effectiveScore - a.effectiveScore;\n\t}\n\tconst priorityDelta = priorityRank(b.item.priority) - priorityRank(a.item.priority);\n\tif (priorityDelta !== 0) {\n\t\treturn priorityDelta;\n\t}\n\tif (a.fullTokens !== b.fullTokens) {\n\t\treturn a.fullTokens - b.fullTokens;\n\t}\n\treturn a.item.id.localeCompare(b.item.id);\n}\n\nfunction priorityRank(priority: ContextBudgetPriorityV2): number {\n\tswitch (priority) {\n\t\tcase \"hard\":\n\t\t\treturn 4;\n\t\tcase \"high\":\n\t\t\treturn 3;\n\t\tcase \"medium\":\n\t\t\treturn 2;\n\t\tcase \"low\":\n\t\t\treturn 1;\n\t}\n}\n\nfunction clamp01(value: number | undefined): number {\n\tif (value === undefined || !Number.isFinite(value)) {\n\t\treturn 0;\n\t}\n\treturn Math.max(0, Math.min(1, value));\n}\n\nfunction deriveRecency(item: ContextBudgetItemV2): number {\n\tif (item.recency !== undefined) {\n\t\treturn clamp01(item.recency);\n\t}\n\tconst age = item.ageTurns ?? 0;\n\tconst halfLife = RECENCY_HALF_LIFE_BY_TIER[item.tier] ?? 6;\n\treturn clamp01(Math.exp(-age / halfLife));\n}\n\nfunction redundancyPenalty(tokens: number): number {\n\treturn Math.max(10, Math.sqrt(Math.max(0, tokens)) * 0.8);\n}\n\n/**\n * Value per token of the CHEAPEST admissible representation. Dividing by\n * `fullTokens` would systematically penalize retrievable or summarizable items,\n * which are exactly the items the planner admits cheaply when the budget is\n * tight — the regime where this ordering decides anything at all.\n */\nfunction density(planned: PlannedItemV2): number {\n\tif (!Number.isFinite(planned.effectiveScore) || planned.effectiveScore <= 0) {\n\t\treturn planned.effectiveScore > 0 ? planned.effectiveScore : 0;\n\t}\n\treturn planned.effectiveScore / Math.max(planned.admissibleTokens, 1);\n}\n"]}

package/dist/core/context-budget-v2-scoring.js

@@ -58,19 +58,30 @@ export function applyRedundancyPenalties(items) {
     }
     return penalties;
 }
+/**
+ * Order optional items for the budgeted 0/1 knapsack the planner greedily fills.
+ *
+ * Value density (effective score per token) is the primary key. Ordering by
+ * priority class first would let a single expensive `high` item evict an
+ * arbitrary number of far denser `medium` items, which makes the greedy
+ * unbounded-bad against the optimal packing. Priority still shapes the outcome
+ * through `PRIORITY_WEIGHT_V2` in the score numerator, and non-negotiable
+ * context uses `hard`/`required`, which the planner pins before this ordering
+ * is consulted. Remaining keys break ties into a deterministic total order.
+ */
 export function compareOptionalForSelection(a, b) {
-    const priorityDelta = priorityRank(b.item.priority) - priorityRank(a.item.priority);
-    if (priorityDelta !== 0) {
-        return priorityDelta;
-    }
-    if (b.effectiveScore !== a.effectiveScore) {
-        return b.effectiveScore - a.effectiveScore;
-    }
     const aDensity = density(a);
     const bDensity = density(b);
     if (bDensity !== aDensity) {
         return bDensity - aDensity;
     }
+    if (b.effectiveScore !== a.effectiveScore) {
+        return b.effectiveScore - a.effectiveScore;
+    }
+    const priorityDelta = priorityRank(b.item.priority) - priorityRank(a.item.priority);
+    if (priorityDelta !== 0) {
+        return priorityDelta;
+    }
     if (a.fullTokens !== b.fullTokens) {
         return a.fullTokens - b.fullTokens;
     }
@@ -105,10 +116,16 @@ function deriveRecency(item) {
 function redundancyPenalty(tokens) {
     return Math.max(10, Math.sqrt(Math.max(0, tokens)) * 0.8);
 }
+/**
+ * Value per token of the CHEAPEST admissible representation. Dividing by
+ * `fullTokens` would systematically penalize retrievable or summarizable items,
+ * which are exactly the items the planner admits cheaply when the budget is
+ * tight — the regime where this ordering decides anything at all.
+ */
 function density(planned) {
     if (!Number.isFinite(planned.effectiveScore) || planned.effectiveScore <= 0) {
         return planned.effectiveScore > 0 ? planned.effectiveScore : 0;
     }
-    return planned.effectiveScore / Math.max(planned.fullTokens, 1);
+    return planned.effectiveScore / Math.max(planned.admissibleTokens, 1);
 }
 //# sourceMappingURL=context-budget-v2-scoring.js.map

package/dist/core/context-budget-v2-scoring.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-v2-scoring.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-scoring.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ContextBudgetItemV2, ContextBudgetPriorityV2, ContextBudgetTierV2 } from \"./context-budget-headroom.ts\";\n\nexport interface PlannedItemV2 {\n\treadonly item: ContextBudgetItemV2;\n\treadonly fullTokens: number;\n\treadonly contentHash: string;\n\treadonly baseScore: number;\n\tredundancyPenalty: number;\n\teffectiveScore: number;\n\treadonly isHard: boolean;\n}\n\nconst PRIORITY_WEIGHT_V2: Record<ContextBudgetPriorityV2, number> = {\n\thard: 1_000_000,\n\thigh: 120,\n\tmedium: 60,\n\tlow: 15,\n};\n\nconst RECENCY_HALF_LIFE_BY_TIER: Readonly<Record<ContextBudgetTierV2, number>> = {\n\tsystem: 999,\n\t\"active-goal\": 12,\n\t\"current-files\": 8,\n\ttools: 4,\n\tskills: 6,\n\tmcp: 6,\n\thistory: 3,\n\tevidence: 8,\n\tscratch: 2,\n};\n\nexport function scoreContextBudgetItemV2(item: ContextBudgetItemV2, estimatedTokens: number): number {\n\tif (item.priority === \"hard\") {\n\t\treturn Number.POSITIVE_INFINITY;\n\t}\n\tconst priority = PRIORITY_WEIGHT_V2[item.priority];\n\tconst relevance = clamp01(item.relevance) * 25;\n\tconst recency = deriveRecency(item) * 15;\n\tconst evidence = clamp01(item.evidenceValue) * 25;\n\tconst cost = Math.sqrt(Math.max(0, estimatedTokens)) * 0.55;\n\treturn priority + relevance + recency + evidence - cost;\n}\n\nexport function applyRedundancyPenalties(items: readonly PlannedItemV2[]): Map<string, number> {\n\tconst penalties = new Map<string, number>();\n\tconst groups = new Map<string, PlannedItemV2[]>();\n\tfor (const planned of items) {\n\t\tif (!planned.item.redundancyKey) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst group = groups.get(planned.item.redundancyKey);\n\t\tif (group) {\n\t\t\tgroup.push(planned);\n\t\t} else {\n\t\t\tgroups.set(planned.item.redundancyKey, [planned]);\n\t\t}\n\t}\n\tfor (const group of groups.values()) {\n\t\tif (group.length <= 1) {\n\t\t\tcontinue;\n\t\t}\n\t\tgroup.sort((a, b) => {\n\t\t\tif (b.baseScore !== a.baseScore) {\n\t\t\t\treturn b.baseScore - a.baseScore;\n\t\t\t}\n\t\t\treturn a.item.id.localeCompare(b.item.id);\n\t\t});\n\t\tfor (let index = 1; index < group.length; index++) {\n\t\t\tconst duplicate = group[index];\n\t\t\tpenalties.set(duplicate.item.id, redundancyPenalty(duplicate.fullTokens) * index);\n\t\t}\n\t}\n\treturn penalties;\n}\n\nexport function compareOptionalForSelection(a: PlannedItemV2, b: PlannedItemV2): number {\n\tconst priorityDelta = priorityRank(b.item.priority) - priorityRank(a.item.priority);\n\tif (priorityDelta !== 0) {\n\t\treturn priorityDelta;\n\t}\n\tif (b.effectiveScore !== a.effectiveScore) {\n\t\treturn b.effectiveScore - a.effectiveScore;\n\t}\n\tconst aDensity = density(a);\n\tconst bDensity = density(b);\n\tif (bDensity !== aDensity) {\n\t\treturn bDensity - aDensity;\n\t}\n\tif (a.fullTokens !== b.fullTokens) {\n\t\treturn a.fullTokens - b.fullTokens;\n\t}\n\treturn a.item.id.localeCompare(b.item.id);\n}\n\nfunction priorityRank(priority: ContextBudgetPriorityV2): number {\n\tswitch (priority) {\n\t\tcase \"hard\":\n\t\t\treturn 4;\n\t\tcase \"high\":\n\t\t\treturn 3;\n\t\tcase \"medium\":\n\t\t\treturn 2;\n\t\tcase \"low\":\n\t\t\treturn 1;\n\t}\n}\n\nfunction clamp01(value: number | undefined): number {\n\tif (value === undefined || !Number.isFinite(value)) {\n\t\treturn 0;\n\t}\n\treturn Math.max(0, Math.min(1, value));\n}\n\nfunction deriveRecency(item: ContextBudgetItemV2): number {\n\tif (item.recency !== undefined) {\n\t\treturn clamp01(item.recency);\n\t}\n\tconst age = item.ageTurns ?? 0;\n\tconst halfLife = RECENCY_HALF_LIFE_BY_TIER[item.tier] ?? 6;\n\treturn clamp01(Math.exp(-age / halfLife));\n}\n\nfunction redundancyPenalty(tokens: number): number {\n\treturn Math.max(10, Math.sqrt(Math.max(0, tokens)) * 0.8);\n}\n\nfunction density(planned: PlannedItemV2): number {\n\tif (!Number.isFinite(planned.effectiveScore) || planned.effectiveScore <= 0) {\n\t\treturn planned.effectiveScore > 0 ? planned.effectiveScore : 0;\n\t}\n\treturn planned.effectiveScore / Math.max(planned.fullTokens, 1);\n}\n"]}
+{"version":3,"file":"context-budget-v2-scoring.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-scoring.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ContextBudgetItemV2, ContextBudgetPriorityV2, ContextBudgetTierV2 } from \"./context-budget-headroom.ts\";\n\nexport interface PlannedItemV2 {\n\treadonly item: ContextBudgetItemV2;\n\treadonly fullTokens: number;\n\t/**\n\t * Cheapest non-omit representation cost, i.e. the true marginal cost of\n\t * admitting this item at all. Equals `fullTokens` when the item has no\n\t * cheaper pointer/summary/headroom representation.\n\t */\n\treadonly admissibleTokens: number;\n\treadonly contentHash: string;\n\treadonly baseScore: number;\n\tredundancyPenalty: number;\n\teffectiveScore: number;\n\treadonly isHard: boolean;\n}\n\nconst PRIORITY_WEIGHT_V2: Record<ContextBudgetPriorityV2, number> = {\n\thard: 1_000_000,\n\thigh: 120,\n\tmedium: 60,\n\tlow: 15,\n};\n\nconst RECENCY_HALF_LIFE_BY_TIER: Readonly<Record<ContextBudgetTierV2, number>> = {\n\tsystem: 999,\n\t\"active-goal\": 12,\n\t\"current-files\": 8,\n\ttools: 4,\n\tskills: 6,\n\tmcp: 6,\n\thistory: 3,\n\tevidence: 8,\n\tscratch: 2,\n};\n\nexport function scoreContextBudgetItemV2(item: ContextBudgetItemV2, estimatedTokens: number): number {\n\tif (item.priority === \"hard\") {\n\t\treturn Number.POSITIVE_INFINITY;\n\t}\n\tconst priority = PRIORITY_WEIGHT_V2[item.priority];\n\tconst relevance = clamp01(item.relevance) * 25;\n\tconst recency = deriveRecency(item) * 15;\n\tconst evidence = clamp01(item.evidenceValue) * 25;\n\tconst cost = Math.sqrt(Math.max(0, estimatedTokens)) * 0.55;\n\treturn priority + relevance + recency + evidence - cost;\n}\n\nexport function applyRedundancyPenalties(items: readonly PlannedItemV2[]): Map<string, number> {\n\tconst penalties = new Map<string, number>();\n\tconst groups = new Map<string, PlannedItemV2[]>();\n\tfor (const planned of items) {\n\t\tif (!planned.item.redundancyKey) {\n\t\t\tcontinue;\n\t\t}\n\t\tconst group = groups.get(planned.item.redundancyKey);\n\t\tif (group) {\n\t\t\tgroup.push(planned);\n\t\t} else {\n\t\t\tgroups.set(planned.item.redundancyKey, [planned]);\n\t\t}\n\t}\n\tfor (const group of groups.values()) {\n\t\tif (group.length <= 1) {\n\t\t\tcontinue;\n\t\t}\n\t\tgroup.sort((a, b) => {\n\t\t\tif (b.baseScore !== a.baseScore) {\n\t\t\t\treturn b.baseScore - a.baseScore;\n\t\t\t}\n\t\t\treturn a.item.id.localeCompare(b.item.id);\n\t\t});\n\t\tfor (let index = 1; index < group.length; index++) {\n\t\t\tconst duplicate = group[index];\n\t\t\tpenalties.set(duplicate.item.id, redundancyPenalty(duplicate.fullTokens) * index);\n\t\t}\n\t}\n\treturn penalties;\n}\n\n/**\n * Order optional items for the budgeted 0/1 knapsack the planner greedily fills.\n *\n * Value density (effective score per token) is the primary key. Ordering by\n * priority class first would let a single expensive `high` item evict an\n * arbitrary number of far denser `medium` items, which makes the greedy\n * unbounded-bad against the optimal packing. Priority still shapes the outcome\n * through `PRIORITY_WEIGHT_V2` in the score numerator, and non-negotiable\n * context uses `hard`/`required`, which the planner pins before this ordering\n * is consulted. Remaining keys break ties into a deterministic total order.\n */\nexport function compareOptionalForSelection(a: PlannedItemV2, b: PlannedItemV2): number {\n\tconst aDensity = density(a);\n\tconst bDensity = density(b);\n\tif (bDensity !== aDensity) {\n\t\treturn bDensity - aDensity;\n\t}\n\tif (b.effectiveScore !== a.effectiveScore) {\n\t\treturn b.effectiveScore - a.effectiveScore;\n\t}\n\tconst priorityDelta = priorityRank(b.item.priority) - priorityRank(a.item.priority);\n\tif (priorityDelta !== 0) {\n\t\treturn priorityDelta;\n\t}\n\tif (a.fullTokens !== b.fullTokens) {\n\t\treturn a.fullTokens - b.fullTokens;\n\t}\n\treturn a.item.id.localeCompare(b.item.id);\n}\n\nfunction priorityRank(priority: ContextBudgetPriorityV2): number {\n\tswitch (priority) {\n\t\tcase \"hard\":\n\t\t\treturn 4;\n\t\tcase \"high\":\n\t\t\treturn 3;\n\t\tcase \"medium\":\n\t\t\treturn 2;\n\t\tcase \"low\":\n\t\t\treturn 1;\n\t}\n}\n\nfunction clamp01(value: number | undefined): number {\n\tif (value === undefined || !Number.isFinite(value)) {\n\t\treturn 0;\n\t}\n\treturn Math.max(0, Math.min(1, value));\n}\n\nfunction deriveRecency(item: ContextBudgetItemV2): number {\n\tif (item.recency !== undefined) {\n\t\treturn clamp01(item.recency);\n\t}\n\tconst age = item.ageTurns ?? 0;\n\tconst halfLife = RECENCY_HALF_LIFE_BY_TIER[item.tier] ?? 6;\n\treturn clamp01(Math.exp(-age / halfLife));\n}\n\nfunction redundancyPenalty(tokens: number): number {\n\treturn Math.max(10, Math.sqrt(Math.max(0, tokens)) * 0.8);\n}\n\n/**\n * Value per token of the CHEAPEST admissible representation. Dividing by\n * `fullTokens` would systematically penalize retrievable or summarizable items,\n * which are exactly the items the planner admits cheaply when the budget is\n * tight — the regime where this ordering decides anything at all.\n */\nfunction density(planned: PlannedItemV2): number {\n\tif (!Number.isFinite(planned.effectiveScore) || planned.effectiveScore <= 0) {\n\t\treturn planned.effectiveScore > 0 ? planned.effectiveScore : 0;\n\t}\n\treturn planned.effectiveScore / Math.max(planned.admissibleTokens, 1);\n}\n"]}

package/dist/core/context-budget-v2-selection.d.ts

@@ -1,4 +1,4 @@
-import { type ContextBudgetItemV2, type ContextBudgetTierV2, type ContextSourceRefV2, chooseHeadroomRepresentation } from "./context-budget-headroom.ts";
+import { type ContextBudgetItemV2, type ContextBudgetTierV2, type ContextSourceRefV2, chooseHeadroomRepresentation, deriveRepresentationCandidates } from "./context-budget-headroom.ts";
 import { type TokenCounterAdapter } from "./context-budget-token-counter.ts";
 import { type ContextBudgetSelectionCacheV2 } from "./context-budget-v2-cache.ts";
 import { type PlannedItemV2 } from "./context-budget-v2-scoring.ts";
@@ -17,7 +17,7 @@ export interface OptionalSelectionState {
     readonly tierUsed: Record<ContextBudgetTierV2, number>;
     readonly usedTokens: number;
 }
-export declare function createPlannedItems(items: readonly ContextBudgetItemV2[], tokenCounter: TokenCounterAdapter | undefined, modelId: string): PlannedItemV2[];
+export declare function createPlannedItems(items: readonly ContextBudgetItemV2[], tokenCounter: TokenCounterAdapter | undefined, modelId: string, qualityPolicy?: Parameters<typeof deriveRepresentationCandidates>[1]): PlannedItemV2[];
 export declare function applyPlannerRedundancyPenalties(plannedItems: PlannedItemV2[]): void;
 export declare function selectHardItem(planned: PlannedItemV2, selection: Map<string, SelectedRepresentationV2>, tierUsed: Record<ContextBudgetTierV2, number>): number;
 export declare function selectOptionalItem(planned: PlannedItemV2, state: OptionalSelectionState): number;

package/dist/core/context-budget-v2-selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-v2-selection.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-selection.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EAExB,KAAK,kBAAkB,EACvB,4BAA4B,EAG5B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAA8B,KAAK,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACzG,OAAO,EAEN,KAAK,6BAA6B,EAElC,MAAM,8BAA8B,CAAC;AAItC,OAAO,EAA4B,KAAK,aAAa,EAA4B,MAAM,gCAAgC,CAAC;AACxH,OAAO,EAEN,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,MAAM,8BAA8B,CAAC;AAEtC,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,mBAAmB,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,6BAA6B,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,mBAAmB,EAAE,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,mBAAmB,EAAE,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC,OAAO,4BAA4B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,EAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,SAAS,mBAAmB,EAAE,EACrC,YAAY,EAAE,mBAAmB,GAAG,SAAS,EAC7C,OAAO,EAAE,MAAM,GACb,aAAa,EAAE,CAmBjB;AAED,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,aAAa,EAAE,GAAG,IAAI,CAQnF;AAED,wBAAgB,cAAc,CAC7B,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAChD,QAAQ,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,GAC3C,MAAM,CAWR;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,sBAAsB,GAAG,MAAM,CAiEhG;AAED,wBAAgB,uBAAuB,CACtC,OAAO,EAAE,SAAS,mBAAmB,EAAE,EACvC,WAAW,EAAE,mBAAmB,EAAE,EAClC,kBAAkB,EAAE,kBAAkB,EAAE,GACtC,IAAI,CAkBN;AAED,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,EACxD,WAAW,EAAE,mBAAmB,EAAE,GAChC,IAAI,CAUN;AAED,wBAAgB,oBAAoB,CACnC,UAAU,EAAE,WAAW,CACtB,mBAAmB,EACnB;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAChF,EACD,MAAM,EAAE,WAAW,CAAC,mBAAmB,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACnE,QAAQ,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,GAC3C,sBAAsB,EAAE,CAY1B;AAED,wBAAgB,eAAe,IAAI,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAYrE","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextRepresentationCandidateV2,\n\ttype ContextSourceRefV2,\n\tchooseHeadroomRepresentation,\n\tderiveRepresentationCandidates,\n\tfullTextTokens,\n} from \"./context-budget-headroom.ts\";\nimport { createFallbackTokenCounter, type TokenCounterAdapter } from \"./context-budget-token-counter.ts\";\nimport {\n\tapplyRepresentationCacheV2,\n\ttype ContextBudgetSelectionCacheV2,\n\twriteRepresentationCacheV2,\n} from \"./context-budget-v2-cache.ts\";\nimport { recordContextBudgetRepresentationCacheHitV2 } from \"./context-budget-v2-cache-telemetry.ts\";\nimport { computeCoverageGap } from \"./context-budget-v2-coverage.ts\";\nimport { contentHashOf } from \"./context-budget-v2-plan-hash.ts\";\nimport { applyRedundancyPenalties, type PlannedItemV2, scoreContextBudgetItemV2 } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tALL_TIERS_V2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetAllocationV2,\n} from \"./context-budget-v2-types.ts\";\n\nexport interface OptionalSelectionState {\n\treadonly allocation: ReadonlyMap<ContextBudgetTierV2, { readonly ceiling: number }>;\n\treadonly available: number;\n\treadonly cache?: ContextBudgetSelectionCacheV2;\n\treadonly diagnostics: QualityDiagnosticV2[];\n\treadonly omitted: ContextBudgetItemV2[];\n\treadonly qualityPolicy: Parameters<typeof chooseHeadroomRepresentation>[2];\n\treadonly retrievalFallbacks: ContextSourceRefV2[];\n\treadonly selection: Map<string, SelectedRepresentationV2>;\n\treadonly tierUsed: Record<ContextBudgetTierV2, number>;\n\treadonly usedTokens: number;\n}\n\nexport function createPlannedItems(\n\titems: readonly ContextBudgetItemV2[],\n\ttokenCounter: TokenCounterAdapter | undefined,\n\tmodelId: string,\n): PlannedItemV2[] {\n\tconst counter = tokenCounter ?? createFallbackTokenCounter();\n\treturn items.map((item) => {\n\t\tconst overrideTokenEstimate = item.tokenEstimate ?? counter.countText(item.text, modelId).tokens;\n\t\tconst itemWithTokens =\n\t\t\titem.tokenEstimate === undefined ? { ...item, tokenEstimate: overrideTokenEstimate } : item;\n\t\tconst fullTokens = fullTextTokens(itemWithTokens);\n\t\tconst isHard = item.priority === \"hard\" || item.required === true;\n\t\tconst baseScore = isHard ? Number.POSITIVE_INFINITY : scoreContextBudgetItemV2(itemWithTokens, fullTokens);\n\t\treturn {\n\t\t\titem: itemWithTokens,\n\t\t\tfullTokens,\n\t\t\tcontentHash: contentHashOf(item.text),\n\t\t\tbaseScore,\n\t\t\tredundancyPenalty: 0,\n\t\t\teffectiveScore: baseScore,\n\t\t\tisHard,\n\t\t};\n\t});\n}\n\nexport function applyPlannerRedundancyPenalties(plannedItems: PlannedItemV2[]): void {\n\tconst penalties = applyRedundancyPenalties(plannedItems.filter((planned) => !planned.isHard));\n\tfor (const planned of plannedItems) {\n\t\tconst penalty = penalties.get(planned.item.id);\n\t\tif (penalty === undefined) continue;\n\t\tplanned.redundancyPenalty = penalty;\n\t\tplanned.effectiveScore = planned.baseScore - penalty;\n\t}\n}\n\nexport function selectHardItem(\n\tplanned: PlannedItemV2,\n\tselection: Map<string, SelectedRepresentationV2>,\n\ttierUsed: Record<ContextBudgetTierV2, number>,\n): number {\n\tconst candidate: ContextRepresentationCandidateV2 = {\n\t\tkind: \"full\",\n\t\ttext: planned.item.text,\n\t\testimatedTokens: planned.fullTokens,\n\t\tfidelity: planned.item.tokenEstimate !== undefined ? \"exact\" : \"bounded\",\n\t\tsourceRef: planned.item.sourceRef,\n\t};\n\tselection.set(planned.item.id, toSelected(planned.item.id, candidate));\n\ttierUsed[planned.item.tier] += planned.fullTokens;\n\treturn planned.fullTokens;\n}\n\nexport function selectOptionalItem(planned: PlannedItemV2, state: OptionalSelectionState): number {\n\tif (state.usedTokens >= state.available) {\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tconst tierCeiling = state.allocation.get(planned.item.tier)?.ceiling ?? state.available;\n\tconst remaining = Math.max(0, state.available - state.usedTokens);\n\tconst candidates = planned.item.representations ?? deriveRepresentationCandidates(planned.item, state.qualityPolicy);\n\tconst materializedEnabled = planned.item.representations === undefined;\n\tconst cachedCandidates = state.cache\n\t\t? applyRepresentationCacheV2({ planned, candidates, cache: state.cache, materializedEnabled })\n\t\t: candidates;\n\tconst chosen = chooseHeadroomRepresentation(\n\t\t{ ...planned.item, representations: cachedCandidates },\n\t\t{\n\t\t\ttierUsedTokens: state.tierUsed[planned.item.tier],\n\t\t\ttierCeilingTokens: tierCeiling,\n\t\t\tremainingGlobalTokens: remaining,\n\t\t},\n\t\tstate.qualityPolicy,\n\t);\n\tif (chosen.kind === \"omit\") {\n\t\tconst tierRemaining = Math.max(0, tierCeiling - state.tierUsed[planned.item.tier]);\n\t\tconst globalFit = cachedCandidates.filter(\n\t\t\t(candidate) => candidate.kind !== \"omit\" && candidate.estimatedTokens <= remaining,\n\t\t);\n\t\tif (globalFit.length > 0 && globalFit.every((candidate) => candidate.estimatedTokens > tierRemaining)) {\n\t\t\tstate.diagnostics.push({\n\t\t\t\treason: \"tier_ceiling_exceeded\",\n\t\t\t\titemId: planned.item.id,\n\t\t\t\tdetail: `${planned.item.tier} item \"${planned.item.id}\" needs ${Math.min(\n\t\t\t\t\t...globalFit.map((candidate) => candidate.estimatedTokens),\n\t\t\t\t)} tokens with ${tierRemaining} tier tokens remaining`,\n\t\t\t});\n\t\t}\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tif (state.tierUsed[planned.item.tier] + chosen.estimatedTokens > tierCeiling) {\n\t\tstate.diagnostics.push({\n\t\t\treason: \"tier_ceiling_exceeded\",\n\t\t\titemId: planned.item.id,\n\t\t\tdetail: `${planned.item.tier} item \"${planned.item.id}\" needs ${chosen.estimatedTokens} tokens with ${Math.max(0, tierCeiling - state.tierUsed[planned.item.tier])} tier tokens remaining`,\n\t\t});\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tif (state.usedTokens + chosen.estimatedTokens > state.available) {\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tif (state.cache) {\n\t\tif (chosen.cache?.hit === true) {\n\t\t\trecordContextBudgetRepresentationCacheHitV2(\n\t\t\t\tstate.cache.telemetry,\n\t\t\t\tchosen.kind,\n\t\t\t\tchosen.cache.keyKind,\n\t\t\t\tplanned.fullTokens,\n\t\t\t);\n\t\t}\n\t\twriteRepresentationCacheV2({ planned, selected: chosen, cache: state.cache, materializedEnabled });\n\t}\n\tstate.selection.set(planned.item.id, toSelected(planned.item.id, chosen));\n\tstate.tierUsed[planned.item.tier] += chosen.estimatedTokens;\n\treturn state.usedTokens + chosen.estimatedTokens;\n}\n\nexport function emitOmissionDiagnostics(\n\tomitted: readonly ContextBudgetItemV2[],\n\tdiagnostics: QualityDiagnosticV2[],\n\tretrievalFallbacks: ContextSourceRefV2[],\n): void {\n\tfor (const item of omitted) {\n\t\tif (item.priority === \"high\" || item.required === true) {\n\t\t\tdiagnostics.push({\n\t\t\t\treason: \"omitted_high_priority\",\n\t\t\t\titemId: item.id,\n\t\t\t\tdetail: `${item.tier} item \"${item.id}\" could not fit within the prompt budget`,\n\t\t\t});\n\t\t}\n\t\tif (item.sourceRef?.retrievable) {\n\t\t\tdiagnostics.push({\n\t\t\t\treason: \"restore_on_demand_hint\",\n\t\t\t\titemId: item.id,\n\t\t\t\tdetail: `retrievable \"${item.id}\" kept as fallback via ${item.sourceRef.uri}`,\n\t\t\t});\n\t\t\tretrievalFallbacks.push(item.sourceRef);\n\t\t}\n\t}\n}\n\nexport function emitCoverageDiagnostics(\n\tquery: string | undefined,\n\tselection: ReadonlyMap<string, SelectedRepresentationV2>,\n\tdiagnostics: QualityDiagnosticV2[],\n): void {\n\tconst coverage = computeCoverageGap(\n\t\tquery,\n\t\t[...selection.values()].map((representation) => representation.text),\n\t);\n\tif (!coverage.gap) return;\n\tdiagnostics.push({\n\t\treason: \"coverage_gap\",\n\t\tdetail: `query terms not covered by selected context: ${coverage.missing.join(\", \")}`,\n\t});\n}\n\nexport function buildTierAllocations(\n\tallocation: ReadonlyMap<\n\t\tContextBudgetTierV2,\n\t\t{ readonly floor: number; readonly ceiling: number; readonly allocated: number }\n\t>,\n\tdemand: ReadonlyMap<ContextBudgetTierV2, { readonly hard: number }>,\n\ttierUsed: Record<ContextBudgetTierV2, number>,\n): TierBudgetAllocationV2[] {\n\treturn ALL_TIERS_V2.map((tier) => {\n\t\tconst raw = allocation.get(tier) ?? { floor: 0, ceiling: 0, allocated: 0 };\n\t\treturn {\n\t\t\ttier,\n\t\t\tfloorTokens: raw.floor,\n\t\t\tceilingTokens: raw.ceiling,\n\t\t\tallocatedTokens: raw.allocated,\n\t\t\tusedTokens: tierUsed[tier],\n\t\t\thardTokens: demand.get(tier)?.hard ?? 0,\n\t\t};\n\t});\n}\n\nexport function createTierUsage(): Record<ContextBudgetTierV2, number> {\n\treturn {\n\t\tsystem: 0,\n\t\t\"active-goal\": 0,\n\t\t\"current-files\": 0,\n\t\ttools: 0,\n\t\tskills: 0,\n\t\tmcp: 0,\n\t\thistory: 0,\n\t\tevidence: 0,\n\t\tscratch: 0,\n\t};\n}\n\nfunction toSelected(itemId: string, candidate: ContextRepresentationCandidateV2): SelectedRepresentationV2 {\n\treturn {\n\t\titemId,\n\t\tkind: candidate.kind,\n\t\ttext: candidate.text,\n\t\testimatedTokens: candidate.estimatedTokens,\n\t\tfidelity: candidate.fidelity,\n\t\tsourceRef: candidate.sourceRef,\n\t\tsummaryHash: candidate.summaryHash,\n\t\tcompressorId: candidate.compressorId,\n\t\tcache: candidate.cache,\n\t};\n}\n\nfunction omitItem(\n\tplanned: PlannedItemV2,\n\tstate: Pick<OptionalSelectionState, \"diagnostics\" | \"omitted\" | \"retrievalFallbacks\">,\n): void {\n\tstate.omitted.push(planned.item);\n\tif (planned.item.sourceRef?.retrievable) {\n\t\tstate.diagnostics.push({\n\t\t\treason: \"retrieval_miss_risk\",\n\t\t\titemId: planned.item.id,\n\t\t\tdetail: `retrievable ${planned.item.tier} item \"${planned.item.id}\" omitted; keep pointer for restore-on-demand`,\n\t\t});\n\t\tstate.retrievalFallbacks.push(planned.item.sourceRef);\n\t}\n}\n"]}
+{"version":3,"file":"context-budget-v2-selection.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-selection.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EAExB,KAAK,kBAAkB,EACvB,4BAA4B,EAC5B,8BAA8B,EAE9B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAA8B,KAAK,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACzG,OAAO,EAEN,KAAK,6BAA6B,EAElC,MAAM,8BAA8B,CAAC;AAItC,OAAO,EAA4B,KAAK,aAAa,EAA4B,MAAM,gCAAgC,CAAC;AACxH,OAAO,EAEN,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,MAAM,8BAA8B,CAAC;AAEtC,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,mBAAmB,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,6BAA6B,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,mBAAmB,EAAE,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,mBAAmB,EAAE,CAAC;IACxC,QAAQ,CAAC,aAAa,EAAE,UAAU,CAAC,OAAO,4BAA4B,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E,QAAQ,CAAC,kBAAkB,EAAE,kBAAkB,EAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IAC1D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAAC;IACvD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC5B;AAgBD,wBAAgB,kBAAkB,CACjC,KAAK,EAAE,SAAS,mBAAmB,EAAE,EACrC,YAAY,EAAE,mBAAmB,GAAG,SAAS,EAC7C,OAAO,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,UAAU,CAAC,OAAO,8BAA8B,CAAC,CAAC,CAAC,CAAC,GAClE,aAAa,EAAE,CAsBjB;AAED,wBAAgB,+BAA+B,CAAC,YAAY,EAAE,aAAa,EAAE,GAAG,IAAI,CAQnF;AAED,wBAAgB,cAAc,CAC7B,OAAO,EAAE,aAAa,EACtB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,EAChD,QAAQ,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,GAC3C,MAAM,CAWR;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,sBAAsB,GAAG,MAAM,CAiEhG;AAED,wBAAgB,uBAAuB,CACtC,OAAO,EAAE,SAAS,mBAAmB,EAAE,EACvC,WAAW,EAAE,mBAAmB,EAAE,EAClC,kBAAkB,EAAE,kBAAkB,EAAE,GACtC,IAAI,CAkBN;AAED,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,EACxD,WAAW,EAAE,mBAAmB,EAAE,GAChC,IAAI,CAUN;AAED,wBAAgB,oBAAoB,CACnC,UAAU,EAAE,WAAW,CACtB,mBAAmB,EACnB;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAChF,EACD,MAAM,EAAE,WAAW,CAAC,mBAAmB,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACnE,QAAQ,EAAE,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,GAC3C,sBAAsB,EAAE,CAY1B;AAED,wBAAgB,eAAe,IAAI,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAYrE","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextRepresentationCandidateV2,\n\ttype ContextSourceRefV2,\n\tchooseHeadroomRepresentation,\n\tderiveRepresentationCandidates,\n\tfullTextTokens,\n} from \"./context-budget-headroom.ts\";\nimport { createFallbackTokenCounter, type TokenCounterAdapter } from \"./context-budget-token-counter.ts\";\nimport {\n\tapplyRepresentationCacheV2,\n\ttype ContextBudgetSelectionCacheV2,\n\twriteRepresentationCacheV2,\n} from \"./context-budget-v2-cache.ts\";\nimport { recordContextBudgetRepresentationCacheHitV2 } from \"./context-budget-v2-cache-telemetry.ts\";\nimport { computeCoverageGap } from \"./context-budget-v2-coverage.ts\";\nimport { contentHashOf } from \"./context-budget-v2-plan-hash.ts\";\nimport { applyRedundancyPenalties, type PlannedItemV2, scoreContextBudgetItemV2 } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tALL_TIERS_V2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetAllocationV2,\n} from \"./context-budget-v2-types.ts\";\n\nexport interface OptionalSelectionState {\n\treadonly allocation: ReadonlyMap<ContextBudgetTierV2, { readonly ceiling: number }>;\n\treadonly available: number;\n\treadonly cache?: ContextBudgetSelectionCacheV2;\n\treadonly diagnostics: QualityDiagnosticV2[];\n\treadonly omitted: ContextBudgetItemV2[];\n\treadonly qualityPolicy: Parameters<typeof chooseHeadroomRepresentation>[2];\n\treadonly retrievalFallbacks: ContextSourceRefV2[];\n\treadonly selection: Map<string, SelectedRepresentationV2>;\n\treadonly tierUsed: Record<ContextBudgetTierV2, number>;\n\treadonly usedTokens: number;\n}\n\n/**\n * Cheapest non-omit representation cost for an item, i.e. what admitting it\n * actually costs when the budget is tight. Falls back to full text when no\n * cheaper representation exists.\n */\nfunction minAdmissibleTokens(candidates: readonly ContextRepresentationCandidateV2[], fullTokens: number): number {\n\tlet min = Number.POSITIVE_INFINITY;\n\tfor (const candidate of candidates) {\n\t\tif (candidate.kind === \"omit\") continue;\n\t\tif (candidate.estimatedTokens < min) min = candidate.estimatedTokens;\n\t}\n\treturn Math.max(1, Number.isFinite(min) ? min : fullTokens);\n}\n\nexport function createPlannedItems(\n\titems: readonly ContextBudgetItemV2[],\n\ttokenCounter: TokenCounterAdapter | undefined,\n\tmodelId: string,\n\tqualityPolicy?: Parameters<typeof deriveRepresentationCandidates>[1],\n): PlannedItemV2[] {\n\tconst counter = tokenCounter ?? createFallbackTokenCounter();\n\treturn items.map((item) => {\n\t\tconst overrideTokenEstimate = item.tokenEstimate ?? counter.countText(item.text, modelId).tokens;\n\t\tconst itemWithTokens =\n\t\t\titem.tokenEstimate === undefined ? { ...item, tokenEstimate: overrideTokenEstimate } : item;\n\t\tconst fullTokens = fullTextTokens(itemWithTokens);\n\t\tconst isHard = item.priority === \"hard\" || item.required === true;\n\t\tconst baseScore = isHard ? Number.POSITIVE_INFINITY : scoreContextBudgetItemV2(itemWithTokens, fullTokens);\n\t\tconst candidates =\n\t\t\titemWithTokens.representations ?? deriveRepresentationCandidates(itemWithTokens, qualityPolicy);\n\t\treturn {\n\t\t\titem: itemWithTokens,\n\t\t\tfullTokens,\n\t\t\tadmissibleTokens: minAdmissibleTokens(candidates, fullTokens),\n\t\t\tcontentHash: contentHashOf(item.text),\n\t\t\tbaseScore,\n\t\t\tredundancyPenalty: 0,\n\t\t\teffectiveScore: baseScore,\n\t\t\tisHard,\n\t\t};\n\t});\n}\n\nexport function applyPlannerRedundancyPenalties(plannedItems: PlannedItemV2[]): void {\n\tconst penalties = applyRedundancyPenalties(plannedItems.filter((planned) => !planned.isHard));\n\tfor (const planned of plannedItems) {\n\t\tconst penalty = penalties.get(planned.item.id);\n\t\tif (penalty === undefined) continue;\n\t\tplanned.redundancyPenalty = penalty;\n\t\tplanned.effectiveScore = planned.baseScore - penalty;\n\t}\n}\n\nexport function selectHardItem(\n\tplanned: PlannedItemV2,\n\tselection: Map<string, SelectedRepresentationV2>,\n\ttierUsed: Record<ContextBudgetTierV2, number>,\n): number {\n\tconst candidate: ContextRepresentationCandidateV2 = {\n\t\tkind: \"full\",\n\t\ttext: planned.item.text,\n\t\testimatedTokens: planned.fullTokens,\n\t\tfidelity: planned.item.tokenEstimate !== undefined ? \"exact\" : \"bounded\",\n\t\tsourceRef: planned.item.sourceRef,\n\t};\n\tselection.set(planned.item.id, toSelected(planned.item.id, candidate));\n\ttierUsed[planned.item.tier] += planned.fullTokens;\n\treturn planned.fullTokens;\n}\n\nexport function selectOptionalItem(planned: PlannedItemV2, state: OptionalSelectionState): number {\n\tif (state.usedTokens >= state.available) {\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tconst tierCeiling = state.allocation.get(planned.item.tier)?.ceiling ?? state.available;\n\tconst remaining = Math.max(0, state.available - state.usedTokens);\n\tconst candidates = planned.item.representations ?? deriveRepresentationCandidates(planned.item, state.qualityPolicy);\n\tconst materializedEnabled = planned.item.representations === undefined;\n\tconst cachedCandidates = state.cache\n\t\t? applyRepresentationCacheV2({ planned, candidates, cache: state.cache, materializedEnabled })\n\t\t: candidates;\n\tconst chosen = chooseHeadroomRepresentation(\n\t\t{ ...planned.item, representations: cachedCandidates },\n\t\t{\n\t\t\ttierUsedTokens: state.tierUsed[planned.item.tier],\n\t\t\ttierCeilingTokens: tierCeiling,\n\t\t\tremainingGlobalTokens: remaining,\n\t\t},\n\t\tstate.qualityPolicy,\n\t);\n\tif (chosen.kind === \"omit\") {\n\t\tconst tierRemaining = Math.max(0, tierCeiling - state.tierUsed[planned.item.tier]);\n\t\tconst globalFit = cachedCandidates.filter(\n\t\t\t(candidate) => candidate.kind !== \"omit\" && candidate.estimatedTokens <= remaining,\n\t\t);\n\t\tif (globalFit.length > 0 && globalFit.every((candidate) => candidate.estimatedTokens > tierRemaining)) {\n\t\t\tstate.diagnostics.push({\n\t\t\t\treason: \"tier_ceiling_exceeded\",\n\t\t\t\titemId: planned.item.id,\n\t\t\t\tdetail: `${planned.item.tier} item \"${planned.item.id}\" needs ${Math.min(\n\t\t\t\t\t...globalFit.map((candidate) => candidate.estimatedTokens),\n\t\t\t\t)} tokens with ${tierRemaining} tier tokens remaining`,\n\t\t\t});\n\t\t}\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tif (state.tierUsed[planned.item.tier] + chosen.estimatedTokens > tierCeiling) {\n\t\tstate.diagnostics.push({\n\t\t\treason: \"tier_ceiling_exceeded\",\n\t\t\titemId: planned.item.id,\n\t\t\tdetail: `${planned.item.tier} item \"${planned.item.id}\" needs ${chosen.estimatedTokens} tokens with ${Math.max(0, tierCeiling - state.tierUsed[planned.item.tier])} tier tokens remaining`,\n\t\t});\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tif (state.usedTokens + chosen.estimatedTokens > state.available) {\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tif (state.cache) {\n\t\tif (chosen.cache?.hit === true) {\n\t\t\trecordContextBudgetRepresentationCacheHitV2(\n\t\t\t\tstate.cache.telemetry,\n\t\t\t\tchosen.kind,\n\t\t\t\tchosen.cache.keyKind,\n\t\t\t\tplanned.fullTokens,\n\t\t\t);\n\t\t}\n\t\twriteRepresentationCacheV2({ planned, selected: chosen, cache: state.cache, materializedEnabled });\n\t}\n\tstate.selection.set(planned.item.id, toSelected(planned.item.id, chosen));\n\tstate.tierUsed[planned.item.tier] += chosen.estimatedTokens;\n\treturn state.usedTokens + chosen.estimatedTokens;\n}\n\nexport function emitOmissionDiagnostics(\n\tomitted: readonly ContextBudgetItemV2[],\n\tdiagnostics: QualityDiagnosticV2[],\n\tretrievalFallbacks: ContextSourceRefV2[],\n): void {\n\tfor (const item of omitted) {\n\t\tif (item.priority === \"high\" || item.required === true) {\n\t\t\tdiagnostics.push({\n\t\t\t\treason: \"omitted_high_priority\",\n\t\t\t\titemId: item.id,\n\t\t\t\tdetail: `${item.tier} item \"${item.id}\" could not fit within the prompt budget`,\n\t\t\t});\n\t\t}\n\t\tif (item.sourceRef?.retrievable) {\n\t\t\tdiagnostics.push({\n\t\t\t\treason: \"restore_on_demand_hint\",\n\t\t\t\titemId: item.id,\n\t\t\t\tdetail: `retrievable \"${item.id}\" kept as fallback via ${item.sourceRef.uri}`,\n\t\t\t});\n\t\t\tretrievalFallbacks.push(item.sourceRef);\n\t\t}\n\t}\n}\n\nexport function emitCoverageDiagnostics(\n\tquery: string | undefined,\n\tselection: ReadonlyMap<string, SelectedRepresentationV2>,\n\tdiagnostics: QualityDiagnosticV2[],\n): void {\n\tconst coverage = computeCoverageGap(\n\t\tquery,\n\t\t[...selection.values()].map((representation) => representation.text),\n\t);\n\tif (!coverage.gap) return;\n\tdiagnostics.push({\n\t\treason: \"coverage_gap\",\n\t\tdetail: `query terms not covered by selected context: ${coverage.missing.join(\", \")}`,\n\t});\n}\n\nexport function buildTierAllocations(\n\tallocation: ReadonlyMap<\n\t\tContextBudgetTierV2,\n\t\t{ readonly floor: number; readonly ceiling: number; readonly allocated: number }\n\t>,\n\tdemand: ReadonlyMap<ContextBudgetTierV2, { readonly hard: number }>,\n\ttierUsed: Record<ContextBudgetTierV2, number>,\n): TierBudgetAllocationV2[] {\n\treturn ALL_TIERS_V2.map((tier) => {\n\t\tconst raw = allocation.get(tier) ?? { floor: 0, ceiling: 0, allocated: 0 };\n\t\treturn {\n\t\t\ttier,\n\t\t\tfloorTokens: raw.floor,\n\t\t\tceilingTokens: raw.ceiling,\n\t\t\tallocatedTokens: raw.allocated,\n\t\t\tusedTokens: tierUsed[tier],\n\t\t\thardTokens: demand.get(tier)?.hard ?? 0,\n\t\t};\n\t});\n}\n\nexport function createTierUsage(): Record<ContextBudgetTierV2, number> {\n\treturn {\n\t\tsystem: 0,\n\t\t\"active-goal\": 0,\n\t\t\"current-files\": 0,\n\t\ttools: 0,\n\t\tskills: 0,\n\t\tmcp: 0,\n\t\thistory: 0,\n\t\tevidence: 0,\n\t\tscratch: 0,\n\t};\n}\n\nfunction toSelected(itemId: string, candidate: ContextRepresentationCandidateV2): SelectedRepresentationV2 {\n\treturn {\n\t\titemId,\n\t\tkind: candidate.kind,\n\t\ttext: candidate.text,\n\t\testimatedTokens: candidate.estimatedTokens,\n\t\tfidelity: candidate.fidelity,\n\t\tsourceRef: candidate.sourceRef,\n\t\tsummaryHash: candidate.summaryHash,\n\t\tcompressorId: candidate.compressorId,\n\t\tcache: candidate.cache,\n\t};\n}\n\nfunction omitItem(\n\tplanned: PlannedItemV2,\n\tstate: Pick<OptionalSelectionState, \"diagnostics\" | \"omitted\" | \"retrievalFallbacks\">,\n): void {\n\tstate.omitted.push(planned.item);\n\tif (planned.item.sourceRef?.retrievable) {\n\t\tstate.diagnostics.push({\n\t\t\treason: \"retrieval_miss_risk\",\n\t\t\titemId: planned.item.id,\n\t\t\tdetail: `retrievable ${planned.item.tier} item \"${planned.item.id}\" omitted; keep pointer for restore-on-demand`,\n\t\t});\n\t\tstate.retrievalFallbacks.push(planned.item.sourceRef);\n\t}\n}\n"]}

package/dist/core/context-budget-v2-selection.js

@@ -6,7 +6,22 @@ import { computeCoverageGap } from "./context-budget-v2-coverage.js";
 import { contentHashOf } from "./context-budget-v2-plan-hash.js";
 import { applyRedundancyPenalties, scoreContextBudgetItemV2 } from "./context-budget-v2-scoring.js";
 import { ALL_TIERS_V2, } from "./context-budget-v2-types.js";
-export function createPlannedItems(items, tokenCounter, modelId) {
+/**
+ * Cheapest non-omit representation cost for an item, i.e. what admitting it
+ * actually costs when the budget is tight. Falls back to full text when no
+ * cheaper representation exists.
+ */
+function minAdmissibleTokens(candidates, fullTokens) {
+    let min = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        if (candidate.kind === "omit")
+            continue;
+        if (candidate.estimatedTokens < min)
+            min = candidate.estimatedTokens;
+    }
+    return Math.max(1, Number.isFinite(min) ? min : fullTokens);
+}
+export function createPlannedItems(items, tokenCounter, modelId, qualityPolicy) {
     const counter = tokenCounter ?? createFallbackTokenCounter();
     return items.map((item) => {
         const overrideTokenEstimate = item.tokenEstimate ?? counter.countText(item.text, modelId).tokens;
@@ -14,9 +29,11 @@ export function createPlannedItems(items, tokenCounter, modelId) {
         const fullTokens = fullTextTokens(itemWithTokens);
         const isHard = item.priority === "hard" || item.required === true;
         const baseScore = isHard ? Number.POSITIVE_INFINITY : scoreContextBudgetItemV2(itemWithTokens, fullTokens);
+        const candidates = itemWithTokens.representations ?? deriveRepresentationCandidates(itemWithTokens, qualityPolicy);
         return {
             item: itemWithTokens,
             fullTokens,
+            admissibleTokens: minAdmissibleTokens(candidates, fullTokens),
             contentHash: contentHashOf(item.text),
             baseScore,
             redundancyPenalty: 0,

package/dist/core/context-budget-v2-selection.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-v2-selection.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-selection.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextRepresentationCandidateV2,\n\ttype ContextSourceRefV2,\n\tchooseHeadroomRepresentation,\n\tderiveRepresentationCandidates,\n\tfullTextTokens,\n} from \"./context-budget-headroom.ts\";\nimport { createFallbackTokenCounter, type TokenCounterAdapter } from \"./context-budget-token-counter.ts\";\nimport {\n\tapplyRepresentationCacheV2,\n\ttype ContextBudgetSelectionCacheV2,\n\twriteRepresentationCacheV2,\n} from \"./context-budget-v2-cache.ts\";\nimport { recordContextBudgetRepresentationCacheHitV2 } from \"./context-budget-v2-cache-telemetry.ts\";\nimport { computeCoverageGap } from \"./context-budget-v2-coverage.ts\";\nimport { contentHashOf } from \"./context-budget-v2-plan-hash.ts\";\nimport { applyRedundancyPenalties, type PlannedItemV2, scoreContextBudgetItemV2 } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tALL_TIERS_V2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetAllocationV2,\n} from \"./context-budget-v2-types.ts\";\n\nexport interface OptionalSelectionState {\n\treadonly allocation: ReadonlyMap<ContextBudgetTierV2, { readonly ceiling: number }>;\n\treadonly available: number;\n\treadonly cache?: ContextBudgetSelectionCacheV2;\n\treadonly diagnostics: QualityDiagnosticV2[];\n\treadonly omitted: ContextBudgetItemV2[];\n\treadonly qualityPolicy: Parameters<typeof chooseHeadroomRepresentation>[2];\n\treadonly retrievalFallbacks: ContextSourceRefV2[];\n\treadonly selection: Map<string, SelectedRepresentationV2>;\n\treadonly tierUsed: Record<ContextBudgetTierV2, number>;\n\treadonly usedTokens: number;\n}\n\nexport function createPlannedItems(\n\titems: readonly ContextBudgetItemV2[],\n\ttokenCounter: TokenCounterAdapter | undefined,\n\tmodelId: string,\n): PlannedItemV2[] {\n\tconst counter = tokenCounter ?? createFallbackTokenCounter();\n\treturn items.map((item) => {\n\t\tconst overrideTokenEstimate = item.tokenEstimate ?? counter.countText(item.text, modelId).tokens;\n\t\tconst itemWithTokens =\n\t\t\titem.tokenEstimate === undefined ? { ...item, tokenEstimate: overrideTokenEstimate } : item;\n\t\tconst fullTokens = fullTextTokens(itemWithTokens);\n\t\tconst isHard = item.priority === \"hard\" || item.required === true;\n\t\tconst baseScore = isHard ? Number.POSITIVE_INFINITY : scoreContextBudgetItemV2(itemWithTokens, fullTokens);\n\t\treturn {\n\t\t\titem: itemWithTokens,\n\t\t\tfullTokens,\n\t\t\tcontentHash: contentHashOf(item.text),\n\t\t\tbaseScore,\n\t\t\tredundancyPenalty: 0,\n\t\t\teffectiveScore: baseScore,\n\t\t\tisHard,\n\t\t};\n\t});\n}\n\nexport function applyPlannerRedundancyPenalties(plannedItems: PlannedItemV2[]): void {\n\tconst penalties = applyRedundancyPenalties(plannedItems.filter((planned) => !planned.isHard));\n\tfor (const planned of plannedItems) {\n\t\tconst penalty = penalties.get(planned.item.id);\n\t\tif (penalty === undefined) continue;\n\t\tplanned.redundancyPenalty = penalty;\n\t\tplanned.effectiveScore = planned.baseScore - penalty;\n\t}\n}\n\nexport function selectHardItem(\n\tplanned: PlannedItemV2,\n\tselection: Map<string, SelectedRepresentationV2>,\n\ttierUsed: Record<ContextBudgetTierV2, number>,\n): number {\n\tconst candidate: ContextRepresentationCandidateV2 = {\n\t\tkind: \"full\",\n\t\ttext: planned.item.text,\n\t\testimatedTokens: planned.fullTokens,\n\t\tfidelity: planned.item.tokenEstimate !== undefined ? \"exact\" : \"bounded\",\n\t\tsourceRef: planned.item.sourceRef,\n\t};\n\tselection.set(planned.item.id, toSelected(planned.item.id, candidate));\n\ttierUsed[planned.item.tier] += planned.fullTokens;\n\treturn planned.fullTokens;\n}\n\nexport function selectOptionalItem(planned: PlannedItemV2, state: OptionalSelectionState): number {\n\tif (state.usedTokens >= state.available) {\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tconst tierCeiling = state.allocation.get(planned.item.tier)?.ceiling ?? state.available;\n\tconst remaining = Math.max(0, state.available - state.usedTokens);\n\tconst candidates = planned.item.representations ?? deriveRepresentationCandidates(planned.item, state.qualityPolicy);\n\tconst materializedEnabled = planned.item.representations === undefined;\n\tconst cachedCandidates = state.cache\n\t\t? applyRepresentationCacheV2({ planned, candidates, cache: state.cache, materializedEnabled })\n\t\t: candidates;\n\tconst chosen = chooseHeadroomRepresentation(\n\t\t{ ...planned.item, representations: cachedCandidates },\n\t\t{\n\t\t\ttierUsedTokens: state.tierUsed[planned.item.tier],\n\t\t\ttierCeilingTokens: tierCeiling,\n\t\t\tremainingGlobalTokens: remaining,\n\t\t},\n\t\tstate.qualityPolicy,\n\t);\n\tif (chosen.kind === \"omit\") {\n\t\tconst tierRemaining = Math.max(0, tierCeiling - state.tierUsed[planned.item.tier]);\n\t\tconst globalFit = cachedCandidates.filter(\n\t\t\t(candidate) => candidate.kind !== \"omit\" && candidate.estimatedTokens <= remaining,\n\t\t);\n\t\tif (globalFit.length > 0 && globalFit.every((candidate) => candidate.estimatedTokens > tierRemaining)) {\n\t\t\tstate.diagnostics.push({\n\t\t\t\treason: \"tier_ceiling_exceeded\",\n\t\t\t\titemId: planned.item.id,\n\t\t\t\tdetail: `${planned.item.tier} item \"${planned.item.id}\" needs ${Math.min(\n\t\t\t\t\t...globalFit.map((candidate) => candidate.estimatedTokens),\n\t\t\t\t)} tokens with ${tierRemaining} tier tokens remaining`,\n\t\t\t});\n\t\t}\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tif (state.tierUsed[planned.item.tier] + chosen.estimatedTokens > tierCeiling) {\n\t\tstate.diagnostics.push({\n\t\t\treason: \"tier_ceiling_exceeded\",\n\t\t\titemId: planned.item.id,\n\t\t\tdetail: `${planned.item.tier} item \"${planned.item.id}\" needs ${chosen.estimatedTokens} tokens with ${Math.max(0, tierCeiling - state.tierUsed[planned.item.tier])} tier tokens remaining`,\n\t\t});\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tif (state.usedTokens + chosen.estimatedTokens > state.available) {\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tif (state.cache) {\n\t\tif (chosen.cache?.hit === true) {\n\t\t\trecordContextBudgetRepresentationCacheHitV2(\n\t\t\t\tstate.cache.telemetry,\n\t\t\t\tchosen.kind,\n\t\t\t\tchosen.cache.keyKind,\n\t\t\t\tplanned.fullTokens,\n\t\t\t);\n\t\t}\n\t\twriteRepresentationCacheV2({ planned, selected: chosen, cache: state.cache, materializedEnabled });\n\t}\n\tstate.selection.set(planned.item.id, toSelected(planned.item.id, chosen));\n\tstate.tierUsed[planned.item.tier] += chosen.estimatedTokens;\n\treturn state.usedTokens + chosen.estimatedTokens;\n}\n\nexport function emitOmissionDiagnostics(\n\tomitted: readonly ContextBudgetItemV2[],\n\tdiagnostics: QualityDiagnosticV2[],\n\tretrievalFallbacks: ContextSourceRefV2[],\n): void {\n\tfor (const item of omitted) {\n\t\tif (item.priority === \"high\" || item.required === true) {\n\t\t\tdiagnostics.push({\n\t\t\t\treason: \"omitted_high_priority\",\n\t\t\t\titemId: item.id,\n\t\t\t\tdetail: `${item.tier} item \"${item.id}\" could not fit within the prompt budget`,\n\t\t\t});\n\t\t}\n\t\tif (item.sourceRef?.retrievable) {\n\t\t\tdiagnostics.push({\n\t\t\t\treason: \"restore_on_demand_hint\",\n\t\t\t\titemId: item.id,\n\t\t\t\tdetail: `retrievable \"${item.id}\" kept as fallback via ${item.sourceRef.uri}`,\n\t\t\t});\n\t\t\tretrievalFallbacks.push(item.sourceRef);\n\t\t}\n\t}\n}\n\nexport function emitCoverageDiagnostics(\n\tquery: string | undefined,\n\tselection: ReadonlyMap<string, SelectedRepresentationV2>,\n\tdiagnostics: QualityDiagnosticV2[],\n): void {\n\tconst coverage = computeCoverageGap(\n\t\tquery,\n\t\t[...selection.values()].map((representation) => representation.text),\n\t);\n\tif (!coverage.gap) return;\n\tdiagnostics.push({\n\t\treason: \"coverage_gap\",\n\t\tdetail: `query terms not covered by selected context: ${coverage.missing.join(\", \")}`,\n\t});\n}\n\nexport function buildTierAllocations(\n\tallocation: ReadonlyMap<\n\t\tContextBudgetTierV2,\n\t\t{ readonly floor: number; readonly ceiling: number; readonly allocated: number }\n\t>,\n\tdemand: ReadonlyMap<ContextBudgetTierV2, { readonly hard: number }>,\n\ttierUsed: Record<ContextBudgetTierV2, number>,\n): TierBudgetAllocationV2[] {\n\treturn ALL_TIERS_V2.map((tier) => {\n\t\tconst raw = allocation.get(tier) ?? { floor: 0, ceiling: 0, allocated: 0 };\n\t\treturn {\n\t\t\ttier,\n\t\t\tfloorTokens: raw.floor,\n\t\t\tceilingTokens: raw.ceiling,\n\t\t\tallocatedTokens: raw.allocated,\n\t\t\tusedTokens: tierUsed[tier],\n\t\t\thardTokens: demand.get(tier)?.hard ?? 0,\n\t\t};\n\t});\n}\n\nexport function createTierUsage(): Record<ContextBudgetTierV2, number> {\n\treturn {\n\t\tsystem: 0,\n\t\t\"active-goal\": 0,\n\t\t\"current-files\": 0,\n\t\ttools: 0,\n\t\tskills: 0,\n\t\tmcp: 0,\n\t\thistory: 0,\n\t\tevidence: 0,\n\t\tscratch: 0,\n\t};\n}\n\nfunction toSelected(itemId: string, candidate: ContextRepresentationCandidateV2): SelectedRepresentationV2 {\n\treturn {\n\t\titemId,\n\t\tkind: candidate.kind,\n\t\ttext: candidate.text,\n\t\testimatedTokens: candidate.estimatedTokens,\n\t\tfidelity: candidate.fidelity,\n\t\tsourceRef: candidate.sourceRef,\n\t\tsummaryHash: candidate.summaryHash,\n\t\tcompressorId: candidate.compressorId,\n\t\tcache: candidate.cache,\n\t};\n}\n\nfunction omitItem(\n\tplanned: PlannedItemV2,\n\tstate: Pick<OptionalSelectionState, \"diagnostics\" | \"omitted\" | \"retrievalFallbacks\">,\n): void {\n\tstate.omitted.push(planned.item);\n\tif (planned.item.sourceRef?.retrievable) {\n\t\tstate.diagnostics.push({\n\t\t\treason: \"retrieval_miss_risk\",\n\t\t\titemId: planned.item.id,\n\t\t\tdetail: `retrievable ${planned.item.tier} item \"${planned.item.id}\" omitted; keep pointer for restore-on-demand`,\n\t\t});\n\t\tstate.retrievalFallbacks.push(planned.item.sourceRef);\n\t}\n}\n"]}
+{"version":3,"file":"context-budget-v2-selection.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-selection.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextRepresentationCandidateV2,\n\ttype ContextSourceRefV2,\n\tchooseHeadroomRepresentation,\n\tderiveRepresentationCandidates,\n\tfullTextTokens,\n} from \"./context-budget-headroom.ts\";\nimport { createFallbackTokenCounter, type TokenCounterAdapter } from \"./context-budget-token-counter.ts\";\nimport {\n\tapplyRepresentationCacheV2,\n\ttype ContextBudgetSelectionCacheV2,\n\twriteRepresentationCacheV2,\n} from \"./context-budget-v2-cache.ts\";\nimport { recordContextBudgetRepresentationCacheHitV2 } from \"./context-budget-v2-cache-telemetry.ts\";\nimport { computeCoverageGap } from \"./context-budget-v2-coverage.ts\";\nimport { contentHashOf } from \"./context-budget-v2-plan-hash.ts\";\nimport { applyRedundancyPenalties, type PlannedItemV2, scoreContextBudgetItemV2 } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tALL_TIERS_V2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetAllocationV2,\n} from \"./context-budget-v2-types.ts\";\n\nexport interface OptionalSelectionState {\n\treadonly allocation: ReadonlyMap<ContextBudgetTierV2, { readonly ceiling: number }>;\n\treadonly available: number;\n\treadonly cache?: ContextBudgetSelectionCacheV2;\n\treadonly diagnostics: QualityDiagnosticV2[];\n\treadonly omitted: ContextBudgetItemV2[];\n\treadonly qualityPolicy: Parameters<typeof chooseHeadroomRepresentation>[2];\n\treadonly retrievalFallbacks: ContextSourceRefV2[];\n\treadonly selection: Map<string, SelectedRepresentationV2>;\n\treadonly tierUsed: Record<ContextBudgetTierV2, number>;\n\treadonly usedTokens: number;\n}\n\n/**\n * Cheapest non-omit representation cost for an item, i.e. what admitting it\n * actually costs when the budget is tight. Falls back to full text when no\n * cheaper representation exists.\n */\nfunction minAdmissibleTokens(candidates: readonly ContextRepresentationCandidateV2[], fullTokens: number): number {\n\tlet min = Number.POSITIVE_INFINITY;\n\tfor (const candidate of candidates) {\n\t\tif (candidate.kind === \"omit\") continue;\n\t\tif (candidate.estimatedTokens < min) min = candidate.estimatedTokens;\n\t}\n\treturn Math.max(1, Number.isFinite(min) ? min : fullTokens);\n}\n\nexport function createPlannedItems(\n\titems: readonly ContextBudgetItemV2[],\n\ttokenCounter: TokenCounterAdapter | undefined,\n\tmodelId: string,\n\tqualityPolicy?: Parameters<typeof deriveRepresentationCandidates>[1],\n): PlannedItemV2[] {\n\tconst counter = tokenCounter ?? createFallbackTokenCounter();\n\treturn items.map((item) => {\n\t\tconst overrideTokenEstimate = item.tokenEstimate ?? counter.countText(item.text, modelId).tokens;\n\t\tconst itemWithTokens =\n\t\t\titem.tokenEstimate === undefined ? { ...item, tokenEstimate: overrideTokenEstimate } : item;\n\t\tconst fullTokens = fullTextTokens(itemWithTokens);\n\t\tconst isHard = item.priority === \"hard\" || item.required === true;\n\t\tconst baseScore = isHard ? Number.POSITIVE_INFINITY : scoreContextBudgetItemV2(itemWithTokens, fullTokens);\n\t\tconst candidates =\n\t\t\titemWithTokens.representations ?? deriveRepresentationCandidates(itemWithTokens, qualityPolicy);\n\t\treturn {\n\t\t\titem: itemWithTokens,\n\t\t\tfullTokens,\n\t\t\tadmissibleTokens: minAdmissibleTokens(candidates, fullTokens),\n\t\t\tcontentHash: contentHashOf(item.text),\n\t\t\tbaseScore,\n\t\t\tredundancyPenalty: 0,\n\t\t\teffectiveScore: baseScore,\n\t\t\tisHard,\n\t\t};\n\t});\n}\n\nexport function applyPlannerRedundancyPenalties(plannedItems: PlannedItemV2[]): void {\n\tconst penalties = applyRedundancyPenalties(plannedItems.filter((planned) => !planned.isHard));\n\tfor (const planned of plannedItems) {\n\t\tconst penalty = penalties.get(planned.item.id);\n\t\tif (penalty === undefined) continue;\n\t\tplanned.redundancyPenalty = penalty;\n\t\tplanned.effectiveScore = planned.baseScore - penalty;\n\t}\n}\n\nexport function selectHardItem(\n\tplanned: PlannedItemV2,\n\tselection: Map<string, SelectedRepresentationV2>,\n\ttierUsed: Record<ContextBudgetTierV2, number>,\n): number {\n\tconst candidate: ContextRepresentationCandidateV2 = {\n\t\tkind: \"full\",\n\t\ttext: planned.item.text,\n\t\testimatedTokens: planned.fullTokens,\n\t\tfidelity: planned.item.tokenEstimate !== undefined ? \"exact\" : \"bounded\",\n\t\tsourceRef: planned.item.sourceRef,\n\t};\n\tselection.set(planned.item.id, toSelected(planned.item.id, candidate));\n\ttierUsed[planned.item.tier] += planned.fullTokens;\n\treturn planned.fullTokens;\n}\n\nexport function selectOptionalItem(planned: PlannedItemV2, state: OptionalSelectionState): number {\n\tif (state.usedTokens >= state.available) {\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tconst tierCeiling = state.allocation.get(planned.item.tier)?.ceiling ?? state.available;\n\tconst remaining = Math.max(0, state.available - state.usedTokens);\n\tconst candidates = planned.item.representations ?? deriveRepresentationCandidates(planned.item, state.qualityPolicy);\n\tconst materializedEnabled = planned.item.representations === undefined;\n\tconst cachedCandidates = state.cache\n\t\t? applyRepresentationCacheV2({ planned, candidates, cache: state.cache, materializedEnabled })\n\t\t: candidates;\n\tconst chosen = chooseHeadroomRepresentation(\n\t\t{ ...planned.item, representations: cachedCandidates },\n\t\t{\n\t\t\ttierUsedTokens: state.tierUsed[planned.item.tier],\n\t\t\ttierCeilingTokens: tierCeiling,\n\t\t\tremainingGlobalTokens: remaining,\n\t\t},\n\t\tstate.qualityPolicy,\n\t);\n\tif (chosen.kind === \"omit\") {\n\t\tconst tierRemaining = Math.max(0, tierCeiling - state.tierUsed[planned.item.tier]);\n\t\tconst globalFit = cachedCandidates.filter(\n\t\t\t(candidate) => candidate.kind !== \"omit\" && candidate.estimatedTokens <= remaining,\n\t\t);\n\t\tif (globalFit.length > 0 && globalFit.every((candidate) => candidate.estimatedTokens > tierRemaining)) {\n\t\t\tstate.diagnostics.push({\n\t\t\t\treason: \"tier_ceiling_exceeded\",\n\t\t\t\titemId: planned.item.id,\n\t\t\t\tdetail: `${planned.item.tier} item \"${planned.item.id}\" needs ${Math.min(\n\t\t\t\t\t...globalFit.map((candidate) => candidate.estimatedTokens),\n\t\t\t\t)} tokens with ${tierRemaining} tier tokens remaining`,\n\t\t\t});\n\t\t}\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tif (state.tierUsed[planned.item.tier] + chosen.estimatedTokens > tierCeiling) {\n\t\tstate.diagnostics.push({\n\t\t\treason: \"tier_ceiling_exceeded\",\n\t\t\titemId: planned.item.id,\n\t\t\tdetail: `${planned.item.tier} item \"${planned.item.id}\" needs ${chosen.estimatedTokens} tokens with ${Math.max(0, tierCeiling - state.tierUsed[planned.item.tier])} tier tokens remaining`,\n\t\t});\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tif (state.usedTokens + chosen.estimatedTokens > state.available) {\n\t\tomitItem(planned, state);\n\t\treturn state.usedTokens;\n\t}\n\tif (state.cache) {\n\t\tif (chosen.cache?.hit === true) {\n\t\t\trecordContextBudgetRepresentationCacheHitV2(\n\t\t\t\tstate.cache.telemetry,\n\t\t\t\tchosen.kind,\n\t\t\t\tchosen.cache.keyKind,\n\t\t\t\tplanned.fullTokens,\n\t\t\t);\n\t\t}\n\t\twriteRepresentationCacheV2({ planned, selected: chosen, cache: state.cache, materializedEnabled });\n\t}\n\tstate.selection.set(planned.item.id, toSelected(planned.item.id, chosen));\n\tstate.tierUsed[planned.item.tier] += chosen.estimatedTokens;\n\treturn state.usedTokens + chosen.estimatedTokens;\n}\n\nexport function emitOmissionDiagnostics(\n\tomitted: readonly ContextBudgetItemV2[],\n\tdiagnostics: QualityDiagnosticV2[],\n\tretrievalFallbacks: ContextSourceRefV2[],\n): void {\n\tfor (const item of omitted) {\n\t\tif (item.priority === \"high\" || item.required === true) {\n\t\t\tdiagnostics.push({\n\t\t\t\treason: \"omitted_high_priority\",\n\t\t\t\titemId: item.id,\n\t\t\t\tdetail: `${item.tier} item \"${item.id}\" could not fit within the prompt budget`,\n\t\t\t});\n\t\t}\n\t\tif (item.sourceRef?.retrievable) {\n\t\t\tdiagnostics.push({\n\t\t\t\treason: \"restore_on_demand_hint\",\n\t\t\t\titemId: item.id,\n\t\t\t\tdetail: `retrievable \"${item.id}\" kept as fallback via ${item.sourceRef.uri}`,\n\t\t\t});\n\t\t\tretrievalFallbacks.push(item.sourceRef);\n\t\t}\n\t}\n}\n\nexport function emitCoverageDiagnostics(\n\tquery: string | undefined,\n\tselection: ReadonlyMap<string, SelectedRepresentationV2>,\n\tdiagnostics: QualityDiagnosticV2[],\n): void {\n\tconst coverage = computeCoverageGap(\n\t\tquery,\n\t\t[...selection.values()].map((representation) => representation.text),\n\t);\n\tif (!coverage.gap) return;\n\tdiagnostics.push({\n\t\treason: \"coverage_gap\",\n\t\tdetail: `query terms not covered by selected context: ${coverage.missing.join(\", \")}`,\n\t});\n}\n\nexport function buildTierAllocations(\n\tallocation: ReadonlyMap<\n\t\tContextBudgetTierV2,\n\t\t{ readonly floor: number; readonly ceiling: number; readonly allocated: number }\n\t>,\n\tdemand: ReadonlyMap<ContextBudgetTierV2, { readonly hard: number }>,\n\ttierUsed: Record<ContextBudgetTierV2, number>,\n): TierBudgetAllocationV2[] {\n\treturn ALL_TIERS_V2.map((tier) => {\n\t\tconst raw = allocation.get(tier) ?? { floor: 0, ceiling: 0, allocated: 0 };\n\t\treturn {\n\t\t\ttier,\n\t\t\tfloorTokens: raw.floor,\n\t\t\tceilingTokens: raw.ceiling,\n\t\t\tallocatedTokens: raw.allocated,\n\t\t\tusedTokens: tierUsed[tier],\n\t\t\thardTokens: demand.get(tier)?.hard ?? 0,\n\t\t};\n\t});\n}\n\nexport function createTierUsage(): Record<ContextBudgetTierV2, number> {\n\treturn {\n\t\tsystem: 0,\n\t\t\"active-goal\": 0,\n\t\t\"current-files\": 0,\n\t\ttools: 0,\n\t\tskills: 0,\n\t\tmcp: 0,\n\t\thistory: 0,\n\t\tevidence: 0,\n\t\tscratch: 0,\n\t};\n}\n\nfunction toSelected(itemId: string, candidate: ContextRepresentationCandidateV2): SelectedRepresentationV2 {\n\treturn {\n\t\titemId,\n\t\tkind: candidate.kind,\n\t\ttext: candidate.text,\n\t\testimatedTokens: candidate.estimatedTokens,\n\t\tfidelity: candidate.fidelity,\n\t\tsourceRef: candidate.sourceRef,\n\t\tsummaryHash: candidate.summaryHash,\n\t\tcompressorId: candidate.compressorId,\n\t\tcache: candidate.cache,\n\t};\n}\n\nfunction omitItem(\n\tplanned: PlannedItemV2,\n\tstate: Pick<OptionalSelectionState, \"diagnostics\" | \"omitted\" | \"retrievalFallbacks\">,\n): void {\n\tstate.omitted.push(planned.item);\n\tif (planned.item.sourceRef?.retrievable) {\n\t\tstate.diagnostics.push({\n\t\t\treason: \"retrieval_miss_risk\",\n\t\t\titemId: planned.item.id,\n\t\t\tdetail: `retrievable ${planned.item.tier} item \"${planned.item.id}\" omitted; keep pointer for restore-on-demand`,\n\t\t});\n\t\tstate.retrievalFallbacks.push(planned.item.sourceRef);\n\t}\n}\n"]}

package/dist/core/context-budget-v2-types.d.ts

@@ -1,7 +1,22 @@
 import type { ContextBudgetItemV2, ContextBudgetTierV2, ContextRepresentationCacheMetadataV2, ContextRepresentationCandidateV2, ContextRepresentationKindV2, ContextSourceRefV2, HeadroomQualityPolicyV2 } from "./context-budget-headroom.ts";
 import type { TokenCounterAdapter } from "./context-budget-token-counter.ts";
 import type { ContextCacheInvalidationSnapshot } from "./context-budget-v2-cache-invalidation.ts";
+/**
+ * Public optimizer identifier. It is reported in the system prompt and used as a
+ * cache namespace, so it must stay stable across internal policy changes.
+ */
 export declare const CONTEXT_BUDGET_POLICY_VERSION_V2 = "context-budget-v2";
+/**
+ * Internal token for the optional-item selection policy, kept separate from the
+ * public identifier so a scoring or ordering change can invalidate cached plans
+ * without renaming the optimizer. Bump it whenever the selected set can differ
+ * for identical inputs; otherwise plans built under the previous policy keep
+ * being served for the whole cache TTL, including from disk.
+ *
+ * `sel-2`: density-ordered selection over the cheapest admissible representation
+ * (previously priority-class-ordered over full-text tokens).
+ */
+export declare const CONTEXT_BUDGET_SELECTION_POLICY_V2 = "sel-2";
 /** Fixed compatibility telemetry for the removed legacy token optimizer. */
 export interface TokenOptimizerRuntimeStatus {
     readonly optimizerId: "legacy-token-optimizer";
@@ -23,6 +38,8 @@ export interface PromptContextBudgetInputV2 {
     readonly modelId?: string;
     readonly tokenizerId?: string;
     readonly policyVersion?: string;
+    /** Overrides {@link CONTEXT_BUDGET_SELECTION_POLICY_V2}. */
+    readonly selectionPolicyVersion?: string;
     readonly promptHash?: string;
     readonly query?: string;
     readonly items: readonly ContextBudgetItemV2[];