fix(config): NudgeConfig docstring defaults drift from actuals; validateConfig accepts non-finite nudge scalars that silently kill growth nudges

[Tyan66666]

Problem

Two defects found while auditing the npm package (0.0.29) during a downstream host-adapter review (billion-context-dsh PR #72); both re-verified against the v0.0.45 source today and still present.

1. NudgeConfig docstrings drift from actual defaults (src/types.ts)

Field	Docstring says	Actual default (defaultConfig, src/config.ts)
minGrowthFloor	Default 5000 (src/types.ts:124)	20000 (src/config.ts:18)
emergencyThresholdPct	Default 0.98 (98%) (src/types.ts:129)	0.95 (src/config.ts:20)

The other 10 nudge fields' docstrings were checked against defaultConfig() and are correct.

Impact: these docstrings are the only tuning contract for config authors — e.g. someone relying on "Default 0.98" will misdiagnose why emergency nudges start at 95%; anti-thrash floor math computed from a 5000 base is off by 4×. The published .d.ts in the npm tarball carries the same stale text.

2. validateConfig accepts non-finite / out-of-range nudge scalars, which silently disable growth nudges

validateConfig (src/config.ts:55) checks only ordering relations among the pct fields (min <= max <= emergency). None of the 12 nudge scalars gets a Number.isFinite or range check — and since every comparison against NaN is false, a NaN anywhere passes with zero errors.

Empirical failure chain for nudge.growthFloor: NaN (probed live on 0.0.29; code path identical at v0.0.45):

// resolveAdaptiveGrowth, src/compress.ts:1015
nudgeGrowthTokens = Math.min(cap, Math.max(NaN, Math.round(limit * ratio)))   // → NaN
// anti-thrash floor, src/compress.ts:1097
growthFloor = Math.max(minGrowthFloor, minGrowthRatio * NaN)                  // → NaN
// src/compress.ts:1122
growthReady = growthSinceReference >= NaN                                     // → false forever

Net effect: the growth-gated nudge path (the normal working band below maxContextLimitPct) never fires again; only the pressure band (usage >= maxContextLimitPct / emergency) still fires when pending content exists. No error, no warning — validateConfig returns [] and processing proceeds normally (call site src/compress.ts:351).

Also unvalidated today: negative or >1 pct values, frequency/iterationThreshold < 1, negative floors/caps. Conspicuous because the newer absorb config does get Number.isFinite checks (src/config.ts:90), so nudge is now the gap.

Fix (suggestion)

1. Correct the two docstrings; optionally add a test asserting docstring defaults match defaultConfig() output to stop future drift.
2. Extend validateConfig: Number.isFinite on all nudge scalars; [0, 1] range for maxContextLimitPct/minContextLimitPct/emergencyThresholdPct; > 0 for growthRatio/minGrowthRatio/tier2GrowthMultiplier; >= 0 (integer where sensible) for frequency/iterationThreshold/growthFloor/growthCap/minGrowthFloor. The existing ordering checks stay and become meaningful once finiteness is guaranteed.

Happy to send a PR if you'd take one.

[ranxianglei]

review 这个 pr 说出为什么要修改 是否引入缓存命中率问题 是否影响注入频率 是否影响所有下游 修复是否正确

[ranxianglei]

先澄清一点：#163 目前是 issue（bug report），不是 PR —— 仓库里没有对应的 PR 分支（refs/pull/163 不存在）。以下按 issue 中的问题描述和 proposed fix，对照 v0.0.45 与当前 master（bed2501）逐条 review 并做了实证验证。

1. 为什么要修改 —— 两个缺陷都属实，且 issue 少报了一个

Docstring 漂移（v0.0.45 与 master 均验证）：

• minGrowthFloor：docstring 写 "Default 5000"（src/types.ts:129），实际默认 20000（src/config.ts:18）—— 4 倍偏差
• emergencyThresholdPct：docstring 写 "Default 0.98"（src/types.ts:133），实际 0.95（src/config.ts:20）
• .d.ts docstring 是下游 config 作者唯一的调参契约，npm tarball 里发布的 .d.ts 带着同样的错误文本，漂移会直接导致误诊。

issue 的审计其实漏了第三处漂移：src/types.ts:125 的注释挂在 growthFloor 上，内容却是 growthRatio 的描述——"Adaptive growth threshold = modelContextLimit × this ratio, clamped to [growthFloor, growthCap]. Default 0.05 (5%)"——而 growthFloor 实际默认是 50000，growthRatio 本身（src/types.ts:124）反而没有 docstring。所以"其余 10 个字段 docstring 正确"的说法不成立，实际有 3 处错误。

validateConfig 缺口（已实证）：

• src/config.ts:55-103 对 nudge 只有两个 ordering 检查（min≤max≤emergency），无任何 finiteness/range 检查
• NaN 在所有比较中静默通过：NaN > 0.75 = false、0.75 > NaN = false → 返回零错误
• NaN 传染链（已用 node 复现）：growthFloor: NaN → nudgeGrowthTokens = Math.min(growthCap, Math.max(NaN, …)) = NaN（src/compress.ts:1020-1026）→ anti-thrash floor Math.max(minGrowthFloor, minGrowthRatio × NaN) = NaN（src/compress.ts:1097-1100）→ growthReady = x >= NaN 恒为 false（src/compress.ts:1125）→ growth-gated nudge 路径永久失效；调用点（src/compress.ts:351-356）只对 validateConfig 结果 console.warn，而结果是空数组 → 全程无声
• 影响面比 issue 描述更广：maxContextLimitPct/emergencyThresholdPct 为 NaN 时 pressure band 同样失效（usage >= NaN 恒 false，src/compress.ts:1076-1077）；tier2GrowthMultiplier 为 NaN 时 T2/T3 的 token-mass 路径失效（tier2Threshold = NaN，src/compress.ts:1120-1122），只剩 count 路径。issue 提出的"对全部 12 个标量做 isFinite"恰好覆盖这些，方向正确
• absorb config 确实已有 Number.isFinite 检查（src/config.ts:89-94），nudge 是不一致的缺口，属实

2. 是否引入缓存命中率问题 —— 不会

• 修复只动 (a) types.ts 的 doc 注释（非运行时代码）和 (b) validateConfig（纯函数，返回字符串数组）
• 调用点 src/compress.ts:351-356 仅 console.warn —— warning 进宿主 stderr，不进对话。不产生新消息内容、不改 ref tag、不改渲染文本、不改任何 state
• 对合法 config（含全部默认值），nudge 决策在修复前后逐位一致 —— 新增检查只对本来就已损坏的 config 触发。前缀缓存键（渲染后的消息序列）不变，缓存命中率不受影响

3. 是否影响注入频率 —— 对任何当前正常工作的 config 无变化

• 合法 config：零行为变化（新检查全部通过；decideNudge 决策逻辑未动）。已验证默认值通过所有新增检查：0.75/0.45/0.95 ∈ [0,1]；0.05/0.45/1.5 > 0；5/15/50000/50000/20000 ≥ 0
• 损坏 config（NaN）：修复前后运行时行为相同（nudge 依旧失效）—— 修复只是让问题通过 console.warn 可见。注入频率只有在宿主据此修好 config 后才会恢复
• 额外发现：frequency 和 iterationThreshold 是死字段 —— 在 NudgeConfig 中声明（src/types.ts:121-122）、有默认值 5/15（src/config.ts:12-13），但 src/ 全目录 grep 无任何读取点（唯一命中是 search tokenizer 里无关的 "Term-frequency" 注释）。实际节奏由 growthFloor/minGrowthRatio + lastShownByTier 控制（src/compress.ts:1171, 1186, 1227）。所以调这两个字段今天对注入频率就没有任何作用；proposed fix 对它们做 >= 0 校验无害，但校验的是 no-op。建议另开 issue 处理移除或接线

4. 是否影响所有下游 —— 无破坏性影响

• validateConfig 错误是 warn-only —— processTurn 不抛异常，下游（pai-acp 等）任何调用点都不会 break
• 传合法 config 的下游：零变化
• 传 NaN/越界标量的下游：开始能看到 console.warn 行；它们的 nudge 路径本来就已静默失效。若某 adapter 把 validateConfig 当严格 preflight 并拒绝，回退 defaultConfig 恰好是正确结果
• 错误字符串纯增量，不删除/改名任何现有错误；.d.ts docstring 变更是 semver-patch 安全的
• 唯一 caveat：解析或统计 console.warn 输出的 adapter 会看到更多行 —— 可忽略

5. 修复是否正确 —— 方向正确，需补 3 点

1. docstring 修复不完整：PR 必须修全部 3 处 —— minGrowthFloor 5000→20000、emergencyThresholdPct 0.98→0.95、以及 growthFloor 的 docstring（当前挂着 growthRatio 的 "Default 0.05 (5%)" 文本，应改为 "Lower clamp for adaptive growth threshold. Default 50000."），并把 ratio 描述补到 growthRatio 上
2. validateConfig 扩展正确：与现有 absorb（src/config.ts:89-94）和 truncate.threshold（src/config.ts:76-78）检查风格一致；finiteness 保证后 ordering 检查才有意义；默认值全部通过
3. 缺口：
   • 修复是 "fail loud" 而非 "fail safe"：调用点只 warn，损坏 config 在宿主修好之前仍产生死掉的 nudge 路径。可考虑（follow-up）kernel 对非法值按字段回退默认值 —— 超出本 issue 范围的设计决策
   • force: "soft"|"strong" 未校验（字符串而非标量）—— 小缺口，可选
   • proposed 的漂移防护测试（断言 docstring 默认值与 defaultConfig() 一致）是好守卫；简单实现：从 types.ts 解析 "Default X" 字符串与 defaultConfig() 输出比对

结论：issue 两个核心主张均经 v0.0.45 与 master 验证属实（含实证复现 NaN 链）；proposed fix 方向正确、无破坏性；将来发 PR 时必须覆盖 issue 自己漏掉的第三处 docstring 漂移。

[ranxianglei]

ework复核这个

[ranxianglei]

复核完成。对当前 master（bed2501）重新独立验证了原 review 的每条结论（重新读码 + 重跑探针，非引用旧结论），全部成立，无需更正。

逐项复核结果：

1. fix(config): NudgeConfig docstring defaults drift from actuals; validateConfig accepts non-finite nudge scalars that silently kill growth nudges #163 是 issue 非 PR —— git ls-remote origin refs/pull/163/* 为空，无对应 PR 分支。✓

2. 3 处 docstring 漂移（src/types.ts，master 行号；对照 defaultConfig src/config.ts:9-22 重新核对）：

   • growthFloor（:126）的 docstring 挂在 :125，内容是 growthRatio 的 "Default 0.05 (5%)"，实际默认 50000 ✗
   • minGrowthFloor（:130）docstring :129 "Default 5000"，实际 20000 ✗
   • emergencyThresholdPct（:134）docstring :133 "Default 0.98 (98%)"，实际 0.95 ✗
   • 其余 3 个有 docstring 的字段（growthCap 50000、minGrowthRatio 0.45、tier2GrowthMultiplier 1.5）均正确 ✓
   • v0.0.45 同样存在这 3 处（git show 复核）✓

3. validateConfig 缺口 —— 用类型剥离后的真实 config.ts 重跑探针：11 个 nudge 标量逐一置 NaN，validateConfig 全部返回 []（零错误）。src/config.ts:63-72 确实只有两个 ordering 检查，无任何 finiteness/range 检查。✓

4. NaN 传染链 —— 重新复现：growthFloor=NaN → nudgeGrowthTokens=NaN（compress.ts:1020-1026）→ growthFloor=NaN（:1097-1100）→ growthReady 恒 false（:1125）；同时 tier2Threshold=NaN（:1120-1122，T2/T3 token-mass 路径失效），而 overLimit 仍 true（:1076，pressure band 存活）。与 issue 描述一致，且影响面更广。✓

5. frequency / iterationThreshold 死字段 —— 全 src/ grep 仅 config.ts 默认值 + types.ts 声明，无读取点。✓

6. 默认值通过所有新增检查 —— 探针确认：pct∈[0,1]、ratios>0、floors/caps/freq/iter≥0 全为 true。✓

7. absorb 已有 Number.isFinite（src/config.ts:89-94）、truncate.threshold∈(0,1]（:76-78）—— 复核属实，nudge 确为不一致缺口。✓

复核中新增的一点（强化原结论，非更正）：
现有 ordering 检查只是"碰巧"拦下部分越界 pct（如 max=1.5 会因 > emergency 0.95 被报），但拦不全 —— 例如 maxContextLimitPct=1.2 配 emergencyThresholdPct=1.5，两者都越出 [0,1]，却因 1.2<1.5 通过 ordering 检查、零报错。这进一步说明必须加显式 [0,1] range 检查，不能依赖 ordering 兜底。

关于 force：复核发现 force 在 kernel 内同样无读取点（仅声明/默认/tests），但它可能由下游 adapter（pai-acp 等）消费以决定 soft/strong 语气，故维持原 review 的"未校验（小缺口，可选）"定性，不升级为"死字段"。

结论：原 review 全部结论经独立复核成立，无需更正。issue 两个核心主张 + 我补充的第三处漂移均属实；proposed fix 方向正确、无破坏性，可据此发 PR（须覆盖全部 3 处 docstring 漂移）。

_{🤖 ework agent · vllm-qwen/qwen3.8-27b}