withCompactionTriggerTokens function

CompactionSettings withCompactionTriggerTokens(CompactionSettings base, { required int window, required int triggerTokens, })

Applies triggerTokens as the compaction firing point to base for a model whose (effective) context window is window.

The trigger of CompactionSettings is window - reserveTokens (shouldCompact); reaching trigger triggerTokens therefore raises the reserve to window - triggerTokens. Two guards keep the pass sane:

• the kept recent region never exceeds half the trigger — a pass always frees tokens, never reshuffles the same budget;
• a trigger at/above the settings' own default threshold is a no-op (the bench knob can only LOWER the trigger, never raise it). A trigger at/above the window clamps to window, which always satisfies this guard — it is the same no-op, never a "fire at the window" outcome.

Pure; returns base unchanged when the trigger changes nothing.

Implementation

CompactionSettings withCompactionTriggerTokens(
  CompactionSettings base, {
  required int window,
  required int triggerTokens,
}) {
  if (!base.enabled) return base;
  final clamped = triggerTokens.clamp(1, window);
  final defaultTrigger = window - base.reserveTokens;
  if (clamped >= defaultTrigger) return base;
  // max<int>(…): a trigger of 1 makes `clamped ~/ 2` 0, and `int.clamp`
  // throws when the lower limit exceeds the upper — a parse-valid env
  // value must degrade, never kill the run (gh-1604 rework). The explicit
  // type argument keeps the static type int under clamp's `num` context.
  final keep = base.keepRecentTokens.clamp(1, max<int>(1, clamped ~/ 2));
  return CompactionSettings(
    enabled: true,
    reserveTokens: window - clamped,
    keepRecentTokens: keep,
  );
}