{"row":{"id":"ADR-105","title":"nika:image_generate — the Media builtin rides a dedicated image plane","file":"adr-105-image-generate-builtin.md","status":"accepted","date":"2026-07-05","cites":4,"supersedes":[],"superseded_by":[],"layers":["L0","L1.5","L4"],"tags":["nika-builtin","media","image-generation","local"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-105: nika:image_generate — the Media builtin rides a dedicated image plane","id":"adr-105-nikaimage_generate--the-media-builtin-rides-a-dedicated-image-plane"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"Workflows increasingly need image ASSETS (OG covers, QR landing heroes, SEO\nbatches) as a step in a larger pipeline, not as a chat artifact. The stdlib\ndeferred the whole media class at the 42→22 consolidation; the spec kept a\n"},{"k":"code","text":"§Media · DEFERRED"},{"k":"text","text":" placeholder. Meanwhile the two providers that matter\nstabilized their image APIs (OpenAI "},{"k":"code","text":"gpt-image-2"},{"k":"text","text":" · Gemini\n"},{"k":"code","text":"gemini-3.1-flash-image"},{"k":"text","text":", primary-source verified 2026-07-05), and the\nengine already owns every primitive the pipeline needs: the kernel http\nseam, the atomic-write fs seam, the "},{"k":"code","text":"permits.fs"},{"k":"text","text":" runtime boundary, base64 +\nsha256 helpers, and a builtin dispatcher with injected effect seams. Two\ntransport facts force a design decision: the FETCH http client carries a 30s\nidle-read guard that kills 60–120s image renders (the F1 timeout class), and\nimage endpoints are engine-fixed constants — never workflow data."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"text","text":"Ship "},{"k":"strong","text":"one official builtin, `nika:image_generate`"},{"k":"text","text":", as a "},{"k":"strong","text":"module family\ninside `nika-builtin`"},{"k":"text","text":" ("},{"k":"code","text":"src/image/"},{"k":"text","text":" · collapse-default rule — no new crate,\nno 12-gate ceremony; feature-level gates still apply) and graduate the spec's\ndeferred Media class (23 → 24 canonical builtins)."}]},{"k":"list","ordered":false,"items":[[{"k":"strong","text":"The image plane"},{"k":"text","text":" · provider calls ride a DEDICATED dispatcher seam —\n"},{"k":"code","text":"image_http: Option<Arc<H>>"},{"k":"text","text":" + "},{"k":"code","text":"with_image_plane(http, keys)"},{"k":"text","text":", wired at the\ncomposition root with the PROVIDER-plane client (SSRF "},{"k":"code","text":"Disabled"},{"k":"text","text":"\nsanctioned: endpoints are const studio-fixed strings, same reasoning as\n"},{"k":"code","text":"infer:"},{"k":"text","text":" · 600s transport ceiling). Unwired ⇒ real providers fail with the\nprecise "},{"k":"code","text":"-002"},{"k":"text","text":"; the mock provider works without it. "},{"k":"code","text":"permits.net.http"},{"k":"text","text":"\ndoes NOT govern the plane (like "},{"k":"code","text":"infer:"},{"k":"text","text":"); "},{"k":"code","text":"permits.tools"},{"k":"text","text":" + "},{"k":"code","text":"permits.fs"},{"k":"text","text":"\nDO."}],[{"k":"strong","text":"Keys"},{"k":"text","text":" · "},{"k":"code","text":"ImageKeys { openai, gemini }"},{"k":"text","text":" (zeroizing "},{"k":"code","text":"Secret"},{"k":"text","text":"s) resolved\nONLY at the composition root's sanctioned env boundary\n("},{"k":"code","text":"NIKA_OPENAI_API_KEY → OPENAI_API_KEY"},{"k":"text","text":" · "},{"k":"code","text":"NIKA_GEMINI_API_KEY → GEMINI_API_KEY"},{"k":"text","text":"). The builtin never reads env, never logs a credential."}],[{"k":"strong","text":"Assets, not blobs"},{"k":"text","text":" · V1 requires "},{"k":"code","text":"save"},{"k":"text","text":" (default true) — images land\nunder "},{"k":"code","text":"output_dir:"},{"k":"text","text":" (boundary-gated per FINAL path before any I/O ·\n"},{"k":"code","text":"NIKA-SEC-004"},{"k":"text","text":"), outputs and the "},{"k":"code","text":"manifest_version: 1"},{"k":"text","text":" provenance manifest\ncarry paths + dimensions + sha256. Base64 NEVER rides outputs/logs/traces;\n"},{"k":"code","text":"debug: true"},{"k":"text","text":" echoes a SANITIZED provider response (payloads stripped)."}],[{"k":"strong","text":"Validation is header-only"},{"k":"text","text":" · magic bytes are the authority (PNG IHDR ·\nJPEG SOF · WebP VP8/VP8L/VP8X) — no pixel decode ⇒ no decompression-bomb\nsurface; dimension/byte bounds refuse absurd payloads ("},{"k":"code","text":"-007"},{"k":"text","text":")."}],[{"k":"strong","text":"Deterministic mock"},{"k":"text","text":" · a hand-rolled stored-deflate PNG encoder\n(byte-stable forever · validated by the independent "},{"k":"code","text":"png"},{"k":"text","text":" dev-dep) makes\nthe whole pipeline offline-testable, golden-grade."}],[{"k":"strong","text":"Static surface"},{"k":"text","text":" · catalog row (21-arg vocabulary · required\n"},{"k":"code","text":"prompt"},{"k":"text","text":"+"},{"k":"code","text":"output_dir"},{"k":"text","text":") · model-facing ToolDef (drift-guarded against the\ncatalog) · "},{"k":"code","text":"builtin_shape"},{"k":"text","text":" ladder (V1 reservations "},{"k":"code","text":"mode: edit"},{"k":"text","text":" /\n"},{"k":"code","text":"reference_images"},{"k":"text","text":" / "},{"k":"code","text":"save: false"},{"k":"text","text":" refused loudly · closed enums · ranges ·\nthe transparent×jpeg conflict) · "},{"k":"code","text":"BuiltinEffect::Fs { path_arg: \"output_dir\", writes, recursive }"},{"k":"text","text":" so escape-check AND "},{"k":"code","text":"--infer-permits"},{"k":"text","text":"\nunderstand the recursive write ("},{"k":"code","text":"<dir>/**"},{"k":"text","text":")."}],[{"k":"strong","text":"V1 boundaries stated, not faked"},{"k":"text","text":" · "},{"k":"code","text":"mode: edit"},{"k":"text","text":", "},{"k":"code","text":"reference_images:"},{"k":"text","text":",\n"},{"k":"code","text":"save: false"},{"k":"text","text":", streaming, Imagen "},{"k":"code","text":":predict"},{"k":"text","text":" are RESERVED with pointed\nerrors + roadmap notes."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"list","ordered":false,"items":[[{"k":"text","text":"The stdlib counts 24 (catalog · defs · schema enum · spec canon.yaml ·\nconformance fixtures 004/005 · showcase "},{"k":"code","text":"t1-og-images"},{"k":"text","text":" — cascade complete,\npack re-vendored)."}],[{"k":"code","text":"n:"},{"k":"text","text":" on gemini = n sequential calls (no verified "},{"k":"code","text":"candidateCount"},{"k":"text","text":" for\nimages) — documented, usage accumulates across calls."}],[{"k":"text","text":"The 64 MiB provider-response cap bounds "},{"k":"code","text":"n × png"},{"k":"text","text":" batches — a clean "},{"k":"code","text":"-003"},{"k":"text","text":"\nhints jpeg/webp+compression."}],[{"k":"code","text":"image_generation.*"},{"k":"text","text":" observability events ride the Emitter seam (stderr\ntoday; the run-stream integration follows the documented\n"},{"k":"code","text":"EventKind::Extension"},{"k":"text","text":" path — FCI-009, unchanged here)."}],[{"k":"text","text":"Run/workflow ids are honestly ABSENT from the manifest (no RunContext\nseam yet — roadmap, never empty-stringed)."}],[{"k":"strong","text":"The 24th builtin crossed the agent router's activation threshold"},{"k":"text","text":"\n("},{"k":"code","text":"RouterConfig::default().min_universe"},{"k":"text","text":" was 24): a plain\n"},{"k":"code","text":"tools: [\"nika:*\"]"},{"k":"text","text":" agent would have silently flipped from\ndeterministic full-catalog passthrough to BM25 narrowing. The default\nis raised to 32 (routing pays for itself on MCP-heavy universes, never\non the stdlib alone) and a composition-root test pins\n"},{"k":"code","text":"tool_defs().len() < min_universe"},{"k":"text","text":" so the next builtin addition fails\nloudly instead of silently re-crossing."}],[{"k":"strong","text":"`provider_text` is a caption, not a payload channel"},{"k":"text","text":": gemini's\ninterleaved text is clamped (2 000 chars · stable\n"},{"k":"code","text":"provider_text_clamped:"},{"k":"text","text":" warning) and the "},{"k":"code","text":"debug:"},{"k":"text","text":" echo clamps ANY\noversized non-payload string — a multimodal response cannot carry\nmegabytes of text into "},{"k":"code","text":"ToolResult.content"},{"k":"text","text":"/the agent's next turn/the\nmanifest (review-swarm refutation, 2026-07-05)."}],[{"k":"strong","text":"v1.1 amendment (2026-07-05 · same-day)"},{"k":"text","text":" — the Socratic sovereignty\nreview found the V1 set violated supernovae-alignment Rule 3 (5 local\nLLM providers · zero sovereign image path). The set opens: "},{"k":"strong","text":"`local`"},{"k":"text","text":"\n(one OpenAI-images-compat wire now covers LocalAI · Ollama · sd.cpp\n"},{"k":"code","text":"sd-server"},{"k":"text","text":" · SGLang Diffusion · vLLM-Omni — landscape-verified; base\nURL = engine config "},{"k":"code","text":"NIKA_IMAGE_LOCAL_URL"},{"k":"text","text":", default LocalAI "},{"k":"code","text":":8080"},{"k":"text","text":",\noptional Bearer; "},{"k":"code","text":"response_format: b64_json"},{"k":"text","text":" forced; url-only answers\nREFUSED — result URLs are never fetched; 300s default timeout; never\ninferred from "},{"k":"code","text":"model:"},{"k":"text","text":") and "},{"k":"strong","text":"`xai`"},{"k":"text","text":" (Imagine API · "},{"k":"code","text":"grok-imagine-image"},{"k":"text","text":"\ndefault, "},{"k":"code","text":"-quality"},{"k":"text","text":" tier as the model knob · native aspect_ratio +\nresolution 1k/2k classes · usage billed in cost ticks → axes stay null).\nRiders: "},{"k":"code","text":"endpoint_host"},{"k":"text","text":" provenance in output+manifest · "},{"k":"code","text":"count_shortfall:"},{"k":"text","text":"\n· "},{"k":"code","text":"revised_prompt_clamped:"},{"k":"text","text":" warnings · "},{"k":"code","text":"format_mismatch:"},{"k":"text","text":" now fires only\non an EXPLICIT "},{"k":"code","text":"format:"},{"k":"text","text":" (xai returns jpeg by design). BFL's cloud FLUX\nAPI stays deferred (async submit→poll wire — a second adapter\narchitecture; the sovereign path to FLUX is "},{"k":"code","text":"local"},{"k":"text","text":"). Mistral has no\nimage-generation API (agent-tool only — verified negative)."}],[{"k":"strong","text":"v1.2 polish (2026-07-05 · same-day)"},{"k":"text","text":" — the top-of-art pass\n(competitive research vs n8n/Dify/LangGraph/CrewAI/Make/ComfyUI ·\nprimary sources · Nika held 7/7 differentiators). Three additions:\n(1) "},{"k":"strong","text":"in-file provenance"},{"k":"text","text":" — saved PNG files carry a "},{"k":"code","text":"nika"},{"k":"text","text":" tEXt chunk\n(deterministic core: tool · engine · provider · model · clamped prompt\n· seed — NO timestamp, so mock byte-determinism holds) inserted after\nIHDR before hashing, the ComfyUI/InvokeAI interchange practice no\nworkflow engine ships; (2) "},{"k":"strong","text":"honest cost"},{"k":"text","text":" — "},{"k":"code","text":"ProviderBatch.cost_usd"},{"k":"text","text":"\n(xai maps "},{"k":"code","text":"cost_in_usd_ticks"},{"k":"text","text":" exactly · 1¢ = 10⁸ ticks · others\nnull-honest) rides output + manifest + the completed event, and the\nruntime meters ANY invoke tool's top-level "},{"k":"code","text":"cost_usd"},{"k":"text","text":" into the run\nledger (the same channel infer rides); (3) "},{"k":"strong","text":"doctor names the image\nplane"},{"k":"text","text":" — one "},{"k":"code","text":"image"},{"k":"text","text":" finding (mock ready · which cloud keys present ·\nthe local URL). Identified-but-deferred: "},{"k":"code","text":"mode: edit"},{"k":"text","text":"/img2img (the one\nreal competitor gap · reserved args already refuse loudly) · async\nsubmit-poll wires (video-class · not stills)."}],[{"k":"strong","text":"The image plane shares the dispatcher's `H` type parameter"},{"k":"text","text":"\n("},{"k":"code","text":"Option<Arc<H>>"},{"k":"text","text":") rather than a "},{"k":"code","text":"dyn"},{"k":"text","text":" seam: "},{"k":"code","text":"HttpPostDyn"},{"k":"text","text":" is a\n"},{"k":"code","text":"trait_variant"},{"k":"text","text":" async trait (not dyn-compatible), and the house\ncomposes generics everywhere — both planes are "},{"k":"code","text":"nika-http"},{"k":"text","text":" clients\nwith different configs. Accepted trade-off; a distinct provider-plane\nTYPE would need a boxing adapter (additive, if ever needed)."}]]}]

ADR-105

nika:image_generate — the Media builtin rides a dedicated image plane

accepted · 2026-07-05 · L0 L1.5 L4 · cites 4

ADR-105: nika:image_generate — the Media builtin rides a dedicated image plane #

Context #

Workflows increasingly need image ASSETS (OG covers, QR landing heroes, SEO batches) as a step in a larger pipeline, not as a chat artifact. The stdlib deferred the whole media class at the 42→22 consolidation; the spec kept a §Media · DEFERRED placeholder. Meanwhile the two providers that matter stabilized their image APIs (OpenAI gpt-image-2 · Gemini gemini-3.1-flash-image, primary-source verified 2026-07-05), and the engine already owns every primitive the pipeline needs: the kernel http seam, the atomic-write fs seam, the permits.fs runtime boundary, base64 + sha256 helpers, and a builtin dispatcher with injected effect seams. Two transport facts force a design decision: the FETCH http client carries a 30s idle-read guard that kills 60–120s image renders (the F1 timeout class), and image endpoints are engine-fixed constants — never workflow data.

Decision #

Ship one official builtin, `nika:image_generate`, as a module family inside `nika-builtin` (src/image/ · collapse-default rule — no new crate, no 12-gate ceremony; feature-level gates still apply) and graduate the spec's deferred Media class (23 → 24 canonical builtins).

The image plane · provider calls ride a DEDICATED dispatcher seam — image_http: Option<Arc<H>> + with_image_plane(http, keys), wired at the composition root with the PROVIDER-plane client (SSRF Disabled sanctioned: endpoints are const studio-fixed strings, same reasoning as infer: · 600s transport ceiling). Unwired ⇒ real providers fail with the precise -002; the mock provider works without it. permits.net.http does NOT govern the plane (like infer:); permits.tools + permits.fs DO.
Keys · ImageKeys { openai, gemini } (zeroizing Secrets) resolved ONLY at the composition root's sanctioned env boundary (NIKA_OPENAI_API_KEY → OPENAI_API_KEY · NIKA_GEMINI_API_KEY → GEMINI_API_KEY). The builtin never reads env, never logs a credential.
Assets, not blobs · V1 requires save (default true) — images land under output_dir: (boundary-gated per FINAL path before any I/O · NIKA-SEC-004), outputs and the manifest_version: 1 provenance manifest carry paths + dimensions + sha256. Base64 NEVER rides outputs/logs/traces; debug: true echoes a SANITIZED provider response (payloads stripped).
Validation is header-only · magic bytes are the authority (PNG IHDR · JPEG SOF · WebP VP8/VP8L/VP8X) — no pixel decode ⇒ no decompression-bomb surface; dimension/byte bounds refuse absurd payloads (-007).
Deterministic mock · a hand-rolled stored-deflate PNG encoder (byte-stable forever · validated by the independent png dev-dep) makes the whole pipeline offline-testable, golden-grade.
Static surface · catalog row (21-arg vocabulary · required prompt+output_dir) · model-facing ToolDef (drift-guarded against the catalog) · builtin_shape ladder (V1 reservations mode: edit / reference_images / save: false refused loudly · closed enums · ranges · the transparent×jpeg conflict) · BuiltinEffect::Fs { path_arg: "output_dir", writes, recursive } so escape-check AND --infer-permits understand the recursive write (<dir>/**).
V1 boundaries stated, not faked · mode: edit, reference_images:, save: false, streaming, Imagen :predict are RESERVED with pointed errors + roadmap notes.

Consequences #

The stdlib counts 24 (catalog · defs · schema enum · spec canon.yaml · conformance fixtures 004/005 · showcase t1-og-images — cascade complete, pack re-vendored).
n: on gemini = n sequential calls (no verified candidateCount for images) — documented, usage accumulates across calls.
The 64 MiB provider-response cap bounds n × png batches — a clean -003 hints jpeg/webp+compression.
image_generation.* observability events ride the Emitter seam (stderr today; the run-stream integration follows the documented EventKind::Extension path — FCI-009, unchanged here).
Run/workflow ids are honestly ABSENT from the manifest (no RunContext seam yet — roadmap, never empty-stringed).
The 24th builtin crossed the agent router's activation threshold (RouterConfig::default().min_universe was 24): a plain tools: ["nika:*"] agent would have silently flipped from deterministic full-catalog passthrough to BM25 narrowing. The default is raised to 32 (routing pays for itself on MCP-heavy universes, never on the stdlib alone) and a composition-root test pins tool_defs().len() < min_universe so the next builtin addition fails loudly instead of silently re-crossing.
`provider_text` is a caption, not a payload channel: gemini's interleaved text is clamped (2 000 chars · stable provider_text_clamped: warning) and the debug: echo clamps ANY oversized non-payload string — a multimodal response cannot carry megabytes of text into ToolResult.content/the agent's next turn/the manifest (review-swarm refutation, 2026-07-05).
v1.1 amendment (2026-07-05 · same-day) — the Socratic sovereignty review found the V1 set violated supernovae-alignment Rule 3 (5 local LLM providers · zero sovereign image path). The set opens: `local` (one OpenAI-images-compat wire now covers LocalAI · Ollama · sd.cpp sd-server · SGLang Diffusion · vLLM-Omni — landscape-verified; base URL = engine config NIKA_IMAGE_LOCAL_URL, default LocalAI :8080, optional Bearer; response_format: b64_json forced; url-only answers REFUSED — result URLs are never fetched; 300s default timeout; never inferred from model:) and `xai` (Imagine API · grok-imagine-image default, -quality tier as the model knob · native aspect_ratio + resolution 1k/2k classes · usage billed in cost ticks → axes stay null). Riders: endpoint_host provenance in output+manifest · count_shortfall: · revised_prompt_clamped: warnings · format_mismatch: now fires only on an EXPLICIT format: (xai returns jpeg by design). BFL's cloud FLUX API stays deferred (async submit→poll wire — a second adapter architecture; the sovereign path to FLUX is local). Mistral has no image-generation API (agent-tool only — verified negative).
v1.2 polish (2026-07-05 · same-day) — the top-of-art pass (competitive research vs n8n/Dify/LangGraph/CrewAI/Make/ComfyUI · primary sources · Nika held 7/7 differentiators). Three additions: (1) in-file provenance — saved PNG files carry a nika tEXt chunk (deterministic core: tool · engine · provider · model · clamped prompt · seed — NO timestamp, so mock byte-determinism holds) inserted after IHDR before hashing, the ComfyUI/InvokeAI interchange practice no workflow engine ships; (2) honest cost — ProviderBatch.cost_usd (xai maps cost_in_usd_ticks exactly · 1¢ = 10⁸ ticks · others null-honest) rides output + manifest + the completed event, and the runtime meters ANY invoke tool's top-level cost_usd into the run ledger (the same channel infer rides); (3) doctor names the image plane — one image finding (mock ready · which cloud keys present · the local URL). Identified-but-deferred: mode: edit/img2img (the one real competitor gap · reserved args already refuse loudly) · async submit-poll wires (video-class · not stills).
The image plane shares the dispatcher's `H` type parameter (Option<Arc<H>>) rather than a dyn seam: HttpPostDyn is a trait_variant async trait (not dyn-compatible), and the house composes generics everywhere — both planes are nika-http clients with different configs. Accepted trade-off; a distinct provider-plane TYPE would need a boxing adapter (additive, if ever needed).

read at v0.107.0 · the decision record ships with the engine

Every decision, with its status This one in the repo