Skip to content

[PR] docs(image-rescale): reconcile the forced-path trigger-gate comments with the code - #7152

Open
ranxianglei wants to merge 3 commits into
masterfrom
2026-11-18_forced-path-image-rescale-docs
Open

ranxianglei wants to merge 3 commits into
masterfrom
2026-11-18_forced-path-image-rescale-docs

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #7150

What

The two comments describing shedDownscaleImage's forced path contradicted each other and both misstated the code:

  • The doRescale header comment (above the gate) claimed "A within-maxDim image is NOT skipped here" — wrong for below-trigger within-maxDim images, which ARE skipped.
  • The shedDownscaleImage doc claimed "there is no trigger gate ... images already within maxDim are left alone" — wrong for above-trigger within-maxDim images, which ARE re-encoded (adopted only if strictly smaller).

Design answer

The within-maxDim trigger gate in the forced path is INTENDED, not a bug. The byte-shed ladder's job is byte reduction; a large (above-trigger) within-maxDim image that re-encodes smaller is a legitimate target, and the keep-smaller check (out.length >= origBytes) makes it safe — no adoption unless it actually shrinks. The 100 KiB clause is a cheap pre-filter to skip the expensive decode+re-encode of small images that are unlikely to shrink. The caller (src/egress-shed.ts:308-310) pre-filters known-dim within-maxDim images, so the within-maxDim forced branch is defensive (only hit when the header parse disagrees with the authoritative Jimp.read).

So: code stays; both comments get reconciled to the actual truth table:

Case Trigger gate Adopted when
above-maxDim (scale<1) not applied strictly smaller
within-maxDim, ≤100KiB applied (skipped) —
within-maxDim, >100KiB not applied strictly smaller

Changes

Behavior change

None. Docs-only + test. The code path is unchanged (the forced condition is bit-identical before/after).

…with the code

The two comments describing shedDownscaleImage's forced path contradicted
each other and both misstated the code:

- The doRescale header comment claimed "A within-maxDim image is NOT skipped
  here" — wrong for below-trigger within-maxDim images, which ARE skipped.
- The shedDownscaleImage doc claimed "there is no trigger gate ... images
  already within maxDim are left alone" — wrong for above-trigger within-
  maxDim images, which ARE re-encoded (adopted only if strictly smaller).

The code (doRescale gate) is correct: the 100 KiB trigger gate applies ONLY to
within-maxDim images as a cheap pre-filter (skip small, re-encode large);
above-maxDim images are always re-encoded. Both comments now state the actual
truth table.

Adds a regression test pinning both gate directions (#3617): below-trigger
within-maxDim is skipped, above-trigger within-maxDim is re-encoded and adopted.

Closes #7150
@ranxianglei ranxianglei added documentation Improvements or additions to documentation image p3 scope/docs labels Nov 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-11-18_forced-path-image-rescale-docs (79fc0ff)

Latest build — install this exact version

npm install -g billion-context@0.0.11117-pr.7152.db3e7b1

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit version build
79fc0ff billion-context@0.0.11117-pr.7152.db3e7b1 build
0108a5b billion-context@0.0.10812-pr.7152.8b9b045 build
cfab299 billion-context@0.0.10804-pr.7152.cabe856 build

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr7152.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei ranxianglei changed the title docs(image-rescale): reconcile the forced-path trigger-gate comments with the code [PR] docs(image-rescale): reconcile the forced-path trigger-gate comments with the code Nov 18, 2026
…ate comment

The rung B pre-filter (egress-shed) only skips KNOWN-dim within-maxDim
images (dims !== undefined && max <= dim), so the defensive within-maxDim
branch is also hit when the header dim parse FAILS (dims === undefined)
and the decode shows within-maxDim — not only when the parse disagrees
with the decode. Align the comment with that exact condition.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重: 不重复。 Searched open+closed for image-rescale forced-path / shedDownscaleImage doc inconsistencies: only the source #7150 and this PR. Other image-rescale issues (#4789, #6846, #6085/#6086, #4070) are different mechanisms (cache-key size limit, cache retention, PTC double-rescale) — none about the forced-path gate comments.

Review of PR #7152 (head 2026-11-18_forced-path-image-rescale-docs, single commit cfab299c + my one-line follow-up below):

  • Comments vs code — verified line by line. The gate is if (scale >= 1 && (!force || origBytes <= RESCALE_TRIGGER_BYTES)) return null; with RESCALE_TRIGGER_BYTES = 100 * 1024 (src/image-rescale.ts:42,166) and the forced keep-smaller check out.length >= origBytes (strict). Both reconciled comments now match the code's exact truth table; the old comments were indeed both wrong, exactly as [Drive-by] forced-path image-rescale docs contradict the code on within-maxDim handling #7150 diagnosed.
  • Design answer ("the gate is INTENDED") — independently confirmed. git log -L shows the !force || clause in the forced path exists since the file's first version — the gate is the original design, not drift. The caller pre-filter is exactly where the PR says (src/egress-shed.ts:308-310, rung B: dims !== undefined && max <= dim → continue), so the within-maxDim forced branch is defensive. Removing the gate would change behavior (re-encode small images, CPU for unlikely shrinkage) — a product decision; keeping the code and fixing the docs is the right, low-risk answer.
  • New test — real, both directions pinned (Test Blind Spot Retrospective: Reinforcing Negative Assertion Discipline, Tightening Fake Upstream Strictness, Thin Inst | 测试盲区复盘:补反向断言纪律、假上游严格化、薄安装冒烟、形态矩阵与生命周期覆盖 #3617). below (b64Bytes 102399 ≤ 102400) → null; if the gate were removed it would re-encode and return non-null → caught. above (102402 > 102402… 102402 > 102400) → re-encoded at same dims, adopted (mocked 8-byte buffer < original) → if the gate were inverted it would return null → caught. Mock pattern matches the file's existing tests; b64Bytes math and the 100 KiB constant verified.
  • One small fix applied on the spot (own commit 0108a5bc, pushed): the new doRescale header comment said the defensive branch is "only hit when the header dim parse disagrees with the authoritative Jimp.read decode" — but the rung B pre-filter only skips known-dim within-maxDim images, so the branch is also hit when the header parse fails (dims === undefined) and the decode shows within-maxDim. Comment now says "fails or disagrees" + "known-dim". Docs-only, no behavior change.

CI (verified live, mirror cache + job logs):

八问 (review 结论):

  1. 是什么问题: 图像强制重编码路径(byte-shed)的两段注释互相矛盾且都与代码不符——一段说 within-maxDim 不跳过,另一段说没有 trigger gate、within-maxDim 原样保留;代码实际是 within-maxDim ≤100KiB 跳过、>100KiB 重编码且仅严格变小时采纳。
  2. 什么原因导致的: 注释按不同假设写成后与代码漂移;trigger gate 本身是原始设计(git log -L 证实 !force || 子句自文件首版存在),不是 bug。
  3. 影响范围与严重程度: 纯文档,零行为影响;风险仅为未来读者误读强制路径契约。p3。
  4. 怎么修复的: 代码不动,两段注释对齐代码真值表;新增回归测试双向钉死 gate(Test Blind Spot Retrospective: Reinforcing Negative Assertion Discipline, Tightening Fake Upstream Strictness, Thin Inst | 测试盲区复盘:补反向断言纪律、假上游严格化、薄安装冒烟、形态矩阵与生命周期覆盖 #3617)。
  5. 是否有回归问题: 无。diff 仅 2 段注释 + 1 个新测试,强制条件前后 bit-identical(已核);无语义/阈值/时序/输出格式漂移。
  6. 是否破坏缓存: 不涉及(未触碰缓存/重试/游标逻辑)。
  7. 是否改了设计方向: 否。PR 回答了 [Drive-by] forced-path image-rescale docs contradict the code on within-maxDim handling #7150 的设计问题——within-maxDim trigger gate 是有意的廉价预过滤(byte-shed 职责是减字节;大尺寸 within-maxDim 图是合法目标,keep-smaller 检查保证安全);我独立核了 gate 历史与调用方预过滤,结论成立。
  8. 是否引入了新的配置: 无。

判定: 代码可合——等 0108a5bc 的新 CI 跑绿(flaky shard 重新抽卡);master 侧 ubuntu/24/2 的 born-red 已报 #4599,不属于本 PR。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

Status update (since my last reply at 12:45Z):

  • The main CI workflow run for head 0108a5bc was cancelled at 12:45:18Z — 3 min after my push, with only the fast guard jobs completed. It was a cancellation, not a test failure (no red job). I could not determine the cancel source from the API (the CI-engineer session ci-engineer-r1 had taken over the windows/22/5 flake at 12:30Z and was still processing; no result posted from it yet).
  • I re-triggered the CI run (run 44306453336, now attempt 2) — it is queued and will run the full suite fresh, including the previously-flaky windows/22/5 shard.
  • 3 e2e workflows are still queued (e2e-pi-codex-ws, e2e-fake-codex, e2e-native-opencode); the other 5 e2e + PR Build Artifact + CI Windows codex overlay + ci-image are already green on 0108a5bc.

Net: PR is still not green — waiting on the re-triggered CI run (attempt 2) + the 3 queued e2e workflows. No code change since 0108a5bc. The verdict from my last reply (代码可合) stands, pending CI green. I will not re-post unless the re-run lands red for a non-flake reason.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

CI is green on the new head 0108a5bc — 37 success / 13 skipped / 0 failures (verified via check-runs API; mirror cache was stale at this check).

The originally failing check test (windows-latest, 22, 5) was a flaky Windows powershell test unrelated to this docs-only PR: #5955 processBirthStamp (tests/issue5955-wedged-same-lane-takeover.test.ts:327) hit the 10s timeout on powershell -NoProfile -NonInteractive -Command "(Get-Process -Id <pid>).StartTime" under 5-shard concurrent Windows CI load — the code comment at src/launcher.ts:5129 itself notes powershell has "~1-3s cold start". On the new head's full CI run, all checks passed.

No code changes were needed in this PR. While I was verifying, another agent (ci-check) pushed a docs tweak (0108a5bc, naming the parse-failure case in a comment), which triggered a fresh full CI run that superseded my re-run of the old head — that run is the green one above.

The flaky #5955 test is a separate, pre-existing Windows CI concern (raise the powershell timeout in src/launcher.ts or harden the test) — out of scope for this docs PR, flagged for follow-up.

八问:

  1. 是什么问题: CI 红 — test (windows-latest, 22, 5) 失败(run 44302461832)。
  2. 什么原因导致的: 与 PR 无关的 flaky 测试 #5955 processBirthStamp——Windows 上 powershell 冷启动 ~1-3s,5-shard 并发 CI 负载下命中 10s 超时,processBirthStamp 返回 undefined,断言 a !== undefined && a.length > 0 失败。
  3. 影响范围与严重程度: 仅影响该 PR 的 CI 绿灯判定;PR 本身 docs-only,无功能影响。严重程度:低(flaky,重跑即过,非回归)。
  4. 怎么修复的: 无需代码修复。先对旧 head 重跑失败 job(rerun-failed-jobs HTTP 201);期间另一 agent 推进 head 至 0108a5bc 触发新全量 CI,旧重跑被 supersede;新 head 的 CI 全绿(37 success / 13 skipped / 0 failure)。
  5. 是否有回归问题: 无。PR 仅改注释(src/image-rescale.ts)+ 加一个回归测试(tests/image-rescale-cache-budget.test.ts),无行为/语义变更。
  6. 是否破坏缓存: 不涉及。
  7. 是否改了设计方向: 不涉及。
  8. 是否引入了新的配置: 不涉及。

判定: PR 已绿,可合并。flaky 的 #5955 测试为独立问题,建议后续单独处理(提高 src/launcher.ts powershell 超时或加固测试),不阻塞本 PR。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

PR #7152 — Merge-Conflict Resolution Complete

What I did this run:

  1. Verified live state (status freshness): PR was merge_state: dirty (conflict with base). PR branch 2026-11-18_forced-path-image-rescale-docs was 111 commits behind master (head 0108a5bc, base 548e3960, master head b10c1a0d).
  2. Merged origin/master into the PR branch (local ci-7152-conflict). ONE conflict: src/image-rescale.ts comment block (lines 153–165). Test file merged cleanly.
  3. Resolved the conflict: Master changed both the code (removed the !force || bypass — the 100 KiB trigger gate now applies to both force and normal modes) and the comment. The PR only changed the comment (code unchanged from base). Merged code = master's version. I kept the PR's comment because it is more detailed and accurate for the merged code (it correctly describes the gate applying to within-maxDim images in both modes).
  4. Verified locally: Ran the targeted test tests/image-rescale-cache-budget.test.ts — all 8 tests pass, including the PR's new regression test (forced within-maxDim: the 100 KiB trigger gate skips small, re-encodes large).
  5. Pushed the merge commit 79fc0ffc792 to the remote PR branch (fast-forward, no force-push needed — remote head was an ancestor).
  6. Verified PR is now mergeable (one-time API fetch): mergeable: true, mergeable_state: blocked (waiting for CI/approval, not a conflict).

八问

  1. 是什么问题: PR [PR] docs(image-rescale): reconcile the forced-path trigger-gate comments with the code #7152 与 master 冲突,merge state 为 dirty,无法合并。
  2. 什么原因导致的: PR 分支落后 master 111 个 commit。期间 master 修改了 src/image-rescale.ts 的代码(移除 !force || bypass,使 100 KiB trigger gate 对 force 和 normal 模式都生效)和注释,而 PR 只修改了注释(未改代码),导致注释块冲突。
  3. 影响范围与严重程度: 仅影响 PR 分支的合并状态,不影响任何用户或生产行为。严重程度: 体验瑕疵(阻塞 PR 合并)。
  4. 怎么修复的: 将 origin/master 合并到 PR 分支,解决唯一的注释冲突。保留 PR 的注释(更详细,且与合并后的代码一致——master 的代码变更使 trigger gate 对两种模式都生效,PR 的注释准确描述了这一行为)。
  5. 是否有回归问题: 无。合并后的代码是 master 的代码(已在 CI 上绿),PR 的测试全部通过(8/8 pass,包括 PR 新增的回归测试)。
  6. 是否破坏缓存: 不涉及。
  7. 是否改了设计方向: 不涉及。
  8. 是否引入了新的配置: 不涉及。

判定: 冲突已解决,PR 现在可合并(mergeable: true)。新 head 79fc0ffc792 将触发新一轮 CI。等待 CI 绿 + 审批。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[ework] CI fix verified green ✓

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation image p3 scope/docs

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Drive-by] forced-path image-rescale docs contradict the code on within-maxDim handling

1 participant