Skip to content

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

Open

Description

@ranxianglei

🤖 Powered by ework · qwen3.8-27b

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".

But the code (line 166, NOT changed by #7147) is:

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.

查重: 无 (searched open+closed issues/PRs for image-rescale forced-path / shedDownscaleImage doc inconsistencies; none found).


Mirrored from ework issue #7151

Activity

  1. ranxianglei commented on Nov 18, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    [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:166 if (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.
    • 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.

  2. ranxianglei commented on Nov 18, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

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

    Done. PR opened: #7152 (labels: documentation p3 scope/docs image; source issue #7150 labeled p3 scope/docs image).

    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):


    结构化八问

    1. 是什么问题: shedDownscaleImage 强制路径的两处注释互相矛盾,且都与代码不符——doRescale 头注释说"within-maxDim 图不会被跳过",shedDownscaleImage 文档说"没有触发门、within-maxDim 图原样保留",但代码实际是"within-maxDim 且 ≤100KiB 跳过、>100KiB 重编码(仅严格变小时采用)"。
    2. 什么原因导致的: 两处注释分别从上/下两个角度描述强制路径,都没对照实际的 gate 逻辑——头注释聚焦 above-maxDim 情形后错误外推到 within-maxDim;文档聚焦"无触发门"后错误外推到"所有 within-maxDim 都原样保留"。代码本身一直是对的。
    3. 影响范围与严重程度: 低 / 纯文档。within-maxDim 强制分支是防御性的(调用方 egress-shed.ts:308-310 已预过滤已知尺寸的 within-maxDim 图),生产环境极少命中。无观测到的行为变化——风险仅在未来读者误读契约。
    4. 怎么修复的: 把两处注释对齐到代码的真实真值表(纯文档),并加一个回归测试钉住 gate 的两个方向(Test Blind Spot Retrospective: Reinforcing Negative Assertion Discipline, Tightening Fake Upstream Strictness, Thin Inst | 测试盲区复盘:补反向断言纪律、假上游严格化、薄安装冒烟、形态矩阵与生命周期覆盖 #3617 负向断言纪律:该跳过的跳过、该重编码的重编码)。
    5. 是否有回归问题: 无。纯文档 + 测试,代码路径未动(强制条件前后 bit-identical)。
    6. 是否破坏缓存: 不涉及。无缓存/重试/游标相关改动。
    7. 是否改了设计方向: 不涉及。设计(gate 是有意为之)未变,只是文档现在如实反映了它。
    8. 是否引入了新的配置: 不涉及。无新 env/config/默认值。

    收工判定: 可合。CI 在跑(镜像缓存显示 9 pending / 0 failed,但 sha 与本次提交不一致,可能是缓存滞后——以 PR 页 CI 为准)。

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

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions