You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[Drive-by] forced-path image-rescale docs contradict the code on within-maxDim handling #7150
Found in: PR #7147 review (fix: restore byte-triggered image re-encoding).
Symptom / trigger
While reviewing the ordinary-path byte-trigger fix, I found the FORCED-path documentation in src/image-rescale.ts is internally inconsistent with the code:
Comment at lines 152-155 (above doRescale) says: "skips the 100 KiB trigger gate ... A within-maxDim image is NOT skipped here — a same-dim re-encode is adopted only if strictly smaller".
shedDownscaleImage's doc (line ~227) says: "there is no trigger gate ... images already within maxDim are left alone".
if (scale >= 1 && origBytes <= RESCALE_TRIGGER_BYTES) return null;
with the forced keep-smaller check out.length >= origBytes (adopt only if strictly smaller). The actual forced-path 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
So the 152-155 comment is wrong for below-trigger within-maxDim images (they ARE skipped), and the shedDownscaleImage doc is wrong for above-trigger within-maxDim images (they ARE re-encoded). The two comments contradict each other about the intent.
Design question (blocks the fix)
Is the within-maxDim trigger gate in the forced path INTENDED (code correct; both comments need reconciling to "within-maxDim images are skipped unless above the trigger"), or is it a BUG (the shedDownscaleImage intent is that ALL within-maxDim images are left alone, and the code should not re-encode above-trigger within-maxDim forced images)?
Impact
Low / documentation-only. In production the egress-shed caller pre-filters maxDim-fitting images before calling shedDownscaleImage, so the within-maxDim branch is defensive and rarely hit. No observed behavior change — the risk is a future reader misreading the contract.
Proposed fix (pending the design answer)
If the gate is intended: reconcile both comments with the code's actual truth table (add a short truth-table note).
If the gate is a bug: remove the origBytes <= RESCALE_TRIGGER_BYTES clause for the forced path and add a regression test pinning within-maxDim forced behavior.
Scope note
Separate from #7147, which fixes the ORDINARY path and provably does not change the forced path (the forced condition is bit-identical before/after that fix). This is the forced-path documentation/contract question only.
scale >= 1 ⟺ within-maxDim. So forced + within-maxDim + ≤100KiB → skipped; forced + within-maxDim + >100KiB → re-encoded at same dims, adopted only if strictly smaller (:173); forced + above-maxDim → always re-encoded.
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).
Design answer (my judgment, pending owner veto): the gate is INTENDED, not a bug. Rationale: 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. Removing it (the "bug" option) would force a pointless decode+re-encode of every small within-maxDim image for zero expected gain.
So: code stays; both comments get reconciled to the actual truth table. Fixing now — docs-only, plus a regression test pinning both gate directions (per the #3617 negative-assertion discipline). Will report back with the commit.
Design answer (final): 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).
What shipped (commit cfab299c9a):
src/image-rescale.ts: reconciled both comments with the code's actual truth table (docs-only, no behavior change).
Activity
ranxianglei commentedon Nov 18, 2026
[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)
Verified the analysis against the code — the truth table in the issue is exactly right:
src/image-rescale.ts:166if (scale >= 1 && (!force || origBytes <= RESCALE_TRIGGER_BYTES)) return null;scale >= 1⟺ within-maxDim. So forced + within-maxDim + ≤100KiB → skipped; forced + within-maxDim + >100KiB → re-encoded at same dims, adopted only if strictly smaller (:173); forced + above-maxDim → always re-encoded.src/egress-shed.ts:308-310pre-filters known-dim within-maxDim images, so the within-maxDim forced branch is defensive (only hit when the header parse disagrees with the authoritativeJimp.read).Design answer (my judgment, pending owner veto): the gate is INTENDED, not a bug. Rationale: 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. Removing it (the "bug" option) would force a pointless decode+re-encode of every small within-maxDim image for zero expected gain.So: code stays; both comments get reconciled to the actual truth table. Fixing now — docs-only, plus a regression test pinning both gate directions (per the #3617 negative-assertion discipline). Will report back with the commit.
ranxianglei commentedon Nov 18, 2026
[bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)
Done. PR opened: #7152 (labels:
documentationp3scope/docsimage; source issue #7150 labeledp3scope/docsimage).Design answer (final): 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 authoritativeJimp.read).What shipped (commit
cfab299c9a):src/image-rescale.ts: reconciled both comments with the code's actual truth table (docs-only, no behavior change).tests/image-rescale-cache-budget.test.ts: added a regression test pinning both gate directions (Test Blind Spot Retrospective: Reinforcing Negative Assertion Discipline, Tightening Fake Upstream Strictness, Thin Inst | 测试盲区复盘:补反向断言纪律、假上游严格化、薄安装冒烟、形态矩阵与生命周期覆盖 #3617 negative-assertion discipline) — below-trigger within-maxDim is skipped, above-trigger within-maxDim is re-encoded and adopted. Targeted run: 8/8 pass.结构化八问
shedDownscaleImage强制路径的两处注释互相矛盾,且都与代码不符——doRescale头注释说"within-maxDim 图不会被跳过",shedDownscaleImage文档说"没有触发门、within-maxDim 图原样保留",但代码实际是"within-maxDim 且 ≤100KiB 跳过、>100KiB 重编码(仅严格变小时采用)"。egress-shed.ts:308-310已预过滤已知尺寸的 within-maxDim 图),生产环境极少命中。无观测到的行为变化——风险仅在未来读者误读契约。收工判定: 可合。CI 在跑(镜像缓存显示 9 pending / 0 failed,但 sha 与本次提交不一致,可能是缓存滞后——以 PR 页 CI 为准)。