Skip to content

Completed: LoRA capability matrix and strict application

Metadata

  • Created: 2026-05-28
  • Status: Completed
  • Completed: 2026-06-22

ADR status

  • Governing ADRs: ADR 0002, ADR 0003
  • ADR impact: No new ADR was required. The shipped design stays inside the existing capability, validation, and fail-closed routing contract.

Outcome

Completed as the production-support boundary for the current MLX-Gen LoRA surface.

MLX-Gen now:

  • surfaces route-level LoRA truth through supports_lora, lora_status, lora_target_roles, and lora_validation_profile;
  • rejects unsupported LoRA requests before model dispatch instead of letting constructors silently ignore them;
  • records structured LoRA application reports in generated metadata;
  • keeps mlxgen prepare --lora-paths/--lora-scales fail-closed until bake/export equivalence is deliberately proven for a family;
  • promotes exact validated rows only when the accepted route has a published model-backed A/B proof.

Closing code reality

  • src/mflux/task_inference.py now owns the public LoRA capability contract.
  • src/mflux/lora_validation_registry.py now records exact public validation rows by model/package and route.
  • src/mflux/models/common/lora/mapping/lora_loader.py now fails on the real error cases that matter to users: unreadable files, corrupt files, zero matched keys, zero applied targets, missing A/B matrices, target-path misses, and matrix-shape mismatches.
  • src/mflux/models/common/lora/lora_compatibility.py now rejects known cached model-card mismatches such as FLUX.2-dev adapters on FLUX.2 Klein.
  • Generated metadata now records lora_application_reports, lora_applied_file_count, and lora_applied_target_count.

Current exact public validated rows include:

  • AbstractFramework/qwen-image-edit-8bit on qwen.edit
  • AbstractFramework/qwen-image-edit-2509-8bit on qwen.edit
  • AbstractFramework/qwen-image-edit-2511-8bit on qwen.edit, qwen.inpaint, qwen.multi-reference, qwen.reframe, and qwen.outpaint
  • AbstractFramework/qwen-image-8bit on qwen.text, qwen.latent, qwen.control, and qwen.control-inpaint
  • AbstractFramework/qwen-image-2512-8bit on qwen.text
  • AbstractFramework/z-image-turbo-8bit on z-image.text
  • AbstractFramework/ernie-image-turbo-8bit on ernie-image.text and ernie-image.latent
  • AbstractFramework/flux.2-klein-9b-8bit on flux2.edit and flux2.multi-reference
  • AbstractFramework/flux.2-klein-base-4b-8bit on flux2.outpaint
  • all current Wan q8 public video rows

That is the public support claim. Other rows may still surface as mapped-unvalidated or unsupported, but they are not part of the production contract until they have their own accepted proof row.

Validation

Focused automated coverage now locks:

  • capability surfacing;
  • unsupported-route rejection;
  • strict scale-count handling;
  • exact validation-profile resolution;
  • FLUX.2 runtime guidance guards on direct model use.

Accepted published proof bundles:

Representative exact-row artifacts:

Remaining boundary

  • FLUX.2-dev adapter support remains a separate item because Klein proof does not justify broad FLUX.2-dev claims.
  • Bonsai packed-runtime LoRA remains a separate architectural problem.
  • Future adapter-family or model-family expansion should land as new bounded items instead of reopening this contract item.