QVAC-14104 feat[api]: SDK diffusion plugin integration

[donriddo]

🎯 What problem does this PR solve?

• The diffusion addon had no SDK surface — users couldn't call image generation through the standard QVAC client API (loadModel + generation())
• The addon existed at the native layer but wasn't wired into the SDK plugin system, registry, or test harness

📝 How does it solve it?

SDK plugin wiring (36 files):

• sdcpp-config.ts schemas: config, stats, request/response, client params with sampling_method enum matching the C++ SdGenHandlers.cpp::parseSampler() ground truth (14 valid samplers)
• sdcpp-generation/plugin.ts with definePlugin(), resolveConfig() for companion artifacts, deterministic createModel()
• generation.ts ops handler (unified txt2img + img2img, mode from init_image presence)
• generation-stream.ts RPC handler via dispatchPluginStream()
• generation() client API with streaming/non-streaming support (outputStream for streamed images, outputs for buffered, stats for generation metadata)
• Wired into: handler-registry, handlers/index, common.ts, model-types, engine-addon-map, load-model, get-model-info, registry, plugin.ts constants, worker.ts, pear/pre.ts, logging/namespaces, index.ts exports

Addon JS layer:

• Fix companion model path resolution to support absolute paths (was always joining with diskPath)

Addon type definitions:

• index.d.ts SamplerMethod type aligned to C++ parser (14 valid values)

Registry & codegen:

• Diffusion model entries added to generated registry (models/registry/models.ts)
• Codegen naming support for diffusion models in models/update-models/naming.ts and codegen.ts
• History artifact models/history/d514e414.txt

Tests & examples:

• 15 integration test definitions: txt2img, img2img, streaming, progress, stats, batch, samplers, schedulers, seed reproducibility, negative prompt, cfg_scale, error cases
• GenerationExecutor desktop executor using AbstractModelExecutor + ResourceManager pattern
• Unit tests for schema validation, plugin dispatch, stats fields, naming conventions
• 3 examples: diffusion-txt2img.ts, diffusion-img2img.ts, diffusion-flux2-klein.ts

🧪 How was it tested?

• 15/15 generation integration tests pass against FLUX.2 Klein 4B Q4_0 on GPU via the MQTT-based QVAC test framework
  • Resource config: FLUX_2_KLEIN_4B_Q4_0 + companions QWEN3_4B_Q4_K_M (LLM) + FLUX_2_KLEIN_4B_VAE (VAE), device: gpu
• 77/77 unit tests pass (sdcpp-plugin.test.ts + update-models-naming.test.ts)
• All 3 examples confirmed working end-to-end via bun run bare:example
• No new lint/typecheck errors

The generation() client helper exposes progressStream (step/totalSteps/elapsedMs ticks), outputStream (streamed images), outputs (buffered images), and stats (final metadata). The generation-streaming-progress integration test asserts progress tick presence and field validity.

🔌 API Changes

import { generation, loadModel, FLUX_2_KLEIN_4B_Q4_0, FLUX_2_KLEIN_4B_VAE, QWEN3_4B_Q4_K_M } from "@qvac/sdk";

const modelId = await loadModel({
  modelSrc: FLUX_2_KLEIN_4B_Q4_0,
  modelType: "diffusion",
  modelConfig: {
    device: "gpu",
    threads: 4,
    llmModelSrc: QWEN3_4B_Q4_K_M,
    vaeModelSrc: FLUX_2_KLEIN_4B_VAE,
  },
});

// txt2img (non-streaming)
const { outputs, stats } = generation({ modelId, prompt: "a cat" });
const buffers = await outputs;

// txt2img (streaming)
const { outputStream } = generation({ modelId, prompt: "a cat", stream: true });
for await (const { data, outputIndex } of outputStream) { ... }

// img2img
const { outputs } = generation({
  modelId, prompt: "watercolor style",
  init_image: fs.readFileSync("photo.jpg"), strength: 0.75,
});

New exports: generation, GenerationClientParams, GenerationProgressTick, GenerationStreamResponse, DiffusionStats, PLUGIN_DIFFUSION

📦 Models

Added models

FLUX_2_KLEIN_4B_Q4_0
FLUX_2_KLEIN_4B_VAE

(Plus other diffusion entries added by registry codegen.)

⚠️ Notes

• @qvac/diffusion-cpp uses file:../lib-infer-diffusion — needs proper versioned reference before release
• Version unchanged at current value — needs bump before merge

---

• To see the specific tasks where the Asana app for GitHub is being used, see below:
  • https://app.asana.com/0/0/1213637721301957

[NamelsKing]

i would lean to something different in api perspective generation feels to generic for me. Mb diffusion?

[github-actions]

Tier-based Approval Status

**PR Tier:** TIER1

**Current Status:** ❌ PENDING

**Requirements:**
- 1 Team Member approval ❌ (0/1)
- 1 Team Lead OR Management approval ❌ (0/1)



---
*This comment is automatically updated when reviews change.*

[NamelsKing]

u would probably want to rebase once more before targeting main and wire up profiler to diffusion addon, can be found in this PR #836

[opaninakuffo]

lets replace these with their counterpart srcs from model registry

[opaninakuffo]

same here, we can also upload sample imgs to or use existing from examples/image dir

[opaninakuffo]

same here

[opaninakuffo]

confirming: diffusion addon doesnt use a loader?

[donriddo]

no, it doesn't