open-multi-agent-kit 1.0.0 → 1.2.2

package/dist/core/context-budget-v2-global-pass.js

@@ -0,0 +1,203 @@
+import { chooseHeadroomRepresentation, deriveRepresentationCandidates, isRepresentationEligible, scoreRepresentationPreferenceV2, } from "./context-budget-headroom.js";
+import { writeRepresentationCacheV2 } from "./context-budget-v2-cache.js";
+import { selectOptionalItem, toSelected } from "./context-budget-v2-selection.js";
+/**
+ * Everything that happens once every tier has spent its floor:
+ *
+ * 1. the global pass admits still-unselected optional items in rank order
+ *    under their tier ceilings;
+ * 2. the exchange pass lets a still-omitted item pay for its admission by
+ *    stepping selected items down to their cheapest admissible form (F04);
+ * 3. the promotion pass spends whatever is left on costlier representations
+ *    the policy prefers (F03).
+ *
+ * Breadth is settled before quality: an exchange that admits another item
+ * cannot be undone by a promotion, because promotion only spends the budget
+ * the exchange left. Returns the final token usage.
+ */
+export function runGlobalSelectionPass(optionalPlanned, state) {
+    let usedTokens = state.usedTokens;
+    for (const planned of optionalPlanned) {
+        if (state.selection.has(planned.item.id))
+            continue;
+        usedTokens = selectOptionalItem(planned, { ...state, usedTokens });
+    }
+    usedTokens = exchangeForOmittedItems(optionalPlanned, { ...state, usedTokens });
+    return promoteSelectedRepresentations(optionalPlanned, { ...state, usedTokens });
+}
+/** Representations the planner priced for this item, in the order selection saw them. */
+function candidatesFor(planned, state) {
+    return (state.resolvedCandidates?.get(planned.item.id) ??
+        planned.candidates ??
+        planned.item.representations ??
+        deriveRepresentationCandidates(planned.item, state.qualityPolicy));
+}
+/** Cheapest representation the policy would allow at all, ignoring budget. */
+function cheapestAdmissible(planned, state) {
+    let best;
+    for (const candidate of candidatesFor(planned, state)) {
+        if (candidate.kind === "omit")
+            continue;
+        if (!isRepresentationEligible(candidate, planned.item, state.qualityPolicy))
+            continue;
+        if (best === undefined || candidate.estimatedTokens < best.estimatedTokens)
+            best = candidate;
+    }
+    return best;
+}
+/**
+ * Plan the cheapest set of step-downs that makes room for `cost` tokens in
+ * `target`'s tier, or `undefined` when no admissible set exists.
+ *
+ * Donors are ordered by the preference the policy loses per token freed, so
+ * the item whose fidelity matters least to the policy yields first. A donor is
+ * skipped when stepping it down would drop its tier below the floor it is
+ * currently honouring: the floor is a reservation, not a budget to raid. An
+ * empty swap list is legitimate — an earlier exchange may already have freed
+ * enough for this item.
+ */
+function planExchange(target, cost, optionalPlanned, state, usedTokens) {
+    const ceilingOf = (tier) => state.allocation.get(tier)?.ceiling ?? state.available;
+    const floorOf = (tier) => state.allocation.get(tier)?.floor ?? 0;
+    const projected = new Map();
+    const tierNow = (tier) => projected.get(tier) ?? state.tierUsed[tier];
+    const donors = [];
+    for (const donor of optionalPlanned) {
+        if (donor.item.id === target.item.id)
+            continue;
+        const current = state.selection.get(donor.item.id);
+        if (current === undefined || current.kind === "omit")
+            continue;
+        const cheap = cheapestAdmissible(donor, state);
+        if (cheap === undefined || cheap.estimatedTokens >= current.estimatedTokens)
+            continue;
+        const freed = current.estimatedTokens - cheap.estimatedTokens;
+        const from = toCandidate(current);
+        const loss = scoreRepresentationPreferenceV2(from, donor.item, state.qualityPolicy, false) -
+            scoreRepresentationPreferenceV2(cheap, donor.item, state.qualityPolicy, false);
+        donors.push({ donor, current, cheap, freed, lossPerToken: loss / freed });
+    }
+    donors.sort((a, b) => a.lossPerToken - b.lossPerToken || a.donor.item.id.localeCompare(b.donor.item.id));
+    const swaps = [];
+    let freed = 0;
+    const fits = () => cost <= state.available - (usedTokens - freed) && tierNow(target.item.tier) + cost <= ceilingOf(target.item.tier);
+    for (const entry of donors) {
+        if (fits())
+            break;
+        const after = tierNow(entry.donor.item.tier) - entry.freed;
+        if (tierNow(entry.donor.item.tier) >= floorOf(entry.donor.item.tier) && after < floorOf(entry.donor.item.tier)) {
+            continue;
+        }
+        projected.set(entry.donor.item.tier, after);
+        swaps.push({ donor: entry.donor, from: entry.current, to: entry.cheap });
+        freed += entry.freed;
+    }
+    return fits() ? { swaps, freed } : undefined;
+}
+/**
+ * Admit still-omitted items by exchanging fidelity for coverage (audit F04).
+ *
+ * Ranking prices an item by its cheapest admissible representation but the
+ * selector may admit it at full text, so one item ranked on a 10-token pointer
+ * can spend 100 and displace two 45-token items the policy would rather keep.
+ * After the global pass, each omitted item in rank order may buy its cheapest
+ * admissible form by stepping selected items down to theirs. The whole exchange
+ * is applied or none of it is; tier floors and ceilings hold throughout. This
+ * is a bounded repair, not joint `(item, representation)` optimization.
+ */
+function exchangeForOmittedItems(optionalPlanned, state) {
+    let usedTokens = state.usedTokens;
+    for (const target of optionalPlanned) {
+        if (state.selection.has(target.item.id))
+            continue;
+        const admit = cheapestAdmissible(target, state);
+        if (admit === undefined)
+            continue;
+        const exchange = planExchange(target, admit.estimatedTokens, optionalPlanned, state, usedTokens);
+        if (exchange === undefined)
+            continue;
+        for (const swap of exchange.swaps) {
+            state.tierUsed[swap.donor.item.tier] += swap.to.estimatedTokens - swap.from.estimatedTokens;
+            state.selection.set(swap.donor.item.id, toSelected(swap.donor.item.id, swap.to));
+            writeSelected(swap.donor, swap.to, state);
+        }
+        state.tierUsed[target.item.tier] += admit.estimatedTokens;
+        state.selection.set(target.item.id, toSelected(target.item.id, admit));
+        writeSelected(target, admit, state);
+        // The global pass already recorded this item as omitted; an admitted item
+        // must leave that list, or the plan reports it as both included and
+        // omitted and bills its full text in omittedTokens.
+        const omittedIndex = state.omitted.findIndex((entry) => entry.id === target.item.id);
+        if (omittedIndex >= 0)
+            state.omitted.splice(omittedIndex, 1);
+        usedTokens = usedTokens - exchange.freed + admit.estimatedTokens;
+    }
+    return usedTokens;
+}
+function writeSelected(planned, selected, state) {
+    if (!state.cache)
+        return;
+    writeRepresentationCacheV2({
+        planned,
+        selected,
+        cache: state.cache,
+        materializedEnabled: planned.item.representations === undefined,
+    });
+}
+/**
+ * Re-offer each selected optional item its costlier representations against
+ * the leftover budget (audit F03). The floor pass admits an item at whatever
+ * fits the tier's remaining floor and the global pass then skips it by id,
+ * so a pointer chosen under a small floor stayed a pointer while most of the
+ * budget went unused. Runs once, in selection-rank order, after the global
+ * pass; a swap happens only when the selection policy itself prefers the
+ * costlier representation under the real remainder and it fits both the
+ * tier ceiling and the global budget. It never demotes, never touches hard
+ * items, and never spends beyond either cap. Returns the updated token usage.
+ */
+function promoteSelectedRepresentations(optionalPlanned, state) {
+    let usedTokens = state.usedTokens;
+    for (const planned of optionalPlanned) {
+        const current = state.selection.get(planned.item.id);
+        if (current === undefined || current.kind === "omit")
+            continue;
+        const remaining = state.available - usedTokens;
+        if (remaining <= 0)
+            break;
+        const ceiling = state.allocation.get(planned.item.tier)?.ceiling ?? state.available;
+        const tierUsedWithout = state.tierUsed[planned.item.tier] - current.estimatedTokens;
+        const upgrades = candidatesFor(planned, state).filter((candidate) => candidate.kind !== "omit" &&
+            candidate.estimatedTokens > current.estimatedTokens &&
+            candidate.estimatedTokens <= remaining + current.estimatedTokens &&
+            tierUsedWithout + candidate.estimatedTokens <= ceiling);
+        if (upgrades.length === 0)
+            continue;
+        // Let the policy rank the current choice against every affordable upgrade
+        // under the real leftover; only a strictly costlier winner is a promotion.
+        const chosen = chooseHeadroomRepresentation({ ...planned.item, representations: [...upgrades, toCandidate(current)] }, {
+            tierUsedTokens: tierUsedWithout,
+            tierCeilingTokens: ceiling,
+            remainingGlobalTokens: remaining + current.estimatedTokens,
+        }, state.qualityPolicy);
+        if (chosen.kind === "omit" || chosen.estimatedTokens <= current.estimatedTokens)
+            continue;
+        writeSelected(planned, chosen, state);
+        state.tierUsed[planned.item.tier] = tierUsedWithout + chosen.estimatedTokens;
+        usedTokens += chosen.estimatedTokens - current.estimatedTokens;
+        state.selection.set(planned.item.id, toSelected(planned.item.id, chosen));
+    }
+    return usedTokens;
+}
+function toCandidate(selected) {
+    return {
+        kind: selected.kind,
+        text: selected.text,
+        estimatedTokens: selected.estimatedTokens,
+        fidelity: selected.fidelity,
+        sourceRef: selected.sourceRef,
+        summaryHash: selected.summaryHash,
+        compressorId: selected.compressorId,
+        cache: selected.cache,
+    };
+}
+//# sourceMappingURL=context-budget-v2-global-pass.js.map

package/dist/core/context-budget-v2-global-pass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget-v2-global-pass.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-global-pass.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype ContextRepresentationCandidateV2,\n\tchooseHeadroomRepresentation,\n\tderiveRepresentationCandidates,\n\tisRepresentationEligible,\n\tscoreRepresentationPreferenceV2,\n} from \"./context-budget-headroom.ts\";\nimport { writeRepresentationCacheV2 } from \"./context-budget-v2-cache.ts\";\nimport type { PlannedItemV2 } from \"./context-budget-v2-scoring.ts\";\nimport { type OptionalSelectionState, selectOptionalItem, toSelected } from \"./context-budget-v2-selection.ts\";\nimport type { SelectedRepresentationV2 } from \"./context-budget-v2-types.ts\";\n\n/** Selection state after the floor-reservation passes; `usedTokens` is the running total so far. */\nexport type GlobalPassState = Omit<OptionalSelectionState, \"floorReservation\">;\n\nexport type PromotionState = Pick<\n\tGlobalPassState,\n\t| \"allocation\"\n\t| \"available\"\n\t| \"cache\"\n\t| \"qualityPolicy\"\n\t| \"resolvedCandidates\"\n\t| \"selection\"\n\t| \"tierUsed\"\n\t| \"usedTokens\"\n>;\n\n/**\n * Everything that happens once every tier has spent its floor:\n *\n * 1. the global pass admits still-unselected optional items in rank order\n *    under their tier ceilings;\n * 2. the exchange pass lets a still-omitted item pay for its admission by\n *    stepping selected items down to their cheapest admissible form (F04);\n * 3. the promotion pass spends whatever is left on costlier representations\n *    the policy prefers (F03).\n *\n * Breadth is settled before quality: an exchange that admits another item\n * cannot be undone by a promotion, because promotion only spends the budget\n * the exchange left. Returns the final token usage.\n */\nexport function runGlobalSelectionPass(optionalPlanned: readonly PlannedItemV2[], state: GlobalPassState): number {\n\tlet usedTokens = state.usedTokens;\n\tfor (const planned of optionalPlanned) {\n\t\tif (state.selection.has(planned.item.id)) continue;\n\t\tusedTokens = selectOptionalItem(planned, { ...state, usedTokens });\n\t}\n\tusedTokens = exchangeForOmittedItems(optionalPlanned, { ...state, usedTokens });\n\treturn promoteSelectedRepresentations(optionalPlanned, { ...state, usedTokens });\n}\n\n/** Representations the planner priced for this item, in the order selection saw them. */\nfunction candidatesFor(planned: PlannedItemV2, state: PromotionState): readonly ContextRepresentationCandidateV2[] {\n\treturn (\n\t\tstate.resolvedCandidates?.get(planned.item.id) ??\n\t\tplanned.candidates ??\n\t\tplanned.item.representations ??\n\t\tderiveRepresentationCandidates(planned.item, state.qualityPolicy)\n\t);\n}\n\n/** Cheapest representation the policy would allow at all, ignoring budget. */\nfunction cheapestAdmissible(\n\tplanned: PlannedItemV2,\n\tstate: PromotionState,\n): ContextRepresentationCandidateV2 | undefined {\n\tlet best: ContextRepresentationCandidateV2 | undefined;\n\tfor (const candidate of candidatesFor(planned, state)) {\n\t\tif (candidate.kind === \"omit\") continue;\n\t\tif (!isRepresentationEligible(candidate, planned.item, state.qualityPolicy)) continue;\n\t\tif (best === undefined || candidate.estimatedTokens < best.estimatedTokens) best = candidate;\n\t}\n\treturn best;\n}\n\ninterface PlannedExchange {\n\treadonly swaps: ReadonlyArray<{\n\t\treadonly donor: PlannedItemV2;\n\t\treadonly from: SelectedRepresentationV2;\n\t\treadonly to: ContextRepresentationCandidateV2;\n\t}>;\n\treadonly freed: number;\n}\n\n/**\n * Plan the cheapest set of step-downs that makes room for `cost` tokens in\n * `target`'s tier, or `undefined` when no admissible set exists.\n *\n * Donors are ordered by the preference the policy loses per token freed, so\n * the item whose fidelity matters least to the policy yields first. A donor is\n * skipped when stepping it down would drop its tier below the floor it is\n * currently honouring: the floor is a reservation, not a budget to raid. An\n * empty swap list is legitimate — an earlier exchange may already have freed\n * enough for this item.\n */\nfunction planExchange(\n\ttarget: PlannedItemV2,\n\tcost: number,\n\toptionalPlanned: readonly PlannedItemV2[],\n\tstate: PromotionState,\n\tusedTokens: number,\n): PlannedExchange | undefined {\n\tconst ceilingOf = (tier: PlannedItemV2[\"item\"][\"tier\"]): number =>\n\t\tstate.allocation.get(tier)?.ceiling ?? state.available;\n\tconst floorOf = (tier: PlannedItemV2[\"item\"][\"tier\"]): number => state.allocation.get(tier)?.floor ?? 0;\n\tconst projected = new Map<string, number>();\n\tconst tierNow = (tier: PlannedItemV2[\"item\"][\"tier\"]): number => projected.get(tier) ?? state.tierUsed[tier];\n\n\tconst donors = [];\n\tfor (const donor of optionalPlanned) {\n\t\tif (donor.item.id === target.item.id) continue;\n\t\tconst current = state.selection.get(donor.item.id);\n\t\tif (current === undefined || current.kind === \"omit\") continue;\n\t\tconst cheap = cheapestAdmissible(donor, state);\n\t\tif (cheap === undefined || cheap.estimatedTokens >= current.estimatedTokens) continue;\n\t\tconst freed = current.estimatedTokens - cheap.estimatedTokens;\n\t\tconst from = toCandidate(current);\n\t\tconst loss =\n\t\t\tscoreRepresentationPreferenceV2(from, donor.item, state.qualityPolicy, false) -\n\t\t\tscoreRepresentationPreferenceV2(cheap, donor.item, state.qualityPolicy, false);\n\t\tdonors.push({ donor, current, cheap, freed, lossPerToken: loss / freed });\n\t}\n\tdonors.sort((a, b) => a.lossPerToken - b.lossPerToken || a.donor.item.id.localeCompare(b.donor.item.id));\n\n\tconst swaps: Array<PlannedExchange[\"swaps\"][number]> = [];\n\tlet freed = 0;\n\tconst fits = (): boolean =>\n\t\tcost <= state.available - (usedTokens - freed) && tierNow(target.item.tier) + cost <= ceilingOf(target.item.tier);\n\tfor (const entry of donors) {\n\t\tif (fits()) break;\n\t\tconst after = tierNow(entry.donor.item.tier) - entry.freed;\n\t\tif (tierNow(entry.donor.item.tier) >= floorOf(entry.donor.item.tier) && after < floorOf(entry.donor.item.tier)) {\n\t\t\tcontinue;\n\t\t}\n\t\tprojected.set(entry.donor.item.tier, after);\n\t\tswaps.push({ donor: entry.donor, from: entry.current, to: entry.cheap });\n\t\tfreed += entry.freed;\n\t}\n\treturn fits() ? { swaps, freed } : undefined;\n}\n\n/**\n * Admit still-omitted items by exchanging fidelity for coverage (audit F04).\n *\n * Ranking prices an item by its cheapest admissible representation but the\n * selector may admit it at full text, so one item ranked on a 10-token pointer\n * can spend 100 and displace two 45-token items the policy would rather keep.\n * After the global pass, each omitted item in rank order may buy its cheapest\n * admissible form by stepping selected items down to theirs. The whole exchange\n * is applied or none of it is; tier floors and ceilings hold throughout. This\n * is a bounded repair, not joint `(item, representation)` optimization.\n */\nfunction exchangeForOmittedItems(optionalPlanned: readonly PlannedItemV2[], state: GlobalPassState): number {\n\tlet usedTokens = state.usedTokens;\n\tfor (const target of optionalPlanned) {\n\t\tif (state.selection.has(target.item.id)) continue;\n\t\tconst admit = cheapestAdmissible(target, state);\n\t\tif (admit === undefined) continue;\n\t\tconst exchange = planExchange(target, admit.estimatedTokens, optionalPlanned, state, usedTokens);\n\t\tif (exchange === undefined) continue;\n\t\tfor (const swap of exchange.swaps) {\n\t\t\tstate.tierUsed[swap.donor.item.tier] += swap.to.estimatedTokens - swap.from.estimatedTokens;\n\t\t\tstate.selection.set(swap.donor.item.id, toSelected(swap.donor.item.id, swap.to));\n\t\t\twriteSelected(swap.donor, swap.to, state);\n\t\t}\n\t\tstate.tierUsed[target.item.tier] += admit.estimatedTokens;\n\t\tstate.selection.set(target.item.id, toSelected(target.item.id, admit));\n\t\twriteSelected(target, admit, state);\n\t\t// The global pass already recorded this item as omitted; an admitted item\n\t\t// must leave that list, or the plan reports it as both included and\n\t\t// omitted and bills its full text in omittedTokens.\n\t\tconst omittedIndex = state.omitted.findIndex((entry) => entry.id === target.item.id);\n\t\tif (omittedIndex >= 0) state.omitted.splice(omittedIndex, 1);\n\t\tusedTokens = usedTokens - exchange.freed + admit.estimatedTokens;\n\t}\n\treturn usedTokens;\n}\n\nfunction writeSelected(\n\tplanned: PlannedItemV2,\n\tselected: ContextRepresentationCandidateV2,\n\tstate: PromotionState,\n): void {\n\tif (!state.cache) return;\n\twriteRepresentationCacheV2({\n\t\tplanned,\n\t\tselected,\n\t\tcache: state.cache,\n\t\tmaterializedEnabled: planned.item.representations === undefined,\n\t});\n}\n\n/**\n * Re-offer each selected optional item its costlier representations against\n * the leftover budget (audit F03). The floor pass admits an item at whatever\n * fits the tier's remaining floor and the global pass then skips it by id,\n * so a pointer chosen under a small floor stayed a pointer while most of the\n * budget went unused. Runs once, in selection-rank order, after the global\n * pass; a swap happens only when the selection policy itself prefers the\n * costlier representation under the real remainder and it fits both the\n * tier ceiling and the global budget. It never demotes, never touches hard\n * items, and never spends beyond either cap. Returns the updated token usage.\n */\nfunction promoteSelectedRepresentations(optionalPlanned: readonly PlannedItemV2[], state: PromotionState): number {\n\tlet usedTokens = state.usedTokens;\n\tfor (const planned of optionalPlanned) {\n\t\tconst current = state.selection.get(planned.item.id);\n\t\tif (current === undefined || current.kind === \"omit\") continue;\n\t\tconst remaining = state.available - usedTokens;\n\t\tif (remaining <= 0) break;\n\t\tconst ceiling = state.allocation.get(planned.item.tier)?.ceiling ?? state.available;\n\t\tconst tierUsedWithout = state.tierUsed[planned.item.tier] - current.estimatedTokens;\n\t\tconst upgrades = candidatesFor(planned, state).filter(\n\t\t\t(candidate) =>\n\t\t\t\tcandidate.kind !== \"omit\" &&\n\t\t\t\tcandidate.estimatedTokens > current.estimatedTokens &&\n\t\t\t\tcandidate.estimatedTokens <= remaining + current.estimatedTokens &&\n\t\t\t\ttierUsedWithout + candidate.estimatedTokens <= ceiling,\n\t\t);\n\t\tif (upgrades.length === 0) continue;\n\t\t// Let the policy rank the current choice against every affordable upgrade\n\t\t// under the real leftover; only a strictly costlier winner is a promotion.\n\t\tconst chosen = chooseHeadroomRepresentation(\n\t\t\t{ ...planned.item, representations: [...upgrades, toCandidate(current)] },\n\t\t\t{\n\t\t\t\ttierUsedTokens: tierUsedWithout,\n\t\t\t\ttierCeilingTokens: ceiling,\n\t\t\t\tremainingGlobalTokens: remaining + current.estimatedTokens,\n\t\t\t},\n\t\t\tstate.qualityPolicy,\n\t\t);\n\t\tif (chosen.kind === \"omit\" || chosen.estimatedTokens <= current.estimatedTokens) continue;\n\t\twriteSelected(planned, chosen, state);\n\t\tstate.tierUsed[planned.item.tier] = tierUsedWithout + chosen.estimatedTokens;\n\t\tusedTokens += chosen.estimatedTokens - current.estimatedTokens;\n\t\tstate.selection.set(planned.item.id, toSelected(planned.item.id, chosen));\n\t}\n\treturn usedTokens;\n}\n\nfunction toCandidate(selected: SelectedRepresentationV2): ContextRepresentationCandidateV2 {\n\treturn {\n\t\tkind: selected.kind,\n\t\ttext: selected.text,\n\t\testimatedTokens: selected.estimatedTokens,\n\t\tfidelity: selected.fidelity,\n\t\tsourceRef: selected.sourceRef,\n\t\tsummaryHash: selected.summaryHash,\n\t\tcompressorId: selected.compressorId,\n\t\tcache: selected.cache,\n\t};\n}\n"]}

package/dist/core/context-budget-v2-planned-items.d.ts

@@ -1,5 +1,17 @@
 import { type ContextBudgetItemV2, deriveRepresentationCandidates } from "./context-budget-headroom.ts";
 import { type TokenCounterAdapter } from "./context-budget-token-counter.ts";
 import { type PlannedItemV2 } from "./context-budget-v2-scoring.ts";
+/**
+ * Identity of the adapter that actually prices this run's text.
+ *
+ * Every representation price now depends on the planner's counter (audit F01),
+ * but the materialized representation key is bucketed rather than exact, so the
+ * static `heuristic-v1` default let two counters share one key space: a run
+ * could admit text at a price its own counter never produced, and the entry's
+ * `tokenizer_mismatch` check compared that constant against itself. Probe a
+ * non-empty string, because `countText("")` short-circuits to the fallback
+ * estimator in the registry and would report the wrong adapter.
+ */
+export declare function resolveEffectiveTokenizerIdV2(tokenCounter: TokenCounterAdapter | undefined, modelId: string): string;
 export declare function createPlannedItems(items: readonly ContextBudgetItemV2[], tokenCounter: TokenCounterAdapter | undefined, modelId: string, qualityPolicy?: Parameters<typeof deriveRepresentationCandidates>[1]): PlannedItemV2[];
 //# sourceMappingURL=context-budget-v2-planned-items.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"context-budget-v2-planned-items.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-planned-items.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,mBAAmB,EAExB,8BAA8B,EAI9B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAA8B,KAAK,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAEzG,OAAO,EAAE,KAAK,aAAa,EAA4B,MAAM,gCAAgC,CAAC;AAwB9F,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","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextRepresentationCandidateV2,\n\tderiveRepresentationCandidates,\n\tfullTextTokens,\n\ttype HeadroomQualityPolicyV2,\n\tisRepresentationEligible,\n} from \"./context-budget-headroom.ts\";\nimport { createFallbackTokenCounter, type TokenCounterAdapter } from \"./context-budget-token-counter.ts\";\nimport { contentHashOf } from \"./context-budget-v2-plan-hash.ts\";\nimport { type PlannedItemV2, scoreContextBudgetItemV2 } from \"./context-budget-v2-scoring.ts\";\n\n// Cheapest representation the chooser could actually pick: only candidates\n// passing the selection policy gate count, so a pointer the chooser would\n// reject cannot make an item look cheaper to admit than it is.\nfunction minAdmissibleTokens(\n\tcandidates: readonly ContextRepresentationCandidateV2[],\n\titem: ContextBudgetItemV2,\n\tpolicy: HeadroomQualityPolicyV2 | undefined,\n\tfullTokens: number,\n): number {\n\tlet min = Number.POSITIVE_INFINITY;\n\tfor (const candidate of candidates) {\n\t\tif (\n\t\t\tcandidate.kind !== \"omit\" &&\n\t\t\tisRepresentationEligible(candidate, item, policy) &&\n\t\t\tcandidate.estimatedTokens < min\n\t\t) {\n\t\t\tmin = candidate.estimatedTokens;\n\t\t}\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, itemWithTokens, qualityPolicy, 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"]}
+{"version":3,"file":"context-budget-v2-planned-items.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-planned-items.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,mBAAmB,EAExB,8BAA8B,EAI9B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAA8B,KAAK,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAEzG,OAAO,EAAE,KAAK,aAAa,EAA4B,MAAM,gCAAgC,CAAC;AAwB9F;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAAC,YAAY,EAAE,mBAAmB,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpH;AAED,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,CA2BjB","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextRepresentationCandidateV2,\n\tderiveRepresentationCandidates,\n\tfullTextTokens,\n\ttype HeadroomQualityPolicyV2,\n\tisRepresentationEligible,\n} from \"./context-budget-headroom.ts\";\nimport { createFallbackTokenCounter, type TokenCounterAdapter } from \"./context-budget-token-counter.ts\";\nimport { contentHashOf } from \"./context-budget-v2-plan-hash.ts\";\nimport { type PlannedItemV2, scoreContextBudgetItemV2 } from \"./context-budget-v2-scoring.ts\";\n\n// Cheapest representation the chooser could actually pick: only candidates\n// passing the selection policy gate count, so a pointer the chooser would\n// reject cannot make an item look cheaper to admit than it is.\nfunction minAdmissibleTokens(\n\tcandidates: readonly ContextRepresentationCandidateV2[],\n\titem: ContextBudgetItemV2,\n\tpolicy: HeadroomQualityPolicyV2 | undefined,\n\tfullTokens: number,\n): number {\n\tlet min = Number.POSITIVE_INFINITY;\n\tfor (const candidate of candidates) {\n\t\tif (\n\t\t\tcandidate.kind !== \"omit\" &&\n\t\t\tisRepresentationEligible(candidate, item, policy) &&\n\t\t\tcandidate.estimatedTokens < min\n\t\t) {\n\t\t\tmin = candidate.estimatedTokens;\n\t\t}\n\t}\n\treturn Math.max(1, Number.isFinite(min) ? min : fullTokens);\n}\n\n/**\n * Identity of the adapter that actually prices this run's text.\n *\n * Every representation price now depends on the planner's counter (audit F01),\n * but the materialized representation key is bucketed rather than exact, so the\n * static `heuristic-v1` default let two counters share one key space: a run\n * could admit text at a price its own counter never produced, and the entry's\n * `tokenizer_mismatch` check compared that constant against itself. Probe a\n * non-empty string, because `countText(\"\")` short-circuits to the fallback\n * estimator in the registry and would report the wrong adapter.\n */\nexport function resolveEffectiveTokenizerIdV2(tokenCounter: TokenCounterAdapter | undefined, modelId: string): string {\n\treturn (tokenCounter ?? createFallbackTokenCounter()).countText(\" \", modelId).adapterId;\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\t// One counter prices the full text and every derived representation, so\n\t// the selector compares like with like (audit F01: a ratio-priced summary\n\t// was admitted into a budget its materialized text could not fit).\n\tconst countTokens = (text: string): number => counter.countText(text, modelId).tokens;\n\treturn items.map((item) => {\n\t\tconst overrideTokenEstimate = item.tokenEstimate ?? countTokens(item.text);\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, countTokens);\n\t\treturn {\n\t\t\titem: itemWithTokens,\n\t\t\tfullTokens,\n\t\t\tadmissibleTokens: minAdmissibleTokens(candidates, itemWithTokens, qualityPolicy, fullTokens),\n\t\t\tcandidates,\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"]}

package/dist/core/context-budget-v2-planned-items.js

@@ -16,19 +16,38 @@ function minAdmissibleTokens(candidates, item, policy, fullTokens) {
     }
     return Math.max(1, Number.isFinite(min) ? min : fullTokens);
 }
+/**
+ * Identity of the adapter that actually prices this run's text.
+ *
+ * Every representation price now depends on the planner's counter (audit F01),
+ * but the materialized representation key is bucketed rather than exact, so the
+ * static `heuristic-v1` default let two counters share one key space: a run
+ * could admit text at a price its own counter never produced, and the entry's
+ * `tokenizer_mismatch` check compared that constant against itself. Probe a
+ * non-empty string, because `countText("")` short-circuits to the fallback
+ * estimator in the registry and would report the wrong adapter.
+ */
+export function resolveEffectiveTokenizerIdV2(tokenCounter, modelId) {
+    return (tokenCounter ?? createFallbackTokenCounter()).countText(" ", modelId).adapterId;
+}
 export function createPlannedItems(items, tokenCounter, modelId, qualityPolicy) {
     const counter = tokenCounter ?? createFallbackTokenCounter();
+    // One counter prices the full text and every derived representation, so
+    // the selector compares like with like (audit F01: a ratio-priced summary
+    // was admitted into a budget its materialized text could not fit).
+    const countTokens = (text) => counter.countText(text, modelId).tokens;
     return items.map((item) => {
-        const overrideTokenEstimate = item.tokenEstimate ?? counter.countText(item.text, modelId).tokens;
+        const overrideTokenEstimate = item.tokenEstimate ?? countTokens(item.text);
         const itemWithTokens = item.tokenEstimate === undefined ? { ...item, tokenEstimate: overrideTokenEstimate } : item;
         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);
+        const candidates = itemWithTokens.representations ?? deriveRepresentationCandidates(itemWithTokens, qualityPolicy, countTokens);
         return {
             item: itemWithTokens,
             fullTokens,
             admissibleTokens: minAdmissibleTokens(candidates, itemWithTokens, qualityPolicy, fullTokens),
+            candidates,
             contentHash: contentHashOf(item.text),
             baseScore,
             redundancyPenalty: 0,

package/dist/core/context-budget-v2-planned-items.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget-v2-planned-items.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-planned-items.ts"],"names":[],"mappings":"AAAA,OAAO,EAGN,8BAA8B,EAC9B,cAAc,EAEd,wBAAwB,GACxB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,0BAA0B,EAA4B,MAAM,mCAAmC,CAAC;AACzG,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAsB,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAE9F,2EAA2E;AAC3E,0EAA0E;AAC1E,+DAA+D;AAC/D,SAAS,mBAAmB,CAC3B,UAAuD,EACvD,IAAyB,EACzB,MAA2C,EAC3C,UAAkB,EACT;IACT,IAAI,GAAG,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACnC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACpC,IACC,SAAS,CAAC,IAAI,KAAK,MAAM;YACzB,wBAAwB,CAAC,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC;YACjD,SAAS,CAAC,eAAe,GAAG,GAAG,EAC9B,CAAC;YACF,GAAG,GAAG,SAAS,CAAC,eAAe,CAAC;QACjC,CAAC;IACF,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC;AAAA,CAC5D;AAED,MAAM,UAAU,kBAAkB,CACjC,KAAqC,EACrC,YAA6C,EAC7C,OAAe,EACf,aAAoE,EAClD;IAClB,MAAM,OAAO,GAAG,YAAY,IAAI,0BAA0B,EAAE,CAAC;IAC7D,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QAC1B,MAAM,qBAAqB,GAAG,IAAI,CAAC,aAAa,IAAI,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC;QACjG,MAAM,cAAc,GACnB,IAAI,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,aAAa,EAAE,qBAAqB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7F,MAAM,UAAU,GAAG,cAAc,CAAC,cAAc,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,KAAK,MAAM,IAAI,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC;QAClE,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,wBAAwB,CAAC,cAAc,EAAE,UAAU,CAAC,CAAC;QAC3G,MAAM,UAAU,GACf,cAAc,CAAC,eAAe,IAAI,8BAA8B,CAAC,cAAc,EAAE,aAAa,CAAC,CAAC;QACjG,OAAO;YACN,IAAI,EAAE,cAAc;YACpB,UAAU;YACV,gBAAgB,EAAE,mBAAmB,CAAC,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,UAAU,CAAC;YAC5F,WAAW,EAAE,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC;YACrC,SAAS;YACT,iBAAiB,EAAE,CAAC;YACpB,cAAc,EAAE,SAAS;YACzB,MAAM;SACN,CAAC;IAAA,CACF,CAAC,CAAC;AAAA,CACH","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextRepresentationCandidateV2,\n\tderiveRepresentationCandidates,\n\tfullTextTokens,\n\ttype HeadroomQualityPolicyV2,\n\tisRepresentationEligible,\n} from \"./context-budget-headroom.ts\";\nimport { createFallbackTokenCounter, type TokenCounterAdapter } from \"./context-budget-token-counter.ts\";\nimport { contentHashOf } from \"./context-budget-v2-plan-hash.ts\";\nimport { type PlannedItemV2, scoreContextBudgetItemV2 } from \"./context-budget-v2-scoring.ts\";\n\n// Cheapest representation the chooser could actually pick: only candidates\n// passing the selection policy gate count, so a pointer the chooser would\n// reject cannot make an item look cheaper to admit than it is.\nfunction minAdmissibleTokens(\n\tcandidates: readonly ContextRepresentationCandidateV2[],\n\titem: ContextBudgetItemV2,\n\tpolicy: HeadroomQualityPolicyV2 | undefined,\n\tfullTokens: number,\n): number {\n\tlet min = Number.POSITIVE_INFINITY;\n\tfor (const candidate of candidates) {\n\t\tif (\n\t\t\tcandidate.kind !== \"omit\" &&\n\t\t\tisRepresentationEligible(candidate, item, policy) &&\n\t\t\tcandidate.estimatedTokens < min\n\t\t) {\n\t\t\tmin = candidate.estimatedTokens;\n\t\t}\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, itemWithTokens, qualityPolicy, 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"]}
+{"version":3,"file":"context-budget-v2-planned-items.js","sourceRoot":"","sources":["../../src/core/context-budget-v2-planned-items.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextRepresentationCandidateV2,\n\tderiveRepresentationCandidates,\n\tfullTextTokens,\n\ttype HeadroomQualityPolicyV2,\n\tisRepresentationEligible,\n} from \"./context-budget-headroom.ts\";\nimport { createFallbackTokenCounter, type TokenCounterAdapter } from \"./context-budget-token-counter.ts\";\nimport { contentHashOf } from \"./context-budget-v2-plan-hash.ts\";\nimport { type PlannedItemV2, scoreContextBudgetItemV2 } from \"./context-budget-v2-scoring.ts\";\n\n// Cheapest representation the chooser could actually pick: only candidates\n// passing the selection policy gate count, so a pointer the chooser would\n// reject cannot make an item look cheaper to admit than it is.\nfunction minAdmissibleTokens(\n\tcandidates: readonly ContextRepresentationCandidateV2[],\n\titem: ContextBudgetItemV2,\n\tpolicy: HeadroomQualityPolicyV2 | undefined,\n\tfullTokens: number,\n): number {\n\tlet min = Number.POSITIVE_INFINITY;\n\tfor (const candidate of candidates) {\n\t\tif (\n\t\t\tcandidate.kind !== \"omit\" &&\n\t\t\tisRepresentationEligible(candidate, item, policy) &&\n\t\t\tcandidate.estimatedTokens < min\n\t\t) {\n\t\t\tmin = candidate.estimatedTokens;\n\t\t}\n\t}\n\treturn Math.max(1, Number.isFinite(min) ? min : fullTokens);\n}\n\n/**\n * Identity of the adapter that actually prices this run's text.\n *\n * Every representation price now depends on the planner's counter (audit F01),\n * but the materialized representation key is bucketed rather than exact, so the\n * static `heuristic-v1` default let two counters share one key space: a run\n * could admit text at a price its own counter never produced, and the entry's\n * `tokenizer_mismatch` check compared that constant against itself. Probe a\n * non-empty string, because `countText(\"\")` short-circuits to the fallback\n * estimator in the registry and would report the wrong adapter.\n */\nexport function resolveEffectiveTokenizerIdV2(tokenCounter: TokenCounterAdapter | undefined, modelId: string): string {\n\treturn (tokenCounter ?? createFallbackTokenCounter()).countText(\" \", modelId).adapterId;\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\t// One counter prices the full text and every derived representation, so\n\t// the selector compares like with like (audit F01: a ratio-priced summary\n\t// was admitted into a budget its materialized text could not fit).\n\tconst countTokens = (text: string): number => counter.countText(text, modelId).tokens;\n\treturn items.map((item) => {\n\t\tconst overrideTokenEstimate = item.tokenEstimate ?? countTokens(item.text);\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, countTokens);\n\t\treturn {\n\t\t\titem: itemWithTokens,\n\t\t\tfullTokens,\n\t\t\tadmissibleTokens: minAdmissibleTokens(candidates, itemWithTokens, qualityPolicy, fullTokens),\n\t\t\tcandidates,\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"]}

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":"AA8BA,OAAO,EAIN,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAI9B,MAAM,8BAA8B,CAAC;AAEtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,0BAA0B,GAAG,yBAAyB,CAmOtG","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextRepresentationCandidateV2,\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 { validateBudgetItems } from \"./context-budget-v2-input-validation.ts\";\nimport { buildObservability } from \"./context-budget-v2-observability.ts\";\nimport { computePlanHash } from \"./context-budget-v2-plan-hash.ts\";\nimport { createPlannedItems } from \"./context-budget-v2-planned-items.ts\";\nimport { compareOptionalForSelection } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tapplyPlannerRedundancyPenalties,\n\tbuildTierAllocations,\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\tALL_TIERS_V2,\n\tCONTEXT_BUDGET_POLICY_VERSION_V2,\n\tDEFAULT_TIER_POLICY_V2,\n\ttype PromptContextBudgetInputV2,\n\ttype PromptContextBudgetPlanV2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetPolicyV2,\n} from \"./context-budget-v2-types.ts\";\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\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(\n\t\tvalidateBudgetItems(input.items, diagnostics),\n\t\tinput.tokenCounter,\n\t\tmodelId,\n\t\tqualityPolicy,\n\t);\n\t// Sanitized items can share a key with valid input, but their diagnostics cannot.\n\tconst canUsePlanCache = diagnostics.length === 0;\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\n\t// Floor-reservation pass: each tier spends its guaranteed claim (the\n\t// `allocated` field — hard demand, else demand capped at the floor) on its\n\t// own optional items before anything competes globally. A tier's floor is\n\t// therefore a real reservation, not a lower bound on its ceiling. Items\n\t// that cannot fit inside the remaining floor stay unselected for the\n\t// global pass; when the summed floors exceed the budget the reservation is\n\t// best-effort in tier order and the plan reports it explicitly.\n\t// One cache-resolution per item, shared by both passes so an item that is\n\t// deferred out of the floor and reconsidered globally does not double\n\t// count provider reads or redo materialization work.\n\tconst resolvedCandidates = new Map<string, readonly ContextRepresentationCandidateV2[]>();\n\tlet totalFloor = 0;\n\tfor (const tier of ALL_TIERS_V2) {\n\t\ttotalFloor += allocation.get(tier)?.floor ?? 0;\n\t}\n\tif (totalFloor > available) {\n\t\tdiagnostics.push({\n\t\t\treason: \"tier_floor_over_budget\",\n\t\t\tdetail: `tier floor guarantees total ${totalFloor} tokens against ${available} available; floors degrade to tier-order best effort`,\n\t\t});\n\t}\n\tfor (const tier of ALL_TIERS_V2) {\n\t\tconst floor = allocation.get(tier)?.floor ?? 0;\n\t\tif (floor <= 0 || tierUsed[tier] >= floor) continue;\n\t\tfor (const planned of optionalPlanned) {\n\t\t\tif (planned.item.tier !== tier || selection.has(planned.item.id)) continue;\n\t\t\tusedTokens = selectOptionalItem(planned, {\n\t\t\t\tallocation,\n\t\t\t\tavailable,\n\t\t\t\tcache,\n\t\t\t\tdiagnostics,\n\t\t\t\tomitted,\n\t\t\t\tqualityPolicy,\n\t\t\t\tretrievalFallbacks,\n\t\t\t\tselection,\n\t\t\t\ttierUsed,\n\t\t\t\tusedTokens,\n\t\t\t\tfloorReservation: { tier, floorTokens: floor },\n\t\t\t\tresolvedCandidates,\n\t\t\t});\n\t\t\tif (tierUsed[tier] >= floor || usedTokens >= available) break;\n\t\t}\n\t}\n\n\tfor (const planned of optionalPlanned) {\n\t\tif (selection.has(planned.item.id)) continue;\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\tresolvedCandidates,\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"]}
+{"version":3,"file":"context-budget-v2-planner.d.ts","sourceRoot":"","sources":["../../src/core/context-budget-v2-planner.ts"],"names":[],"mappings":"AA+BA,OAAO,EAIN,KAAK,0BAA0B,EAC/B,KAAK,yBAAyB,EAI9B,MAAM,8BAA8B,CAAC;AAEtC,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,0BAA0B,GAAG,yBAAyB,CAkOtG","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextRepresentationCandidateV2,\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 { runGlobalSelectionPass } from \"./context-budget-v2-global-pass.ts\";\nimport { validateBudgetItems } from \"./context-budget-v2-input-validation.ts\";\nimport { buildObservability } from \"./context-budget-v2-observability.ts\";\nimport { computePlanHash } from \"./context-budget-v2-plan-hash.ts\";\nimport { createPlannedItems, resolveEffectiveTokenizerIdV2 } from \"./context-budget-v2-planned-items.ts\";\nimport { compareOptionalForSelection } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tapplyPlannerRedundancyPenalties,\n\tbuildTierAllocations,\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\tALL_TIERS_V2,\n\tCONTEXT_BUDGET_POLICY_VERSION_V2,\n\tDEFAULT_TIER_POLICY_V2,\n\ttype PromptContextBudgetInputV2,\n\ttype PromptContextBudgetPlanV2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetPolicyV2,\n} from \"./context-budget-v2-types.ts\";\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\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(\n\t\tvalidateBudgetItems(input.items, diagnostics),\n\t\tinput.tokenCounter,\n\t\tmodelId,\n\t\tqualityPolicy,\n\t);\n\t// Sanitized items can share a key with valid input, but their diagnostics cannot.\n\tconst canUsePlanCache = diagnostics.length === 0;\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 ?? resolveEffectiveTokenizerIdV2(input.tokenCounter, modelId),\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\n\t// Floor-reservation pass: each tier spends its guaranteed claim (the\n\t// `allocated` field — hard demand, else demand capped at the floor) on its\n\t// own optional items before anything competes globally. A tier's floor is\n\t// therefore a real reservation, not a lower bound on its ceiling. Items\n\t// that cannot fit inside the remaining floor stay unselected for the\n\t// global pass; when the summed floors exceed the budget the reservation is\n\t// best-effort in tier order and the plan reports it explicitly.\n\t// One cache-resolution per item, shared by both passes so an item that is\n\t// deferred out of the floor and reconsidered globally does not double\n\t// count provider reads or redo materialization work.\n\tconst resolvedCandidates = new Map<string, readonly ContextRepresentationCandidateV2[]>();\n\tlet totalFloor = 0;\n\tfor (const tier of ALL_TIERS_V2) {\n\t\ttotalFloor += allocation.get(tier)?.floor ?? 0;\n\t}\n\tif (totalFloor > available) {\n\t\tdiagnostics.push({\n\t\t\treason: \"tier_floor_over_budget\",\n\t\t\tdetail: `tier floor guarantees total ${totalFloor} tokens against ${available} available; floors degrade to tier-order best effort`,\n\t\t});\n\t}\n\tfor (const tier of ALL_TIERS_V2) {\n\t\tconst floor = allocation.get(tier)?.floor ?? 0;\n\t\tif (floor <= 0 || tierUsed[tier] >= floor) continue;\n\t\tfor (const planned of optionalPlanned) {\n\t\t\tif (planned.item.tier !== tier || selection.has(planned.item.id)) continue;\n\t\t\tusedTokens = selectOptionalItem(planned, {\n\t\t\t\tallocation,\n\t\t\t\tavailable,\n\t\t\t\tcache,\n\t\t\t\tdiagnostics,\n\t\t\t\tomitted,\n\t\t\t\tqualityPolicy,\n\t\t\t\tretrievalFallbacks,\n\t\t\t\tselection,\n\t\t\t\ttierUsed,\n\t\t\t\tusedTokens,\n\t\t\t\tfloorReservation: { tier, floorTokens: floor },\n\t\t\t\tresolvedCandidates,\n\t\t\t});\n\t\t\tif (tierUsed[tier] >= floor || usedTokens >= available) break;\n\t\t}\n\t}\n\n\t// Global pass under tier ceilings, then promotion of floor-admitted items\n\t// with whatever the global pass left unused (audit F03).\n\tusedTokens = runGlobalSelectionPass(optionalPlanned, {\n\t\tallocation,\n\t\tavailable,\n\t\tcache,\n\t\tdiagnostics,\n\t\tomitted,\n\t\tqualityPolicy,\n\t\tresolvedCandidates,\n\t\tretrievalFallbacks,\n\t\tselection,\n\t\ttierUsed,\n\t\tusedTokens,\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"]}

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

@@ -1,9 +1,10 @@
 import { DEFAULT_HEADROOM_QUALITY_POLICY, } from "./context-budget-headroom.js";
 import { buildContextBudgetPlanCacheKeyV2, createContextBudgetCacheKeyBaseV2, createContextBudgetSelectionCacheV2, finalizeContextBudgetCacheTelemetryV2, readValidPlanCacheV2, writePlanCacheV2, } from "./context-budget-v2-cache.js";
+import { runGlobalSelectionPass } from "./context-budget-v2-global-pass.js";
 import { validateBudgetItems } from "./context-budget-v2-input-validation.js";
 import { buildObservability } from "./context-budget-v2-observability.js";
 import { computePlanHash } from "./context-budget-v2-plan-hash.js";
-import { createPlannedItems } from "./context-budget-v2-planned-items.js";
+import { createPlannedItems, resolveEffectiveTokenizerIdV2 } from "./context-budget-v2-planned-items.js";
 import { compareOptionalForSelection } from "./context-budget-v2-scoring.js";
 import { applyPlannerRedundancyPenalties, buildTierAllocations, createTierUsage, emitCoverageDiagnostics, emitOmissionDiagnostics, selectHardItem, selectOptionalItem, } from "./context-budget-v2-selection.js";
 import { allocateTiers, computeTierDemand } from "./context-budget-v2-tiers.js";
@@ -39,7 +40,7 @@ export function planPromptContextBudgetV2(input) {
         queryIntentHash: input.queryIntentHash,
         redactionPolicyHash: input.redactionPolicyHash,
         safetyProfileHash: input.safetyProfileHash,
-        tokenizerId: input.tokenizerId,
+        tokenizerId: input.tokenizerId ?? resolveEffectiveTokenizerIdV2(input.tokenCounter, modelId),
     });
     const planCacheKey = buildContextBudgetPlanCacheKeyV2({
         availableTokens: available,
@@ -133,23 +134,21 @@ export function planPromptContextBudgetV2(input) {
                 break;
         }
     }
-    for (const planned of optionalPlanned) {
-        if (selection.has(planned.item.id))
-            continue;
-        usedTokens = selectOptionalItem(planned, {
-            allocation,
-            available,
-            cache,
-            diagnostics,
-            omitted,
-            qualityPolicy,
-            resolvedCandidates,
-            retrievalFallbacks,
-            selection,
-            tierUsed,
-            usedTokens,
-        });
-    }
+    // Global pass under tier ceilings, then promotion of floor-admitted items
+    // with whatever the global pass left unused (audit F03).
+    usedTokens = runGlobalSelectionPass(optionalPlanned, {
+        allocation,
+        available,
+        cache,
+        diagnostics,
+        omitted,
+        qualityPolicy,
+        resolvedCandidates,
+        retrievalFallbacks,
+        selection,
+        tierUsed,
+        usedTokens,
+    });
     const omittedHighPriority = omitted.some((item) => item.priority === "high" || item.required === true);
     emitOmissionDiagnostics(omitted, diagnostics, retrievalFallbacks);
     emitCoverageDiagnostics(input.query, selection, diagnostics);

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,EAKN,+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,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC1E,OAAO,EAAE,2BAA2B,EAAE,MAAM,gCAAgC,CAAC;AAC7E,OAAO,EACN,+BAA+B,EAC/B,oBAAoB,EACpB,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,YAAY,EACZ,gCAAgC,EAChC,sBAAsB,GAMtB,MAAM,8BAA8B,CAAC;AAEtC,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;IAE1E,MAAM,UAAU,GAA8D;QAC7E,GAAG,sBAAsB;QACzB,GAAG,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC;KAC3B,CAAC;IACF,MAAM,WAAW,GAAG,kBAAkB,CACrC,mBAAmB,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC,EAC7C,KAAK,CAAC,YAAY,EAClB,OAAO,EACP,aAAa,CACb,CAAC;IACF,kFAAkF;IAClF,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,KAAK,CAAC,CAAC;IACjD,+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,sBAAsB,EAAE,KAAK,CAAC,sBAAsB;QACpD,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;IAE3G,qEAAqE;IACrE,6EAA2E;IAC3E,0EAA0E;IAC1E,wEAAwE;IACxE,qEAAqE;IACrE,2EAA2E;IAC3E,gEAAgE;IAChE,0EAA0E;IAC1E,sEAAsE;IACtE,qDAAqD;IACrD,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAuD,CAAC;IAC1F,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QACjC,UAAU,IAAI,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,UAAU,GAAG,SAAS,EAAE,CAAC;QAC5B,WAAW,CAAC,IAAI,CAAC;YAChB,MAAM,EAAE,wBAAwB;YAChC,MAAM,EAAE,+BAA+B,UAAU,mBAAmB,SAAS,sDAAsD;SACnI,CAAC,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC;QAC/C,IAAI,KAAK,IAAI,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,KAAK;YAAE,SAAS;QACpD,KAAK,MAAM,OAAO,IAAI,eAAe,EAAE,CAAC;YACvC,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBAAE,SAAS;YAC3E,UAAU,GAAG,kBAAkB,CAAC,OAAO,EAAE;gBACxC,UAAU;gBACV,SAAS;gBACT,KAAK;gBACL,WAAW;gBACX,OAAO;gBACP,aAAa;gBACb,kBAAkB;gBAClB,SAAS;gBACT,QAAQ;gBACR,UAAU;gBACV,gBAAgB,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE;gBAC9C,kBAAkB;aAClB,CAAC,CAAC;YACH,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,UAAU,IAAI,SAAS;gBAAE,MAAM;QAC/D,CAAC;IACF,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,eAAe,EAAE,CAAC;QACvC,IAAI,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,SAAS;QAC7C,UAAU,GAAG,kBAAkB,CAAC,OAAO,EAAE;YACxC,UAAU;YACV,SAAS;YACT,KAAK;YACL,WAAW;YACX,OAAO;YACP,aAAa;YACb,kBAAkB;YAClB,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","sourcesContent":["import {\n\ttype ContextBudgetItemV2,\n\ttype ContextBudgetTierV2,\n\ttype ContextRepresentationCandidateV2,\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 { validateBudgetItems } from \"./context-budget-v2-input-validation.ts\";\nimport { buildObservability } from \"./context-budget-v2-observability.ts\";\nimport { computePlanHash } from \"./context-budget-v2-plan-hash.ts\";\nimport { createPlannedItems } from \"./context-budget-v2-planned-items.ts\";\nimport { compareOptionalForSelection } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tapplyPlannerRedundancyPenalties,\n\tbuildTierAllocations,\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\tALL_TIERS_V2,\n\tCONTEXT_BUDGET_POLICY_VERSION_V2,\n\tDEFAULT_TIER_POLICY_V2,\n\ttype PromptContextBudgetInputV2,\n\ttype PromptContextBudgetPlanV2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetPolicyV2,\n} from \"./context-budget-v2-types.ts\";\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\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(\n\t\tvalidateBudgetItems(input.items, diagnostics),\n\t\tinput.tokenCounter,\n\t\tmodelId,\n\t\tqualityPolicy,\n\t);\n\t// Sanitized items can share a key with valid input, but their diagnostics cannot.\n\tconst canUsePlanCache = diagnostics.length === 0;\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\n\t// Floor-reservation pass: each tier spends its guaranteed claim (the\n\t// `allocated` field — hard demand, else demand capped at the floor) on its\n\t// own optional items before anything competes globally. A tier's floor is\n\t// therefore a real reservation, not a lower bound on its ceiling. Items\n\t// that cannot fit inside the remaining floor stay unselected for the\n\t// global pass; when the summed floors exceed the budget the reservation is\n\t// best-effort in tier order and the plan reports it explicitly.\n\t// One cache-resolution per item, shared by both passes so an item that is\n\t// deferred out of the floor and reconsidered globally does not double\n\t// count provider reads or redo materialization work.\n\tconst resolvedCandidates = new Map<string, readonly ContextRepresentationCandidateV2[]>();\n\tlet totalFloor = 0;\n\tfor (const tier of ALL_TIERS_V2) {\n\t\ttotalFloor += allocation.get(tier)?.floor ?? 0;\n\t}\n\tif (totalFloor > available) {\n\t\tdiagnostics.push({\n\t\t\treason: \"tier_floor_over_budget\",\n\t\t\tdetail: `tier floor guarantees total ${totalFloor} tokens against ${available} available; floors degrade to tier-order best effort`,\n\t\t});\n\t}\n\tfor (const tier of ALL_TIERS_V2) {\n\t\tconst floor = allocation.get(tier)?.floor ?? 0;\n\t\tif (floor <= 0 || tierUsed[tier] >= floor) continue;\n\t\tfor (const planned of optionalPlanned) {\n\t\t\tif (planned.item.tier !== tier || selection.has(planned.item.id)) continue;\n\t\t\tusedTokens = selectOptionalItem(planned, {\n\t\t\t\tallocation,\n\t\t\t\tavailable,\n\t\t\t\tcache,\n\t\t\t\tdiagnostics,\n\t\t\t\tomitted,\n\t\t\t\tqualityPolicy,\n\t\t\t\tretrievalFallbacks,\n\t\t\t\tselection,\n\t\t\t\ttierUsed,\n\t\t\t\tusedTokens,\n\t\t\t\tfloorReservation: { tier, floorTokens: floor },\n\t\t\t\tresolvedCandidates,\n\t\t\t});\n\t\t\tif (tierUsed[tier] >= floor || usedTokens >= available) break;\n\t\t}\n\t}\n\n\tfor (const planned of optionalPlanned) {\n\t\tif (selection.has(planned.item.id)) continue;\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\tresolvedCandidates,\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"]}
+{"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 ContextRepresentationCandidateV2,\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 { runGlobalSelectionPass } from \"./context-budget-v2-global-pass.ts\";\nimport { validateBudgetItems } from \"./context-budget-v2-input-validation.ts\";\nimport { buildObservability } from \"./context-budget-v2-observability.ts\";\nimport { computePlanHash } from \"./context-budget-v2-plan-hash.ts\";\nimport { createPlannedItems, resolveEffectiveTokenizerIdV2 } from \"./context-budget-v2-planned-items.ts\";\nimport { compareOptionalForSelection } from \"./context-budget-v2-scoring.ts\";\nimport {\n\tapplyPlannerRedundancyPenalties,\n\tbuildTierAllocations,\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\tALL_TIERS_V2,\n\tCONTEXT_BUDGET_POLICY_VERSION_V2,\n\tDEFAULT_TIER_POLICY_V2,\n\ttype PromptContextBudgetInputV2,\n\ttype PromptContextBudgetPlanV2,\n\ttype QualityDiagnosticV2,\n\ttype SelectedRepresentationV2,\n\ttype TierBudgetPolicyV2,\n} from \"./context-budget-v2-types.ts\";\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\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(\n\t\tvalidateBudgetItems(input.items, diagnostics),\n\t\tinput.tokenCounter,\n\t\tmodelId,\n\t\tqualityPolicy,\n\t);\n\t// Sanitized items can share a key with valid input, but their diagnostics cannot.\n\tconst canUsePlanCache = diagnostics.length === 0;\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 ?? resolveEffectiveTokenizerIdV2(input.tokenCounter, modelId),\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\n\t// Floor-reservation pass: each tier spends its guaranteed claim (the\n\t// `allocated` field — hard demand, else demand capped at the floor) on its\n\t// own optional items before anything competes globally. A tier's floor is\n\t// therefore a real reservation, not a lower bound on its ceiling. Items\n\t// that cannot fit inside the remaining floor stay unselected for the\n\t// global pass; when the summed floors exceed the budget the reservation is\n\t// best-effort in tier order and the plan reports it explicitly.\n\t// One cache-resolution per item, shared by both passes so an item that is\n\t// deferred out of the floor and reconsidered globally does not double\n\t// count provider reads or redo materialization work.\n\tconst resolvedCandidates = new Map<string, readonly ContextRepresentationCandidateV2[]>();\n\tlet totalFloor = 0;\n\tfor (const tier of ALL_TIERS_V2) {\n\t\ttotalFloor += allocation.get(tier)?.floor ?? 0;\n\t}\n\tif (totalFloor > available) {\n\t\tdiagnostics.push({\n\t\t\treason: \"tier_floor_over_budget\",\n\t\t\tdetail: `tier floor guarantees total ${totalFloor} tokens against ${available} available; floors degrade to tier-order best effort`,\n\t\t});\n\t}\n\tfor (const tier of ALL_TIERS_V2) {\n\t\tconst floor = allocation.get(tier)?.floor ?? 0;\n\t\tif (floor <= 0 || tierUsed[tier] >= floor) continue;\n\t\tfor (const planned of optionalPlanned) {\n\t\t\tif (planned.item.tier !== tier || selection.has(planned.item.id)) continue;\n\t\t\tusedTokens = selectOptionalItem(planned, {\n\t\t\t\tallocation,\n\t\t\t\tavailable,\n\t\t\t\tcache,\n\t\t\t\tdiagnostics,\n\t\t\t\tomitted,\n\t\t\t\tqualityPolicy,\n\t\t\t\tretrievalFallbacks,\n\t\t\t\tselection,\n\t\t\t\ttierUsed,\n\t\t\t\tusedTokens,\n\t\t\t\tfloorReservation: { tier, floorTokens: floor },\n\t\t\t\tresolvedCandidates,\n\t\t\t});\n\t\t\tif (tierUsed[tier] >= floor || usedTokens >= available) break;\n\t\t}\n\t}\n\n\t// Global pass under tier ceilings, then promotion of floor-admitted items\n\t// with whatever the global pass left unused (audit F03).\n\tusedTokens = runGlobalSelectionPass(optionalPlanned, {\n\t\tallocation,\n\t\tavailable,\n\t\tcache,\n\t\tdiagnostics,\n\t\tomitted,\n\t\tqualityPolicy,\n\t\tresolvedCandidates,\n\t\tretrievalFallbacks,\n\t\tselection,\n\t\ttierUsed,\n\t\tusedTokens,\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"]}

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

@@ -1,4 +1,4 @@
-import type { ContextBudgetItemV2 } from "./context-budget-headroom.ts";
+import type { ContextBudgetItemV2, ContextRepresentationCandidateV2 } from "./context-budget-headroom.ts";
 export interface PlannedItemV2 {
     readonly item: ContextBudgetItemV2;
     readonly fullTokens: number;
@@ -8,6 +8,12 @@ export interface PlannedItemV2 {
      * cheaper pointer/summary/headroom representation.
      */
     readonly admissibleTokens: number;
+    /**
+     * Representations priced with the planner's token counter. Selection must
+     * choose from these rather than re-deriving with a different estimator, or
+     * the cost an item was ranked on and the cost it pays can diverge.
+     */
+    readonly candidates?: readonly ContextRepresentationCandidateV2[];
     readonly contentHash: string;
     readonly baseScore: number;
     redundancyPenalty: number;

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;;;;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;AAsBD,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\n/** E-folding time in turns: at this age the factor is exp(-1), not one half. */\nconst RECENCY_TIME_CONSTANT_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\tconst aScore = Number.isNaN(a.effectiveScore) ? Number.NEGATIVE_INFINITY : a.effectiveScore;\n\tconst bScore = Number.isNaN(b.effectiveScore) ? Number.NEGATIVE_INFINITY : b.effectiveScore;\n\tif (bScore !== aScore) return bScore - aScore;\n\tconst priorityDelta = priorityRank(b.item.priority) - priorityRank(a.item.priority);\n\tif (priorityDelta !== 0) {\n\t\treturn priorityDelta;\n\t}\n\tconst aTokens = Number.isNaN(a.fullTokens) ? Number.POSITIVE_INFINITY : a.fullTokens;\n\tconst bTokens = Number.isNaN(b.fullTokens) ? Number.POSITIVE_INFINITY : b.fullTokens;\n\tif (aTokens !== bTokens) return aTokens - bTokens;\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 timeConstant = RECENCY_TIME_CONSTANT_BY_TIER[item.tier] ?? 6;\n\treturn clamp01(Math.exp(-age / timeConstant));\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\tconst value = planned.effectiveScore / Math.max(planned.admissibleTokens, 1);\n\treturn Number.isNaN(value) ? 0 : value;\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,EACX,mBAAmB,EAGnB,gCAAgC,EAChC,MAAM,8BAA8B,CAAC;AAEtC,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;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gCAAgC,EAAE,CAAC;IAClE,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;AAsBD,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 {\n\tContextBudgetItemV2,\n\tContextBudgetPriorityV2,\n\tContextBudgetTierV2,\n\tContextRepresentationCandidateV2,\n} 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\t/**\n\t * Representations priced with the planner's token counter. Selection must\n\t * choose from these rather than re-deriving with a different estimator, or\n\t * the cost an item was ranked on and the cost it pays can diverge.\n\t */\n\treadonly candidates?: readonly ContextRepresentationCandidateV2[];\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\n/** E-folding time in turns: at this age the factor is exp(-1), not one half. */\nconst RECENCY_TIME_CONSTANT_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\tconst aScore = Number.isNaN(a.effectiveScore) ? Number.NEGATIVE_INFINITY : a.effectiveScore;\n\tconst bScore = Number.isNaN(b.effectiveScore) ? Number.NEGATIVE_INFINITY : b.effectiveScore;\n\tif (bScore !== aScore) return bScore - aScore;\n\tconst priorityDelta = priorityRank(b.item.priority) - priorityRank(a.item.priority);\n\tif (priorityDelta !== 0) {\n\t\treturn priorityDelta;\n\t}\n\tconst aTokens = Number.isNaN(a.fullTokens) ? Number.POSITIVE_INFINITY : a.fullTokens;\n\tconst bTokens = Number.isNaN(b.fullTokens) ? Number.POSITIVE_INFINITY : b.fullTokens;\n\tif (aTokens !== bTokens) return aTokens - bTokens;\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 timeConstant = RECENCY_TIME_CONSTANT_BY_TIER[item.tier] ?? 6;\n\treturn clamp01(Math.exp(-age / timeConstant));\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\tconst value = planned.effectiveScore / Math.max(planned.admissibleTokens, 1);\n\treturn Number.isNaN(value) ? 0 : value;\n}\n"]}