Walkthrough

Adds Iris-3B support with Qwen3-VL prompt conditioning, a pixel-space diffusion model and runner, pipeline configuration, and usage documentation.

Changes

Iris-3B support

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant ModelLoader
  participant ModelBuilders
  participant LLMEmbedder
  participant IrisRunner
  participant DiffusionEngine
  ModelLoader->>ModelBuilders: Select VERSION_IRIS
  ModelBuilders->>LLMEmbedder: Create Qwen3-VL conditioner
  ModelBuilders->>IrisRunner: Create diffusion runner
  LLMEmbedder->>IrisRunner: Provide text conditioning and mask
  IrisRunner->>DiffusionEngine: Return pixel-space output

Suggested reviewers: aapakhomov

Merge Risk: 🔵 Low · up to f4a8b

Long prompts with some supported tokenizers can lose part of the required Iris prompt template. The change is mergeable with owner awareness, though correcting the token budget before merge is preferable.

Security Architecture Review

Security architecture risk: 🟡 Moderate · up to f4a8b

The main unresolved risk requires loading a specially prepared file, rather than ordinary prompt text. Some file-derived sizes lack a complete validation contract, although normal input shapes and concurrent requests have existing controls. Practical exploitation or data disclosure was not demonstrated.

Retained concerns

• Medium · security · inferred: Checkpoint-derived pixel attention dimensions are not constrained to the divisibility required by the new positional-buffer generator. Some even dimensions produce fewer initialized floats than the backend tensor's requested transfer length, potentially bringing uninitialized reserved storage into execution. This is an introduced contract gap with conditional security consequences, not a verified disclosure: ordinary defaults are compatible, inconsistent weights are rejected, and downstream rejection before transfer remains unresolved.

Security review details

Security Blast Radius

• inferred — The identified contract risk requires influence over a checkpoint loaded into the native inference process. The supported scope is that process and its backend buffers; remote reachability, tenant sharing, and wider service exposure are not established.

Security Findings and Attack Paths

• inferred — A crafted, shape-consistent checkpoint could select a pixel attention head dimension incompatible with the initialized positional-buffer length. Backend transfer uses the tensor byte count rather than the vector's initialized length. Whether graph validation blocks the transfer, and whether any resulting values become externally observable, remain unresolved.

Trust Boundaries and Controls

• observed — The in-repository Iris prompt path supplies a hard-coded suffix and a locally owned mask. Caller prompt text remains conditioning data; the inspected path does not grant it tool, credential, or command authority.

Resilience and Maintainability Implications

• observed — The existing public-context guard rejects concurrent or reentrant operations on the same context. Its execution scope ends runners on completion, while graph guards handle sequential graph failure cleanup. These controls counter a new same-context buffer race through the supported public API; direct external use of internal runner methods remains outside inspected coverage.

Hardening Proposals

• proposed — Validate checkpoint-derived head dimensions and their divisibility relationships before constructing the runner, and bind backend transfers to explicitly checked initialized buffer lengths. Reject unsupported configurations through the existing recoverable construction-error boundary.

---

---

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 38 functions across 7 files. (2 skipped: 2…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check		The title clearly and concisely describes the main change: adding Iris-3B text-to-image support.
Description check		The description includes all required sections, summarizes the change, provides verification details with a command and image, and confirms the contribution checklist.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

---