feat: add configurable image subfolder strategies

[Pfannkuchensack]

Summary

Add support for organizing output images into subfolders instead of a single flat directory. Four strategies are available via the image_subfolder_strategy config setting:

• flat (default): Current behavior, all images in one directory
• date: Organized by YYYY/MM/DD
• type: Organized by image category (general, intermediate, mask, etc.)
• hash: UUID prefix for filesystem performance (~256 evenly distributed subfolders)

The strategy can be changed at any time — existing images keep their paths, only new images use the new strategy. This is achieved by storing each image's subfolder in a new image_subfolder DB column.

• image_name (DB primary key) remains unchanged — no API or frontend changes needed
• A separate image_subfolder column stores the relative path prefix
• Old images get image_subfolder = "" (backward compatible, stays in root)
• Path traversal protection is maintained while allowing controlled subdirectories
• Thumbnails mirror the same subfolder structure

QA Instructions

1. Start InvokeAI with default config (image_subfolder_strategy: flat) — verify images are saved to outputs/images/ as before
2. Set image_subfolder_strategy: date in invokeai.yaml, restart, generate an image — verify it appears in outputs/images/YYYY/MM/DD/
3. Set image_subfolder_strategy: type, generate — verify images land in outputs/images/general/ (or intermediate/ for intermediate images)
4. Set image_subfolder_strategy: hash, generate — verify images land in outputs/images/XX/ (first 2 chars of UUID)
5. Switch back to flat — verify old subfolder images are still accessible in the gallery
6. Test "Clear Intermediates" — verify it works across all strategies
7. Test image download/bulk download with mixed subfolder images

Merge Plan

• DB migration 28 adds a new column with a default value — safe to run on existing databases
• Config schema migrates from 4.0.2 to 4.0.3 automatically
• No frontend changes required
• No breaking API changes

Checklist

• The PR has a short but descriptive title, suitable for a changelog
• Tests added / updated (if applicable)
• ❗Changes to a redux slice have a corresponding migration
• Documentation added / updated (if applicable)
• Updated What's New copy (if doing a release after this PR)

[JPPhoto]

Dropping my comments here because I think this needs some tests:

1. The new subfolder path surface is effectively untested, including the security checks. image_files_disk.py now accepts nested image_subfolder values and validates them in _validate_subfolder(), but the only existing coverage in test_image_files_disk.py still exercises only traversal through image_name. This PR should add parameterized pytest cases for valid nested folders and invalid inputs like ../x, x/../y, /abs, a//b, and a\\b, plus a save/delete round-trip that asserts thumbnails mirror the same subfolder.

2. images_default.py introduces the core behavior change, but there are no ImageService unit tests locking it down. create(), get_pil_image(), get_workflow(), get_graph(), get_path(), delete(), and delete_intermediates() now all depend on image_subfolder being pulled from the DB and forwarded to image_files. A flat-only manual QA pass will miss regressions here. Add mock-based service tests that assert the exact image_subfolder is passed through for flat, date, type, hash, and is_intermediate=True.

3. images_default.py now swallows every exception during delete_images_on_board() file cleanup and still deletes the DB rows. That means one bad subfolder/path can silently orphan files on disk. At minimum this needs a regression test that defines the intended contract before merge: either fail the delete when file cleanup fails, or explicitly log and preserve records until cleanup succeeds.

4. The upgrade path is not covered. config_default.py adds 4.0.2 -> 4.0.3, and migration_28.py adds the new DB column, but the passing suites do not exercise either path. Add tests for loading a 4.0.2 config and for migrating an existing images table so old rows get image_subfolder = ''.

5. Because there is no full DOM gallery harness, the backend route regression still needs coverage. recall_parameters.py switched from image_files to images, which is correct for subfolders, but there is no test proving recall still works for a record stored outside the root outputs/images/ folder. A small router/helper test around load_image_file() would cover that user-visible path without needing browser tests.

[JPPhoto]

One remaining test gap: the PR now covers path validation, service forwarding, recall behavior, config migration, and migration 28, but it still does not verify the SQLite storage contract for image_subfolder.

The risky path is invokeai/app/services/image_records/image_records_sqlite.py, invokeai/app/services/image_records/image_records_sqlite.py, and invokeai/app/services/image_records/image_records_sqlite.py: save(), get()/get_many(), and delete_intermediates() all now depend on real DB round-tripping of image_subfolder. The new tests mostly mock above this layer, so they would not catch a persistence or deserialization regression here. Consider one temporary DB-backed test with the same strategy used in tests/app/services/model_records/test_model_records_sql.py.

More importantly, we collectively still have to have a conversation about how migrating or changing this setting affects existing images, if at all.