Check Processing Workflow Contracts

Perform a detailed step-by-step trace of generation workflows from UI definitions and submit bindings to backend execution, then validate that parameters are passed, typed, and initialized correctly.

When To Use

• A change touched UI submit wiring for txt2img, img2img, control, or caption workflows
• Processing code changed and regressions are suspected in argument ordering or defaults
• A new parameter was added to UI or processing classes/functions and needs end-to-end validation
• You want a pre-PR contract audit for generation flow integrity

Guidance

• Consult .github/instructions/core.instructions.md for relevant core runtime guidance before proceeding.

Required Workflow Coverage

Run workflow coverage in this order to keep checks focused and complete:

1. txt2img: modules/ui_txt2img.py -> modules/txt2img.py -> modules/processing.py:process_images -> modules/processing_diffusers.py:process_diffusers
2. img2img: modules/ui_img2img.py -> modules/img2img.py -> modules/processing.py:process_images -> modules/processing_diffusers.py:process_diffusers
3. control/process: modules/ui_control.py -> modules/control/run.py (and related control processing entrypoints) -> modules/processing.py:process_images -> modules/processing_diffusers.py:process_diffusers
4. caption/process: modules/ui_caption.py -> caption handler module(s) -> modules/processing.py:process_images and/or postprocess/caption execution module(s), depending on selected caption backend
5. video: modules/ui_video.py -> modules/video_models/video_run.py -> modules/processing.py:process_images and/or postprocess/video execution module(s), depending on implementation

Also validate script hooks when present:

• modules/scripts_manager.py (run, before_process, process, process_images, after)

Primary Files

• modules/ui_txt2img.py
• modules/txt2img.py
• modules/ui_img2img.py
• modules/img2img.py
• modules/ui_control.py
• modules/control/run.py
• modules/ui_caption.py
• modules/ui_video.py
• modules/video_models/video_run.py
• modules/processing.py
• modules/processing_diffusers.py
• modules/scripts_manager.py

Audit Goals

For each covered workflow, verify all three dimensions:

1. Parameter pass-through correctness (name, order, semantic meaning)
2. Type correctness (UI component output shape vs function signature expectations)
3. Initialization correctness (defaults, None handling, fallback logic, and object state)

Procedure

1. Build End-To-End Call Graph

For each workflow (txt2img, img2img, control, caption, video):

• Locate submit/click bindings in UI modules.
• Capture the exact inputs=[...] list order and target function (fn=...).
• Resolve wrappers (call_queue.wrap_gradio_gpu_call, queued wrappers) to actual function signatures.
• Follow function flow through processing class construction and execution (processing.process_images, then process_diffusers when applicable).

Produce a table per workflow with standardized columns and consistent formatting:

• UI input component name
• UI expected output type
• receiving argument in submit target
• receiving processing-object field (if applicable)
• downstream consumption point

2. Validate Argument Order And Arity

For each submit path:

• Compare UI inputs order against function positional parameter order.
• Validate handling of *args and script arguments.
• Confirm state, task id, mode flags, and tab selections align with function signatures.
• Flag positional drift where adding/removing an argument in one layer is not propagated.

3. Validate Name And Semantic Parity

Check that semantically related parameters remain coherent across layers:

• sampler fields (sampler_index, hr_sampler_index, sampler name conversion)
• guidance/cfg fields
• size/resize fields
• denoise/refiner/hires fields
• detailer, hdr, grading fields
• override settings fields

Flag mismatches such as:

• same concept with divergent naming and wrong destination
• field sent but never consumed
• required field consumed but never provided

4. Validate Type Contracts

Audit type compatibility from UI component to processing target:

• gr.Image/gr.File/gr.Video outputs vs expected Python types (PIL.Image, bytes, list, path-like, etc.)
• radios returning index/value and expected downstream representation
• sliders/number inputs (int vs float) and conversion points
• optional objects (None) and .name/attribute access safety

Flag ambiguous or unsafe assumptions, especially for optional file inputs and mixed scalar/list values.

5. Validate Initialization And Defaults

In target modules (txt2img.py, img2img.py, control/run.py, processing classes):

• verify defaults/fallbacks for invalid or missing inputs
• verify guards for unset model/state and expected error paths
• verify object fields are initialized before first use
• verify flow-specific defaults are not leaking across workflows

Include checks for common regressions:

• None passed into required processing fields
• missing fallback for sampler/seed/size values
• stale fields retained from prior job state

6. Validate Script Hook Contracts

Where script systems are involved:

• verify scripts_*.run(...) fallback behavior to processing.process_images(...)
• verify scripts_*.after(...) receives compatible processed object
• ensure script args wiring matches setup_ui(...) order

7. Runtime Spot Check (Preferred)

If feasible, run lightweight smoke validation for each workflow:

• one minimal txt2img run
• one minimal img2img run
• one minimal control run
• one minimal caption run

Use very small dimensions/steps to limit runtime. If runtime checks are not feasible, explicitly report static-only limitations.

Reporting Format

Return findings by severity:

1. Blocking contract failures (will break execution)
2. High-risk mismatches (likely wrong behavior)
3. Type/init safety issues
4. Non-blocking consistency issues

For each finding include:

• workflow (txt2img | img2img | control | caption)
• layer transition (ui -> handler, handler -> processing, processing -> diffusers)
• file location
• mismatch summary
• minimal fix

Also include summary counts:

• workflows checked
• UI bindings checked
• function signatures checked
• parameter mappings validated
• runtime checks executed vs skipped

Pass Criteria

A full pass requires all of the following:

• UI submit input order matches target function signatures
• all required parameters are passed end-to-end with correct semantics
• type expectations are explicit and compatible at each boundary
• initialization/default logic prevents unset/invalid state usage
• scripts fallback path to processing.process_images is coherent

If only part of the workflow scope was checked, report partial pass with explicit exclusions.