[skunkworxdark]

Summary

Node workflows previously required wiring core_metadata manually or relying on four model-specific *_meta wrapper invocations (denoise_latents_meta, flux_denoise_meta, z_image_denoise_meta, anima_denoise_meta) to record denoise parameters. The remaining 15 image and video denoise invocations either accepted WithMetadata without emitting metadata or lacked WithMetadata altogether, and workflow-generated IP-Adapters and ControlNets were out of sync with v7 metadata schemas.

• Discussion Thread: Discord #developer-forum discussion, stage proposals, and updates
• Before: Only 4 denoise families had *_meta wrappers; 15 denoise invocations could not emit or merge metadata on their output; IP-Adapters in workflows were written only to legacy ipAdapters (ignored by v7 Reference Images recall), and metadata_to_ip_adapters failed to recall v6/v7 ref_images.
• After:
  • All 19 image and video denoise invocations inherit WithMetadata, build and merge their denoise parameters via _build_metadata(), and return metadata: Optional[MetadataField] (LatentsMetaOutput on all 17 image/Wan denoise invocations, and an optional metadata field on LTX2DenoiseOutput and MiniMaxH3DenoiseOutput).
  • Denoise metadata automatically stamps app_version and metadata_version (CORE_METADATA_VERSION, currently "1.2.0") and infers generation_mode (*txt2img, *img2img, *inpaint, and video modes) when not already present in upstream metadata.
  • denoise_latents, tiled_multi_diffusion_denoise_latents, flux_denoise, and anima_denoise serialize IP-Adapters into v7 ref_images (type: "ip_adapter"), and metadata_to_ip_adapters recalls v7 ref_images (including clip_vision_model and method), v5/v6 canvas_v2_metadata.referenceImages (both array and entities container formats), and v4 ipAdapters.
  • All control-capable model families (denoise_latents, tiled_multi_diffusion_denoise_latents, flux_denoise, flux2_denoise, anima_denoise, qwen_image_denoise, z_image_denoise) emit controlnets, and metadata_to_controlnets / metadata_to_t2i_adapters use safe field lookups with v7 control_layers (Restore Canvas metadata and recall parity #10127) and v5/v6 canvas_v2_metadata.controlLayers (both array and entities container formats) fallbacks.
  • The 4 legacy *_meta invocations remain as deprecated thin subclasses of their base denoise invocations for backward compatibility with existing saved workflows.
  • Expanded CORE_LABELS and its typed variants in metadata_linked.py (CUSTOM_LABEL first) across all supported model families.
  • Updated embedded node versions across the 28 bundled Wan and Video workflow JSON files in default_workflows/ to match invocation versions (ltx2_denoise: 1.6.0, minimax_h3_denoise: 1.5.0, wan_denoise: 1.1.0, wan_video_denoise: 1.1.0).

Architectural Roadmap: 3-Stage Metadata Unification

Discussion & Updates: The full stage proposals, architectural discussion, and ongoing progress updates are in the InvokeAI Discord developer forum: Discord Thread.

This PR is Stage 1 of a planned three-stage initiative to make metadata propagation first-class, automatic, and fully schema-compliant across node workflows:

Stage 1: Denoise Invocations Unification (Current PR)

• Goal: Every denoise invocation natively builds, enriches, and emits metadata without requiring custom wrappers or manual core_metadata wiring.
• Key Deliverables:
  • Add WithMetadata and metadata: Optional[MetadataField] across all 19 image and video denoise invocations (LatentsMetaOutput subclassing LatentsOutput).
  • Automatic generation_mode, app_version, and metadata_version inference.
  • Native serialization of controlnets and v7 ref_images (type: "ip_adapter").
  • Backward-compatible recall in MetadataToIPAdapters, MetadataToControlnets, and MetadataToT2IAdapters supporting v4, v5/v6 (canvas_v2_metadata), and v7 schemas.
  • Deprecate the 4 legacy *_meta wrapper nodes while preserving backward compatibility.

Stage 2: Conditioning Metadata Propagation (Upcoming)

• Goal: Enable text prompt and conditioning nodes to emit their own metadata alongside conditioning data, flowing naturally downstream into denoise nodes.
• Key Deliverables:
  • Enrich conditioning invocations (CompelInvocation, SDXLCompelPromptInvocation, FluxClipInvocation, CLIPSkipInvocation, etc.) to produce structured prompt and style metadata.
  • Pass metadata through conditioning chains (concatenation, masking, scheduling) without loss.
  • Denoise nodes merge upstream conditioning metadata with their own sampling/denoise parameters automatically via _build_metadata().

Stage 3: Image Reference, Latent Operations & Decode Unification (Future)

• Goal: Complete the metadata lifecycle across upstream image inputs and downstream decoding/saving.
• Key Deliverables:
  • Standardize reference image handling (FLUX.1/FLUX.3 Redux, Style/Content adapters, Image-to-Image / Inpaint initial images).
  • Preserve and merge metadata across intermediate latent operations (LatentsBlendInvocation, CropLatentsInvocation, etc.).
  • Latents-to-Image / VAE Decode invocations carry metadata through to final saved image artifacts, ensuring every output image retains complete provenance without explicit UI builder intervention.

QA Instructions

• Automated checks run:
  • uv run --no-sync ruff check invokeai/app/invocations tests/app/invocations/test_denoise_metadata.py (passed)
  • uv run --no-sync ruff format --check invokeai/app/invocations tests/app/invocations/test_denoise_metadata.py (passed)
  • uv run --no-sync pytest tests/app/invocations/test_denoise_metadata.py tests/app/services/workflow_records/test_default_workflows_registry.py tests/app/invocations/test_flux3_denoise_wiring.py (111 passed)
  • pnpm format:openapi, pnpm typegen, pnpm lint, and pnpm test in invokeai/frontend/api (passed)
  • pnpm run lint:tsc in invokeai/frontend/webv2 (passed)
• Manual workflow testing completed so far on SD 1.5, SDXL (including IP-Adapter ref_images output and recall), and Krea-2; additional live workflow smoke-testing across remaining model families is in progress while in Draft.

Review

• Resolved findings during review:
  • Removed duplicate legacy ipAdapters key emission from denoise_latents, tiled_multi_diffusion_denoise_latents, and flux_denoise so v7 denoise nodes write IP-Adapters exclusively to ref_images while metadata_to_ip_adapters retains backward-compatible recall for v7, v5/v6, and v4 formats.
  • Filtered non-SD IP-Adapter models (such as FLUX and Anima IP-Adapters) out of MetadataToIPAdaptersInvocation so IPAdapterOutput recall only emits SD-1/SD-2/SDXL IP-Adapters.
  • Hardened serialize_control_metadata, serialize_ip_adapter_ref_images, and MetadataTo* recall helpers against malformed dicts/lists and non-positive weights.
  • Integrated upstream additions (moss_image_denoise, flux3_denoise, Anima IP-Adapter serialization, Krea-2 & Qwen-2.1 KV cache keys).
• Remaining limits:
  • Prompts, text encoder identifiers, and conditioning modifiers still require upstream metadata wiring in custom node workflows until Stage 2 (conditioning metadata propagation).

Compatibility / Rollout

• Saved workflows: Existing workflows using denoise_latents_meta, flux_denoise_meta, z_image_denoise_meta, or anima_denoise_meta continue to load and execute via deprecated subclasses. Existing connections to latents on all 17 image/Wan denoise invocations and video_latents/audio_latents on ltx2_denoise and minimax_h3_denoise are unchanged (LatentsMetaOutput is a subclass of LatentsOutput).
• Bundled default workflows: Embedded node versions in default_workflows/ updated for all bumped denoise invocations.
• Generated API contracts: invokeai/frontend/api/openapi.json and invokeai/frontend/api/schema.ts are updated for the new metadata input/output fields, InvocationOutputMap, and expanded CORE_LABELS* literals.

Checklist

• The PR has a short but descriptive title, suitable for a changelog
• Meaningful regression coverage added / updated where needed; obsolete tests/code removed
• Persisted-state and API changes include required migrations / compatibility validation
• Relevant performance/efficiency opportunities considered; material claims have evidence
• Material review findings resolved and relevant checks rerun
• Documentation added / updated (if applicable)
• Updated What's New copy (if doing a release after this PR)

[skunkworxdark]

Manual Workflow Testing Progress & Fixes (98286f771e)

End-to-end node workflow generation and metadata recall (metadata_item_linked -> *denoise*.metadata -> decode node -> gallery recall) have been manually tested and verified so far across 10 model families:

• CogView4 (cogview4_denoise)
• FLUX (flux_denoise)
• FLUX.3 (flux3_denoise)
• Krea 2 (krea2_denoise)
• MOSS-Image (moss_image_denoise)
• Qwen-Image (qwen_image_denoise)
• Qwen-Image 2.1 (qwen_image_2_1_denoise)
• SD 1.5 (denoise_latents)
• SD 3.5 (sd3_denoise)
• SDXL (denoise_latents)

Fixes included in 98286f771e discovered during testing:

1. Flux3DenoiseInvocation._build_metadata(): Added "scheduler": "euler" so FLUX.3 workflow metadata includes its fixed flow-matching scheduler alongside FluxDenoiseInvocation, Flux2DenoiseInvocation, and ZImageDenoiseInvocation.
2. MetadataItemLinkedInvocation & MetadataItemInvocation (unwrap_metadata_value): When wiring a model loader's submodel output port (VAEField, Qwen3VLEncoderField, T5EncoderField, CLIPField, Qwen3EncoderField, MistralEncoderField, UNetField, TransformerField, PiDDecoderField) into Metadata Item Linked.value (Any), unwrap the outer submodel wrapper ({tokenizer, text_encoder, loras} or {vae, seamless_axes}) to its inner ModelIdentifierField so frontend metadata recall can restore text encoders and VAEs directly. Also ensured MetadataItemLinkedInvocation.invoke() copies self.metadata.root rather than mutating in place.

[skunkworxdark]

Manual Workflow Testing Update (978eb0399f)

Completed end-to-end manual workflow generation and gallery metadata recall testing across all 15 local image model families:

• Anima (anima_denoise)
• CogView4 (cogview4_denoise)
• ERNIE-Image (ernie_image_denoise)
• FLUX (flux_denoise)
• FLUX.2 (flux2_denoise)
• FLUX.3 (flux3_denoise)
• Ideogram 4 (ideogram4_denoise) — (also identified and filed #10140 for the frontend webv2 core_metadata / imageRecall.ts preset & override gap; Ideogram4DenoiseInvocation._build_metadata() in this PR already computes the effective preset/override values)
• Krea 2 (krea2_denoise)
• MOSS-Image (moss_image_denoise)
• Qwen-Image (qwen_image_denoise)
• Qwen-Image 2.1 (qwen_image_2_1_denoise)
• SD 1.5 (denoise_latents)
• SD 3.5 (sd3_denoise)
• SDXL (denoise_latents)
• Z-Image (z_image_denoise)

Fix included in 978eb0399f:

• MetadataItemLinkedInvocation & MetadataItemInvocation (value=None handling): When an optional upstream model loader output port (such as anima_model_loader.qwen3_5_encoder on Anima 2B or sd3_model_loader.t5_encoder when omitted) is wired into Metadata Item Linked.value and resolves to None at runtime, allow value=None during _validate_invoke_fields() and omit None-valued keys from the output metadata dictionary instead of raising MissingInputException.