Module stable diffusion Roadmap

Roadmap-Hinweis: Vage Bullets ohne Akzeptanzkriterien in Checkbox-Tasks überführen. Format: - [ ] <Task> (Target: <Q/Jahr>).

Stable Diffusion Plugin Roadmap

Current Status

Core pipeline is operational in stub mode and optional real-backend mode. ControlNet request fields, LoRA request handling, perceptual hash metadata, model SHA-256 integrity validation, and request dimension guards are implemented in SDPlugin and covered by focused tests.

Completed ✅

• IImageGenerationBackend interface + THEMIS_IMGGEN_PLUGIN() export macro
• SDPromptSanitizer — keyword blocklist (case-insensitive, file-loadable)
• ISDGenerator strategy interface
• SDStubGenerator (CI / no model) with img2img pass-through
• InMemorySDGenerator test double (with img2img inspection helpers)
• SDPlugin — provenance stamps, blocked_count, DL entry points
• SDConfig::fromJson / toJson with clamping
• Real PNG encoder with IDAT chunk (stored-deflate, CRC-32, Adler-32 — no external deps)
• generateBatch(prompts, cfg) on IImageGenerationBackend and SDPlugin
• generateImg2Img(prompt, cfg) + Img2ImgConfig struct
• ISDGenerator::generateImg2Img() default fallback
• SDStubGenerator::generateImg2Img() — input-image pass-through
• SDCppGenerator — real stable-diffusion.cpp wrapper (THEMIS_ENABLE_STABLE_DIFFUSION guard)
• Thread-safety: generate_mutex_ serialises all generate paths
• negative_prompt content-policy enforcement (SECURITY.md gap SD-NP-01 resolved)
• ControlNet request fields (control_image_rgb, control_model_path, control_strength)
• LoRA request application (applyLoRA) with per-request scale validation
• Perceptual hash metadata (GeneratedImage::perceptual_hash) with non-fatal fallback
• Model SHA-256 verification gate in initialize() (model_sha256)
• Dimension guards (<=8192, overflow-safe, positive dimensions)
• 62 unit tests (SDPluginFocusedTests, groups A–Q)
• Plugin manifest + CMake registration
• SDCppGenerator — wraps stable-diffusion.cpp C API under THEMIS_ENABLE_STABLE_DIFFUSION guard (Issue: #4590) (2026-04-12)
• Real PNG IDAT encoder — encodeMinimalPng() produces valid IDAT block via stored-deflate + CRC32 + Adler32 (Issue: #4590) (2026-04-12)
• SDStubGenerator::generateImg2Img — returns input-image pass-through (Issue: #4590) (2026-04-12)
• 51 unit tests (SDPluginFocusedTests, groups A–Q) — 6 new tests groups P–Q for SDCppGenerator + real PNG encoder (Issue: #4590) (2026-04-12)
• SDPluginAdapter + SDPluginRegistrar — IThemisPlugin adapter wrapping SDPlugin; createPlugin, createAdapter, defaultReloadCallback, enableHotPlug, disableHotPlug; 12 unit tests (SDPluginRegistrarTests, groups A–D) (2026-04-16)

In Progress

(none)

Planned Features

• [~] Benchmark gate: stable_diffusion benchmark target added; baseline publication pending (Target: Q3 2026)
• [~] End-to-end real-model gate (THEMIS_ENABLE_STABLE_DIFFUSION=ON) in CI (Target: Q3 2026)
• [~] Dedicated parallel-call audit for SDCppGenerator backend semantics (Target: Q4 2026)

Implementation Phases

Phase 1 — Design / API Contract ✅

• IImageGenerationBackend, GeneratedImage, SDGenerationConfig defined
• SDPromptSanitizer separating content policy from inference

Phase 2 — Core Implementation ✅

• SDPlugin wiring sanitizer → generator → provenance → PNG
• SDConfig with JSON round-trip

Phase 3 — Error Handling & Edge Cases ✅

• Blocked prompts: success=false, blocked_count++, no generator call
• Uninitialised state: success=false, error_message
• Generator exception isolation

Phase 4 — Tests ✅

• Focused coverage expanded to 62 tests across groups A–Q
• Added coverage for model SHA-256 gate, dimension guards, ControlNet+LoRA request flow, pHash behavior

Phase 5 — Performance / Hardening

• Thread-safe generate/generateBatch/generateImg2Img (v2.1.0)
• negative_prompt content-policy enforcement (v2.1.0)
• Real PNG encoder — stored-deflate zlib with CRC-32 and Adler-32 (v2.2.0)
• Dimension guard enforcement for generation/img2img/control image paths
• Model SHA-256 verification gate at initialization
• [~] Benchmark: time-to-PNG target added (bench_stable_diffusion_release_gates); real-model baseline pending
• [~] Thread-safety audit for SDCppGenerator (parallel calls) — opt-in real-backend audit target added

Phase 6 — Documentation & Acceptance ✅

• README, CHANGELOG, ROADMAP, ARCHITECTURE, FUTURE_ENHANCEMENTS, AUDIT, SECURITY

Production Readiness Checklist

• Unit tests present (62 tests)
• Stub mode for CI without model file
• Injection constructor for test doubles
• Content-policy sanitizer before every generate call
• Provenance stamps on every result
• Thread-safe generate/generateBatch/generateImg2Img
• negative_prompt content-policy enforcement
• Batch generation API
• Img2img interface with stub pass-through
• Real PNG encoder (IDAT chunk, CRC-32, Adler-32 — no external deps)
• SDCppGenerator — real stable-diffusion.cpp integration (compiled when THEMIS_ENABLE_STABLE_DIFFUSION=ON)
• [~] End-to-end integration test with a real GGUF model file — opt-in target present
• [~] SDCppGenerator thread-safety audit for parallel calls — opt-in target present

Phase 7 — PluginManager Hot-Plug Integration ✅ (v2.3.0)

• SDPluginAdapter : IThemisPlugin — wraps SDPlugin, implements initialize(config_json), shutdown(), getType(), getCapabilities(), getInstance(); PluginType::IMAGE_GENERATION
• SDPluginRegistrar — createPlugin(), createAdapter(), defaultReloadCallback(), enableHotPlug(), disableHotPlug()
• 12 unit tests (SDPluginRegistrarTests, groups A–D) in src/stable_diffusion/tests/test_sd_plugin_registrar.cpp

Known Issues & Limitations

• SDCppGenerator requires the stable-diffusion.cpp submodule and THEMIS_ENABLE_STABLE_DIFFUSION=ON; without them SDStubGenerator is used automatically.
• SDPlugin thread-safety applies to individual method calls; external callers must not share an SDPlugin instance across threads without external synchronisation for initialize() calls.
• SDCppGenerator parallel-call safety depends on stable-diffusion.cpp's own thread model; a full audit is pending.

Breaking Changes

None (v2.0.0 is the initial release).

Latente Symbole (Unused-Functions-Audit)

Stand: 2026-04-20 – Quelle: [[src/UNUSED_FUNCTIONS_REPORT.md|UNUSED-FUNCTIONS-REPORT]]

🧪 NUR_TESTS (implementiert, kein Produktions-Aufrufer)

• SDPlugin – Stable-Diffusion-Plugin-Implementierung; Tests + Plugin-Registrar vorhanden

  Aktion: ROADMAP-Ticket für Produktions-Integration ergänzen oder als CANDIDATE_FOR_REMOVAL markieren.

🟡 UNGENUTZT (kein Test, kein externer Aufrufer)

• samplerFromString – Parst Sampler-Namen (euler, ddim, …) zu Enum; Header-only Helper

  Aktion: Für jedes Symbol entscheiden: (1) Verdrahten, (2) Testen oder (3) als CANDIDATE_FOR_REMOVAL einplanen.

Program Execution Model — Wave Context

This module is a contributing module in the program-level Wave A → B → C → D execution model. It does not own a primary wave deliverable but must remain release_critical-green throughout all waves and must deliver Wave D operability improvements in Q1 2027. See [[../../ROADMAP.md|ROADMAP]] for the full wave model and exit criteria.

Wave D Contribution for stable_diffusion

• Deliver or validate distributed tracing, high-cardinality stress coverage, exporter reliability, and operator remediation hints as applicable to this module (Target: Q1 2027)
• Contribute to or validate long-duration soak test coverage for this module's primary paths (Target: Q1 2027)
• Ensure runbook coverage for operator-critical scenarios in this module (Target: Q1 2027)

Cross-Wave Requirements

• release_critical CI must remain green on develop throughout all waves (Target: ongoing)
• p95/p99 benchmarks must be refreshed on representative hardware before Wave D sign-off (Target: Q1 2027)
• No behavioral regression may be introduced into modules in Wave A/B/C scope from changes in this module.

Program-Level Success Criteria (contribution)

• This module's distributed/acceleration paths fail closed (Target: Q1 2027)
• Benchmark-backed p95/p99 baselines exist on representative hardware (Target: Q1 2027)
• Operator-critical paths have diagnostics, alerts, and runbooks (Target: Q1 2027)