Victor KuznetsovandClaude Opus 5
4a896cd4b5
`InvisibleOptions` promises in its docstring that every default mirrors
`InvisibleEngine`. Two fields made that promise cost something to keep: `force` is
not an engine parameter at all, and `controlnet_scale` was a third spelling of the
engine's `controlnet_conditioning_scale`. The mirror test carried an exception
table for each. This removes both, so the comparison needs no exceptions -- a field
that needs one is a field that belongs somewhere else.
`force` decides WHETHER the engine runs, which is settled before it is built, so it
joins `backend` and `sensitivity` as a parameter of `remove_all` and `remove_batch`
and is threaded to `_run_invisible` as its own argument. `controlnet_scale` takes
the engine's own name; the click option stays `--controlnet-scale` and is now
translated exactly once instead of at three forwarding sites.
Safe to do today: both symbols landed after 0.25.0 and have never been published.
The forwarding turned out to be the weaker half. A defaults comparison cannot see a
hardcoded literal at the seam, and `_run_invisible` passed the entire suite with
`controlnet_conditioning_scale` pinned to a constant. Each of the two knobs also
reaches the engine through TWO paths -- `remove_all` versus `remove_batch(mode="all")`
for `force`, `_run_invisible` versus `_batch_engine` for the scale -- and guarding one
left the other free to hardcode with a green suite. So:
* `test_every_field_arrives_at_the_engine_with_the_caller_s_value` drives the real
seam with all 13 fields set off their defaults; mutating any one of them to its
default fails it.
* `test_force_reaches_the_scrub_gate_in_every_scrubbing_mode` and
`test_batch_controlnet_scale_flows_to_the_cached_engine` are parametrized over
both modes, so neither path can be pinned alone.
Also fixes an order-dependent test surfaced by the added tests reshuffling the xdist
shards. `test_visible_path_decodes_file_once` counted every `image_io.imread` in the
process, but the Gemini engine loads its own bundled capture assets on first
construction, so the count was 3 on a cold engine and 1 on a warm one and the test
passed only when an earlier test happened to build the engine first. It now counts
decodes of the SOURCE, which is the invariant it exists for, and still fails when the
shared decode is broken. The production path was never wrong: the source bitmap is
decoded exactly once.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
5.8 KiB
globs, description
| globs | description | |||||||
|---|---|---|---|---|---|---|---|---|
|
Command contracts, project gate, typing boundaries, model-adjacent test invariants, and the detection-path measurement rule. |
Development invariants
Command contracts
Every single-image command declares source with dir_okay=False; batch declares its directory with file_okay=False. Keep tests/test_cli_robustness.py::TestDirectoryInputIsRejected as the regression guard.
Exit-code and no-signal behavior is a public contract. Read the command-line section of ../../docs/module-internals.md before changing it.
Do not add an option whose only outcome is an error. Model id, step count and CFG are fixed by the profile, so none of them is a parameter of the CLI, InvisibleEngine, or WatermarkRemover -- they were accepted-then-rejected for a while, which moved the failure several frames below the caller and advertised choices the pinned stack cannot honor. If a value cannot vary, delete the knob rather than validating it.
device is the deliberate exception and stays a library parameter: None/"auto" detect, "cuda" pins without detecting, and everything else raises at construction. It is not a CLI option, because the only value a user could usefully type is the one auto-detection already finds.
The same rule applies to install hints: name the extra that actually makes the command work (qwen-zimage, not diffusion), and keep the printed command shell-quoted -- bare pkg[extra] is a glob in zsh.
Local gate
Run bash maintain.sh from the repository root. The authoritative type gate is scoped to src/; full-project Pyright can exhaust Node memory on the ML dependency graph.
Boundary modules for cv2, Torch, and Diffusers may carry narrow per-file relaxations for unknown third-party types. Keep pure-logic files strict, preserve the local piexif stub, and fix real errors before widening a pragma.
Model-adjacent tests
Do not classify an entire module as untestable because its main path downloads a model. Keep pure behavior covered without downloads, including:
- target-size selection in
test_invisible_engine.py; - unsharp and adaptive-polish helpers in
test_humanizer.py; - tiling geometry and blending in
test_tiling.py; - prompt-embedding cache keying, storage round-trip, and the cross-pipeline reuse
that lets a stack load without its text encoder, in
test_qwen_zimage_pipeline.py; - the face stack's dtype, in
test_qwen_zimage_pipeline.py. A subclass that changes the pipeline dtype for its own global model must not change the inherited face stage's;sdxl-zimageshipped doing exactly that and crashed on every image with a face. When one profile inherits another's stage, guard the invariants that stage relies on, not just the code path. - the
InvisibleOptionsdefaults, intest_api.py. When one signature promises to mirror another, compare them field by field rather than pinning the values you happen to know about, so the next field added on one side and not the other fails at the seam. Two of these defaults drifted in practice and neither needed a GPU to catch; the incident is recorded indocs/module-internals.md. Keep the comparison free of an exception table: a field that needs one is a field that belongs elsewhere, which is whatforceturned out to be.
A defaults comparison is not a forwarding test, and the two fail differently. Pin the
VALUE at the seam, not just the name -- _run_invisible passed the whole suite with
controlnet_conditioning_scale hardcoded, because nothing asserted the caller's value
arrived. test_every_field_arrives_at_the_engine_with_the_caller_s_value drives the
real seam with every field set off its default, so one test covers the whole bag
instead of one assertion per knob.
Count the seams before believing a knob is covered. Each of force and
controlnet_conditioning_scale reaches the engine through TWO paths -- remove_all
versus remove_batch(mode="all") for the first, _run_invisible versus _batch_engine
for the second -- and in both cases guarding one path left the other free to hardcode a
constant with a green suite. The mode-parametrized guards in
TestRemoveBatchLibrary::test_force_reaches_the_scrub_gate_in_every_scrubbing_mode and
TestBatchCommand::test_batch_controlnet_scale_flows_to_the_cached_engine exist because
that is what actually happened.
Use availability checks only for paths that actually load large models.
One measurement, one gate seam
A detector is split into a trust-level-blind scan and a verdict that applies the
threshold, so detect and detect_both reach the same numbers by construction. Two
rules follow, and both were broken in practice before they were written down:
- A per-mark demotion goes in the
_post_gatehook (or, for a whole-scan precondition like LibLibAI's size floor, in_scan) -- never in adetectoverride. An override is invisible todetect_both, so the RunningHub and Yuanbao anchor gates silently stopped applying on the arbiter's perception path.TestSinglePassPerceptionis the guard: it assertsdetect_bothequals twodetectcalls field for field. - Detection and the removal mask must read ONE sweep. The winning box travels on
TextMarkDetection.match_boxand the registry threads the detection into the mask builder; a mask path that re-runs its own sweep is how the two drift apart.
Before changing anything in the detection path, record the detectors' exact verdicts over a local sample first and diff them after. A refactor here is only correct if that record is byte-identical, and a green test suite does not establish that on its own.
Environment setup, dependency recovery, CI behavior, and fixture policy: ../../docs/development.md.