# 0002: Save-node ownership of generated image formats

- Status: Superseded by [0003](0003-generator-owned-image-save-configuration.md)
- Date: 2026-08-30
- Owners: Maintainers

## Context

The unified background generator previously decoded provider results and permanently re-encoded Nano Banana output as PNG. This obscured whether `output_format` was a provider capability or a local save choice, and discarded the original PNG/JPEG container returned by Nano Banana. The released `O1keyImageSave` node also delegated to ComfyUI's PNG-only helper.

## Decision

Generation paths retain provider bytes and detected format. Panel-triggered jobs place those bytes in ComfyUI temp storage and return `type=temp` descriptors. `O1keyImageSave` is the only component that promotes them into output storage, through its append-only `格式` widget and the batch-bound `/o1key/image/save` route.

`格式=原始` preserves PNG/JPEG/WebP compressed image data; workflow metadata may be inserted into the container without recompressing pixels. Explicit PNG and WebP use lossless encoding. Explicit JPEG uses quality 100 with 4:4:4 subsampling. If pixels were modified after generation or original bytes are unavailable, `原始` falls back to PNG.

Nano Banana payloads never contain `output_format`. GPT Image keeps its API-level `output_format`, which determines provider output but does not bypass the save node.

## Consequences

- Nano Banana PNG and JPEG responses remain distinguishable and recoverable.
- API output options and local save options have separate owners and labels.
- Background generation must retain temp results until the save route succeeds.
- Original-format preservation requires private in-memory tensor metadata on the direct execution path; ordinary downstream tensor operations may invalidate it and trigger the PNG fallback.
- Existing workflows gain only one appended save-node widget and migrate to `原始` idempotently.

## Alternatives considered

- Continue saving every background result as PNG. Rejected because it destroys the provider container and implies a Nano Banana capability that does not exist.
- Let the generator select the permanent local format. Rejected because it duplicates the output responsibility and leaves the save node semantically misleading.
- Store original bytes inside workflow JSON. Rejected because large binary payloads do not belong in workflows and would make saved graphs unsafe and impractical.

## Validation

- `tests/test_o1key_image_save.py` verifies original JPEG/PNG preservation, metadata injection, explicit conversions, and PNG fallback.
- `tests/test_o1key_image_jobs.py` verifies Nano Banana ignores GPT-only fields, jobs produce temp descriptors, and save-route path binding.
- `tests/test_o1key_image_generator_frontend.mjs` verifies temp promotion, workflow metadata submission, result restoration, and idempotent widget migration.