chore(release): 1.13.0 [skip ci]

# [1.13.0](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.12.0...v1.13.0) (2026-10-02)

### Bug Fixes

* **negpip:** support Krea attention on ComfyUI 0.28 ([e4eabfe](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/e4eabfefd540f3a6066c29761cefb8f8b3c80f68))

### Features

* **sampling:** add noise inversion and composable sampler options ([be4bd9b](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/be4bd9bb162f6ed4252e0c4d4ef0f3efebe8c674))
* **sampling:** refine sampler options and inversion controls ([ab7cebc](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/ab7cebcebc4d5dfa95aa8d834456af1778fe56a6))

.comfyignore

@@ -0,0 +1,13 @@
+.github/
+tests/
+tools/
+scripts/
+web/src/
+web/tests/
+AGENTS.md
+.releaserc.cjs
+eslint.config.js
+package-lock.json
+package.json
+tsconfig.json
+vitest.config.ts

.github/workflows/quality-gates.yml

@@ -0,0 +1,62 @@
+name: quality gates
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    env:
+      SIMPLE_SYRUP_TEST_COMFY_CPU: "1"
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22.14.0
+          cache: npm
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Install ComfyUI host dependencies
+        shell: bash
+        run: |
+          set -euo pipefail
+          git clone --depth 1 https://github.com/comfyanonymous/ComfyUI.git "$RUNNER_TEMP/ComfyUI"
+          rsync -a --exclude=".git" "$RUNNER_TEMP/ComfyUI/" "$GITHUB_WORKSPACE/../.."/
+          pip install -r "$GITHUB_WORKSPACE/../../requirements.txt"
+
+      - name: Install Python dependencies
+        run: pip install -e . pytest pytest-xdist ruff mypy
+
+      - name: Check architecture governance
+        run: python -m tools.check_architecture
+
+      - name: Check test governance
+        run: python -m tools.check_test_governance
+
+      - name: Verify Python formatting
+        run: ruff format --check .
+
+      - name: Verify Python lint
+        run: ruff check .
+
+      - name: Verify Python types
+        run: mypy --strict simple_syrup tests
+
+      - name: Verify Python tests
+        run: pytest -n auto -q -m "not external_artifact"
+
+      - name: Verify frontend
+        run: npm run check:web

.github/workflows/release.yml

@@ -50,12 +50,15 @@ jobs:
           "transformers${{ matrix.version }}"
 
       - name: Verify GroundingDINO BERT compatibility
+        env:
+          PYTHONPATH: ${{ github.workspace }}/tests
         run: >-
           python -m pytest -q
+          --noconftest
           --rootdir=tests
           --confcutdir=tests
-          tests/test_grounding_dino_bert_adapter.py
-          tests/test_grounding_dino_text_token_masks.py
+          tests/segmentation/detection/test_grounding_dino_bert_adapter.py
+          tests/segmentation/detection/test_grounding_dino_text_token_masks.py
 
   release:
     if: github.event_name != 'pull_request'
@@ -97,6 +100,12 @@ jobs:
       - name: Verify Python formatting
         run: ruff format --check .
 
+      - name: Check architecture governance
+        run: python -m tools.check_architecture
+
+      - name: Check test governance
+        run: python -m tools.check_test_governance
+
       - name: Verify Python lint
         run: ruff check .
 
@@ -104,7 +113,7 @@ jobs:
         run: mypy --strict simple_syrup tests
 
       - name: Verify Python tests
-        run: pytest -n auto -q
+        run: pytest -n auto -q -m "not external_artifact"
 
       - name: Verify frontend
         run: npm run check:web
@@ -113,6 +122,10 @@ jobs:
         id: release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GIT_AUTHOR_NAME: Daisy
+          GIT_AUTHOR_EMAIL: daisy@artificialsweetener.ai
+          GIT_COMMITTER_NAME: Daisy
+          GIT_COMMITTER_EMAIL: daisy@artificialsweetener.ai
         shell: bash
         run: |
           set -euo pipefail

.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+repos:
+  - repo: local
+    hooks:
+      - id: architecture-governance
+        name: Enforce architecture governance
+        entry: ..\..\venv\Scripts\python.exe -m tools.check_architecture
+        language: system
+        pass_filenames: false
+        always_run: true
+      - id: test-governance
+        name: Enforce test governance
+        entry: ..\..\venv\Scripts\python.exe -m tools.check_test_governance
+        language: system
+        pass_filenames: false
+        always_run: true
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [--fix=lf]
+        exclude: '(\.bat$|\.cmd$|\.ps1$)'
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: check-json
+        exclude: '(^web/dist/|tsconfig\.json$)'
+      - id: check-toml

AGENTS.md

@@ -35,6 +35,8 @@ Engineering priority is strict architecture, strong separation of concerns, comp
 ### Required Command Forms
 
 - Tests: `..\..\venv\Scripts\python.exe -m pytest -n auto -q`
+- Architecture: `..\..\venv\Scripts\python.exe -m tools.check_architecture`
+- Test governance: `..\..\venv\Scripts\python.exe -m tools.check_test_governance`
 - Lint: `..\..\venv\Scripts\ruff.exe check .`
 - Format: `..\..\venv\Scripts\ruff.exe format .`
 - Type check: `..\..\venv\Scripts\mypy.exe --strict simple_syrup tests`
@@ -94,6 +96,34 @@ If a required tool is missing from `..\..\venv`, install or update development d
 - Reorganize modules when it improves architecture.
 - Align touched modules with the ownership and dependency rules in this file.
 
+## Architecture Governance
+
+- Repository governance lives under `governance/`.
+- `governance/architecture/policy.toml` defines every authored-code root,
+  extension, exclusion, and the 350-line soft and 500-line hard structural
+  thresholds.
+- `governance/architecture/debt.toml` records exact assessed mixed ownership.
+- `governance/architecture/waivers.toml` records exact bounded hard-gate
+  exceptions.
+- `governance/architecture/import_debt.toml` records exact current dependency-
+  direction violations; new violations are prohibited.
+- `governance/architecture/soft_reviews.toml` records the current human
+  disposition of every file between the soft and hard thresholds.
+- Every hard-gate file requires source-level ownership review.
+- Use a structural waiver only for one cohesive authoritative owner whose
+  invariants would be divided by extraction.
+- Mixed ownership requires debt and a linked remediation waiver naming the
+  next extraction and a lower next limit.
+- Waivers and debt are fingerprinted current state, not historical ledgers.
+- Delete resolved records; do not extend dates or limits merely to pass the
+  checker.
+- `governance/testing/policy.toml` defines Python and frontend test-layout and
+  reliability discovery.
+- Every test-governance candidate requires an exact classification or
+  debt-remediation disposition.
+- Run both governance checkers after changing authored structure, test
+  placement, isolation, timing, resources, or reviewed state.
+
 ## ComfyUI Node Rules
 
 - Public node identifiers are compatibility-sensitive.

CHANGELOG.md

@@ -1,86 +1,154 @@
-# [1.6.0](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.5.0...v1.6.0) (2026-08-09)
+# [1.13.0](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.12.0...v1.13.0) (2026-10-02)
 
 
 ### Bug Fixes
 
-* **cache:** make integer narrowing checker-independent ([6e2d1e1](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/6e2d1e1844b361f9b2f3a31c8538cfde0ce7c6b1))
-* **mask:** preserve missing-alpha image geometry ([70ffeb5](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/70ffeb530acb1f5e55ac6e06adcc07ba4560d776))
-* **media:** stabilize native ordered preview controls ([3d03b1d](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/3d03b1dfbc2eef3cee900173ddda57e03d5bc43d))
-* **regional:** align prompt batches and LoRA hooks ([646e4e7](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/646e4e7cab0ed299e704c4acbf64849181180076))
-* **runtime:** centralize Comfy patcher lifecycle ([fda2ef4](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/fda2ef4074e8550a406ada317f0a3bfb7db39cf6))
+* **negpip:** support Krea attention on ComfyUI 0.28 ([e4eabfe](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/e4eabfefd540f3a6066c29761cefb8f8b3c80f68))
 
 
 ### Features
 
-* **conditioning:** add regional prompting and SEP-local LoRAs ([be26493](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/be264935a8cb0e805222de9d615a197a788d8f01))
-* **conditioning:** support labeled prompt separators ([a24da13](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/a24da1359cc9966762d8e1fa4fde3dbdef879cfa))
-* **loaders:** add automatic FLUX model loaders ([08fd18c](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/08fd18cc6fdf6a7f9ff3657c323b31e8960a235a))
-* **media:** add native ordered loaders and SEGS preview ([dbde2a9](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/dbde2a9266dd043b92126e42e502cc88d9fba777))
-* **sampling:** add contextual diffusion sampler ([6c2e2da](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/6c2e2dad9c6db42a2a2a82d1e4a17e4db4bb0fbf))
-* **sampling:** expose evaluated context SEGS ([53a2771](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/53a2771ce815a0705b92f4766e56f11adbd9dedb))
-* **segmentation:** add interactive SEGS preview ([21db62d](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/21db62d3acee0b1d087f83e01fb5b92c912f4df6))
-* **segmentation:** add SAM region overlay ([d1ead71](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/d1ead71ca714e365bf27448170e6c8c8fccd2f5a))
-* **segmentation:** add SAM-guided tiled diffusion ([e50ec0e](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/e50ec0ea79620af63f32c25a934b2b06fc4d9484))
+* **sampling:** add noise inversion and composable sampler options ([be4bd9b](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/be4bd9bb162f6ed4252e0c4d4ef0f3efebe8c674))
+* **sampling:** refine sampler options and inversion controls ([ab7cebc](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/ab7cebcebc4d5dfa95aa8d834456af1778fe56a6))
 
-# [1.5.0](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.4.0...v1.5.0) (2026-07-14)
+# [1.12.0](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.11.1...v1.12.0) (2026-09-29)
 
 
 ### Bug Fixes
 
-* **groundingdino:** support transformers v4 and v5 ([239070b](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/239070b12d3eecbfd5c47c9410c7ca31ac1402ac))
+* **release:** satisfy RES4LYF publication contracts ([04dc35a](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/04dc35af00163689509cace1541a8e7d33b5053e))
 
 
 ### Features
 
-* **masking:** expand segmentation tooling and progress ([f70766d](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/f70766dafe096895ad8d6309681fd59270664600))
+* **sampling:** add RES4LYF sampler methods and schedules ([7b1efef](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/7b1efef47e20b9bf6f032dd57971899d99881822))
 
-# [1.4.0](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.3.0...v1.4.0) (2026-06-02)
+## [1.11.1](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.11.0...v1.11.1) (2026-09-25)
 
 
 ### Bug Fixes
 
-* **tiled-diffusion:** clamp overlap for small latents ([d7448c6](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/d7448c6ca52ce517b8d0f8ee697249c5def13535))
+* **release:** attribute automation to Daisy ([2ae545d](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/2ae545d64d70a454f635ee647fb7e6a1c3500b9b))
+
+# [1.11.0](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.10.1...v1.11.0) (2026-09-25)
 
 
 ### Features
 
-* **detailing:** add external llm segs tagging ([b7cd40c](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/b7cd40c85ae9f9514d0b1ff3c3f6007730796752))
-* **segs:** add regional batching and wd14 tagging nodes ([fef60ad](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/fef60adeca2c8ec7c0641e8106bb0863ee2f195e))
+* **sampling:** make negative conditioning optional ([0bc81dc](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/0bc81dc4d00a13d42c65440da2058e94a505e8d5))
 
-# [1.3.0](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.2.0...v1.3.0) (2026-05-26)
-
-
-### Features
-
-* **prompt-control:** add schedule and encode prompt node ([bd515e6](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/bd515e696cedcc78d056af6c23b9193e34f131bc))
-
-# [1.2.0](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.1.0...v1.2.0) (2026-05-25)
-
-
-### Features
-
-* **nodes:** add VAE options and clone-safe diffusion ([6ff2dc8](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/6ff2dc8c24a6f7ddde3182b81bcbe6aad65427f4))
-
-# [1.1.0](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.0.0...v1.1.0) (2026-05-23)
+## [1.10.1](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.10.0...v1.10.1) (2026-09-24)
 
 
 ### Bug Fixes
 
-* **detailers:** align SEGS mask blending behavior ([74c83a6](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/74c83a6a70407aea6a34b0c0e31408f32b929882))
-* use SimpleSyrup package identity ([4fa5582](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/4fa5582796e9ace2a8805cb1ea2aebce65551e89))
+* **ci:** expose test support to compatibility jobs ([0517f71](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/0517f71da891414e9773c5cd47879ff748492e70))
+* **governance:** enforce SugarSubstitute quality standards ([bbaed2c](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/bbaed2c90656cd4e65e5bfcd4c0451f90ec2d7c7))
+
+# [1.10.0](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.9.3...v1.10.0) (2026-09-21)
 
 
 ### Features
 
-* **detection:** add keep-only SEGS selection ([8f8ee91](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/8f8ee91dea3ce1a044c0e61b482e571c51b372bc))
+* **loaders:** add Krea 2 model loader ([166f029](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/166f029d12e5fce019133cc38be7279d05a5ecbc))
 
-# 1.0.0 (2026-05-22)
+## [1.9.3](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.9.2...v1.9.3) (2026-09-20)
+
+
+### Bug Fixes
+
+* **attention-coupling:** restore regional LoRA sampling ([0255a0f](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/0255a0f5044278f14452b6b2582ec6646083f756))
+
+## [1.9.2](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.9.1...v1.9.2) (2026-09-20)
+
+
+### Bug Fixes
+
+* **registry:** remove flagged package content ([f3a53b5](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/f3a53b5ec6c080d98f7e9599cf55e849cf338021))
+
+## [1.9.1](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.9.0...v1.9.1) (2026-09-20)
+
+
+### Bug Fixes
+
+* **contextual-diffusion:** project reference latents into views ([4cd780a](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/4cd780a2451aa472ce826834e4426b65693c46e8))
+
+# [1.9.0](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.8.0...v1.9.0) (2026-09-19)
 
 
 ### Features
 
-* initial release ([e513baf](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/e513baf70a20306856e40fbf2afd80b25f5655a6))
+* **prompts:** add automatic NegPiP support ([6d052e9](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/6d052e9800985696972bf431fa7dae4972a56313))
 
-# Changelog
+# [1.8.0](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.7.1...v1.8.0) (2026-09-19)
 
-All notable changes to this project will be documented in this file.
+
+### Bug Fixes
+
+* **downloads:** keep unknown sizes indeterminate ([a31467c](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/a31467cd3a4299e9e3929d44281018dba0322b3e))
+* **models:** hide installed catalog choices ([d887e87](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/d887e87e03eb6d0d9d5325fe43b67fbd9e47cf71))
+
+
+### Features
+
+* **models:** add curated ultralytics downloads ([b907fa2](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/b907fa2a17afa30170bc22cf1134a750241e55c2))
+* **models:** prioritize installed ultralytics choices ([d30e04f](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/d30e04f229366d3e1d2388bd4d713b2b47a12a1f))
+
+## [1.7.1](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.7.0...v1.7.1) (2026-09-11)
+
+
+### Bug Fixes
+
+* **regional:** preserve shared model patch ancestry ([6059a3f](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/6059a3f913a9502671666e83faeb8686a7a8da27))
+
+# [1.7.0](https://github.com/Artificial-Sweetener/SimpleSyrup/compare/v1.6.0...v1.7.0) (2026-09-05)
+
+
+### Bug Fixes
+
+* **anima:** support regional prompting across Comfy versions ([41a234a](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/41a234a85a4cfcdc4cfce68b80b4b9982719aab4))
+* **attention:** preserve anchored concept geometry ([1136efd](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/1136efd2ad8708b14320d04eab2f6489efbec282))
+* **cache:** make integer narrowing checker-independent ([2547767](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/254776791766c41c75a69ceb5b207c54949446c9))
+* **detailers:** align SEGS mask blending behavior ([a3120ae](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/a3120aebe8834982706d93784a39ab501c6ff40a))
+* **groundingdino:** support transformers v4 and v5 ([3387c03](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/3387c03eb59f244d56f6a0dfe86cedab1847a8e2))
+* **mask:** preserve missing-alpha image geometry ([caf7d37](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/caf7d37a154ddc62405807b56550efdaa831d09e))
+* **media:** stabilize native ordered preview controls ([1235652](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/123565225a1104234a7c9f5c43af0772c7508db8))
+* **regional:** align prompt batches and LoRA hooks ([656d197](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/656d1970e12be18304b057b07204dcbbe367432b))
+* **runtime:** centralize Comfy patcher lifecycle ([0e5f513](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/0e5f513ae0f33f40c6a8bd09161043a5af598392))
+* **sampling:** normalize model-specific latent layouts ([b2084a7](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/b2084a7a9bf04709af51380bc1ef4a09ccb9babc))
+* **tiled-diffusion:** clamp overlap for small latents ([fecba36](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/fecba36e4e11f0da681c6a5d9d42e18093d741fc))
+* **tools:** return host-native checkpoint selections ([c7cb8d2](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/c7cb8d29f83ebd44b48038b7ce5e65a0a6f445b4))
+* use SimpleSyrup package identity ([1659d13](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/1659d131f4215fa0baccc4c70024d63590460e67))
+
+
+### Features
+
+* **anima:** add cached quantization profiles ([c20664f](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/c20664f8925305465ccb4c028d0a78a6364a037d))
+* **attention:** add sampler-derived concept regions ([8ca5d2c](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/8ca5d2c325e1caee822883ba568b25f721e51343))
+* **attention:** default regional prompts to full weight ([f829321](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/f82932193951bae75d59e1c7c7dba2d187e3c175))
+* **attention:** improve concept isolation fidelity and speed ([01826ad](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/01826ad1b7c64b11c8af031691403ecf521cb1b5))
+* **attention:** refine attention-derived region masks ([dff84cc](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/dff84cce2322e64b8a9ada91b84550faf3a5c7a1))
+* **conditioning:** add regional prompting and SEP-local LoRAs ([d3de028](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/d3de02816b24bea129e77b82568ad47a0fd0ba99))
+* **conditioning:** support labeled prompt separators ([a708e0b](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/a708e0b4187b0d5f9aeb58f5ab0d276b8a046395))
+* **detailing:** add external llm segs tagging ([207c449](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/207c4492908371f41aca84c74332c1a1f63d8045))
+* **detection:** add keep-only SEGS selection ([4f65ae0](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/4f65ae0dd36e43347b40ae64039f40e8a67aea48))
+* initial release ([4b6525c](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/4b6525ce6ff42f06a7ffd48a54186fcb625f0e21))
+* **loaders:** add automatic FLUX model loaders ([33bff75](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/33bff75af1b001b716a45f4fadc9e0e0aa20ced1))
+* **masking:** expand segmentation tooling and progress ([adba198](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/adba1981a4bdb43307496a84cccbfe100ae2174f))
+* **media:** add native ordered loaders and SEGS preview ([fcf38f2](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/fcf38f2010cfadc76be74410857387c74db3b575))
+* **nodes:** add VAE options and clone-safe diffusion ([5fc0f3d](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/5fc0f3d8e5ef5fbac0306b1d3c70464a035c396c))
+* **prompt-control:** add schedule and encode prompt node ([af32cec](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/af32cec99f5bdadcbed9f8c33db0d816ad4b72f0))
+* **regional:** add native SDXL adapter execution ([068e3db](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/068e3db17d13c875a383c85e6cf931f96459c3b1))
+* **regional:** add universal attention coupling foundation ([edfc26c](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/edfc26c9122ff0c18d63e9b80832d587594e9e62))
+* **regional:** build universal adapter execution foundation ([864852d](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/864852dc9e591a3041e23b342346495a7fbf6589))
+* **regional:** complete capability-routed execution ([fe96a20](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/fe96a206dbf1edcae022b1346f998ed184142062))
+* **regional:** complete persistent regional LoRA execution ([7b5987d](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/7b5987d6fa66f8deee2655d18b1209bbe20271d6))
+* **sampling:** add contextual diffusion sampler ([24bf630](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/24bf6309023c552f65947814d9641555a73c8337))
+* **sampling:** add deterministic seed variation ([7921be3](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/7921be3f9067a26fe5fa47fb8fb370e7cb1679f3))
+* **sampling:** add regional diffusion sampling ([f7dffca](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/f7dffcacfe104be173793ce412f994519e11e02e))
+* **sampling:** bypass inactive attention coupling ([b2b8dc4](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/b2b8dc4b016307fd351892f50264c64532898681))
+* **sampling:** expose evaluated context SEGS ([04a2c3e](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/04a2c3e6e90f9bbb9e3922412844afe5a4e6869f))
+* **segmentation:** add interactive SEGS preview ([c9e303e](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/c9e303ec4727576af124d9e8ea20d0103f67e7ae))
+* **segmentation:** add SAM region overlay ([a72c796](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/a72c796d8d6d64a52fed7d281fe53eebc74639ed))
+* **segmentation:** add SAM-guided tiled diffusion ([968090d](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/968090de87a4fad726fd37d0a08966c01f11a8fd))
+* **segs:** add regional batching and wd14 tagging nodes ([600d9e3](https://github.com/Artificial-Sweetener/SimpleSyrup/commit/600d9e311b5b8c45762e15c88f54df33454261b5))

PLAN.md

@@ -1,543 +0,0 @@
-# Plan: Image-Associated Mask to SEGS
-
-## Goal
-
-Add a SimpleSyrup node that converts an existing ComfyUI mask into Impact-compatible SEGS while associating every SEG with cropped image data from the source image.
-
-The node should feel like `Detect SEGS w/ Ultralytics`, but it must take an `IMAGE` and a `MASK` instead of an image and detector model. It should expose the same general region workflow controls where they make sense: size filtering, keep-only limiting, mask dilation, post-dilation, crop factor, sort order, and optional unioning into one SEG.
-
-## Decisions From Maintainer Discussion
-
-- This should be a first-class SimpleSyrup node, not just documentation for an Impact Pack workflow chain.
-- The node should behave like a detector-style SEGS source because downstream users think of this as "pre-detected regions from a mask."
-- The node must take both `image` and `mask`.
-- The output SEGS must include full image association by storing each SEG's `cropped_image` from the input image.
-- The node should support masks with multiple disconnected regions.
-- The node should let users choose whether disconnected regions become separate SEGs or one combined SEG.
-- The node should include controls similar to `Detect SEGS w/ Ultralytics` and in a similar order.
-- The node should not expose detector confidence controls because the input is an existing mask, not detector predictions.
-- Segment confidence should be fixed at `1.0`.
-- The existing Impact Pack nodes can already do some of this with `MASK to SEGS` plus `Set Default Image for SEGS`, but that is not the desired UX for SimpleSyrup.
-
-## Existing Code To Reuse
-
-Use these SimpleSyrup modules as the main implementation references:
-
-- `simple_syrup/nodes/detect_segs_with_ultralytics.py`
-  - Existing detector-style node UX and control order.
-  - Current output shape: `RETURN_TYPES = ("SEGS", "MASK")`.
-  - Current list behavior for batched images: `OUTPUT_IS_LIST = (True, False)`.
-  - Applies `limit_segs`, `sort_segs`, and then `build_combined_segs_result`.
-- `simple_syrup/services/segs_detection_service.py`
-  - Existing service pattern for constructing `Segment` objects from masks and image crops.
-  - Uses `crop_region_for_bbox`, `crop_mask`, `crop_image`, and `dilate_mask`.
-- `simple_syrup/services/segs_output_service.py`
-  - `build_combined_segs_result()` already creates a one-SEG union with `cropped_image`.
-  - `combined_mask_from_segs()` already produces the mask output from SEGS.
-  - `coerce_cropped_mask()` validates crop-local SEG masks.
-  - This module should become the shared owner for detector-style SEGS output finalization.
-- `simple_syrup/masking/segs_mask_ops.py`
-  - Reuse image validation, mask crop, image crop, resize, crop factor, and signed dilation behavior.
-- `simple_syrup/domain/segs.py`
-  - Reuse `Segment`, `BoundingBox`, `CropRegion`, `NativeSegs`, `SORT_ORDER_OPTIONS`, `limit_segs`, `sort_segs`, and `to_impact_compatible_segs`.
-
-Use these Impact Pack modules only as behavioral references, not as imports:
-
-- `E:\ComfyUI\custom_nodes\comfyui-impact-pack\modules\impact\segs_nodes.py`
-  - `MaskToSEGS` splits or combines mask regions.
-  - `DefaultImageForSEGS` attaches cropped source image data after mask conversion.
-  - `SEGSMerge`, `SEGSOrderedFilter`, and `DilateMaskInSEGS` show existing user expectations.
-- `E:\ComfyUI\custom_nodes\comfyui-impact-pack\modules\impact\core.py`
-  - `mask_to_segs()` uses contour detection for disconnected regions.
-  - `batch_mask_to_segs()` handles batched masks for video-style masks.
-
-Do not import Impact Pack code. SimpleSyrup tests already enforce avoiding external pack imports.
-
-## Node Name And Contract
-
-Add a new Comfy v3 node:
-
-- Node id: `SimpleSyrup.MaskToSEGS`
-- Display name: `Mask to SEGS`
-- Category: `SimpleSyrup/Detection`
-- Search aliases: `mask`, `segs`, `region`, `detect`, `segmentation`
-- Description: `Converts an existing mask into image-associated SEGS for detail and regional workflows.`
-
-Outputs:
-
-- `segs: SEGS`
-- `mask: MASK`
-
-Output behavior should match `Detect SEGS w/ Ultralytics`:
-
-- `segs` is list-output compatible, one SEGS payload per input image/mask pair.
-- `mask` is a standard ComfyUI batched mask tensor with shape `(B, H, W)`.
-- The output mask is the union of the retained SEGS after filtering, sorting, and optional combining.
-
-## Architecture Landing Shape
-
-Do not add a third copy of the detector-style output pipeline.
-
-The current code has two nodes that inline the same sequence after SEGS extraction:
-
-1. `simple_syrup/nodes/detect_segs_with_ultralytics.py`
-2. `simple_syrup/nodes/prompt_segs_with_sam.py`
-
-Both nodes currently perform:
-
-```python
-segs = limit_segs(segs, keep_only, keep_by)
-segs = sort_segs(segs, sort_order)
-combined = build_combined_segs_result(single_image, segs, crop_factor)
-output_segs = combined.segs if combine_segs else segs
-segs_outputs.append(to_impact_compatible_segs(output_segs))
-mask_outputs.append(combined.mask)
-```
-
-The new mask node must not duplicate this sequence inline. Instead, implement a shared output-finalization helper in `simple_syrup/services/segs_output_service.py` and refactor the existing detector nodes to use it.
-
-Recommended shape:
-
-- `MaskToSEGSService`
-  - Owns only one-image, one-mask extraction into separate native SEGS.
-  - Does not own `keep_only`, `sort_order`, `combine_segs`, Impact-compatible conversion, or output mask construction.
-- `segs_output_service`
-  - Owns the common detector-style post-processing pipeline:
-    1. limit SEGS
-    2. sort SEGS
-    3. build the combined result
-    4. choose separate or combined output SEGS
-    5. convert output SEGS to Impact-compatible shape
-    6. return the paired mask output
-- Node classes
-  - Own Comfy-facing schema, batch iteration, and wiring only.
-  - Delegate source-specific extraction to a source service.
-  - Delegate shared final output shaping to `segs_output_service`.
-
-This keeps ownership strict:
-
-- Mask-derived region extraction belongs to the mask-to-SEGS service.
-- Detector model inference belongs to detector services.
-- Prompt/SAM detection belongs to the SAM prompt service.
-- Sorting, limiting, combining, and output mask generation belong to the shared SEGS output service.
-- Domain helpers remain pure SEGS policies and value conversions.
-
-## Input Schema
-
-Use this input order:
-
-1. `image: IMAGE`
-2. `mask: MASK`
-3. `mask_threshold: FLOAT`
-4. `size_threshold: INT`
-5. `keep_only: INT`
-6. `mask_dilation: INT`
-7. `post_dilation: INT`
-8. `crop_factor: FLOAT`
-9. `sort_order: SORT_ORDER_OPTIONS`
-10. `combine_segs: BOOLEAN`
-11. `label: STRING`
-
-Detailed input behavior:
-
-- `image`
-  - Source image used to associate cropped image data with every SEG.
-  - Must be a ComfyUI `IMAGE` tensor shaped `(B, H, W, C)`.
-- `mask`
-  - Source mask to convert into SEGS.
-  - Must be a ComfyUI `MASK` tensor shaped `(B, H, W)` or a single mask compatible with the image batch.
-  - The implementation may support a single mask for a single image first. If supporting image batches, batch count must either match the image batch or be exactly `1` for reuse across all images.
-- `mask_threshold`
-  - Default: `0.5`
-  - Min: `0.0`
-  - Max: `1.0`
-  - Step: `0.01`
-  - Converts soft masks into active pixels before region extraction.
-  - Active pixels are `mask >= mask_threshold`.
-- `size_threshold`
-  - Default: `10`
-  - Min: `1`
-  - Max: `8192`
-  - Drops extracted regions whose bounding box is smaller than this many pixels wide or tall.
-  - Match the wording and role of `Detect SEGS w/ Ultralytics`'s `size_threshold`.
-- `keep_only`
-  - Default: `0`
-  - Min: `0`
-  - Max: `4096`
-  - Keeps only the largest N regions after size filtering. `0` keeps all regions.
-  - Do not expose a confidence ranking option. There is no detector confidence.
-- `mask_dilation`
-  - Default: `0`
-  - Min: `-512`
-  - Max: `512`
-  - Signed dilation applied to the full input mask before region extraction.
-  - Positive grows mask regions; negative erodes them.
-- `post_dilation`
-  - Default: `0`
-  - Min: `-512`
-  - Max: `512`
-  - Signed dilation applied to each final crop-local SEG mask after the crop is chosen.
-  - This mirrors the Ultralytics node's final SEG mask cleanup behavior.
-- `crop_factor`
-  - Default: `3.0`
-  - Min: `0.0`
-  - Max: `100.0`
-  - Step: `0.1`
-  - `0.0` means use the full image as the crop, matching SimpleSyrup's existing detector convention.
-  - Values greater than or equal to `1.0` expand the SEG crop around the extracted region's bounding box.
-  - Values between `0.0` and `1.0` must fail with an actionable `ValueError`.
-- `sort_order`
-  - Use `SORT_ORDER_OPTIONS` from `simple_syrup.domain.segs`.
-  - Default: `largest to smallest`.
-  - Sort extracted regions before output and before any combined mask result is built.
-- `combine_segs`
-  - Default: `False`
-  - `False` returns one SEG per disconnected mask region.
-  - `True` returns one unioned SEG representing all retained mask pixels.
-- `label`
-  - Default: `mask`
-  - Label applied to extracted SEGs.
-  - If `combine_segs` is true, the combined output label should be `combined` unless there is a strong reason to preserve the user label. Match `build_combined_segs_result()` unless intentionally extending it.
-
-## Behavior Details
-
-### Region Extraction
-
-Add a new service, probably `simple_syrup/services/mask_to_segs_service.py`, with a class such as `MaskToSEGSService`.
-
-The service should own:
-
-- Image and mask validation.
-- Mask thresholding.
-- Signed full-mask dilation.
-- Disconnected region extraction.
-- Per-region bounding box calculation.
-- Size filtering.
-- Crop region calculation.
-- Crop-local mask creation.
-- Optional post-dilation on each crop-local mask.
-- Cropped image association.
-- Native immutable SEGS output.
-
-The service must not own:
-
-- `keep_only`
-- final `sort_order`
-- `combine_segs`
-- Impact-compatible conversion
-- final output mask construction
-
-Those responsibilities belong to the shared SEGS output finalization helper.
-
-The node should own only Comfy-facing schema, input ordering, batch iteration, and wiring.
-
-### Connected Components
-
-Implement disconnected region extraction inside SimpleSyrup. Do not import Impact Pack.
-
-Prefer a torch-based or standard-library implementation over adding a new required runtime dependency. A simple deterministic flood-fill or connected-components routine is acceptable because masks are 2D binary tensors and the node is not model-bound.
-
-Connectivity decision:
-
-- Use 8-connected components unless tests or existing SimpleSyrup behavior strongly point to 4-connected components.
-- Document this in the service docstring and tests.
-- 8-connected behavior usually matches user expectations for painted masks where diagonal contact should remain one region.
-
-Extraction algorithm outline:
-
-1. Convert mask to a CPU `torch.bool` active-pixel tensor after threshold and dilation.
-2. If no pixels are active, return empty native SEGS. The shared output finalization helper is responsible for turning that into a zero mask output.
-3. Find connected components.
-4. For each component, compute bbox from active pixel coordinates.
-5. Drop components where bbox width or height is less than `size_threshold`.
-6. Create one `Segment` per kept component.
-
-The service always returns separate native SEGS. `combine_segs` is handled later by the shared output finalization helper so all detector-style SEGS nodes use the same combine behavior.
-
-### Mask Values
-
-Use thresholded masks to decide region membership, but preserve useful soft-mask values when forming crop-local masks where possible.
-
-Recommended behavior:
-
-- Use the thresholded, dilated mask for topology and bbox extraction.
-- Use the original normalized mask after `mask_dilation` as the crop-local mask values.
-- Zero out pixels outside the active component for each separate SEG.
-- Clamp all final masks to `0.0..1.0`.
-
-This lets soft masks retain feathered values inside each SEG while still giving deterministic region extraction.
-
-### Cropped Image Association
-
-Every returned `Segment` must set:
-
-- `cropped_image = crop_image(single_image, crop_region).detach().clone()`
-- `cropped_mask = crop-local mask tensor`
-- `confidence = 1.0`
-- `crop_region = CropRegion(...)`
-- `bbox = BoundingBox(...)`
-- `label = label`
-- `control_net_wrapper = None`
-
-This is the key difference from Impact Pack's `MASK to SEGS`, which creates SEGS without cropped image data and relies on a separate `Set Default Image for SEGS` node.
-
-### Batch Handling
-
-Match existing SimpleSyrup detector behavior as closely as possible:
-
-- Validate the image batch with `validate_image_batch()`.
-- Iterate image items with `iter_single_images()`.
-- Produce one SEGS payload per image.
-- Concatenate mask outputs into one `(B, H, W)` tensor.
-
-Mask batch rules:
-
-- If mask batch size equals image batch size, pair by index.
-- If mask batch size is `1` and image batch size is greater than `1`, reuse the mask for every image.
-- Otherwise raise `ValueError` explaining the mismatch.
-- Mask height and width must match the image height and width. Do not silently resize masks for this node unless the maintainer explicitly approves it later.
-
-## Sorting And Keeping
-
-Do not expose `keep_by` unless there is a future product decision to add multiple non-confidence policies.
-
-For `keep_only`, retain the largest regions by crop area before final sorting. Reuse `limit_segs(segs, keep_only, "largest size")` inside the shared output finalization helper for this node. Do not add a new ranking abstraction unless tests show the current domain helper cannot express the behavior clearly.
-
-Final output order must come from `sort_segs(segs, sort_order)`.
-
-## Shared Output Finalization
-
-Add a small result type and helper to `simple_syrup/services/segs_output_service.py`.
-
-Suggested result type:
-
-```python
-@dataclass(frozen=True)
-class FinalizedSegsOutput:
-    """Return Impact-compatible SEGS and its paired output mask."""
-
-    segs: object
-    mask: torch.Tensor
-```
-
-Suggested helper:
-
-```python
-def finalize_detector_segs_output(
-    image: object,
-    segs: NativeSegs,
-    keep_only: int,
-    keep_by: str,
-    crop_factor: float,
-    sort_order: str,
-    combine_segs: bool,
-) -> FinalizedSegsOutput:
-    """Apply shared detector-style SEGS output policy."""
-```
-
-Behavior:
-
-1. Apply `limit_segs(segs, keep_only, keep_by)`.
-2. Apply `sort_segs(segs, sort_order)`.
-3. Build `combined = build_combined_segs_result(image, segs, crop_factor)`.
-4. Use `combined.segs` when `combine_segs` is true; otherwise use the sorted separate SEGS.
-5. Convert chosen SEGS with `to_impact_compatible_segs`.
-6. Return the converted SEGS and `combined.mask`.
-
-For the new mask node, call this helper with `keep_by="largest size"` internally.
-
-Refactor these existing nodes to use the helper as part of this change:
-
-- `simple_syrup/nodes/detect_segs_with_ultralytics.py`
-- `simple_syrup/nodes/prompt_segs_with_sam.py`
-
-Add characterization tests before refactoring or preserve existing tests that already prove:
-
-- final sorting happens before combined output construction
-- keep-only limiting happens before final sorting
-- `combine_segs` chooses the combined SEGS while retaining the same output mask
-- returned SEGS are Impact-compatible
-
-The helper should be narrow. Do not move source-specific detection behavior into it.
-
-## V3 Registration
-
-Comfy v3 is the only supported export path.
-
-Preferred implementation:
-
-- Add a direct v3 node class under `simple_syrup/nodes_v3/mask_to_segs.py`.
-- Register it in `simple_syrup/nodes_v3/__init__.py::get_nodes()`.
-- Do not add `NODE_CLASS_MAPPINGS` or legacy export mappings.
-
-If reusing the legacy adapter pattern would materially reduce risk, it is acceptable to add a legacy-style internal node class under `simple_syrup/nodes/` and wrap it with `LegacyNodeV3Adapter`, but the public export must still be v3-only.
-
-The implementation should look native to the current codebase and should not add compatibility shims.
-
-## Tooltips
-
-Every visible input and output must have concise user-facing tooltip text.
-
-Required tooltip intent:
-
-- `image`: source image used for SEG crops.
-- `mask`: mask whose active regions become SEGS.
-- `mask_threshold`: threshold used to decide active mask pixels.
-- `size_threshold`: smallest region width or height to keep, in pixels.
-- `keep_only`: maximum number of largest regions to keep; `0` keeps all.
-- `mask_dilation`: grow or shrink the source mask before regions are found.
-- `post_dilation`: grow or shrink each final SEG mask after cropping.
-- `crop_factor`: context around each region; `0` uses the full image.
-- `sort_order`: output ordering for separate SEGS.
-- `combine_segs`: return one unioned SEG instead of separate regions.
-- `label`: label stored on extracted SEGs.
-- `segs` output: image-associated SEGS from the mask.
-- `mask` output: union of retained SEGS as a ComfyUI mask.
-
-## Tests To Add
-
-Add focused tests before or alongside implementation.
-
-### Shared Output Finalization Tests
-
-Add tests for the new helper in `tests/test_segs_output_service.py` or extend the existing SEGS output service coverage currently housed in `tests/test_ultralytics_detection_service.py`.
-
-Cover:
-
-- Applies `limit_segs` before `sort_segs`.
-- Builds the combined result from the limited and sorted SEGS.
-- Returns separate SEGS when `combine_segs` is false.
-- Returns one combined SEG when `combine_segs` is true.
-- Always returns the mask from `build_combined_segs_result`.
-- Converts output SEGS to Impact-compatible tuple/list shape.
-- Supports `keep_by="largest size"` for mask-derived SEGS.
-
-After this helper is tested, refactor `Detect SEGS w/ Ultralytics` and `Prompt SEGS w/ SAM` to use it without changing their public behavior.
-
-### Service Tests
-
-Create `tests/test_mask_to_segs_service.py`.
-
-Cover:
-
-- Single rectangular mask creates one SEG.
-- `cropped_image` matches the source image crop.
-- `cropped_mask` matches the mask crop.
-- Two disconnected regions create two separate SEGs.
-- Service always returns separate SEGS; combining is covered by shared output finalization tests and node tests.
-- Empty mask returns empty native SEGS from the service and a zero mask output through the node/output helper.
-- `mask_threshold` controls active pixels.
-- `mask_dilation` grows a source mask before region extraction.
-- Negative `mask_dilation` erodes a source mask.
-- `post_dilation` changes only crop-local final masks.
-- `crop_factor` expands crop regions.
-- `crop_factor = 0.0` uses the full image.
-- `0.0 < crop_factor < 1.0` raises `ValueError`.
-- `size_threshold` drops small components.
-- Soft mask values are clamped and retained inside component masks.
-- Batch mask and image mismatch raises an actionable error if batch handling is in the service.
-
-### Node Contract Tests
-
-Create `tests/test_mask_to_segs_node.py` or a v3-specific equivalent.
-
-Cover:
-
-- Node id is `SimpleSyrup.MaskToSEGS`.
-- Display name is `Mask to SEGS`.
-- Category is `SimpleSyrup/Detection`.
-- Outputs are `SEGS` and `MASK`.
-- The input list order exactly matches the plan.
-- Every input has a tooltip.
-- Every output has a tooltip.
-- No confidence input exists.
-- No detector model input exists.
-- No `keep_by` widget exists unless the implementation deliberately adds more non-confidence policies and updates this plan.
-- Execution returns Impact-compatible SEGS and a `(B, H, W)` mask.
-- `combine_segs = false` returns separate SEGs.
-- `combine_segs = true` returns one combined SEG.
-- `keep_only` keeps the largest mask-derived regions.
-- `sort_order` orders separate regions using existing domain policies.
-- Batched images return list-output SEGS and batched masks.
-
-### Registration Tests
-
-Update existing registration tests:
-
-- `SimpleSyrup.MaskToSEGS` appears in `get_nodes()`.
-- Adding the node does not remove or rename existing nodes.
-- Root `comfy_entrypoint` still exposes v3 nodes only.
-
-### Tooltip Coverage Tests
-
-Update `tests/test_node_tooltips.py` so the new node passes the repository tooltip requirements.
-
-## Implementation Steps
-
-- [x] Add or confirm characterization tests for the existing Ultralytics and SAM detector-style output behavior.
-  - Landing note: Existing node tests already covered separate/combined outputs, keep-only limiting, final sorting, combined-builder input order, and batch handling for both detector nodes.
-- [x] Add shared output finalization tests.
-  - Landing note: `tests/test_segs_output_service.py` now covers limit-before-sort, combined output selection, returned mask preservation, Impact-compatible conversion, and `keep_by="largest size"` for mask-derived SEGS.
-- [x] Add the shared output finalization helper in `segs_output_service.py`.
-  - Landing note: `FinalizedSegsOutput` and `finalize_detector_segs_output()` now own detector-style limit/sort/combine/conversion/mask finalization.
-- [x] Refactor `Detect SEGS w/ Ultralytics` and `Prompt SEGS w/ SAM` to use the helper without behavior changes.
-  - Landing note: Both nodes still own source-specific extraction and batch wiring, but delegate shared output shaping to `finalize_detector_segs_output()` with their injectable combined builders.
-- [x] Add the connected-component helper and mask-to-SEGS service.
-  - Landing note: `mask_components.py` implements deterministic 8-connected component extraction, and `MaskToSEGSService` now converts one image plus one mask into separate native SEGS with cropped image association.
-- [x] Add direct v3 node schema and execution wrapper.
-  - Landing note: `MaskToSEGSV3` defines the Comfy v3 schema directly, owns image/mask batch pairing, and delegates extraction plus shared output finalization.
-- [x] Register the node in `simple_syrup/nodes_v3/__init__.py`.
-  - Landing note: `SimpleSyrup.MaskToSEGS` is included in the base v3 node list.
-- [x] Add or update registration and tooltip tests.
-  - Landing note: Registration expectations include `SimpleSyrup.MaskToSEGS`; the schema-driven tooltip coverage includes every new input and output.
-- [x] Run focused tests for shared output finalization, existing detector nodes, the new service, the new node, registration, and tooltips.
-  - Landing note: Focused plan checks pass: `51 passed`.
-- [x] Run full Python gates.
-  - Landing note: `ruff format .`, `ruff check .`, `mypy --strict simple_syrup tests`, and full `pytest -n auto -q` pass. Full test result: `969 passed`.
-- [x] Do not touch frontend code unless the Comfy v3 UI requires it.
-  - Landing note: No frontend source or generated browser artifact was changed.
-
-## Verification Commands
-
-Run all commands from repository root with the ComfyUI virtual environment two directories above this repo.
-
-Focused checks during development:
-
-```powershell
-..\..\venv\Scripts\python.exe -m pytest -n auto -q tests\test_detect_segs_with_ultralytics_node.py tests\test_prompt_segs_with_sam_node.py
-..\..\venv\Scripts\python.exe -m pytest -n auto -q tests\test_segs_output_service.py
-..\..\venv\Scripts\python.exe -m pytest -n auto -q tests\test_mask_to_segs_service.py tests\test_mask_to_segs_node.py
-..\..\venv\Scripts\python.exe -m pytest -n auto -q tests\test_registration.py tests\test_node_tooltips.py
-```
-
-Required final gates:
-
-```powershell
-..\..\venv\Scripts\ruff.exe format .
-..\..\venv\Scripts\ruff.exe check .
-..\..\venv\Scripts\mypy.exe --strict simple_syrup tests
-..\..\venv\Scripts\python.exe -m pytest -n auto -q
-```
-
-If frontend code is touched, also run:
-
-```powershell
-npm ci
-npm run lint:web
-npm run typecheck:web
-npm run test:web
-npm run build:web
-```
-
-## Acceptance Criteria
-
-- A user can plug in an image and a mask and get ready-to-use image-associated SEGS.
-- A mask with two disconnected regions can produce either two SEGs or one combined SEG.
-- The node has detector-style controls that feel aligned with `Detect SEGS w/ Ultralytics`.
-- The node exposes no detector confidence controls.
-- Each SEG has `cropped_image`, `cropped_mask`, `crop_region`, `bbox`, `label`, and `confidence = 1.0`.
-- The returned SEGS are Impact-compatible.
-- The returned mask is the union of retained output SEGS.
-- The implementation does not import Impact Pack.
-- The implementation is covered by behavior tests, node contract tests, registration tests, and tooltip tests.
-- Full Python verification gates pass.

README.md

@@ -12,13 +12,13 @@ The pack now covers model loading, regional prompting and segmentation, high-res
 
 ## Highlights
 
-- Loaders that keep checkpoints, Anima, FLUX.1, and FLUX.2 models together with the text encoders, VAE, precision, and device choices they need.
+- Loaders that keep checkpoints, Anima, FLUX.1, FLUX.2, and Krea 2 models together with the text encoders, VAE, precision, and device choices they need.
 - My original Contextual Diffusion method for coherent high-resolution edits, plus MultiDiffusion and Mixture of Diffusers tiled sampling.
 - Impact-compatible SEGS detection, segmentation, interactive preview, batching, and detailers.
 - ADetailer-style `[SEP]` prompt batches, masked conditioning, and regional samplers, with optional Prompt Control scheduling and LoRA hooks.
 - WD14 and external vision LLM tagging that stays aligned with the right regions.
 - Ordered image and mask loading, GPU Lanczos resizing, tiled VAE options, and provenance-aware latent tools.
-- WebUI-inspired sampler and scheduler extras including A1111 Euler ancestral behavior, AYS, GITS, `automatic_a1111`, and beta57.
+- WebUI-inspired sampling extras including seed variation, A1111 Euler ancestral behavior, AYS, GITS, `automatic_a1111`, and RES4LYF sampler methods and schedules.
 
 ## Contents
 
@@ -74,7 +74,9 @@ Loading a checkpoint used to feel like choosing one file. Newer model families c
 
 **Simple Load FLUX** handles FLUX.1 with CLIP-L, T5-XXL, and its VAE. **Simple Load FLUX.2** inspects the selected diffusion model and chooses the matching text encoder family for FLUX.2 dev, Klein 4B, or Klein 9B/KV conditioning. Both loaders can find or download their known text encoders and VAEs with visible Comfy progress.
 
-The FLUX loaders only download those revision-locked, checksum-pinned support files. You still install and select the diffusion model. They also expose manual component selection, diffusion weight precision, and text-encoder device placement. Moving text encoding to the CPU can save VRAM, although it will take longer.
+**Simple Load Krea 2** validates the selected Raw or Turbo diffusion model and loads the required Qwen3-VL 4B encoder with Krea's layered conditioning plus the Qwen Image VAE. Auto uses the official FP8-scaled encoder; the advanced encoder choice can download either the checksum-pinned FP8-scaled or BF16 file.
+
+The FLUX and Krea 2 loaders only download those revision-locked, checksum-pinned support files. You still install and select the diffusion model. They also expose manual component selection, diffusion weight precision, and text-encoder device placement. Moving text encoding to the CPU can save VRAM, although it will take longer.
 
 ## Large images and high-resolution edits
 
@@ -150,7 +152,9 @@ The external LLM nodes use a configured OpenAI-compatible provider. **Tag SEGS w
 
 **Simple VAE Encode** can reuse the source latent when the graph proves that its image came directly from an unmodified `VAEDecode`. **Upscale Latent From Image** uses the same provenance to find and resize the original latent. Loading, editing, cropping, detailing, or resizing the image breaks that provenance. These nodes follow the graph instead of trying to identify a latent from the finished tensor.
 
-**KSampler (Extras)** adds the A1111/k-diffusion-style `euler_a_a1111` sampler, AYS SD1 and SDXL schedules, GITS, the `automatic_a1111` scheduler, and a local implementation of the RES4LYF beta57 preset. It keeps Comfy's regular seed handling, partial denoise behavior, progress callbacks, and conditioning inputs.
+**KSampler (Extras)** adds the A1111/k-diffusion-style `euler_a_a1111` sampler, AYS SD1 and SDXL schedules, GITS, `automatic_a1111`, and the RES4LYF beta57 and `bong_tangent` schedules. Its sampler dropdown includes 118 RES4LYF methods, including `exponential/ddim`. These methods are also available in the contextual, tiled, and Attention Coupling KSamplers. RES4LYF methods use their upstream default initial noise; Comfy samplers keep Comfy's normal noise path.
+
+**Seed Variation** patches a MODEL so Comfy-native samplers mix their normal initial noise toward a second deterministic seed. Strength `0` keeps the sampler seed unchanged, while strength `1` uses variation-seed initial noise. Ancestral and SDE samplers continue to use the sampler seed for additional noise introduced after initialization.
 
 The remaining utilities are **Latent Diagnostics**, **Scale Factor**, and **Seed**. Latent Diagnostics reports the latent shape, dtype, device, and tiled-sampling compatibility while passing it through unchanged.
 
@@ -162,7 +166,7 @@ SimpleSyrup adds three ComfyUI settings:
 - **SimpleSyrup: External LLM endpoint** stores the OpenAI-compatible base URL used to discover provider models and run the external prompt nodes.
 - **SimpleSyrup: External LLM API key** stores the provider key in OS credential storage.
 
-With downloadable models enabled, selecting a known missing catalog entry lets its loader download the required files. With the setting disabled, the dropdowns contain models SimpleSyrup can verify locally. Anima, FLUX.1, and FLUX.2 support components are resolved by their own loaders and use checksum-pinned automatic choices.
+With downloadable models enabled, selecting a known missing catalog entry lets its loader download the required files. With the setting disabled, the dropdowns contain models SimpleSyrup can verify locally. Anima, FLUX.1, FLUX.2, and Krea 2 support components are resolved by their own loaders and use checksum-pinned automatic choices. Automatic resolution checks cached and official paths first, then recognizes renamed files with matching size and checksum inside the appropriate ComfyUI model category. Known local support files are represented by their automatic choice instead of appearing again as manual dropdown entries.
 
 Saving the external LLM endpoint and API key refreshes the provider models available in connected SimpleSyrup nodes. Image inputs require a provider model with vision support.
 
@@ -178,6 +182,8 @@ SimpleSyrup currently interoperates with:
 
 AGPL-3.0-or-later is a strong copyleft license. If you convey SimpleSyrup or a modified version, you must provide the corresponding source. If users interact with a modified version over a network, you must offer those users the corresponding source for that version.
 
+The vendored RES4LYF license copy includes its upstream commercial-service paragraph before the GNU AGPL v3 text. Read the [RES4LYF license copy](third_party/licenses/res4lyf.LICENSE.txt) and [third-party notices](third_party/NOTICE.md) for the terms and provenance recorded with that code.
+
 SimpleSyrup owes a lot to other projects:
 
 - [ComfyUI](https://github.com/Comfy-Org/ComfyUI) provides the engine and graph ecosystem this pack runs on.
@@ -186,7 +192,8 @@ SimpleSyrup owes a lot to other projects:
 - [ComfyUI Prompt Control](https://github.com/asagi4/comfyui-prompt-control) provides the scheduled prompt and LoRA-hook behavior used by the optional integration.
 - [ComfyUI Layer Style Advance](https://github.com/chflame163/ComfyUI_LayerStyle_Advance) provides the SAM model bundle SimpleSyrup can adapt.
 - [Tiled Diffusion & VAE for AUTOMATIC1111](https://github.com/pkuliyi2015/multidiffusion-upscaler-for-automatic1111) informed the practical tiled diffusion and Mixture of Diffusers behavior reimplemented here.
-- [RES4LYF](https://github.com/ClownsharkBatwing/RES4LYF) is the source of the beta57 scheduler preset reimplemented here.
+- [RES4LYF](https://github.com/ClownsharkBatwing/RES4LYF) by ClownsharkBatwing and contributors provides the Runge-Kutta and exponential sampler methods included here, along with the `bong_tangent` schedule and the beta57 preset.
+- [ComfyUI-ppm](https://github.com/pamparamm/ComfyUI-ppm) by pamparamm provides the ModelPatcher-based NegPiP behavior adapted here and builds on the [ComfyUI port](https://github.com/laksjdjf/cd-tuner_negpip-ComfyUI) by laksjdjf and the [original WebUI implementation](https://github.com/hako-mikan/sd-webui-negpip) by hako-mikan.
 
 SimpleSyrup also vendors or reimplements selected third-party behavior for SAM-HQ, MobileSAM, GroundingDINO, AUTOMATIC1111 sampler behavior, k-diffusion, and tiled diffusion. See [third_party/NOTICE.md](third_party/NOTICE.md) for the complete notices.
 

__init__.py

@@ -12,13 +12,24 @@ from . import simple_syrup as _simple_syrup_package
 
 sys.modules.setdefault("simple_syrup", _simple_syrup_package)
 
-from .simple_syrup.runtime.external_llm_routes import (  # noqa: E402
+from .simple_syrup.integration.external_llm_routes import (  # noqa: E402
     register_external_llm_routes,
 )
-from .simple_syrup.runtime.mask_batch_preview_routes import (  # noqa: E402
+from .simple_syrup.integration.mask_batch_preview_routes import (  # noqa: E402
     register_mask_batch_preview_routes,
 )
-from .simple_syrup.runtime.settings_routes import register_settings_routes  # noqa: E402
+from .simple_syrup.integration.quant_cache_routes import (  # noqa: E402
+    register_quant_cache_routes,
+)
+from .simple_syrup.integration.settings_routes import (  # noqa: E402
+    register_settings_routes,
+)
+from .simple_syrup.runtime.attention_region_prompt_handler import (  # noqa: E402
+    register_attention_region_prompt_handler,
+)
+from .simple_syrup.runtime.comfy_safetensors_dtypes import (  # noqa: E402
+    register_comfy_safetensors_dtypes,
+)
 
 WEB_DIRECTORY = "./web/dist"
 
@@ -42,8 +53,11 @@ async def comfy_entrypoint() -> object:
 
 
 register_settings_routes()
+register_comfy_safetensors_dtypes()
+register_quant_cache_routes()
 register_external_llm_routes()
 register_mask_batch_preview_routes()
+register_attention_region_prompt_handler()
 
 __all__ = [
     "WEB_DIRECTORY",

governance/architecture/debt.toml

@@ -0,0 +1,2 @@
+schema_version = 1
+debts = []

governance/architecture/import_debt.toml

@@ -0,0 +1 @@
+schema_version = 1

governance/architecture/policy.toml

@@ -0,0 +1,41 @@
+schema_version = 2
+
+[structure]
+soft_lines = 350
+hard_lines = 500
+source_roots = [
+  "simple_syrup/domain",
+  "simple_syrup/image",
+  "simple_syrup/integration",
+  "simple_syrup/masking",
+  "simple_syrup/nodes",
+  "simple_syrup/nodes_v3",
+  "simple_syrup/runtime",
+  "simple_syrup/services",
+  "simple_syrup/shared",
+  "tests",
+  "tools",
+  "scripts",
+  "web/src",
+  "web/tests",
+]
+source_files = [
+  "__init__.py",
+  ".releaserc.cjs",
+  "eslint.config.js",
+  "simple_syrup/__init__.py",
+  "vitest.config.ts",
+]
+source_extensions = [
+  ".cjs",
+  ".js",
+  ".mjs",
+  ".py",
+  ".pyi",
+  ".ts",
+]
+excluded_paths = []
+
+[registries]
+debt = "governance/architecture/debt.toml"
+waivers = "governance/architecture/waivers.toml"

governance/architecture/soft_reviews.toml

@@ -0,0 +1,58 @@
+schema_version = 1
+review_by = 2027-03-31
+fingerprint = "sha256:a71fe87163eb7585fafbca08b585954be79abd884e3a1df38bc041c2bc934764"
+
+cohesive_paths = [
+  "simple_syrup/masking/prompt_segs_with_sam_service.py",
+  "simple_syrup/nodes/prompt_segs_with_sam.py",
+  "simple_syrup/runtime/attention_region_affinity.py",
+  "simple_syrup/runtime/attention_region_capture.py",
+  "simple_syrup/runtime/attention_sampler_lineage.py",
+  "simple_syrup/runtime/regional_lora/anima_module_surface.py",
+  "simple_syrup/runtime/spatial_model_arguments.py",
+  "simple_syrup/services/concept_attention_evidence.py",
+  "tests/comfy_integration/test_comfy_regional_adapter_resolver.py",
+  "tests/comfy_integration/test_comfy_regional_conditioning_processing.py",
+  "tests/models/loading/test_checkpoint_quantizer.py",
+  "tests/models/patching/test_model_patcher_mutations.py",
+  "tests/prompting/prompt_control/test_prompt_control_schedule_encode_graph.py",
+  "tests/regional_generation/anima/test_anima_activation_context.py",
+  "tests/regional_generation/anima/test_anima_full_tile_lora_equivalence.py",
+  "tests/regional_generation/anima/test_anima_loader.py",
+  "tests/regional_generation/anima/test_anima_multi_lora_composition.py",
+  "tests/regional_generation/anima/test_anima_regional_diagnostics.py",
+  "tests/regional_generation/anima/test_anima_regional_diagnostics_wrapper.py",
+  "tests/regional_generation/anima/test_anima_regional_permutation_diagnostics.py",
+  "tests/regional_generation/anima/test_anima_single_adapter_mutations.py",
+  "tests/regional_generation/attention_coupling/test_attention_coupling_model_preparation_service.py",
+  "tests/regional_generation/attention_regions/test_attention_region_capture.py",
+  "tests/regional_generation/attention_regions/test_attention_region_completion.py",
+  "tests/regional_generation/attention_regions/test_attention_region_components.py",
+  "tests/regional_generation/attention_regions/test_attention_region_geometry.py",
+  "tests/regional_generation/regional/test_regional_attention_batching.py",
+  "tests/regional_generation/regional/test_regional_linear_execution.py",
+  "tests/regional_generation/regional/test_regional_model_patch_interop.py",
+  "tests/regional_generation/regional/test_regional_multidiffusion_sampling.py",
+  "tests/regional_generation/spatial/test_contextual_model_wrapper.py",
+  "tests/sampling/test_multidiffusion_sampling.py",
+  "tests/sampling/test_sampling_scheduler_references.py",
+  "tests/sampling/test_sampling_schedulers.py",
+  "tests/segmentation/detection/test_ultralytics_loader.py",
+  "tests/segmentation/segs/test_detail_segs_as_regions_service.py",
+  "tests/segmentation/segs/test_prompt_segs_with_sam_node.py",
+  "tools/architecture_governance/validation.py",
+  "tools/attention_coupling_benchmark/comfy_probe/negpip_runtime.py",
+  "tools/negpip_integration/run.py",
+  "tools/prompt_control_attention_coupling_integration/validation.py",
+  "tools/run_global_prompt_lora_proof.py",
+  "tools/test_governance/semantic_patterns.py",
+  "tools/test_governance/validation.py",
+  "web/src/orderedMediaNode.ts",
+  "web/src/orderedMediaPreviewActions.ts",
+  "web/tests/media/orderedMediaPreviewActions.test.ts",
+]
+
+debt_paths = [
+]
+
+remediations = []

governance/architecture/waivers.toml

@@ -0,0 +1,67 @@
+schema_version = 1
+
+[[waivers]]
+id = "SSY-WAIVER-S001"
+owner = "model catalog"
+rule = "STRUCT003"
+path = "simple_syrup/runtime/model_catalog.py"
+kind = "structural"
+justification = "This module is the single immutable catalog authority for supported model families and artifacts. Most of its size is declarative checksums, repository identities, filenames, and URLs; its small query surface and entry constructors enforce one catalog schema and change with that same metadata contract. Splitting entries by provider would scatter uniqueness and lookup review without separating behavior or ownership."
+issue = "chore:SSY-WAIVER-S001"
+review_by = 2027-03-31
+max_lines = 687
+
+[[waivers]]
+id = "SSY-WAIVER-S003"
+owner = "Anima cross-attention patch contracts"
+rule = "STRUCT003"
+path = "tests/regional_generation/anima/test_anima_cross_attention.py"
+kind = "structural"
+justification = "This module is one integration contract for AnimaRegionalCrossAttentionPatch: it installs the exact Anima module surface, supplies one deterministic attention double, drives branch/mask/context alignment, verifies failure restoration, and proves all 28 clone-local patches. The sizable builders encode a single valid execution context and are not independent production responsibilities."
+issue = "chore:SSY-WAIVER-S003"
+review_by = 2027-03-31
+max_lines = 661
+
+[[waivers]]
+id = "SSY-WAIVER-S004"
+owner = "Anima multi-LoRA fidelity contracts"
+rule = "STRUCT003"
+path = "tests/regional_generation/anima/test_anima_multi_lora_fidelity.py"
+kind = "structural"
+justification = "This module owns one numerical fidelity matrix for ordered multi-LoRA composition across schedules, branches, regions, target families, and the complete Anima surface. Its execution and reference helpers intentionally remain adjacent so every permutation is compared through the same independently calculated oracle; splitting by scenario would duplicate or conceal that shared proof authority."
+issue = "chore:SSY-WAIVER-S004"
+review_by = 2027-03-31
+max_lines = 678
+
+[[waivers]]
+id = "SSY-WAIVER-S005"
+owner = "regional convolution execution contracts"
+rule = "STRUCT003"
+path = "tests/regional_generation/regional/test_regional_convolution_execution.py"
+kind = "structural"
+justification = "This module is the complete numerical contract for RegionalConvolutionExecutor across direct, pointwise, LoCon, strided, grouped, tiled-batch, ordered-adapter, and low-precision execution. Its fixture builds the same execution plan and independent convolution reference for every case, so the tests share one owner, oracle, dependency surface, and change cadence."
+issue = "chore:SSY-WAIVER-S005"
+review_by = 2027-03-31
+max_lines = 556
+
+[[waivers]]
+id = "SSY-WAIVER-S006"
+owner = "Ultralytics detection node contracts"
+rule = "STRUCT003"
+path = "tests/segmentation/detection/test_detect_segs_with_ultralytics_node.py"
+kind = "structural"
+justification = "This module owns the workflow-facing contract of one Comfy node, including its schema, exact input order, batch behavior, sorting/ranking limits, union mode, and output shape. The service and builder doubles are deliberately local representations of that node boundary; every test changes with the same node API and persisted workflow contract."
+issue = "chore:SSY-WAIVER-S006"
+review_by = 2027-03-31
+max_lines = 592
+
+[[waivers]]
+id = "SSY-WAIVER-S007"
+owner = "scale-factor detail service contracts"
+rule = "STRUCT003"
+path = "tests/segmentation/segs/test_detail_segs_by_scale_factor_service.py"
+kind = "structural"
+justification = "This module is the end-to-end behavioral contract for DetailSEGSByScaleFactorService, whose single orchestration transaction selects per-segment conditioning, sizes and resizes crops, applies masks, samples, decodes, and pastes results. Its sampler and resizer doubles record that one transaction; splitting them would duplicate setup without creating a distinct behavior owner."
+issue = "chore:SSY-WAIVER-S007"
+review_by = 2027-03-31
+max_lines = 532

governance/testing/debt.toml

@@ -0,0 +1,2 @@
+schema_version = 1
+debts = []

governance/testing/policy.toml

@@ -0,0 +1,27 @@
+schema_version = 1
+
+[scope]
+test_root = "tests"
+semantic_support_roots = ["tools"]
+root_source_extensions = [".py", ".pyi"]
+allowed_root_source_paths = [
+  "tests/ci_test_policy.py",
+  "tests/conftest.py",
+]
+
+[discovery]
+serial_policy = "tests/ci_test_policy.py"
+wait_calls = ["QTest.qWait", "time.sleep"]
+wall_clock_calls = [
+  "QElapsedTimer",
+  "monotonic",
+  "perf_counter",
+  "time.monotonic",
+  "time.perf_counter",
+]
+xdist_environment_name = "PYTEST_XDIST_WORKER"
+repository_scratch_name = ".pytest-tmp"
+
+[registries]
+debt = "governance/testing/debt.toml"
+waivers = "governance/testing/waivers.toml"

governance/testing/waivers.toml

@@ -0,0 +1,153 @@
+schema_version = 1
+
+[[waivers]]
+id = "SSY-TEST-WAIVER-C001"
+owner = "pytest CUDA isolation bootstrap"
+kind = "classification"
+disposition = "framework_infrastructure"
+rule = "ENV001"
+candidates = ["ENV001|tests/conftest.py|<module>:environment-mutation:1"]
+paths = ["tests/conftest.py"]
+fingerprint = "sha256:481069f16237eff312f817f1e4dd3213e804eee0f3341e3f6c4aa2ba73066af3"
+rationale = "The root pytest bootstrap disables CUDA visibility before Torch and ComfyUI are imported unless the maintainer explicitly enables hardware tests. Every xdist worker receives the same inherited setting before collection, so this is suite framework configuration rather than mutable test-owned state."
+issue = "chore:SSY-TEST-WAIVER-C001"
+review_by = 2027-03-31
+
+[[waivers]]
+id = "SSY-TEST-WAIVER-C002"
+owner = "native checkpoint quantization proofs"
+kind = "classification"
+disposition = "platform_native"
+rule = "OPTIONAL001"
+candidates = [
+  "OPTIONAL001|tests/models/loading/test_checkpoint_quantizer.py|<module>:optional-proof:1",
+  "OPTIONAL001|tests/models/loading/test_checkpoint_quantizer.py|<module>:optional-proof:2",
+  "OPTIONAL001|tests/models/loading/test_checkpoint_quantizer.py|<module>:optional-proof:3",
+  "OPTIONAL001|tests/models/loading/test_checkpoint_quantizer.py|<module>:optional-proof:4",
+  "OPTIONAL001|tests/models/loading/test_checkpoint_quantizer.py|<module>:optional-proof:5",
+]
+paths = ["tests/models/loading/test_checkpoint_quantizer.py"]
+fingerprint = "sha256:bc2bee06ddb6cf41ba66497855e7349e5aa5dd5292f732284a812a615fa65c49"
+rationale = "These proofs exercise installed ComfyUI NVFP4/MXFP8 kernels, GPU compute capability, and optional comfy-aimdo reload behavior. CPU fake-boundary tests in the same module always run; only the native serialization contracts are skipped when their external runtime or hardware capability does not exist."
+issue = "chore:SSY-TEST-WAIVER-C002"
+review_by = 2027-03-31
+
+[[waivers]]
+id = "SSY-TEST-WAIVER-C003"
+owner = "CUDA Anima projection precision proof"
+kind = "classification"
+disposition = "platform_native"
+rule = "OPTIONAL001"
+candidates = ["OPTIONAL001|tests/regional_generation/anima/test_anima_projection_batch.py|<module>:optional-proof:1"]
+paths = ["tests/regional_generation/anima/test_anima_projection_batch.py"]
+fingerprint = "sha256:cb5e280524450a58144b350799129b3c27a6d4ce430867de582da19303987c33"
+rationale = "This exact comparison bounds BF16 batched projection error on CUDA tensors against independently generated projections. Its behavior depends on the installed CUDA execution path and cannot truthfully be substituted by CPU arithmetic; all device-independent projection contracts remain mandatory."
+issue = "chore:SSY-TEST-WAIVER-C003"
+review_by = 2027-03-31
+
+[[waivers]]
+id = "SSY-TEST-WAIVER-C004"
+owner = "native Anima quantization workflow"
+kind = "classification"
+disposition = "platform_native"
+rule = "OPTIONAL001"
+candidates = ["OPTIONAL001|tests/regional_generation/anima/test_anima_quantization_workflow.py|<module>:optional-proof:1"]
+paths = ["tests/regional_generation/anima/test_anima_quantization_workflow.py"]
+fingerprint = "sha256:ff02416ea8c16112605b221975425a6f88013f66e2a8bc66bdc2d1a0ecfa5053"
+rationale = "The workflow proof intentionally uses the installed ComfyUI NVFP4 implementation and the active GPU's native compute support before loading the generated Anima artifact. It remains optional only where that hardware capability is absent; the portable resolver and policy tests still run everywhere."
+issue = "chore:SSY-TEST-WAIVER-C004"
+review_by = 2027-03-31
+
+[[waivers]]
+id = "SSY-TEST-WAIVER-C005"
+owner = "installed Anima CUDA smoke"
+kind = "classification"
+disposition = "platform_native"
+rule = "OPTIONAL001"
+candidates = ["OPTIONAL001|tests/regional_generation/anima/test_anima_regional_model_smoke.py|<module>:optional-proof:1"]
+paths = ["tests/regional_generation/anima/test_anima_regional_model_smoke.py"]
+fingerprint = "sha256:73b3bde9d6009b71608aec73dde862d963a3a723d5ad5d57c130428a4c1511c6"
+rationale = "This smoke test constructs the installed Comfy Anima model and executes its complete patched forward on CUDA tensors. It proves the native device/runtime integration and is skipped only without CUDA; deterministic component and surface contracts cover the same code boundaries on every host."
+issue = "chore:SSY-TEST-WAIVER-C005"
+review_by = 2027-03-31
+
+[[waivers]]
+id = "SSY-TEST-WAIVER-C006"
+owner = "regional convolution CUDA precision"
+kind = "classification"
+disposition = "platform_native"
+rule = "OPTIONAL001"
+candidates = ["OPTIONAL001|tests/regional_generation/regional/test_regional_convolution_execution.py|<module>:optional-proof:1"]
+paths = ["tests/regional_generation/regional/test_regional_convolution_execution.py"]
+fingerprint = "sha256:f197de881034f1c11b46ce290f3b6c515fe251d5bdef7efb419f43ad7257bf40"
+rationale = "The optional parameterized cases prove FP16 and BF16 regional convolution behavior through the installed CUDA kernels. CPU tests in the same contract cover dimensions, grouping, stride, masking, ordering, and reference math; only device-specific low-precision execution requires CUDA."
+issue = "chore:SSY-TEST-WAIVER-C006"
+review_by = 2027-03-31
+
+[[waivers]]
+id = "SSY-TEST-WAIVER-C007"
+owner = "regional linear CUDA precision"
+kind = "classification"
+disposition = "platform_native"
+rule = "OPTIONAL001"
+candidates = [
+  "OPTIONAL001|tests/regional_generation/regional/test_regional_linear_execution.py|<module>:optional-proof:1",
+  "OPTIONAL001|tests/regional_generation/regional/test_regional_linear_execution.py|<module>:optional-proof:2",
+]
+paths = ["tests/regional_generation/regional/test_regional_linear_execution.py"]
+fingerprint = "sha256:d8a833ef160838b80db21d7240d789879deb8a4dc39f89d52145b1ebf580f765"
+rationale = "These cases validate installed CUDA FP16/BF16 projection rounding and compatible-adapter accumulation on the actual device execution path. The module's CPU contracts always prove masking, ordering, preparation, and reference deltas; the classified cases add hardware-specific numerical evidence."
+issue = "chore:SSY-TEST-WAIVER-C007"
+review_by = 2027-03-31
+
+[[waivers]]
+id = "SSY-TEST-WAIVER-C008"
+owner = "fused regional LoRA CUDA kernel"
+kind = "classification"
+disposition = "platform_native"
+rule = "OPTIONAL001"
+candidates = ["OPTIONAL001|tests/regional_generation/regional/test_regional_lora_fused_active_accumulation.py|<module>:optional-proof:1"]
+paths = ["tests/regional_generation/regional/test_regional_lora_fused_active_accumulation.py"]
+fingerprint = "sha256:2053ff281c4e707c99db6424074ef3526c901ad84f0f750e044c35116981cd9c"
+rationale = "The entire module qualifies the CUDA-only fused regional LoRA accumulator across low-precision dtypes, adapter counts, and indexed paths. There is no CPU implementation to exercise, while the non-fused accumulation owner has mandatory portable reference coverage."
+issue = "chore:SSY-TEST-WAIVER-C008"
+review_by = 2027-03-31
+
+[[waivers]]
+id = "SSY-TEST-WAIVER-C009"
+owner = "fused multiplier CUDA transport"
+kind = "classification"
+disposition = "platform_native"
+rule = "OPTIONAL001"
+candidates = ["OPTIONAL001|tests/regional_generation/regional/test_regional_lora_fused_multiplier_transport.py|<module>:optional-proof:1"]
+paths = ["tests/regional_generation/regional/test_regional_lora_fused_multiplier_transport.py"]
+fingerprint = "sha256:56ef4217551bdccc97fc6277bd2ade11ac10b9512ee3725c46b210044f380f21"
+rationale = "This module proves multiple adapter multipliers reach the CUDA fused kernel without an intermediate stack. The production behavior exists only for a CUDA-capable device, and portable composition tests independently cover ordering and multiplier semantics outside this native optimization."
+issue = "chore:SSY-TEST-WAIVER-C009"
+review_by = 2027-03-31
+
+[[waivers]]
+id = "SSY-TEST-WAIVER-C010"
+owner = "ordered tensor CUDA accumulation"
+kind = "classification"
+disposition = "platform_native"
+rule = "OPTIONAL001"
+candidates = ["OPTIONAL001|tests/sampling/test_ordered_tensor_accumulation.py|<module>:optional-proof:1"]
+paths = ["tests/sampling/test_ordered_tensor_accumulation.py"]
+fingerprint = "sha256:b6306323fd555706f0b7525078acfa199c657f47f96432ce320da9057fc41709"
+rationale = "The parameter matrix compares stepwise CUDA accumulation and its exact low-precision rounding across one and multiple Triton launches. Mandatory CPU contracts prove ordered in-place accumulation; only the GPU kernel and device dtypes are capability-gated."
+issue = "chore:SSY-TEST-WAIVER-C010"
+review_by = 2027-03-31
+
+[[waivers]]
+id = "SSY-TEST-WAIVER-C011"
+owner = "managed Windows Comfy process lifetime"
+kind = "classification"
+disposition = "platform_native"
+rule = "PROCESS001"
+candidates = ["PROCESS001|tools/comfy_integration/server_process.py|<module>:unscoped-child-process:1"]
+paths = ["tools/comfy_integration/server_process.py"]
+fingerprint = "sha256:6892815fbffe96d59bbb3f9069e44bfcdb9d6ea39e3f17f844695408af4233c0"
+rationale = "WindowsComfyProcess intentionally transfers the created Popen and log handles into an explicit long-lived owner because the integration run must use the server after start returns. Its stop method signals the exact process group, bounds both graceful and forced waits, retries bounded taskkill calls, and closes both logs in finally."
+issue = "chore:SSY-TEST-WAIVER-C011"
+review_by = 2027-03-31

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "simple-syrup-comfyui",
-  "version": "1.6.0",
+  "version": "1.13.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "simple-syrup-comfyui",
-      "version": "1.6.0",
+      "version": "1.13.0",
       "license": "AGPL-3.0-or-later",
       "devDependencies": {
         "@eslint/js": "^9.39.1",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-syrup-comfyui",
-  "version": "1.6.0",
+  "version": "1.13.0",
   "private": true,
   "license": "AGPL-3.0-or-later",
   "type": "module",

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "SimpleSyrup"
 description = "Workflow-focused ComfyUI extensions for image generation."
-version = "1.6.0"
+version = "1.13.0"
 license = "AGPL-3.0-or-later"
 license-files = ["LICENSE"]
 requires-python = ">=3.11"
@@ -36,6 +36,7 @@ line-length = 88
 target-version = "py311"
 extend-exclude = [
     "simple_syrup/third_party/groundingdino_runtime",
+    "simple_syrup/third_party/res4lyf_runtime",
     "simple_syrup/third_party/sam_hq_runtime",
 ]
 
@@ -43,8 +44,11 @@ extend-exclude = [
 select = ["E", "F", "I", "UP", "B", "C4", "ANN"]
 ignore = ["ANN401"]
 
+[tool.ruff.lint.isort]
+known-first-party = ["simple_syrup"]
+
 [tool.mypy]
-python_version = "3.11"
+python_version = "3.12"
 warn_return_any = true
 warn_unused_configs = true
 disallow_untyped_defs = true
@@ -53,8 +57,10 @@ check_untyped_defs = true
 no_implicit_optional = true
 strict_equality = true
 explicit_package_bases = true
+mypy_path = ["tests"]
 exclude = [
     "simple_syrup/third_party/groundingdino_runtime",
+    "simple_syrup/third_party/res4lyf_runtime",
     "simple_syrup/third_party/sam_hq_runtime",
 ]
 
@@ -62,9 +68,17 @@ exclude = [
 module = ["comfy.*"]
 ignore_missing_imports = true
 
+[[tool.mypy.overrides]]
+module = ["simple_syrup.third_party.res4lyf_runtime.*"]
+follow_imports = "skip"
+
 [tool.pytest.ini_options]
 pythonpath = [".", "../.."]
 testpaths = ["tests"]
+addopts = ["--strict-markers", "--import-mode=importlib"]
+markers = [
+    "external_artifact: requires a locally installed external source or generated benchmark artifact",
+]
 filterwarnings = [
     "error",
     "ignore:builtin type SwigPyPacked has no __module__ attribute:DeprecationWarning",

requirements.txt

@@ -7,3 +7,5 @@ addict>=2.4.0
 yapf>=0.43.0
 huggingface-hub>=0.34.0
 keyring>=25.0.0
+mpmath>=1.3.0
+PyWavelets>=1.6.0

simple_syrup/__init__.py

@@ -6,6 +6,6 @@
 
 from __future__ import annotations
 
-__version__ = "1.6.0"
+__version__ = "1.13.0"
 
 __all__: list[str] = ["__version__"]

simple_syrup/domain/anima_quantization.py

@@ -0,0 +1,118 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define versioned, quality-aware Anima quantization profiles."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .model_quantization import (
+    QuantizationFormat,
+    QuantizationProfile,
+    TensorDescriptor,
+)
+
+ORIGINAL_PROFILE = QuantizationProfile("original", "Original", 2, frozenset())
+FP8_E4M3_PROFILE = QuantizationProfile(
+    "fp8-e4m3",
+    "FP8 E4M3",
+    2,
+    frozenset({QuantizationFormat.FP8_E4M3}),
+)
+FP8_E5M2_PROFILE = QuantizationProfile(
+    "fp8-e5m2",
+    "FP8 E5M2",
+    2,
+    frozenset({QuantizationFormat.FP8_E5M2}),
+)
+MXFP8_PROFILE = QuantizationProfile(
+    "mxfp8",
+    "MXFP8",
+    2,
+    frozenset({QuantizationFormat.MXFP8}),
+)
+NVFP4_MIXED_PROFILE = QuantizationProfile(
+    "nvfp4-mixed",
+    "NVFP4 (Mixed)",
+    3,
+    frozenset({QuantizationFormat.FP8_E4M3, QuantizationFormat.NVFP4}),
+)
+_PROFILES = (
+    ORIGINAL_PROFILE,
+    FP8_E4M3_PROFILE,
+    FP8_E5M2_PROFILE,
+    MXFP8_PROFILE,
+    NVFP4_MIXED_PROFILE,
+)
+_MAIN_BLOCK_PATTERN = re.compile(
+    r"(?:^|\.)(?:net|diffusion_model)\.blocks\.(?P<index>\d+)\."
+)
+_PROTECTED_BLOCKS = {0, 1, 27}
+_FLOAT_DTYPES = {"F16", "BF16", "F32", "F64"}
+
+
+@dataclass(frozen=True)
+class AnimaQuantizationRecipe:
+    """Assign formats only within Anima's quality-safe DiT block envelope."""
+
+    model_family: str = "Anima"
+    version: int = 2
+
+    @property
+    def profiles(self) -> tuple[QuantizationProfile, ...]:
+        """Return Anima's stable workflow-facing profile order."""
+
+        return _PROFILES
+
+    def profile_from_selection(self, selection: str) -> QuantizationProfile:
+        """Parse one current workflow selection into its profile."""
+
+        for profile in self.profiles:
+            if selection in (profile.label, profile.profile_id):
+                return profile
+        valid = ", ".join(profile.label for profile in self.profiles)
+        raise ValueError(f"quantization profile must be one of: {valid}.")
+
+    def policy_for(
+        self,
+        tensor: TensorDescriptor,
+        profile: QuantizationProfile,
+    ) -> QuantizationFormat | None:
+        """Return Anima's per-tensor format while preserving sensitive layers."""
+
+        if profile not in self.profiles:
+            raise ValueError(
+                f"Unknown Anima quantization profile '{profile.profile_id}'."
+            )
+        if profile.is_original or not _is_matrix_weight(tensor):
+            return None
+        if "llm_adapter" in tensor.name or "adaln_modulation" in tensor.name:
+            return None
+        block_match = _MAIN_BLOCK_PATTERN.search(tensor.name)
+        if block_match is None:
+            return None
+        if int(block_match.group("index")) in _PROTECTED_BLOCKS:
+            return None
+        if profile.profile_id == NVFP4_MIXED_PROFILE.profile_id:
+            if "v_proj" in tensor.name or ".mlp." in tensor.name:
+                return QuantizationFormat.FP8_E4M3
+            if any(
+                projection in tensor.name
+                for projection in ("q_proj", "k_proj", "output_proj")
+            ):
+                return QuantizationFormat.NVFP4
+            return None
+        return next(iter(profile.required_formats))
+
+
+def _is_matrix_weight(tensor: TensorDescriptor) -> bool:
+    """Return whether a tensor is an eligible floating-point matrix weight."""
+
+    return (
+        tensor.dtype_name in _FLOAT_DTYPES
+        and len(tensor.shape) == 2
+        and tensor.name.endswith(".weight")
+    )

simple_syrup/domain/attention_concepts.py

@@ -0,0 +1,15 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Parse explicit attention concepts without interpreting prompt language."""
+
+from __future__ import annotations
+
+
+def parse_attention_concepts(value: str) -> tuple[str, ...]:
+    """Return canonical concepts separated only by vertical bars."""
+
+    if not isinstance(value, str):
+        raise TypeError("Attention concepts must be text.")
+    return tuple(part.strip() for part in value.split("|") if part.strip())

simple_syrup/domain/attention_coupling_preparation.py

@@ -0,0 +1,20 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define validated Attention Coupling preparation data."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .raw_regional_attention import RawRegionalAttentionPlan
+
+
+@dataclass(frozen=True, slots=True)
+class AttentionCouplingPreparation:
+    """Retain the full raw plan and base-only ordinary sampler inputs."""
+
+    plan: RawRegionalAttentionPlan
+    positive: object
+    negative: object

simple_syrup/domain/attention_coupling_request.py

@@ -0,0 +1,46 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Classify complete Attention Coupling requests before runtime preparation."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from .conditioning_batch import ConditioningBatch
+
+
+class AttentionCouplingRequestMode(StrEnum):
+    """Select ordinary sampling or complete regional Attention Coupling."""
+
+    BYPASS = "bypass"
+    ACTIVE = "active"
+
+
+def classify_attention_coupling_request(
+    *,
+    positive: object,
+    negative: object,
+    region_masks: object | None,
+) -> AttentionCouplingRequestMode:
+    """Return the execution mode or reject a partial regional request."""
+
+    has_conditioning_batch = isinstance(positive, ConditioningBatch) or isinstance(
+        negative,
+        ConditioningBatch,
+    )
+    has_region_masks = region_masks is not None
+    if not has_conditioning_batch and not has_region_masks:
+        return AttentionCouplingRequestMode.BYPASS
+    if has_conditioning_batch and has_region_masks:
+        return AttentionCouplingRequestMode.ACTIVE
+    if has_conditioning_batch:
+        raise ValueError(
+            "Attention Coupling conditioning batches require region_masks. "
+            "Connect ordered masks or use ordinary CONDITIONING on both inputs."
+        )
+    raise ValueError(
+        "Attention Coupling region_masks require a CONDITIONING_BATCH on the "
+        "positive or negative input. Disconnect the masks for ordinary sampling."
+    )

simple_syrup/domain/attention_geometry.py

@@ -0,0 +1,30 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Resolve explicit two-dimensional geometry for flattened attention maps."""
+
+from __future__ import annotations
+
+import math
+
+
+def factor_spatial_geometry(
+    token_count: int, *, target_aspect: float
+) -> tuple[int, int]:
+    """Return the token factor pair nearest the supplied positive aspect ratio."""
+
+    if type(token_count) is not int or token_count < 1:
+        raise ValueError("Attention spatial token count must be positive.")
+    if target_aspect <= 0.0:
+        raise ValueError("Attention target aspect ratio must be positive.")
+    candidates: list[tuple[float, int, int]] = []
+    for height in range(1, math.isqrt(token_count) + 1):
+        if token_count % height:
+            continue
+        width = token_count // height
+        for candidate_height, candidate_width in ((height, width), (width, height)):
+            error = abs(math.log((candidate_width / candidate_height) / target_aspect))
+            candidates.append((error, candidate_height, candidate_width))
+    _error, height, width = min(candidates)
+    return height, width

simple_syrup/domain/attention_region_capture.py

@@ -0,0 +1,175 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define immutable requests and plans for attention-region capture."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from .attention_spatial_transform import AttentionSpatialTransform
+from .graph_provenance import GraphLink
+
+
+class AttentionRegionRequestKind(StrEnum):
+    """Identify one public attention-region operation."""
+
+    CONCEPT_SEGS = "concept_segs"
+    ALL_PROMPT_SEGS = "all_prompt_segs"
+    REGION_MASK = "region_mask"
+    MASKED_CONDITIONING = "masked_conditioning"
+
+
+class AttentionCaptureProfile(StrEnum):
+    """Select the density of attention observations retained during sampling."""
+
+    FAST = "fast"
+    BALANCED = "balanced"
+    EXHAUSTIVE = "exhaustive"
+
+
+class AttentionEvidenceMode(StrEnum):
+    """Select honest inspection or derived concept-isolation evidence."""
+
+    CONCEPT = "concept isolation"
+    RAW = "raw attention"
+
+
+@dataclass(frozen=True, slots=True)
+class AttentionRegionControls:
+    """Hold validated attention-native capture and region-shaping controls."""
+
+    capture_start: float
+    capture_end: float
+    minimum_strength: float
+    minimum_consensus: float
+    split_sensitivity: float
+    minimum_region_size: int
+    profile: AttentionCaptureProfile
+    instance_recall: float = 0.65
+    geometry_recall: float = 0.85
+    keep_only: int = 0
+    keep_by: str = "largest size"
+    combine_segs: bool = False
+    matte_solidity: float = 0.0
+    edge_feather: int = 8
+    evidence_mode: AttentionEvidenceMode = AttentionEvidenceMode.CONCEPT
+
+    def __post_init__(self) -> None:
+        """Require normalized ranges and a non-empty capture interval."""
+
+        normalized = (
+            self.capture_start,
+            self.capture_end,
+            self.minimum_strength,
+            self.minimum_consensus,
+            self.split_sensitivity,
+            self.instance_recall,
+            self.geometry_recall,
+            self.matte_solidity,
+        )
+        if any(
+            isinstance(value, bool) or not isinstance(value, int | float)
+            for value in normalized
+        ):
+            raise TypeError("Attention-region controls must be real numbers.")
+        if not 0.0 <= self.capture_start < self.capture_end <= 1.0:
+            raise ValueError("Attention capture start must be below end within 0..1.")
+        if not 0.0 <= self.minimum_strength <= 1.0:
+            raise ValueError("Minimum attention strength must be within 0..1.")
+        if not 0.0 <= self.minimum_consensus <= 1.0:
+            raise ValueError("Minimum attention consensus must be within 0..1.")
+        if not 0.0 <= self.split_sensitivity <= 1.0:
+            raise ValueError("Attention split sensitivity must be within 0..1.")
+        if not 0.0 <= self.instance_recall <= 1.0:
+            raise ValueError("Attention instance recall must be within 0..1.")
+        if not 0.0 <= self.geometry_recall <= 1.0:
+            raise ValueError("Attention geometry recall must be within 0..1.")
+        if type(self.minimum_region_size) is not int or self.minimum_region_size < 1:
+            raise ValueError("Minimum attention region size must be positive.")
+        if type(self.keep_only) is not int or self.keep_only < 0:
+            raise ValueError("Attention keep_only must be non-negative.")
+        if self.keep_by not in ("largest size", "highest confidence"):
+            raise ValueError("Attention keep_by has an invalid policy.")
+        if type(self.combine_segs) is not bool:
+            raise TypeError("Attention combine_segs must be boolean.")
+        if not 0.0 <= self.matte_solidity <= 1.0:
+            raise ValueError("Attention matte solidity must be within 0..1.")
+        if type(self.edge_feather) is not int or self.edge_feather < 0:
+            raise ValueError("Attention edge feather must be non-negative.")
+        if not isinstance(self.profile, AttentionCaptureProfile):
+            raise TypeError("Attention capture profile has an invalid type.")
+        if not isinstance(self.evidence_mode, AttentionEvidenceMode):
+            raise TypeError("Attention evidence mode has an invalid type.")
+
+
+@dataclass(frozen=True, slots=True)
+class AttentionRegionRequest:
+    """Bind one public node request to its queries and capture controls."""
+
+    node_id: str
+    kind: AttentionRegionRequestKind
+    queries: tuple[str, ...]
+    controls: AttentionRegionControls
+    sampler_stage: int = 1
+    spatial_transforms: tuple[AttentionSpatialTransform, ...] = ()
+
+    def __post_init__(self) -> None:
+        """Require stable node identity and canonical non-empty query strings."""
+
+        if not self.node_id.strip():
+            raise ValueError("Attention-region request node id cannot be empty.")
+        if not isinstance(self.kind, AttentionRegionRequestKind):
+            raise TypeError("Attention-region request kind has an invalid type.")
+        if any(not query or query != query.strip() for query in self.queries):
+            raise ValueError("Attention-region queries must be canonical strings.")
+        if self.kind is AttentionRegionRequestKind.ALL_PROMPT_SEGS:
+            if self.queries:
+                raise ValueError(
+                    "All-prompt attention requests cannot contain queries."
+                )
+        elif not self.queries:
+            raise ValueError("Concept and mask attention requests require concepts.")
+        if type(self.sampler_stage) is not int or self.sampler_stage < -1:
+            raise ValueError("Attention sampler stage must be -1 or greater.")
+        if any(
+            not isinstance(transform, AttentionSpatialTransform)
+            for transform in self.spatial_transforms
+        ):
+            raise TypeError("Attention request spatial transforms are invalid.")
+
+
+@dataclass(frozen=True, slots=True)
+class AttentionCapturePlan:
+    """Describe one coalesced sampler capture and its graph rewrite authority."""
+
+    sampler_node_id: str
+    model_owner_node_id: str
+    model_input_name: str
+    model_link: GraphLink
+    positive_link: GraphLink
+    requests: tuple[AttentionRegionRequest, ...]
+    prompt_text: str | None = None
+    clip_link: GraphLink | None = None
+    source_aspect: float | None = None
+
+    def __post_init__(self) -> None:
+        """Require canonical unique requests and complete graph-edge identity."""
+
+        if not self.sampler_node_id or not self.model_owner_node_id:
+            raise ValueError("Attention capture plan node ids cannot be empty.")
+        if not self.model_input_name:
+            raise ValueError("Attention capture plan model input cannot be empty.")
+        if self.source_aspect is not None and self.source_aspect <= 0.0:
+            raise ValueError("Attention capture source aspect must be positive.")
+        request_ids = tuple(request.node_id for request in self.requests)
+        if not request_ids or request_ids != tuple(sorted(set(request_ids))):
+            raise ValueError("Attention capture requests must be unique and ordered.")
+
+    @property
+    def capture_node_id(self) -> str:
+        """Return a collision-resistant deterministic injected node id."""
+
+        return f"__simple_syrup_attention_capture__{self.sampler_node_id}"

simple_syrup/domain/attention_region_evidence.py

@@ -0,0 +1,21 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define rendered attention evidence before component and matte shaping."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+
+
+@dataclass(frozen=True, slots=True)
+class AttentionConceptEvidence:
+    """Hold one concept's alpha, support, and confidence evidence."""
+
+    label: str
+    alpha: torch.Tensor
+    support: torch.Tensor
+    confidence: torch.Tensor

simple_syrup/domain/attention_region_maps.py

@@ -0,0 +1,198 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Model prompt-token spans and compact captured attention observations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+
+from .attention_spatial_transform import AttentionSpatialTransform
+from .regional_model_capabilities import RegionalModelFamily
+
+
+@dataclass(frozen=True, slots=True)
+class AttentionTokenSpan:
+    """Bind a readable prompt occurrence to exact conditioning token positions."""
+
+    label: str
+    occurrence: int
+    token_indices: tuple[int, ...]
+    head_token_indices: tuple[int, ...] = ()
+
+    def __post_init__(self) -> None:
+        """Require canonical labels and ordered non-negative token indices."""
+
+        if not self.label or self.label != self.label.strip():
+            raise ValueError("Attention token span label must be canonical.")
+        if type(self.occurrence) is not int or self.occurrence < 1:
+            raise ValueError("Attention token span occurrence must be positive.")
+        if (
+            not self.token_indices
+            or self.token_indices != tuple(sorted(set(self.token_indices)))
+            or self.token_indices[0] < 0
+        ):
+            raise ValueError("Attention token indices must be ordered and unique.")
+        if self.head_token_indices and (
+            self.head_token_indices != tuple(sorted(set(self.head_token_indices)))
+            or not set(self.head_token_indices).issubset(self.token_indices)
+        ):
+            raise ValueError("Attention head tokens must be an ordered span subset.")
+
+    @property
+    def semantic_head_indices(self) -> tuple[int, ...]:
+        """Return explicit noun-head positions or a safe final-token fallback."""
+
+        return self.head_token_indices or self.token_indices[-1:]
+
+    @property
+    def display_label(self) -> str:
+        """Disambiguate repeated concepts while keeping first labels concise."""
+
+        return (
+            self.label if self.occurrence == 1 else f"{self.label} #{self.occurrence}"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class AttentionTokenCatalog:
+    """Hold readable prompt spans and conditioning sequence length."""
+
+    sequence_length: int
+    spans: tuple[AttentionTokenSpan, ...]
+    token_ids: tuple[object, ...]
+
+    def __post_init__(self) -> None:
+        """Require all spans to fit the captured conditioning sequence."""
+
+        if type(self.sequence_length) is not int or self.sequence_length < 1:
+            raise ValueError("Attention token sequence length must be positive.")
+        if len(self.token_ids) != self.sequence_length:
+            raise ValueError("Attention token ids must match the sequence length.")
+        if any(
+            index >= self.sequence_length
+            for span in self.spans
+            for index in span.token_indices
+        ):
+            raise ValueError("Attention token span exceeds its conditioning sequence.")
+
+    def exact_matches(self, query: str) -> tuple[AttentionTokenSpan, ...]:
+        """Return every prompt occurrence whose normalized label equals a query."""
+
+        normalized = _normalized_label(query)
+        return tuple(
+            span for span in self.spans if _normalized_label(span.label) == normalized
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class CapturedAttentionMap:
+    """Store one head-aggregated token map and its denoising observation identity."""
+
+    label: str
+    values: torch.Tensor
+    progress: float
+    layer_key: str
+    batch_index: int = 0
+    confidence: float = 1.0
+    spatial_height: int | None = None
+    spatial_width: int | None = None
+    spatial_transforms: tuple[AttentionSpatialTransform, ...] = ()
+    concept_values: torch.Tensor | None = None
+    uniform_probability: float = 0.0
+    model_family: RegionalModelFamily = RegionalModelFamily.STANDARD_UNET
+
+    def __post_init__(self) -> None:
+        """Require a finite CPU spatial vector and normalized progress."""
+
+        if not self.label:
+            raise ValueError("Captured attention map label cannot be empty.")
+        if (
+            not isinstance(self.values, torch.Tensor)
+            or self.values.device.type != "cpu"
+            or self.values.ndim != 1
+            or self.values.numel() < 1
+            or not self.values.is_floating_point()
+            or not torch.isfinite(self.values).all().item()
+        ):
+            raise ValueError("Captured attention values must be a finite CPU vector.")
+        if not 0.0 <= self.progress <= 1.0:
+            raise ValueError("Captured attention progress must be within 0..1.")
+        if not self.layer_key:
+            raise ValueError("Captured attention layer key cannot be empty.")
+        if type(self.batch_index) is not int or self.batch_index < 0:
+            raise ValueError("Captured attention batch index must be non-negative.")
+        if not 0.0 <= self.confidence <= 1.0:
+            raise ValueError("Captured attention confidence must be within 0..1.")
+        if (self.spatial_height is None) != (self.spatial_width is None):
+            raise ValueError("Captured attention geometry must be complete or absent.")
+        if self.spatial_height is not None and (
+            type(self.spatial_height) is not int
+            or self.spatial_height < 1
+            or type(self.spatial_width) is not int
+            or self.spatial_width < 1
+            or self.spatial_height * self.spatial_width != int(self.values.numel())
+        ):
+            raise ValueError("Captured attention geometry must match its values.")
+        if any(
+            not isinstance(transform, AttentionSpatialTransform)
+            for transform in self.spatial_transforms
+        ):
+            raise TypeError("Captured attention spatial transforms are invalid.")
+        if self.concept_values is not None and (
+            not isinstance(self.concept_values, torch.Tensor)
+            or self.concept_values.device.type != "cpu"
+            or self.concept_values.shape != self.values.shape
+            or not self.concept_values.is_floating_point()
+            or not torch.isfinite(self.concept_values).all().item()
+        ):
+            raise ValueError(
+                "Captured concept evidence must match its finite CPU attention map."
+            )
+        if (
+            isinstance(self.uniform_probability, bool)
+            or not isinstance(self.uniform_probability, int | float)
+            or not 0.0 <= float(self.uniform_probability) <= 1.0
+        ):
+            raise ValueError("Captured uniform probability must be within 0..1.")
+        if not isinstance(self.model_family, RegionalModelFamily):
+            raise TypeError("Captured attention model family has an invalid type.")
+
+
+@dataclass(frozen=True, slots=True)
+class OpenVocabularyContext:
+    """Hold one query's encoded SDXL context and semantic token positions."""
+
+    label: str
+    values: torch.Tensor
+    token_indices: tuple[int, ...]
+
+    def __post_init__(self) -> None:
+        """Require one finite CPU context with valid unique token positions."""
+
+        if not self.label.strip() or self.label != self.label.strip():
+            raise ValueError("Open-vocabulary labels must be canonical strings.")
+        if self.values.ndim != 3 or int(self.values.shape[0]) != 1:
+            raise ValueError("Open-vocabulary context must have shape 1xTxC.")
+        if self.values.device.type != "cpu" or not torch.isfinite(self.values).all():
+            raise ValueError("Open-vocabulary context must be finite CPU storage.")
+        if not self.token_indices or self.token_indices != tuple(
+            sorted(set(self.token_indices))
+        ):
+            raise ValueError(
+                "Open-vocabulary token positions must be unique and ordered."
+            )
+        if any(
+            index < 0 or index >= int(self.values.shape[1])
+            for index in self.token_indices
+        ):
+            raise ValueError("Open-vocabulary token positions exceed their context.")
+
+
+def _normalized_label(value: str) -> str:
+    """Normalize human prompt labels without changing tokenizer semantics."""
+
+    return " ".join(value.casefold().replace("_", " ").split())

simple_syrup/domain/attention_sampler_lineage.py

@@ -0,0 +1,78 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Model ordered sampling stages along one spatial provenance path."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .attention_spatial_transform import AttentionSpatialTransform
+from .graph_provenance import GraphLink
+
+
+@dataclass(frozen=True, slots=True)
+class AttentionSamplerStage:
+    """Describe one sampler's patch and conditioning authority."""
+
+    sampler_node_id: str
+    model_owner_node_id: str
+    model_link: GraphLink
+    positive_link: GraphLink
+    upstream_link: GraphLink
+    upstream_kind: str
+    forward_transforms: tuple[AttentionSpatialTransform, ...] = ()
+    source_aspect: float | None = None
+    capture_supported: bool = True
+    unsupported_reason: str | None = None
+
+    def __post_init__(self) -> None:
+        """Require unsupported stages to explain why capture cannot be projected."""
+
+        if self.capture_supported and self.unsupported_reason is not None:
+            raise ValueError("Supported attention sampler stages cannot have a reason.")
+        if not self.capture_supported and not self.unsupported_reason:
+            raise ValueError("Unsupported attention sampler stages require a reason.")
+        if self.source_aspect is not None and self.source_aspect <= 0.0:
+            raise ValueError("Attention sampler source aspect must be positive.")
+
+
+@dataclass(frozen=True, slots=True)
+class AttentionSamplerSelection:
+    """Bind a selected stage to its one-based chronological position."""
+
+    stage: AttentionSamplerStage
+    stage_number: int
+    stage_count: int
+    was_clamped: bool
+
+
+@dataclass(frozen=True, slots=True)
+class AttentionSamplerLineage:
+    """Hold sampling stages ordered from oldest to direct provenance."""
+
+    stages: tuple[AttentionSamplerStage, ...]
+
+    def __post_init__(self) -> None:
+        """Require at least one uniquely identified stage."""
+
+        identities = tuple(stage.sampler_node_id for stage in self.stages)
+        if not identities or len(set(identities)) != len(identities):
+            raise ValueError("Attention sampler lineage must contain unique stages.")
+
+    def select(self, requested_stage: int) -> AttentionSamplerSelection:
+        """Resolve one-based selection with 0/-1 aliases for direct provenance."""
+
+        if type(requested_stage) is not int or requested_stage < -1:
+            raise ValueError("Attention sampler stage must be -1 or greater.")
+        count = len(self.stages)
+        if requested_stage in (-1, 0):
+            return AttentionSamplerSelection(self.stages[-1], count, count, False)
+        selected_number = min(requested_stage, count)
+        return AttentionSamplerSelection(
+            self.stages[selected_number - 1],
+            selected_number,
+            count,
+            requested_stage > count,
+        )

simple_syrup/domain/attention_spatial_transform.py

@@ -0,0 +1,70 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Describe graph-visible full-canvas transformations for attention masks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+_ANCHORS = frozenset(
+    {
+        "center",
+        "top-left",
+        "top",
+        "top-right",
+        "left",
+        "right",
+        "bottom-left",
+        "bottom",
+        "bottom-right",
+    }
+)
+
+
+class AttentionSpatialTransformKind(StrEnum):
+    """Identify a supported mask-coordinate transformation."""
+
+    RESIZE = "resize"
+    FIT_RESIZE = "fit_resize"
+    SCALE = "scale"
+    COVER_CROP = "cover_crop"
+    FIT_PAD = "fit_pad"
+
+
+@dataclass(frozen=True, slots=True)
+class AttentionSpatialTransform:
+    """Hold validated resize, crop, or pad parameters from one graph node."""
+
+    kind: AttentionSpatialTransformKind
+    width: int | None = None
+    height: int | None = None
+    scale: float | None = None
+    anchor: str = "center"
+    divisible_by: int = 1
+
+    def __post_init__(self) -> None:
+        """Require complete parameters for the selected transformation kind."""
+
+        if self.anchor not in _ANCHORS:
+            raise ValueError("Attention spatial transform anchor is invalid.")
+        if self.kind is AttentionSpatialTransformKind.SCALE:
+            if self.scale is None or self.scale <= 0.0:
+                raise ValueError("Attention scale transform requires a positive scale.")
+            if self.width is not None or self.height is not None:
+                raise ValueError("Attention scale transform cannot contain a size.")
+            if self.divisible_by != 1:
+                raise ValueError("Attention scale transform cannot set divisibility.")
+            return
+        if (
+            type(self.width) is not int
+            or self.width < 1
+            or type(self.height) is not int
+            or self.height < 1
+            or self.scale is not None
+        ):
+            raise ValueError("Attention spatial transform requires a positive size.")
+        if type(self.divisible_by) is not int or self.divisible_by < 1:
+            raise ValueError("Attention spatial divisibility must be positive.")

simple_syrup/domain/conditioning_schedule.py

@@ -0,0 +1,90 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Own immutable authored and model-converted conditioning schedule bounds."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ConditioningScheduleRange:
+    """Retain optional authored percentages and converted sigma boundaries."""
+
+    start_percent: float | None
+    end_percent: float | None
+    timestep_start: float | None
+    timestep_end: float | None
+
+    def __post_init__(self) -> None:
+        """Validate exact optional bounds without inventing absent metadata."""
+
+        start_percent = _optional_finite_float(
+            self.start_percent,
+            name="start_percent",
+        )
+        end_percent = _optional_finite_float(
+            self.end_percent,
+            name="end_percent",
+        )
+        timestep_start = _optional_finite_float(
+            self.timestep_start,
+            name="timestep_start",
+        )
+        timestep_end = _optional_finite_float(
+            self.timestep_end,
+            name="timestep_end",
+        )
+        for name, value in (
+            ("start_percent", start_percent),
+            ("end_percent", end_percent),
+        ):
+            if value is not None and not 0.0 <= value <= 1.0:
+                raise ValueError(f"Conditioning {name} must be in [0, 1].")
+        effective_start = 0.0 if start_percent is None else start_percent
+        effective_end = 1.0 if end_percent is None else end_percent
+        if effective_start > effective_end:
+            raise ValueError("Conditioning start_percent must not exceed end_percent.")
+        if (
+            timestep_start is not None
+            and timestep_end is not None
+            and timestep_start < timestep_end
+        ):
+            raise ValueError(
+                "Conditioning timestep_start must not be below timestep_end."
+            )
+        object.__setattr__(self, "start_percent", start_percent)
+        object.__setattr__(self, "end_percent", end_percent)
+        object.__setattr__(self, "timestep_start", timestep_start)
+        object.__setattr__(self, "timestep_end", timestep_end)
+
+    @property
+    def is_time_invariant(self) -> bool:
+        """Report whether this entry remains admitted for the whole trajectory."""
+
+        if self.start_percent is None and self.timestep_start is not None:
+            return False
+        if self.end_percent is None and self.timestep_end is not None:
+            return False
+        effective_start = 0.0 if self.start_percent is None else self.start_percent
+        effective_end = 1.0 if self.end_percent is None else self.end_percent
+        return effective_start == 0.0 and effective_end == 1.0
+
+
+def _optional_finite_float(value: object, *, name: str) -> float | None:
+    """Normalize one optional real boundary without accepting booleans."""
+
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        raise TypeError(f"Conditioning {name} must be a real number or None.")
+    normalized = float(value)
+    if not math.isfinite(normalized):
+        raise ValueError(f"Conditioning {name} must be finite.")
+    return normalized
+
+
+UNBOUNDED_CONDITIONING_SCHEDULE = ConditioningScheduleRange(None, None, None, None)

simple_syrup/domain/conditioning_schedule_selection.py

@@ -0,0 +1,49 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Own installed-Comfy-equivalent conditioning schedule admission."""
+
+from __future__ import annotations
+
+import math
+
+from .conditioning_schedule import ConditioningScheduleRange
+
+
+class ConditioningScheduleSelectionPolicy:
+    """Match installed Comfy's inclusive converted-sigma admission policy."""
+
+    @staticmethod
+    def is_active(
+        schedule: ConditioningScheduleRange,
+        *,
+        sigma: float,
+    ) -> bool:
+        """Return installed Comfy's inclusive start/end decision."""
+
+        if not isinstance(schedule, ConditioningScheduleRange):
+            raise TypeError("Conditioning selection requires a schedule range.")
+        current_sigma = normalize_conditioning_sigma(sigma)
+        if (
+            schedule.timestep_start is not None
+            and current_sigma > schedule.timestep_start
+        ):
+            return False
+        return not (
+            schedule.timestep_end is not None and current_sigma < schedule.timestep_end
+        )
+
+
+def normalize_conditioning_sigma(value: object) -> float:
+    """Normalize one finite real current sigma without accepting booleans."""
+
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        raise TypeError("Conditioning selection sigma must be a real number.")
+    sigma = float(value)
+    if not math.isfinite(sigma):
+        raise ValueError("Conditioning selection sigma must be finite.")
+    return sigma
+
+
+CONDITIONING_SCHEDULE_SELECTION_POLICY = ConditioningScheduleSelectionPolicy()

simple_syrup/domain/contextual_diffusion.py

@@ -8,8 +8,12 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+import torch
+
+from .regional_tiled_diffusion import build_region_constrained_tiled_diffusion_plan
 from .segs import NativeSegs
 from .segs_tiled_diffusion import build_segs_guided_tiled_diffusion_plan
+from .spatial_views import SpatialView, SpatialViewKind
 from .tiled_diffusion import TiledDiffusionPlan, build_tiled_diffusion_plan
 
 
@@ -23,16 +27,37 @@ class ContextualDiffusionControls:
     global_weight: float
     global_steps: int
     global_decay: float
+    latent_tile_width: int | None = None
+    latent_tile_height: int | None = None
+
+    @property
+    def tile_width(self) -> int:
+        """Use explicit local geometry or the convenience node's context size."""
+        return self.latent_tile_width or self.latent_context_size
+
+    @property
+    def tile_height(self) -> int:
+        """Keep the global context independent of a rectangular local tile."""
+        return self.latent_tile_height or self.latent_context_size
 
     def validate(self) -> None:
         """Reject controls that cannot produce a stable bounded context plan."""
 
         if self.latent_context_size < 16:
             raise ValueError("latent_context_size must be at least 16 latent pixels.")
-        if not 0 <= self.latent_context_overlap < self.latent_context_size:
+        for value in (self.latent_tile_width, self.latent_tile_height):
+            if value is not None and (type(value) is not int or value < 16):
+                raise ValueError(
+                    "Local tile dimensions must be at least 16 latent pixels."
+                )
+        if (
+            not 0
+            <= self.latent_context_overlap
+            < min(self.tile_width, self.tile_height)
+        ):
             raise ValueError(
                 "latent_context_overlap must be non-negative and smaller than "
-                "latent_context_size."
+                "both local tile dimensions."
             )
         if self.latent_context_batch_size < 1:
             raise ValueError("latent_context_batch_size must be at least 1.")
@@ -44,25 +69,13 @@ class ContextualDiffusionControls:
             raise ValueError("global_decay must be between 0 and 1.")
 
 
-@dataclass(frozen=True)
-class SpatialContext:
-    """Describe one source rectangle evaluated at a bounded model context shape."""
-
-    x: int
-    y: int
-    width: int
-    height: int
-    context_width: int
-    context_height: int
-
-
 @dataclass(frozen=True)
 class ContextualDiffusionPlan:
     """Own the global context and sole tiled plan for one latent canvas."""
 
     latent_width: int
     latent_height: int
-    global_context: SpatialContext
+    global_view: SpatialView
     tile_plan: TiledDiffusionPlan
 
 
@@ -72,6 +85,8 @@ def build_contextual_diffusion_plan(
     latent_height: int,
     controls: ContextualDiffusionControls,
     segs: NativeSegs | None,
+    region_masks: torch.Tensor | None = None,
+    segs_canvas: tuple[int, int] | None = None,
 ) -> ContextualDiffusionPlan:
     """Return a global context plus the regular or SEGS-guided context plan."""
 
@@ -81,38 +96,51 @@ def build_contextual_diffusion_plan(
         latent_height,
         controls.latent_context_size,
     )
-    global_context = SpatialContext(
-        x=0,
-        y=0,
-        width=latent_width,
-        height=latent_height,
-        context_width=global_width,
-        context_height=global_height,
+    global_view = SpatialView(
+        kind=SpatialViewKind.CONTEXTUAL_GLOBAL,
+        source_x=0,
+        source_y=0,
+        source_width=latent_width,
+        source_height=latent_height,
+        model_width=global_width,
+        model_height=global_height,
     )
-    tile_plan = (
-        build_segs_guided_tiled_diffusion_plan(
+    if region_masks is not None:
+        tile_plan = build_region_constrained_tiled_diffusion_plan(
+            region_masks=region_masks,
             segs=segs,
             latent_width=latent_width,
             latent_height=latent_height,
-            tile_width=controls.latent_context_size,
-            tile_height=controls.latent_context_size,
+            tile_width=controls.tile_width,
+            tile_height=controls.tile_height,
             overlap=controls.latent_context_overlap,
             tile_batch_size=controls.latent_context_batch_size,
+            segs_canvas=segs_canvas,
         )
-        if segs is not None
-        else build_tiled_diffusion_plan(
+    elif segs is not None:
+        tile_plan = build_segs_guided_tiled_diffusion_plan(
+            segs=segs,
             latent_width=latent_width,
             latent_height=latent_height,
-            tile_width=controls.latent_context_size,
-            tile_height=controls.latent_context_size,
+            tile_width=controls.tile_width,
+            tile_height=controls.tile_height,
+            overlap=controls.latent_context_overlap,
+            tile_batch_size=controls.latent_context_batch_size,
+            segs_canvas=segs_canvas,
+        )
+    else:
+        tile_plan = build_tiled_diffusion_plan(
+            latent_width=latent_width,
+            latent_height=latent_height,
+            tile_width=controls.tile_width,
+            tile_height=controls.tile_height,
             overlap=controls.latent_context_overlap,
             tile_batch_size=controls.latent_context_batch_size,
         )
-    )
     return ContextualDiffusionPlan(
         latent_width=latent_width,
         latent_height=latent_height,
-        global_context=global_context,
+        global_view=global_view,
         tile_plan=tile_plan,
     )
 

simple_syrup/domain/global_context_schedule.py

@@ -0,0 +1,42 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Select decayed reduced-global authority from denoising timesteps."""
+
+from __future__ import annotations
+
+import torch
+
+
+class GlobalContextSchedule:
+    """Limit whole-image authority to an initial denoising-step fraction."""
+
+    def __init__(
+        self, *, sigmas: torch.Tensor, active_steps: int, decay: float
+    ) -> None:
+        """Capture model-evaluation sigmas and the active initial step count."""
+
+        step_sigmas = sigmas.detach().to(device="cpu", dtype=torch.float64).flatten()
+        if step_sigmas.numel() < 2:
+            raise ValueError(
+                "Contextual Diffusion requires at least one denoising step."
+            )
+        self._step_sigmas = step_sigmas[:-1]
+        self._active_steps = min(len(self._step_sigmas), max(0, active_steps))
+        self._decay = decay
+
+    def scale_for(self, timestep: object) -> float:
+        """Return the decayed global scale for the nearest scheduled step."""
+
+        if self._active_steps == 0:
+            return 0.0
+        if not isinstance(timestep, torch.Tensor) or timestep.numel() == 0:
+            raise ValueError(
+                "Contextual Diffusion timestep must be a non-empty tensor."
+            )
+        sigma = timestep.detach().flatten()[0].to(device="cpu", dtype=torch.float64)
+        step_index = int(torch.argmin(torch.abs(self._step_sigmas - sigma)).item())
+        if step_index >= self._active_steps:
+            return 0.0
+        return self._decay**step_index

simple_syrup/domain/inversion_solver.py

@@ -0,0 +1,89 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Integrate source-derived inversion states without ComfyUI dependencies."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import torch
+
+from .noise_inversion import INVERSION_METHODS, InversionMethod
+
+InversionVelocity = Callable[[torch.Tensor, torch.Tensor, int], torch.Tensor]
+SpatialResize = Callable[[torch.Tensor, int, int], torch.Tensor]
+
+
+@dataclass(slots=True)
+class InversionSolverEvidence:
+    """Count the actual denoiser evaluations performed by an integration stage."""
+
+    evaluations: int = 0
+
+
+def integrate_inversion(
+    source: torch.Tensor,
+    sigmas: torch.Tensor,
+    evaluate: InversionVelocity,
+    *,
+    method: InversionMethod,
+    evidence: InversionSolverEvidence | None = None,
+) -> torch.Tensor:
+    """Advance a finite state over strictly increasing positive inversion sigmas."""
+    if method not in INVERSION_METHODS:
+        raise ValueError("Inversion method must be euler or heun.")
+    if sigmas.ndim != 1 or len(sigmas) < 2 or not bool(torch.isfinite(sigmas).all()):
+        raise ValueError("A finite one-dimensional inversion schedule is required.")
+    if not bool(torch.all(sigmas > 0)) or not bool(torch.all(sigmas[1:] > sigmas[:-1])):
+        raise ValueError("Inversion sigmas must be positive and increasing.")
+    if not source.is_floating_point() or not bool(torch.isfinite(source).all()):
+        raise ValueError("Inversion source must contain finite floating-point values.")
+    record = evidence if evidence is not None else InversionSolverEvidence()
+    state = source.clone()
+
+    def velocity(x: torch.Tensor, sigma: torch.Tensor, index: int) -> torch.Tensor:
+        """Count every denoiser evaluation and reject corrupted predictions."""
+        record.evaluations += 1
+        value = evaluate(x, sigma, index)
+        if value.shape != x.shape or not bool(torch.isfinite(value).all()):
+            raise FloatingPointError("Invalid inversion velocity shape or values.")
+        return value
+
+    for index in range(len(sigmas) - 1):
+        current, following = sigmas[index], sigmas[index + 1]
+        delta = following - current
+        estimate = velocity(state, current, index)
+        if method == "heun":
+            corrected = velocity(state + delta * estimate, following, index)
+            estimate = (estimate + corrected) / 2
+        state = state + delta * estimate
+        if not bool(torch.isfinite(state).all()):
+            raise FloatingPointError(f"Non-finite inversion state at step {index}.")
+    return state
+
+
+def lift_inversion_displacement(
+    full_source: torch.Tensor,
+    coarse_source: torch.Tensor,
+    coarse_endpoint: torch.Tensor,
+    *,
+    resize: SpatialResize,
+) -> torch.Tensor:
+    """Lift only the inferred change so existing full-size detail survives transfer."""
+    if coarse_source.shape != coarse_endpoint.shape:
+        raise ValueError("Coarse inversion source and endpoint shapes must match.")
+    if full_source.shape[:-2] != coarse_source.shape[:-2]:
+        raise ValueError(
+            "Inversion transfer must preserve batch and channel dimensions."
+        )
+    height, width = full_source.shape[-2:]
+    lifted = resize(coarse_endpoint - coarse_source, height, width)
+    if lifted.shape != full_source.shape:
+        raise ValueError("Inversion displacement resize produced an invalid shape.")
+    endpoint = full_source + lifted
+    if not bool(torch.isfinite(endpoint).all()):
+        raise FloatingPointError("Inversion transfer produced non-finite values.")
+    return endpoint

simple_syrup/domain/model_quantization.py

@@ -0,0 +1,82 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define model-independent checkpoint quantization profile contracts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Protocol
+
+
+class QuantizationFormat(StrEnum):
+    """Identify one reusable ComfyUI tensor quantization format."""
+
+    FP8_E4M3 = "float8_e4m3fn"
+    FP8_E5M2 = "float8_e5m2"
+    NVFP4 = "nvfp4"
+    MXFP8 = "mxfp8"
+
+    @property
+    def label(self) -> str:
+        """Return the concise format label used in diagnostics."""
+
+        return {
+            QuantizationFormat.FP8_E4M3: "FP8 E4M3",
+            QuantizationFormat.FP8_E5M2: "FP8 E5M2",
+            QuantizationFormat.NVFP4: "NVFP4",
+            QuantizationFormat.MXFP8: "MXFP8",
+        }[self]
+
+
+@dataclass(frozen=True)
+class QuantizationProfile:
+    """Describe one workflow-facing, versioned per-tensor policy profile."""
+
+    profile_id: str
+    label: str
+    version: int
+    required_formats: frozenset[QuantizationFormat]
+
+    @property
+    def is_original(self) -> bool:
+        """Return whether this profile loads the source checkpoint unchanged."""
+
+        return not self.required_formats
+
+
+@dataclass(frozen=True)
+class TensorDescriptor:
+    """Describe a checkpoint tensor without coupling policy to PyTorch."""
+
+    name: str
+    shape: tuple[int, ...]
+    dtype_name: str
+
+
+class ModelQuantizationRecipe(Protocol):
+    """Assign model-specific per-tensor formats for named profiles."""
+
+    @property
+    def model_family(self) -> str:
+        """Return the stable family identifier used in cache identity."""
+
+    @property
+    def version(self) -> int:
+        """Return the recipe version used in cache invalidation."""
+
+    @property
+    def profiles(self) -> tuple[QuantizationProfile, ...]:
+        """Return deterministic workflow profiles owned by this recipe."""
+
+    def profile_from_selection(self, selection: str) -> QuantizationProfile:
+        """Parse a workflow selection into a recipe-owned profile."""
+
+    def policy_for(
+        self,
+        tensor: TensorDescriptor,
+        profile: QuantizationProfile,
+    ) -> QuantizationFormat | None:
+        """Return the tensor format or ``None`` to preserve source precision."""

simple_syrup/domain/negative_prompt_weights.py

@@ -0,0 +1,89 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Detect effective negative weights in Comfy-style prompt emphasis."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class _WeightedPromptSegment:
+    """Retain one parsed prompt fragment and its effective scalar weight."""
+
+    text: str
+    weight: float
+
+
+def contains_negative_prompt_weight(text: str) -> bool:
+    """Return whether valid nested emphasis gives any prompt text a negative weight."""
+
+    if not isinstance(text, str):
+        raise TypeError("Negative prompt-weight detection requires text.")
+    escaped = text.replace(r"\)", "\0\1").replace(r"\(", "\0\2")
+    return any(
+        segment.text and segment.weight < 0.0
+        for segment in _weighted_segments(escaped, 1.0)
+    )
+
+
+def _weighted_segments(
+    text: str,
+    current_weight: float,
+) -> tuple[_WeightedPromptSegment, ...]:
+    """Parse emphasis with the same nesting and final-colon rules as ComfyUI."""
+
+    parsed: list[_WeightedPromptSegment] = []
+    for item in _parenthesized_items(text):
+        weight = current_weight
+        if len(item) >= 2 and item[0] == "(" and item[-1] == ")":
+            inner = item[1:-1]
+            delimiter = inner.rfind(":")
+            weight *= 1.1
+            if delimiter > 0:
+                try:
+                    weight = float(inner[delimiter + 1 :])
+                except ValueError:
+                    pass
+                else:
+                    inner = inner[:delimiter]
+            parsed.extend(_weighted_segments(inner, weight))
+            continue
+        parsed.append(
+            _WeightedPromptSegment(
+                item.replace("\0\1", ")").replace("\0\2", "("),
+                current_weight,
+            )
+        )
+    return tuple(parsed)
+
+
+def _parenthesized_items(text: str) -> tuple[str, ...]:
+    """Split top-level parenthesized regions while preserving malformed input."""
+
+    result: list[str] = []
+    current = ""
+    nesting = 0
+    for character in text:
+        if character == "(":
+            if nesting == 0:
+                if current:
+                    result.append(current)
+                current = "("
+            else:
+                current += character
+            nesting += 1
+        elif character == ")":
+            nesting -= 1
+            if nesting == 0:
+                result.append(f"{current})")
+                current = ""
+            else:
+                current += character
+        else:
+            current += character
+    if current:
+        result.append(current)
+    return tuple(result)

simple_syrup/domain/noise_inversion.py

@@ -0,0 +1,68 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define validated source-preserving noise inversion configuration."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Literal
+
+InversionMethod = Literal["euler", "heun"]
+INVERSION_METHODS: tuple[InversionMethod, ...] = ("euler", "heun")
+
+
+@dataclass(frozen=True, slots=True)
+class NoiseInversionOptions:
+    """Configure reduced-resolution inversion and an optional full-size finish.
+
+    The transition is a fraction of the target inversion sigma, not the forward
+    denoise steps. A full-size inversion uses ``steps`` and needs no transfer.
+    """
+
+    method: InversionMethod = "euler"
+    resolution_scale: float = 0.5
+    steps: int = 2
+    switch_fraction: float = 0.75
+    finishing_steps: int = 1
+
+    def __post_init__(self) -> None:
+        """Reject invalid or internally incomplete inversion recipes."""
+        if self.method not in INVERSION_METHODS:
+            raise ValueError("Inversion method must be euler or heun.")
+        if (
+            not math.isfinite(self.resolution_scale)
+            or not 0 < self.resolution_scale <= 1
+        ):
+            raise ValueError("Inversion resolution scale must be in (0, 1].")
+        if type(self.steps) is not int or not 1 <= self.steps <= 64:
+            raise ValueError("Inversion steps must be an integer between 1 and 64.")
+        if type(self.finishing_steps) is not int or not 0 <= self.finishing_steps <= 64:
+            raise ValueError("Inversion finishing steps must be between 0 and 64.")
+        if not math.isfinite(self.switch_fraction) or not 0 < self.switch_fraction <= 1:
+            raise ValueError("Inversion transition must be in (0, 1].")
+        if self.resolution_scale < 1 and self.finishing_steps > 0:
+            if self.switch_fraction == 1:
+                raise ValueError("A full-size finish requires a transition below 100%.")
+
+    @property
+    def coarse_target_fraction(self) -> float:
+        """Reach the full target unless an enabled full-size stage follows transfer."""
+        return (
+            self.switch_fraction
+            if self.resolution_scale < 1 and self.finishing_steps
+            else 1.0
+        )
+
+    def coarse_shape(self, height: int, width: int) -> tuple[int, int]:
+        """Preserve full dimensions or align reduced transformer grids to even sizes."""
+        if height < 1 or width < 1:
+            raise ValueError("Inversion source dimensions must be positive.")
+        if self.resolution_scale == 1:
+            return height, width
+        return (
+            max(2, round(height * self.resolution_scale / 2) * 2),
+            max(2, round(width * self.resolution_scale / 2) * 2),
+        )

simple_syrup/domain/processed_regional_attention.py

@@ -0,0 +1,190 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Own immutable processed regional Attention Coupling runtime plans."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from uuid import UUID
+
+import torch
+
+from .conditioning_schedule import ConditioningScheduleRange
+from .regional_attention import (
+    require_non_negative_regional_attention_index,
+    validate_regional_attention_plan_authorities,
+)
+from .regional_lora_plan import RegionalLoraPlan
+from .regional_mask_bank import RegionalMaskBank
+
+
+@dataclass(frozen=True, slots=True)
+class ProcessedRegionalAttentionEntry:
+    """Retain one ordered model-ready conditioning entry and Comfy strength."""
+
+    entry_index: int
+    uuid: UUID
+    schedule: ConditioningScheduleRange
+    cross_attention: torch.Tensor
+    strength: float
+    cross_attention_value_multiplier: torch.Tensor | None = None
+
+    def __post_init__(self) -> None:
+        """Validate entry order, model context, and finite scalar strength."""
+
+        require_non_negative_regional_attention_index(
+            self.entry_index,
+            name="entry_index",
+        )
+        if not isinstance(self.uuid, UUID):
+            raise TypeError("Processed conditioning entry UUID must be uuid.UUID.")
+        if not isinstance(self.schedule, ConditioningScheduleRange):
+            raise TypeError(
+                "Processed conditioning entry schedule has an invalid type."
+            )
+        if not isinstance(self.cross_attention, torch.Tensor):
+            raise TypeError("Processed cross_attention must be a torch.Tensor.")
+        if self.cross_attention.ndim != 3:
+            raise ValueError("Processed cross_attention must use BxSxD layout.")
+        if any(int(size) < 1 for size in self.cross_attention.shape):
+            raise ValueError("Processed cross_attention dimensions must be positive.")
+        if not self.cross_attention.is_floating_point():
+            raise TypeError("Processed cross_attention must be floating point.")
+        if not bool(torch.isfinite(self.cross_attention).all().item()):
+            raise ValueError("Processed cross_attention must contain finite values.")
+        if isinstance(self.strength, bool) or not isinstance(
+            self.strength,
+            int | float,
+        ):
+            raise TypeError("Processed conditioning strength must be a real number.")
+        if not math.isfinite(float(self.strength)):
+            raise ValueError("Processed conditioning strength must be finite.")
+        object.__setattr__(self, "strength", float(self.strength))
+        multiplier = self.cross_attention_value_multiplier
+        if multiplier is None:
+            return
+        if (
+            not isinstance(multiplier, torch.Tensor)
+            or multiplier.shape != (*self.cross_attention.shape[:2], 1)
+            or not multiplier.is_floating_point()
+            or multiplier.device != self.cross_attention.device
+            or multiplier.dtype != self.cross_attention.dtype
+            or not bool(torch.isfinite(multiplier).all().item())
+        ):
+            raise ValueError(
+                "Processed attention value multiplier must be a finite floating "
+                "BxSx1 tensor aligned with cross_attention."
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class ProcessedRegionalAttentionContext:
+    """Retain every ordered processed entry for one authored conditioning."""
+
+    conditioning_index: int
+    region_index: int | None
+    entries: tuple[ProcessedRegionalAttentionEntry, ...]
+
+    def __post_init__(self) -> None:
+        """Validate global/regional ownership and model-ready tensor structure."""
+
+        if self.region_index is None:
+            if self.conditioning_index != 0:
+                raise ValueError(
+                    "Processed base attention context must use conditioning index 0."
+                )
+        else:
+            require_non_negative_regional_attention_index(
+                self.region_index,
+                name="region_index",
+            )
+            if self.conditioning_index != self.region_index + 1:
+                raise ValueError(
+                    "Processed regional conditioning_index must equal region_index + 1."
+                )
+        if not isinstance(self.entries, tuple) or not self.entries:
+            raise ValueError("Processed attention context requires ordered entries.")
+        if any(
+            not isinstance(entry, ProcessedRegionalAttentionEntry)
+            for entry in self.entries
+        ):
+            raise TypeError("Processed attention context contains an invalid entry.")
+        if tuple(entry.entry_index for entry in self.entries) != tuple(
+            range(len(self.entries))
+        ):
+            raise ValueError("Processed attention entries must use canonical order.")
+
+
+@dataclass(frozen=True, slots=True)
+class ProcessedRegionalAttentionBranch:
+    """Retain one processed base context and ordered regional context bank."""
+
+    base_context: ProcessedRegionalAttentionContext
+    regional_contexts: tuple[ProcessedRegionalAttentionContext, ...]
+
+    def __post_init__(self) -> None:
+        """Require one global base and canonical regional context order."""
+
+        if not isinstance(self.base_context, ProcessedRegionalAttentionContext):
+            raise TypeError("Processed attention base context has an invalid type.")
+        if self.base_context.region_index is not None:
+            raise ValueError("Processed attention base context must be global.")
+        if not isinstance(self.regional_contexts, tuple):
+            raise TypeError("Processed regional attention contexts must be a tuple.")
+        if any(
+            not isinstance(context, ProcessedRegionalAttentionContext)
+            for context in self.regional_contexts
+        ):
+            raise TypeError(
+                "Processed regional attention branch contains an invalid context."
+            )
+        indices = tuple(context.region_index for context in self.regional_contexts)
+        if indices != tuple(range(len(self.regional_contexts))):
+            raise ValueError(
+                "Processed regional attention contexts must use canonical order."
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class ProcessedRegionalAttentionPlan:
+    """Retain processed branches and shared canonical regional authorities."""
+
+    positive: ProcessedRegionalAttentionBranch
+    negative: ProcessedRegionalAttentionBranch
+    mask_bank: RegionalMaskBank
+    lora_plan: RegionalLoraPlan
+
+    def __post_init__(self) -> None:
+        """Validate plan owners and regional LoRA bounds."""
+
+        if not isinstance(
+            self.positive, ProcessedRegionalAttentionBranch
+        ) or not isinstance(self.negative, ProcessedRegionalAttentionBranch):
+            raise TypeError(
+                "Processed regional attention plan contains an invalid branch."
+            )
+        validate_regional_attention_plan_authorities(
+            mask_bank=self.mask_bank,
+            lora_plan=self.lora_plan,
+            positive_region_count=len(self.positive.regional_contexts),
+            negative_region_count=len(self.negative.regional_contexts),
+        )
+
+    @property
+    def is_time_invariant(self) -> bool:
+        """Report whether contexts and regional LoRA strengths remain fixed."""
+
+        branches = (self.positive, self.negative)
+        contexts = tuple(
+            context
+            for branch in branches
+            for context in (branch.base_context, *branch.regional_contexts)
+        )
+        return self.lora_plan.is_time_invariant and all(
+            entry.schedule.is_time_invariant
+            for context in contexts
+            for entry in context.entries
+        )

simple_syrup/domain/quant_cache.py

@@ -0,0 +1,310 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define validated identities and records for quantized profile artifacts."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import cast
+
+from .model_quantization import QuantizationProfile
+
+MANIFEST_SCHEMA_VERSION = 2
+
+
+@dataclass(frozen=True)
+class SourceCheckpointIdentity:
+    """Identify an authoritative source checkpoint and its current file state."""
+
+    display_name: str
+    path: Path
+    size_bytes: int
+    modified_ns: int
+    sha256: str
+
+
+@dataclass(frozen=True)
+class QuantCacheIdentity:
+    """Identify one profile and recipe derivative of a source checkpoint."""
+
+    source: SourceCheckpointIdentity
+    profile: QuantizationProfile
+    model_family: str
+    recipe_version: int
+
+    @property
+    def stable_key(self) -> str:
+        """Return the collision-resistant cache key."""
+
+        identity = "\0".join(
+            (
+                self.source.sha256,
+                self.profile.profile_id,
+                str(self.profile.version),
+                self.model_family,
+                str(self.recipe_version),
+            )
+        )
+        return hashlib.sha256(identity.encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class QuantCacheManifest:
+    """Describe one complete SimpleSyrup-managed cache artifact."""
+
+    source_model: str
+    source_path: str
+    source_sha256: str
+    source_size_bytes: int
+    source_modified_ns: int
+    profile_id: str
+    profile_label: str
+    profile_version: int
+    quantization_formats: tuple[str, ...]
+    model_family: str
+    recipe_version: int
+    artifact_file: str
+    artifact_size_bytes: int
+    created_at: str
+    last_used_at: str
+    schema_version: int = MANIFEST_SCHEMA_VERSION
+    managed_by: str = "SimpleSyrup"
+
+    @classmethod
+    def create(
+        cls,
+        identity: QuantCacheIdentity,
+        artifact_file: str,
+        artifact_size_bytes: int,
+    ) -> QuantCacheManifest:
+        """Create a current manifest for a completed artifact."""
+
+        now = datetime.now(UTC).isoformat()
+        return cls(
+            source_model=identity.source.display_name,
+            source_path=str(identity.source.path),
+            source_sha256=identity.source.sha256,
+            source_size_bytes=identity.source.size_bytes,
+            source_modified_ns=identity.source.modified_ns,
+            profile_id=identity.profile.profile_id,
+            profile_label=identity.profile.label,
+            profile_version=identity.profile.version,
+            quantization_formats=tuple(
+                sorted(item.value for item in identity.profile.required_formats)
+            ),
+            model_family=identity.model_family,
+            recipe_version=identity.recipe_version,
+            artifact_file=artifact_file,
+            artifact_size_bytes=artifact_size_bytes,
+            created_at=now,
+            last_used_at=now,
+        )
+
+    def matches_current_source(
+        self,
+        source_model: str,
+        source_path: Path,
+        source_size_bytes: int,
+        source_modified_ns: int,
+        profile: QuantizationProfile,
+        model_family: str,
+        recipe_version: int,
+    ) -> bool:
+        """Return whether this artifact derives from the unchanged source file."""
+
+        return (
+            self.source_model == source_model
+            and Path(self.source_path) == source_path
+            and self.source_size_bytes == source_size_bytes
+            and self.source_modified_ns == source_modified_ns
+            and self.profile_id == profile.profile_id
+            and self.profile_version == profile.version
+            and self.model_family == model_family
+            and self.recipe_version == recipe_version
+        )
+
+    def matches_identity(self, identity: QuantCacheIdentity) -> bool:
+        """Return whether this v2 manifest exactly describes an identity."""
+
+        return (
+            self.schema_version == MANIFEST_SCHEMA_VERSION
+            and self.source_sha256 == identity.source.sha256
+            and self.profile_id == identity.profile.profile_id
+            and self.profile_version == identity.profile.version
+            and self.model_family == identity.model_family
+            and self.recipe_version == identity.recipe_version
+        )
+
+    def touched(self) -> QuantCacheManifest:
+        """Return a copy with a current explicit LRU timestamp."""
+
+        payload = self.to_payload()
+        payload["last_used_at"] = datetime.now(UTC).isoformat()
+        return QuantCacheManifest.from_payload(payload)
+
+    def to_payload(self) -> dict[str, object]:
+        """Return the human-readable JSON representation."""
+
+        if self.schema_version == 1:
+            return {
+                "schema_version": 1,
+                "managed_by": self.managed_by,
+                "source_model": self.source_model,
+                "source_path": self.source_path,
+                "source_sha256": self.source_sha256,
+                "source_size_bytes": self.source_size_bytes,
+                "source_modified_ns": self.source_modified_ns,
+                "quantization_format": self.quantization_formats[0],
+                "model_family": self.model_family,
+                "recipe_version": self.recipe_version,
+                "artifact_file": self.artifact_file,
+                "artifact_size_bytes": self.artifact_size_bytes,
+                "created_at": self.created_at,
+                "last_used_at": self.last_used_at,
+            }
+        return {
+            "schema_version": self.schema_version,
+            "managed_by": self.managed_by,
+            "source_model": self.source_model,
+            "source_path": self.source_path,
+            "source_sha256": self.source_sha256,
+            "source_size_bytes": self.source_size_bytes,
+            "source_modified_ns": self.source_modified_ns,
+            "profile_id": self.profile_id,
+            "profile_label": self.profile_label,
+            "profile_version": self.profile_version,
+            "quantization_formats": list(self.quantization_formats),
+            "model_family": self.model_family,
+            "recipe_version": self.recipe_version,
+            "artifact_file": self.artifact_file,
+            "artifact_size_bytes": self.artifact_size_bytes,
+            "created_at": self.created_at,
+            "last_used_at": self.last_used_at,
+        }
+
+    @classmethod
+    def from_payload(cls, payload: object) -> QuantCacheManifest:
+        """Validate managed manifests, retaining v1 only for cache cleanup."""
+
+        if not isinstance(payload, dict):
+            raise ValueError("Quant cache manifest must be a JSON object.")
+        if payload.get("schema_version") == 1:
+            return cls._from_legacy_payload(payload)
+        required_strings = (
+            "managed_by",
+            "source_model",
+            "source_path",
+            "source_sha256",
+            "profile_id",
+            "profile_label",
+            "model_family",
+            "artifact_file",
+            "created_at",
+            "last_used_at",
+        )
+        for key in required_strings:
+            if not isinstance(payload.get(key), str):
+                raise ValueError(
+                    f"Quant cache manifest field '{key}' must be a string."
+                )
+        required_integers = (
+            "schema_version",
+            "source_size_bytes",
+            "source_modified_ns",
+            "profile_version",
+            "recipe_version",
+            "artifact_size_bytes",
+        )
+        for key in required_integers:
+            value = payload.get(key)
+            if not isinstance(value, int) or isinstance(value, bool):
+                raise ValueError(
+                    f"Quant cache manifest field '{key}' must be an integer."
+                )
+        raw_formats = payload.get("quantization_formats")
+        if not isinstance(raw_formats, list) or not all(
+            isinstance(item, str) for item in raw_formats
+        ):
+            raise ValueError(
+                "Quant cache manifest field 'quantization_formats' must be a "
+                "string list."
+            )
+        if payload["managed_by"] != "SimpleSyrup":
+            raise ValueError("Quant cache manifest is not managed by SimpleSyrup.")
+        if payload["schema_version"] != MANIFEST_SCHEMA_VERSION:
+            raise ValueError("Quant cache manifest schema version is unsupported.")
+        return cls(
+            schema_version=payload["schema_version"],
+            managed_by=payload["managed_by"],
+            source_model=payload["source_model"],
+            source_path=payload["source_path"],
+            source_sha256=payload["source_sha256"],
+            source_size_bytes=payload["source_size_bytes"],
+            source_modified_ns=payload["source_modified_ns"],
+            profile_id=payload["profile_id"],
+            profile_label=payload["profile_label"],
+            profile_version=payload["profile_version"],
+            quantization_formats=tuple(raw_formats),
+            model_family=payload["model_family"],
+            recipe_version=payload["recipe_version"],
+            artifact_file=payload["artifact_file"],
+            artifact_size_bytes=payload["artifact_size_bytes"],
+            created_at=payload["created_at"],
+            last_used_at=payload["last_used_at"],
+        )
+
+    @classmethod
+    def _from_legacy_payload(cls, payload: dict[object, object]) -> QuantCacheManifest:
+        """Decode v1 solely so ordinary LRU and clearing can remove it."""
+
+        required_strings = (
+            "managed_by",
+            "source_model",
+            "source_path",
+            "source_sha256",
+            "quantization_format",
+            "model_family",
+            "artifact_file",
+            "created_at",
+            "last_used_at",
+        )
+        required_integers = (
+            "source_size_bytes",
+            "source_modified_ns",
+            "recipe_version",
+            "artifact_size_bytes",
+        )
+        if any(not isinstance(payload.get(key), str) for key in required_strings):
+            raise ValueError("Legacy quant cache manifest has invalid string fields.")
+        if any(
+            not isinstance(payload.get(key), int) or isinstance(payload.get(key), bool)
+            for key in required_integers
+        ):
+            raise ValueError("Legacy quant cache manifest has invalid integer fields.")
+        if payload["managed_by"] != "SimpleSyrup":
+            raise ValueError("Quant cache manifest is not managed by SimpleSyrup.")
+        quantization_format = str(payload["quantization_format"])
+        return cls(
+            schema_version=1,
+            managed_by=str(payload["managed_by"]),
+            source_model=str(payload["source_model"]),
+            source_path=str(payload["source_path"]),
+            source_sha256=str(payload["source_sha256"]),
+            source_size_bytes=cast(int, payload["source_size_bytes"]),
+            source_modified_ns=cast(int, payload["source_modified_ns"]),
+            profile_id=f"legacy-v1-{quantization_format}",
+            profile_label=f"Legacy v1 {quantization_format}",
+            profile_version=1,
+            quantization_formats=(quantization_format,),
+            model_family=str(payload["model_family"]),
+            recipe_version=cast(int, payload["recipe_version"]),
+            artifact_file=str(payload["artifact_file"]),
+            artifact_size_bytes=cast(int, payload["artifact_size_bytes"]),
+            created_at=str(payload["created_at"]),
+            last_used_at=str(payload["last_used_at"]),
+        )

simple_syrup/domain/raw_regional_attention.py

@@ -0,0 +1,147 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Own immutable raw regional Attention Coupling authoring plans."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .conditioning_batch import ConditioningBatch
+from .regional_attention import (
+    require_non_negative_regional_attention_index,
+    validate_regional_attention_plan_authorities,
+)
+from .regional_lora_plan import EMPTY_REGIONAL_LORA_PLAN, RegionalLoraPlan
+from .regional_mask_bank import RegionalMaskBank
+from .regional_prompting import build_regional_conditioning_plan
+
+
+@dataclass(frozen=True, slots=True)
+class RawRegionalAttentionContext:
+    """Retain one original regional conditioning and its canonical indices."""
+
+    conditioning_index: int
+    region_index: int
+    conditioning: object
+
+    def __post_init__(self) -> None:
+        """Require the established global-first positional relationship."""
+
+        require_non_negative_regional_attention_index(
+            self.region_index,
+            name="region_index",
+        )
+        if self.conditioning_index != self.region_index + 1:
+            raise ValueError(
+                "Regional attention conditioning_index must equal region_index + 1."
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class RawRegionalAttentionBranch:
+    """Retain one base conditioning and ordered regional conditionings."""
+
+    base_conditioning: object
+    regional_contexts: tuple[RawRegionalAttentionContext, ...]
+
+    def __post_init__(self) -> None:
+        """Require immutable canonical regional order."""
+
+        if not isinstance(self.regional_contexts, tuple):
+            raise TypeError("Raw regional attention contexts must be a tuple.")
+        if any(
+            not isinstance(context, RawRegionalAttentionContext)
+            for context in self.regional_contexts
+        ):
+            raise TypeError(
+                "Raw regional attention branch contains an invalid context."
+            )
+        indices = tuple(context.region_index for context in self.regional_contexts)
+        if indices != tuple(range(len(self.regional_contexts))):
+            raise ValueError(
+                "Raw regional attention contexts must use canonical order."
+            )
+
+
+@dataclass(frozen=True, slots=True)
+class RawRegionalAttentionPlan:
+    """Retain both raw branches and shared canonical regional authorities."""
+
+    positive: RawRegionalAttentionBranch
+    negative: RawRegionalAttentionBranch
+    mask_bank: RegionalMaskBank
+    lora_plan: RegionalLoraPlan
+
+    def __post_init__(self) -> None:
+        """Validate plan owners and regional LoRA bounds."""
+
+        if not isinstance(self.positive, RawRegionalAttentionBranch) or not isinstance(
+            self.negative, RawRegionalAttentionBranch
+        ):
+            raise TypeError("Raw regional attention plan contains an invalid branch.")
+        validate_regional_attention_plan_authorities(
+            mask_bank=self.mask_bank,
+            lora_plan=self.lora_plan,
+            positive_region_count=len(self.positive.regional_contexts),
+            negative_region_count=len(self.negative.regional_contexts),
+        )
+
+
+def build_raw_regional_attention_plan(
+    *,
+    positive: object,
+    negative: object,
+    mask_bank: RegionalMaskBank,
+    lora_plan: RegionalLoraPlan = EMPTY_REGIONAL_LORA_PLAN,
+) -> RawRegionalAttentionPlan:
+    """Build both branches through the authoritative global-first pairing policy."""
+
+    if not isinstance(mask_bank, RegionalMaskBank):
+        raise TypeError("Raw regional attention requires a RegionalMaskBank.")
+    return RawRegionalAttentionPlan(
+        positive=_build_raw_branch(
+            positive,
+            mask_bank=mask_bank,
+            input_name="positive",
+        ),
+        negative=_build_raw_branch(
+            negative,
+            mask_bank=mask_bank,
+            input_name="negative",
+        ),
+        mask_bank=mask_bank,
+        lora_plan=lora_plan,
+    )
+
+
+def _build_raw_branch(
+    conditioning: object,
+    *,
+    mask_bank: RegionalMaskBank,
+    input_name: str,
+) -> RawRegionalAttentionBranch:
+    """Pair one raw conditioning branch without restating index policy."""
+
+    entries = (
+        conditioning.entries
+        if isinstance(conditioning, ConditioningBatch)
+        else (conditioning,)
+    )
+    pairing = build_regional_conditioning_plan(
+        region_count=mask_bank.region_count,
+        conditioning_count=len(entries),
+        input_name=input_name,
+    )
+    return RawRegionalAttentionBranch(
+        base_conditioning=entries[0],
+        regional_contexts=tuple(
+            RawRegionalAttentionContext(
+                conditioning_index=pair.conditioning_index,
+                region_index=pair.mask_index,
+                conditioning=entries[pair.conditioning_index],
+            )
+            for pair in pairing.pairs
+        ),
+    )

simple_syrup/domain/regional_activation_geometry.py

@@ -0,0 +1,237 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define model-neutral regional activation geometry and batch alignment."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from .spatial_views import SpatialBatchLayout
+
+
+class RegionalActivationLayout(StrEnum):
+    """Classify the explicit spatial organization of one adapter activation."""
+
+    DIRECT_CONVOLUTION_1D = "direct_convolution_1d"
+    DIRECT_CONVOLUTION_2D = "direct_convolution_2d"
+    DIRECT_CONVOLUTION_3D = "direct_convolution_3d"
+    FLATTENED_SPATIAL_TOKENS = "flattened_spatial_tokens"
+    CONSUMER_SPATIALIZED = "consumer_spatialized"
+    BRANCH_TOKENS = "branch_tokens"
+
+
+class RegionalTemporalOwnership(StrEnum):
+    """Declare how a two-dimensional authored mask owns temporal activations."""
+
+    NONE = "none"
+    REPEAT_SPATIAL_MASK = "repeat_spatial_mask"
+
+
+@dataclass(frozen=True, slots=True)
+class RegionalActivationBatchAlignment:
+    """Retain CFG, latent-batch, and optional view-major alignment evidence."""
+
+    latent_batch_size: int
+    chunk_count: int
+    spatial_layout: SpatialBatchLayout | None = None
+
+    def __post_init__(self) -> None:
+        """Require positive counts and one layout over the complete base batch."""
+
+        _positive_integer(self.latent_batch_size, name="latent_batch_size")
+        _positive_integer(self.chunk_count, name="chunk_count")
+        if self.spatial_layout is not None:
+            if not isinstance(self.spatial_layout, SpatialBatchLayout):
+                raise TypeError(
+                    "Regional activation spatial_layout must be a SpatialBatchLayout."
+                )
+            if self.spatial_layout.input_batch_size != self.base_batch_size:
+                raise ValueError(
+                    "Regional activation spatial layout input batch must match "
+                    "CFG chunks times latent batch size."
+                )
+
+    @property
+    def base_batch_size(self) -> int:
+        """Return the model batch before spatial-view expansion."""
+
+        return self.latent_batch_size * self.chunk_count
+
+    @property
+    def invocation_batch_size(self) -> int:
+        """Return the active model batch after optional view expansion."""
+
+        if self.spatial_layout is None:
+            return self.base_batch_size
+        return self.spatial_layout.expanded_batch_size
+
+
+@dataclass(frozen=True, slots=True)
+class RegionalActivationGeometry:
+    """Describe one exact rank activation and its authored-mask correspondence."""
+
+    layout: RegionalActivationLayout
+    invocation_shape: tuple[int, ...]
+    feature_axis: int
+    spatial_height: int
+    spatial_width: int
+    batch_alignment: RegionalActivationBatchAlignment
+    temporal_axis: int | None = None
+    temporal_ownership: RegionalTemporalOwnership = RegionalTemporalOwnership.NONE
+
+    def __post_init__(self) -> None:
+        """Reject ambiguous axes, batches, tokens, and temporal ownership."""
+
+        if not isinstance(self.layout, RegionalActivationLayout):
+            raise TypeError("Regional activation layout has an invalid type.")
+        if not isinstance(self.invocation_shape, tuple) or not self.invocation_shape:
+            raise ValueError("Regional activation shape must be a nonempty tuple.")
+        for dimension in self.invocation_shape:
+            _positive_integer(dimension, name="shape dimension")
+        if not isinstance(self.batch_alignment, RegionalActivationBatchAlignment):
+            raise TypeError("Regional activation requires batch alignment evidence.")
+        _positive_integer(self.spatial_height, name="spatial_height")
+        _positive_integer(self.spatial_width, name="spatial_width")
+        if self.invocation_shape[0] != self.batch_alignment.invocation_batch_size:
+            raise ValueError(
+                "Regional activation leading batch must match its alignment."
+            )
+        rank = len(self.invocation_shape)
+        _axis(self.feature_axis, rank=rank, name="feature_axis")
+        if self.feature_axis == 0:
+            raise ValueError(
+                "Regional activation feature axis cannot be the batch axis."
+            )
+        if not isinstance(self.temporal_ownership, RegionalTemporalOwnership):
+            raise TypeError(
+                "Regional activation temporal ownership has an invalid type."
+            )
+        self._validate_layout()
+
+    def _validate_layout(self) -> None:
+        """Match the declared layout to its exact conventional tensor shape."""
+
+        batch = self.batch_alignment.invocation_batch_size
+        features = self.invocation_shape[self.feature_axis]
+        if self.layout is RegionalActivationLayout.DIRECT_CONVOLUTION_1D:
+            self._require_shape((batch, features, self.spatial_width), feature_axis=1)
+            if self.spatial_height != 1:
+                raise ValueError("Direct Conv1d regional geometry requires height one.")
+            self._require_no_temporal_axis()
+            return
+        if self.layout is RegionalActivationLayout.DIRECT_CONVOLUTION_2D:
+            self._require_shape(
+                (batch, features, self.spatial_height, self.spatial_width),
+                feature_axis=1,
+            )
+            self._require_no_temporal_axis()
+            return
+        if self.layout is RegionalActivationLayout.DIRECT_CONVOLUTION_3D:
+            if self.feature_axis != 1 or len(self.invocation_shape) != 5:
+                raise ValueError("Direct Conv3d regional geometry requires B/C/D/H/W.")
+            if self.temporal_axis != 2:
+                raise ValueError(
+                    "Direct Conv3d regional geometry requires temporal axis 2."
+                )
+            if self.invocation_shape[3:] != (
+                self.spatial_height,
+                self.spatial_width,
+            ):
+                raise ValueError("Direct Conv3d regional H/W must match its tensor.")
+            if (
+                self.temporal_ownership
+                is not RegionalTemporalOwnership.REPEAT_SPATIAL_MASK
+            ):
+                raise ValueError(
+                    "Direct Conv3d regional geometry requires explicit repeated "
+                    "spatial-mask temporal ownership."
+                )
+            return
+        if self.layout in (
+            RegionalActivationLayout.FLATTENED_SPATIAL_TOKENS,
+            RegionalActivationLayout.CONSUMER_SPATIALIZED,
+        ):
+            self._require_shape(
+                (
+                    batch,
+                    self.spatial_height * self.spatial_width,
+                    features,
+                ),
+                feature_axis=2,
+            )
+            self._require_no_temporal_axis()
+            return
+        if self.layout is RegionalActivationLayout.BRANCH_TOKENS:
+            self._require_shape(
+                (batch, self.spatial_width, features),
+                feature_axis=2,
+            )
+            if self.spatial_height != 1:
+                raise ValueError("Branch-token regional geometry requires height one.")
+            self._require_no_temporal_axis()
+            return
+        raise AssertionError(f"Unhandled regional activation layout: {self.layout}")
+
+    def _require_shape(
+        self,
+        expected: tuple[int, ...],
+        *,
+        feature_axis: int,
+    ) -> None:
+        """Require one conventional shape and feature-axis location."""
+
+        if self.feature_axis != feature_axis or self.invocation_shape != expected:
+            raise ValueError(
+                f"{self.layout.value} regional geometry expected shape {expected} "
+                f"with feature axis {feature_axis}; observed "
+                f"{self.invocation_shape} and axis {self.feature_axis}."
+            )
+
+    def _require_no_temporal_axis(self) -> None:
+        """Reject temporal claims from non-temporal image activation layouts."""
+
+        if self.temporal_axis is not None:
+            raise ValueError(
+                "Non-temporal regional geometry cannot declare a temporal axis."
+            )
+        if self.temporal_ownership is not RegionalTemporalOwnership.NONE:
+            raise ValueError(
+                "Non-temporal regional geometry cannot claim temporal ownership."
+            )
+
+    @property
+    def temporal_size(self) -> int | None:
+        """Return the explicit temporal size when this activation owns one."""
+
+        if self.temporal_axis is None:
+            return None
+        return self.invocation_shape[self.temporal_axis]
+
+    def broadcast_mask_shape(self, region_count: int) -> tuple[int, ...]:
+        """Return the exact region-major multiplier shape for this activation."""
+
+        _positive_integer(region_count, name="region_count")
+        shape = list(self.invocation_shape)
+        shape[self.feature_axis] = 1
+        return (region_count, *shape)
+
+
+def _positive_integer(value: object, *, name: str) -> None:
+    """Require one strictly positive non-boolean integer."""
+
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"Regional activation {name} must be an integer.")
+    if value < 1:
+        raise ValueError(f"Regional activation {name} must be positive.")
+
+
+def _axis(value: object, *, rank: int, name: str) -> None:
+    """Require one non-negative axis inside the invocation rank."""
+
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"Regional activation {name} must be an integer.")
+    if not 0 <= value < rank:
+        raise ValueError(f"Regional activation {name} is outside the tensor rank.")

simple_syrup/domain/regional_attention.py

@@ -0,0 +1,69 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Own shared regional Attention Coupling contracts and validation."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from .regional_lora_plan import RegionalLoraPlan
+from .regional_mask_bank import RegionalMaskBank
+
+
+class RegionalAttentionBranch(StrEnum):
+    """Name the processed conditioning bank selected for one Comfy chunk."""
+
+    POSITIVE = "positive"
+    NEGATIVE = "negative"
+
+
+def require_non_negative_regional_attention_index(
+    value: object,
+    *,
+    name: str,
+) -> None:
+    """Require one non-negative integer regional-attention index."""
+
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"Regional attention {name} must be an integer.")
+    if value < 0:
+        raise ValueError(f"Regional attention {name} must be non-negative.")
+
+
+def validate_regional_attention_plan_authorities(
+    *,
+    mask_bank: object,
+    lora_plan: object,
+    positive_region_count: int,
+    negative_region_count: int,
+) -> None:
+    """Validate shared mask, LoRA, and branch-count plan authorities."""
+
+    if not isinstance(mask_bank, RegionalMaskBank):
+        raise TypeError("Regional attention plan requires a RegionalMaskBank.")
+    if not isinstance(lora_plan, RegionalLoraPlan):
+        raise TypeError("Regional attention plan requires a RegionalLoraPlan.")
+    for branch_name, region_count in (
+        ("positive", positive_region_count),
+        ("negative", negative_region_count),
+    ):
+        require_non_negative_regional_attention_index(
+            region_count,
+            name=f"{branch_name} region count",
+        )
+        if region_count > mask_bank.region_count:
+            raise ValueError(
+                f"Regional attention {branch_name} branch exceeds the mask bank."
+            )
+    out_of_bounds = tuple(
+        adapter
+        for adapter in lora_plan.adapters
+        if adapter.region_index >= mask_bank.region_count
+    )
+    if out_of_bounds:
+        indices = ", ".join(str(adapter.region_index) for adapter in out_of_bounds)
+        raise ValueError(
+            "Regional attention LoRA region indices exceed the mask bank: " + indices
+        )

simple_syrup/domain/regional_attention_batch.py

@@ -0,0 +1,227 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Own immutable chunk-major regional attention batch alignment values."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import torch
+
+from .regional_attention import RegionalAttentionBranch
+
+
+@dataclass(frozen=True, slots=True)
+class RegionalAttentionChunkBatch:
+    """Describe one Comfy chunk's contiguous slice of the model batch."""
+
+    chunk_index: int
+    branch: RegionalAttentionBranch
+    batch_start: int
+    batch_stop: int
+
+    def __post_init__(self) -> None:
+        """Validate one positive non-empty contiguous batch slice."""
+
+        for name, value in (
+            ("chunk_index", self.chunk_index),
+            ("batch_start", self.batch_start),
+            ("batch_stop", self.batch_stop),
+        ):
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise TypeError(f"Regional attention {name} must be an integer.")
+        if self.chunk_index < 0 or self.batch_start < 0:
+            raise ValueError("Regional attention chunk indices must be non-negative.")
+        if self.batch_stop <= self.batch_start:
+            raise ValueError("Regional attention chunk batch slice must be non-empty.")
+        if not isinstance(self.branch, RegionalAttentionBranch):
+            raise TypeError("Regional attention chunk branch has an invalid type.")
+
+
+@dataclass(frozen=True, slots=True)
+class BatchedRegionalAttentionEntry:
+    """Retain one aligned regional entry and its per-sample Comfy strengths."""
+
+    entry_index: int
+    context: torch.Tensor
+    strengths: tuple[float, ...]
+    cross_attention_value_multiplier: torch.Tensor | None = None
+
+    def __post_init__(self) -> None:
+        """Validate entry order, aligned context, and finite sample strengths."""
+
+        if isinstance(self.entry_index, bool) or not isinstance(self.entry_index, int):
+            raise TypeError("Regional attention entry_index must be an integer.")
+        if self.entry_index < 0:
+            raise ValueError("Regional attention entry_index must be non-negative.")
+        _validate_aligned_context(self.context, name="entry")
+        if not isinstance(self.strengths, tuple):
+            raise TypeError("Regional attention entry strengths must be a tuple.")
+        if len(self.strengths) != int(self.context.shape[0]):
+            raise ValueError(
+                "Regional attention entry strength count must match its batch."
+            )
+        for strength in self.strengths:
+            if isinstance(strength, bool) or not isinstance(strength, int | float):
+                raise TypeError(
+                    "Regional attention entry strength must be a real number."
+                )
+            if not math.isfinite(float(strength)):
+                raise ValueError("Regional attention entry strength must be finite.")
+        _validate_value_multiplier(
+            self.cross_attention_value_multiplier,
+            self.context,
+            name="entry",
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class BatchedRegionalAttentionRegion:
+    """Retain every aligned active conditioning entry for one region."""
+
+    region_index: int
+    entries: tuple[BatchedRegionalAttentionEntry, ...]
+
+    def __post_init__(self) -> None:
+        """Require a non-empty canonical entry bank for one region."""
+
+        if isinstance(self.region_index, bool) or not isinstance(
+            self.region_index, int
+        ):
+            raise TypeError("Regional attention region_index must be an integer.")
+        if self.region_index < 0:
+            raise ValueError("Regional attention region_index must be non-negative.")
+        if not isinstance(self.entries, tuple) or not self.entries:
+            raise ValueError("Regional attention region requires active entries.")
+        if any(
+            not isinstance(entry, BatchedRegionalAttentionEntry)
+            for entry in self.entries
+        ):
+            raise TypeError("Regional attention region contains an invalid entry.")
+        if tuple(entry.entry_index for entry in self.entries) != tuple(
+            range(len(self.entries))
+        ):
+            raise ValueError("Regional attention region entries must be canonical.")
+
+
+@dataclass(frozen=True, slots=True)
+class BatchedRegionalAttentionContexts:
+    """Retain chunk-major base and per-region active-entry model contexts."""
+
+    latent_batch_size: int
+    chunks: tuple[RegionalAttentionChunkBatch, ...]
+    base_context: torch.Tensor
+    regions: tuple[BatchedRegionalAttentionRegion, ...]
+    base_value_multiplier: torch.Tensor | None = None
+
+    def __post_init__(self) -> None:
+        """Validate complete chunk and tensor alignment."""
+
+        if isinstance(self.latent_batch_size, bool) or not isinstance(
+            self.latent_batch_size, int
+        ):
+            raise TypeError("Regional attention latent_batch_size must be an integer.")
+        if self.latent_batch_size < 1:
+            raise ValueError("Regional attention latent_batch_size must be positive.")
+        if not isinstance(self.chunks, tuple) or not self.chunks:
+            raise ValueError("Regional attention batch requires at least one chunk.")
+        if any(
+            not isinstance(chunk, RegionalAttentionChunkBatch) for chunk in self.chunks
+        ):
+            raise TypeError("Regional attention batch contains an invalid chunk.")
+        expected_start = 0
+        for chunk_index, chunk in enumerate(self.chunks):
+            if chunk.chunk_index != chunk_index or chunk.batch_start != expected_start:
+                raise ValueError(
+                    "Regional attention chunks must be contiguous and ordered."
+                )
+            if chunk.batch_stop - chunk.batch_start != self.latent_batch_size:
+                raise ValueError(
+                    "Regional attention chunk size must match latent batch."
+                )
+            expected_start = chunk.batch_stop
+        _validate_aligned_context(
+            self.base_context,
+            expected_batch=expected_start,
+            name="base",
+        )
+        _validate_value_multiplier(
+            self.base_value_multiplier,
+            self.base_context,
+            name="base",
+        )
+        if not isinstance(self.regions, tuple):
+            raise TypeError("Regional attention regions must be a tuple.")
+        if tuple(region.region_index for region in self.regions) != tuple(
+            range(len(self.regions))
+        ):
+            raise ValueError("Regional attention regions must use canonical order.")
+        for region in self.regions:
+            for entry in region.entries:
+                _validate_aligned_context(
+                    entry.context,
+                    expected_batch=expected_start,
+                    name=f"region {region.region_index} entry {entry.entry_index}",
+                )
+                if entry.context.shape[1:] != self.base_context.shape[1:]:
+                    raise ValueError(
+                        "Regional attention context sequence shapes must match."
+                    )
+                if (
+                    entry.context.device != self.base_context.device
+                    or entry.context.dtype != self.base_context.dtype
+                ):
+                    raise ValueError(
+                        "Regional attention context device and dtype must match."
+                    )
+
+
+def _validate_aligned_context(
+    context: object,
+    *,
+    name: str,
+    expected_batch: int | None = None,
+) -> None:
+    """Validate one finite floating BxSxD context tensor."""
+
+    if not isinstance(context, torch.Tensor):
+        raise TypeError(f"Regional attention {name} context must be a tensor.")
+    if context.ndim != 3 or (
+        expected_batch is not None and int(context.shape[0]) != expected_batch
+    ):
+        raise ValueError(
+            f"Regional attention {name} context has an invalid aligned batch."
+        )
+    if not context.is_floating_point() or not bool(
+        torch.isfinite(context).all().item()
+    ):
+        raise ValueError(
+            f"Regional attention {name} context must contain finite floating values."
+        )
+
+
+def _validate_value_multiplier(
+    multiplier: object,
+    context: torch.Tensor,
+    *,
+    name: str,
+) -> None:
+    """Validate one optional value multiplier against its aligned context."""
+
+    if multiplier is None:
+        return
+    if (
+        not isinstance(multiplier, torch.Tensor)
+        or multiplier.shape != (*context.shape[:2], 1)
+        or not multiplier.is_floating_point()
+        or multiplier.device != context.device
+        or multiplier.dtype != context.dtype
+        or not bool(torch.isfinite(multiplier).all().item())
+    ):
+        raise ValueError(
+            f"Regional attention {name} value multiplier must be a finite "
+            "floating BxSx1 tensor aligned with its context."
+        )

simple_syrup/domain/regional_attention_execution.py

@@ -0,0 +1,15 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Own the immutable spatial execution vocabulary for regional attention."""
+
+from enum import StrEnum
+
+
+class RegionalAttentionExecutionMode(StrEnum):
+    """Identify how one prepared regional model traverses the latent canvas."""
+
+    FULL = "full-context"
+    TILED = "tiled"
+    CONTEXTUAL = "Contextual"

simple_syrup/domain/regional_attention_selection.py

@@ -0,0 +1,220 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Select exact active processed Attention Coupling entries for one sigma."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import UUID
+
+from .conditioning_schedule_selection import (
+    CONDITIONING_SCHEDULE_SELECTION_POLICY,
+    ConditioningScheduleSelectionPolicy,
+    normalize_conditioning_sigma,
+)
+from .processed_regional_attention import (
+    ProcessedRegionalAttentionBranch,
+    ProcessedRegionalAttentionEntry,
+    ProcessedRegionalAttentionPlan,
+)
+from .regional_attention import (
+    RegionalAttentionBranch,
+    require_non_negative_regional_attention_index,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class ActiveProcessedRegionalAttentionChunk:
+    """Bind one Comfy chunk UUID to its active base and regional entries."""
+
+    chunk_index: int
+    branch: RegionalAttentionBranch
+    base_entry: ProcessedRegionalAttentionEntry
+    regional_entries: tuple[
+        tuple[ProcessedRegionalAttentionEntry, ...] | None,
+        ...,
+    ]
+
+    def __post_init__(self) -> None:
+        """Validate canonical immutable active selection state."""
+
+        require_non_negative_regional_attention_index(
+            self.chunk_index,
+            name="chunk_index",
+        )
+        if not isinstance(self.branch, RegionalAttentionBranch):
+            raise TypeError("Regional attention chunk branch has an invalid type.")
+        if not isinstance(self.base_entry, ProcessedRegionalAttentionEntry):
+            raise TypeError("Regional attention chunk base entry has an invalid type.")
+        if not isinstance(self.regional_entries, tuple):
+            raise TypeError("Regional attention chunk regions must be a tuple.")
+        for entries in self.regional_entries:
+            if entries is not None and (
+                not isinstance(entries, tuple)
+                or any(
+                    not isinstance(entry, ProcessedRegionalAttentionEntry)
+                    for entry in entries
+                )
+            ):
+                raise TypeError(
+                    "Regional attention chunk contains invalid active entries."
+                )
+
+
+class RegionalAttentionSelectionService:
+    """Match Comfy chunk UUIDs to active base and regional entry banks."""
+
+    def __init__(
+        self,
+        schedule_policy: ConditioningScheduleSelectionPolicy | None = None,
+    ) -> None:
+        """Retain the focused schedule policy collaborator."""
+
+        self._schedule_policy = schedule_policy or ConditioningScheduleSelectionPolicy()
+
+    def select_chunks(
+        self,
+        plan: ProcessedRegionalAttentionPlan,
+        *,
+        cond_or_uncond: object,
+        conditioning_uuids: object,
+        sigma: float,
+    ) -> tuple[ActiveProcessedRegionalAttentionChunk, ...]:
+        """Select exact active entries in Comfy's supplied UUID order."""
+
+        if not isinstance(plan, ProcessedRegionalAttentionPlan):
+            raise TypeError("Regional attention selection requires a processed plan.")
+        selectors = _selectors(cond_or_uncond)
+        identities = _conditioning_uuids(conditioning_uuids)
+        if len(selectors) != len(identities):
+            raise ValueError(
+                "Regional attention selectors and UUIDs must have equal lengths."
+            )
+        current_sigma = normalize_conditioning_sigma(sigma)
+        return tuple(
+            self._select_chunk(
+                plan,
+                chunk_index=chunk_index,
+                selector=selector,
+                conditioning_uuid=conditioning_uuid,
+                sigma=current_sigma,
+            )
+            for chunk_index, (selector, conditioning_uuid) in enumerate(
+                zip(selectors, identities, strict=True)
+            )
+        )
+
+    def _select_chunk(
+        self,
+        plan: ProcessedRegionalAttentionPlan,
+        *,
+        chunk_index: int,
+        selector: object,
+        conditioning_uuid: UUID,
+        sigma: float,
+    ) -> ActiveProcessedRegionalAttentionChunk:
+        """Resolve one branch UUID and all regional schedules atomically."""
+
+        branch, contexts = _branch(plan, selector=selector, chunk_index=chunk_index)
+        matching_base = tuple(
+            entry
+            for entry in contexts.base_context.entries
+            if entry.uuid is conditioning_uuid
+        )
+        if len(matching_base) != 1:
+            raise ValueError(
+                f"Regional attention {branch.value} chunk {chunk_index} UUID "
+                "does not identify exactly one processed base entry."
+            )
+        base_entry = matching_base[0]
+        if not self._schedule_policy.is_active(base_entry.schedule, sigma=sigma):
+            raise ValueError(
+                f"Regional attention {branch.value} chunk {chunk_index} UUID is "
+                f"inactive at sigma {sigma}."
+            )
+        return ActiveProcessedRegionalAttentionChunk(
+            chunk_index=chunk_index,
+            branch=branch,
+            base_entry=base_entry,
+            regional_entries=tuple(
+                self._regional_entries(contexts, region_index, sigma=sigma)
+                for region_index in range(plan.mask_bank.region_count)
+            ),
+        )
+
+    def _regional_entries(
+        self,
+        branch: ProcessedRegionalAttentionBranch,
+        region_index: int,
+        *,
+        sigma: float,
+    ) -> tuple[ProcessedRegionalAttentionEntry, ...] | None:
+        """Distinguish absent regions from authored regions with no active entry."""
+
+        if region_index >= len(branch.regional_contexts):
+            return None
+        return self._active_entries(
+            branch.regional_contexts[region_index].entries,
+            sigma=sigma,
+        )
+
+    def _active_entries(
+        self,
+        entries: tuple[ProcessedRegionalAttentionEntry, ...],
+        *,
+        sigma: float,
+    ) -> tuple[ProcessedRegionalAttentionEntry, ...]:
+        """Retain every active entry in authored order at one finite sigma."""
+
+        return tuple(
+            entry
+            for entry in entries
+            if self._schedule_policy.is_active(entry.schedule, sigma=sigma)
+        )
+
+
+def _branch(
+    plan: ProcessedRegionalAttentionPlan,
+    *,
+    selector: object,
+    chunk_index: int,
+) -> tuple[RegionalAttentionBranch, ProcessedRegionalAttentionBranch]:
+    """Narrow one Comfy branch selector without accepting booleans."""
+
+    if isinstance(selector, bool) or not isinstance(selector, int):
+        raise TypeError(
+            f"cond_or_uncond selector {chunk_index} must be integer 0 or 1."
+        )
+    if selector == 0:
+        return RegionalAttentionBranch.POSITIVE, plan.positive
+    if selector == 1:
+        return RegionalAttentionBranch.NEGATIVE, plan.negative
+    raise ValueError(
+        f"cond_or_uncond selector {chunk_index} must be 0 or 1; observed {selector}."
+    )
+
+
+def _selectors(value: object) -> tuple[object, ...]:
+    """Require Comfy's ordered selector container."""
+
+    if not isinstance(value, list | tuple):
+        raise TypeError("cond_or_uncond must be a list or tuple of chunk selectors.")
+    return tuple(value)
+
+
+def _conditioning_uuids(value: object) -> tuple[UUID, ...]:
+    """Require exact Comfy UUID objects for every supplied chunk."""
+
+    if not isinstance(value, list | tuple):
+        raise TypeError("Conditioning UUIDs must be a list or tuple.")
+    identities = tuple(value)
+    if any(not isinstance(identity, UUID) for identity in identities):
+        raise TypeError("Every conditioning identity must be a Comfy UUID.")
+    return identities
+
+
+REGIONAL_ATTENTION_SELECTION_SERVICE = RegionalAttentionSelectionService(
+    CONDITIONING_SCHEDULE_SELECTION_POLICY
+)

simple_syrup/domain/regional_attention_weights.py

@@ -0,0 +1,252 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Normalize regional attention weights and blend ordered branch outputs."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import torch
+
+
+@dataclass(frozen=True, slots=True)
+class RegionalAttentionWeights:
+    """Hold raw base, region, and denominator weights on one query grid."""
+
+    base: torch.Tensor
+    regions: torch.Tensor
+    denominator: torch.Tensor
+
+    def __post_init__(self) -> None:
+        """Require consistent finite non-negative weighting tensors."""
+
+        for name, tensor in (
+            ("Base", self.base),
+            ("Region", self.regions),
+            ("Denominator", self.denominator),
+        ):
+            if not isinstance(tensor, torch.Tensor):
+                raise TypeError(f"{name} attention weights must be a torch.Tensor.")
+            if not tensor.is_floating_point():
+                raise TypeError(
+                    f"{name} attention weights must use a floating-point dtype."
+                )
+            if not bool(torch.isfinite(tensor).all()):
+                raise ValueError(f"{name} attention weights must be finite.")
+            if not bool((tensor >= 0.0).all()):
+                raise ValueError(f"{name} attention weights must be non-negative.")
+        if self.base.ndim < 1:
+            raise ValueError("Base attention weights require a query-grid dimension.")
+        if self.regions.ndim != self.base.ndim + 1:
+            raise ValueError(
+                "Region attention weights require a leading region dimension."
+            )
+        if int(self.regions.shape[0]) < 1:
+            raise ValueError("Region attention weights require at least one region.")
+        if tuple(self.regions.shape[1:]) != tuple(self.base.shape):
+            raise ValueError("Region attention weights must match the base query grid.")
+        if self.denominator.shape != self.base.shape:
+            raise ValueError("Attention denominator must match the base query grid.")
+        if not (
+            self.base.dtype == self.regions.dtype == self.denominator.dtype
+            and self.base.device == self.regions.device == self.denominator.device
+        ):
+            raise ValueError(
+                "Base, region, and denominator weights must share dtype and device."
+            )
+        if not bool((self.denominator > 0.0).all()):
+            raise ValueError("Attention denominator must be strictly positive.")
+
+    @property
+    def normalized_base(self) -> torch.Tensor:
+        """Return normalized base-complement weights."""
+
+        return self.base / self.denominator
+
+    @property
+    def normalized_regions(self) -> torch.Tensor:
+        """Return normalized ordered regional weights."""
+
+        return self.regions / self.denominator.unsqueeze(0)
+
+
+class RegionalAttentionWeightingPolicy:
+    """Own Comfy-compatible base complement and normalized branch composition."""
+
+    def weights(
+        self,
+        masks: torch.Tensor,
+        *,
+        region_strengths: tuple[float, ...],
+        epsilon: float = 1e-6,
+    ) -> RegionalAttentionWeights:
+        """Return raw weighting terms for ordered region-first query masks."""
+
+        self._validate_mask_structure(masks)
+        strengths = self._validate_strengths(
+            region_strengths,
+            region_count=int(masks.shape[0]),
+        )
+        if (
+            isinstance(epsilon, bool)
+            or not isinstance(epsilon, int | float)
+            or not math.isfinite(float(epsilon))
+            or epsilon <= 0.0
+        ):
+            raise ValueError("Regional attention epsilon must be finite and positive.")
+        self._validate_mask_values(masks)
+
+        strength_shape = (len(strengths),) + (1,) * (masks.ndim - 1)
+        strength_tensor = masks.new_tensor(strengths).reshape(strength_shape)
+        region_weights = masks.clamp(0.0, 1.0) * strength_tensor
+        region_sum = region_weights.sum(dim=0)
+        base_weight = torch.relu(1.0 - region_sum)
+        denominator = (base_weight + region_sum).clamp_min(float(epsilon))
+        return RegionalAttentionWeights(
+            base=base_weight,
+            regions=region_weights,
+            denominator=denominator,
+        )
+
+    def blend(
+        self,
+        *,
+        weights: RegionalAttentionWeights,
+        base_output: torch.Tensor,
+        regional_outputs: torch.Tensor,
+    ) -> torch.Tensor:
+        """Blend one base and ordered regional outputs over their query grid."""
+
+        self._validate_outputs(
+            weights=weights,
+            base_output=base_output,
+            regional_outputs=regional_outputs,
+        )
+        feature_dimensions = base_output.ndim - weights.base.ndim
+        feature_shape = (1,) * feature_dimensions
+        base_weight = weights.base.reshape((*weights.base.shape, *feature_shape)).to(
+            dtype=base_output.dtype
+        )
+        region_weights = weights.regions.reshape(
+            (*weights.regions.shape, *feature_shape)
+        ).to(dtype=base_output.dtype)
+        denominator = weights.denominator.reshape(
+            (*weights.denominator.shape, *feature_shape)
+        ).to(dtype=base_output.dtype)
+        numerator = base_weight * base_output + (region_weights * regional_outputs).sum(
+            dim=0
+        )
+        blended = numerator / denominator
+        if not bool(torch.isfinite(blended).all()):
+            raise ValueError(
+                "Blended regional attention output contains non-finite values."
+            )
+        return blended
+
+    @staticmethod
+    def _validate_mask_structure(masks: torch.Tensor) -> None:
+        """Validate mask type and shape without inspecting device values."""
+
+        if not isinstance(masks, torch.Tensor):
+            raise TypeError("Regional attention masks must be a torch.Tensor.")
+        if masks.ndim < 2:
+            raise ValueError(
+                "Regional attention masks require region and query-grid dimensions."
+            )
+        if int(masks.shape[0]) < 1 or any(int(size) < 1 for size in masks.shape[1:]):
+            raise ValueError(
+                "Regional attention masks require non-empty region and query grids."
+            )
+        if not masks.is_floating_point():
+            raise TypeError("Regional attention masks must use a floating-point dtype.")
+
+    @staticmethod
+    def _validate_mask_values(masks: torch.Tensor) -> None:
+        """Reject non-finite mask values before constructing strength tensors."""
+
+        if not bool(torch.isfinite(masks).all()):
+            raise ValueError("Regional attention masks must contain finite values.")
+
+    @staticmethod
+    def _validate_strengths(
+        strengths: tuple[float, ...],
+        *,
+        region_count: int,
+    ) -> tuple[float, ...]:
+        """Validate ordered immutable regional strengths before tensor creation."""
+
+        if not isinstance(strengths, tuple):
+            raise TypeError("Regional attention strengths must be an immutable tuple.")
+        if len(strengths) != region_count:
+            raise ValueError(
+                "Regional attention strength count must match the mask region count."
+            )
+        normalized: list[float] = []
+        for index, strength in enumerate(strengths):
+            if isinstance(strength, bool) or not isinstance(strength, int | float):
+                raise TypeError(
+                    f"Regional attention strength {index} must be a real number."
+                )
+            value = float(strength)
+            if not math.isfinite(value) or value < 0.0:
+                raise ValueError(
+                    f"Regional attention strength {index} must be finite and "
+                    "non-negative."
+                )
+            normalized.append(value)
+        return tuple(normalized)
+
+    @staticmethod
+    def _validate_outputs(
+        *,
+        weights: RegionalAttentionWeights,
+        base_output: torch.Tensor,
+        regional_outputs: torch.Tensor,
+    ) -> None:
+        """Validate branch output ordering, grids, features, and tensor state."""
+
+        if not isinstance(weights, RegionalAttentionWeights):
+            raise TypeError("Regional blend weights must be RegionalAttentionWeights.")
+        if not isinstance(base_output, torch.Tensor) or not isinstance(
+            regional_outputs, torch.Tensor
+        ):
+            raise TypeError(
+                "Regional attention branch outputs must be torch.Tensor values."
+            )
+        if (
+            not base_output.is_floating_point()
+            or not regional_outputs.is_floating_point()
+        ):
+            raise TypeError(
+                "Regional attention branch outputs must use floating-point dtypes."
+            )
+        if base_output.dtype != regional_outputs.dtype:
+            raise ValueError("Regional attention branch output dtypes must match.")
+        if base_output.device != regional_outputs.device:
+            raise ValueError("Regional attention branch output devices must match.")
+        expected_regional_shape = (int(weights.regions.shape[0]), *base_output.shape)
+        if regional_outputs.shape != expected_regional_shape:
+            raise ValueError(
+                "Regional outputs must contain one ordered branch per region with "
+                "the complete base output shape."
+            )
+        query_dimensions = weights.base.ndim
+        if base_output.ndim < query_dimensions or tuple(
+            base_output.shape[:query_dimensions]
+        ) != tuple(weights.base.shape):
+            raise ValueError(
+                "Regional attention outputs must begin with the weighting query grid."
+            )
+        if weights.base.device != base_output.device:
+            raise ValueError(
+                "Regional weights and branch outputs must share one device."
+            )
+        if not bool(torch.isfinite(base_output).all()) or not bool(
+            torch.isfinite(regional_outputs).all()
+        ):
+            raise ValueError(
+                "Regional attention branch outputs must contain finite values."
+            )

simple_syrup/domain/regional_conditioning_output.py

@@ -0,0 +1,105 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Own Comfy-equivalent within-region conditioning-output combination."""
+
+from __future__ import annotations
+
+import math
+
+import torch
+
+
+class RegionalConditioningOutputCombiner:
+    """Combine ordered active-entry outputs with native Comfy strength semantics."""
+
+    def combine(
+        self,
+        outputs: tuple[torch.Tensor, ...],
+        *,
+        strengths: tuple[tuple[float, ...], ...],
+    ) -> torch.Tensor:
+        """Return the ordered strength-weighted output normalized like Comfy."""
+
+        if not isinstance(outputs, tuple) or not outputs:
+            raise ValueError("Regional conditioning combination requires outputs.")
+        if not isinstance(strengths, tuple) or len(strengths) != len(outputs):
+            raise ValueError(
+                "Regional conditioning strengths must align with ordered outputs."
+            )
+        authority = outputs[0]
+        if not isinstance(authority, torch.Tensor) or authority.ndim < 1:
+            raise TypeError("Regional conditioning output must be a tensor batch.")
+        if len(outputs) == 1:
+            entry_strengths = strengths[0]
+            self._validate_entry(
+                authority,
+                entry_strengths,
+                authority=authority,
+                entry_index=0,
+            )
+            if all(strength == 1.0 for strength in entry_strengths):
+                return authority
+        weighted = torch.zeros_like(authority)
+        counts = torch.ones_like(authority) * 1e-37
+        weight_shape = (int(authority.shape[0]),) + (1,) * (authority.ndim - 1)
+        active_rows = torch.zeros(
+            weight_shape,
+            dtype=torch.bool,
+            device=authority.device,
+        )
+        for entry_index, (output, entry_strengths) in enumerate(
+            zip(outputs, strengths, strict=True)
+        ):
+            self._validate_entry(
+                output,
+                entry_strengths,
+                authority=authority,
+                entry_index=entry_index,
+            )
+            weights = authority.new_tensor(entry_strengths).reshape(weight_shape)
+            weighted += output * weights
+            counts += weights
+            active_rows |= weights.ne(0)
+        denominator = torch.where(active_rows, counts, torch.ones_like(counts))
+        return weighted / denominator
+
+    @staticmethod
+    def _validate_entry(
+        output: object,
+        strengths: object,
+        *,
+        authority: torch.Tensor,
+        entry_index: int,
+    ) -> None:
+        """Require exact output structure and one finite strength per sample."""
+
+        if not isinstance(output, torch.Tensor):
+            raise TypeError(
+                f"Regional conditioning output {entry_index} must be a tensor."
+            )
+        if (
+            output.shape != authority.shape
+            or output.device != authority.device
+            or output.dtype != authority.dtype
+        ):
+            raise ValueError(
+                f"Regional conditioning output {entry_index} must match the first "
+                "output shape, device, and dtype."
+            )
+        if not isinstance(strengths, tuple) or len(strengths) != int(
+            authority.shape[0]
+        ):
+            raise ValueError(
+                f"Regional conditioning output {entry_index} strengths must match "
+                "the output batch."
+            )
+        for strength in strengths:
+            if isinstance(strength, bool) or not isinstance(strength, int | float):
+                raise TypeError("Regional conditioning strengths must be real numbers.")
+            if not math.isfinite(float(strength)):
+                raise ValueError("Regional conditioning strengths must be finite.")
+
+
+REGIONAL_CONDITIONING_OUTPUT_COMBINER = RegionalConditioningOutputCombiner()

simple_syrup/domain/regional_features.py

@@ -0,0 +1,145 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define immutable regional feature requests, capabilities, and admissions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from .regional_model_capabilities import RegionalModelCapabilities
+
+
+class RegionalFeature(StrEnum):
+    """Identify one independently admitted regional sampling feature."""
+
+    FULL_CONTEXT_MASKED_CONDITIONING = "full_context_masked_conditioning"
+    ATTENTION_COUPLING = "attention_coupling"
+    SPATIAL_MODEL_PATCH = "spatial_model_patch"
+    CONTROL = "control"
+    GLIGEN = "gligen"
+    REFERENCE_LATENTS = "reference_latents"
+
+
+@dataclass(frozen=True, slots=True)
+class RegionalFeatureRequest:
+    """Describe the complete immutable regional feature intent for one sample."""
+
+    features: frozenset[RegionalFeature] = frozenset()
+
+    def __post_init__(self) -> None:
+        """Require an immutable set containing only typed regional features."""
+
+        _validate_features(self.features, value_name="Regional feature request")
+
+    def with_feature(self, feature: RegionalFeature) -> RegionalFeatureRequest:
+        """Return a new request containing one additional typed feature."""
+
+        if not isinstance(feature, RegionalFeature):
+            raise TypeError("Requested regional feature must be a RegionalFeature.")
+        return RegionalFeatureRequest(self.features | {feature})
+
+
+@dataclass(frozen=True, slots=True)
+class RegionalSamplerCapabilities:
+    """Describe the complete regional feature set implemented by one sampler."""
+
+    features: frozenset[RegionalFeature]
+
+    def __post_init__(self) -> None:
+        """Require an immutable set containing only typed regional features."""
+
+        _validate_features(self.features, value_name="Regional sampler capabilities")
+
+
+@dataclass(frozen=True, slots=True)
+class RegionalCapabilityAdmission:
+    """Record one complete successful request admission for downstream use."""
+
+    request: RegionalFeatureRequest
+    admitted_features: frozenset[RegionalFeature]
+    model_capabilities: RegionalModelCapabilities | None
+
+    def __post_init__(self) -> None:
+        """Reject partial, untyped, or model-incomplete admission state."""
+
+        if not isinstance(self.request, RegionalFeatureRequest):
+            raise TypeError(
+                "Regional admission request must be RegionalFeatureRequest."
+            )
+        _validate_features(
+            self.admitted_features,
+            value_name="Admitted regional features",
+        )
+        if self.admitted_features != self.request.features:
+            raise ValueError("Regional capability admission cannot be partial.")
+        if self.model_capabilities is not None and not isinstance(
+            self.model_capabilities,
+            RegionalModelCapabilities,
+        ):
+            raise TypeError(
+                "Regional admission model capabilities must be "
+                "RegionalModelCapabilities."
+            )
+        if self.admitted_features & MODEL_DEPENDENT_REGIONAL_FEATURES:
+            if self.model_capabilities is None:
+                raise ValueError(
+                    "Model-dependent regional features require model capabilities."
+                )
+
+    def supports(self, feature: RegionalFeature) -> bool:
+        """Return whether one typed feature was admitted for this sample."""
+
+        if not isinstance(feature, RegionalFeature):
+            raise TypeError("Regional feature query must be a RegionalFeature.")
+        return feature in self.admitted_features
+
+
+MODEL_DEPENDENT_REGIONAL_FEATURES = frozenset(
+    {
+        RegionalFeature.ATTENTION_COUPLING,
+        RegionalFeature.SPATIAL_MODEL_PATCH,
+        RegionalFeature.CONTROL,
+        RegionalFeature.GLIGEN,
+        RegionalFeature.REFERENCE_LATENTS,
+    }
+)
+
+
+def _validate_features(
+    features: frozenset[RegionalFeature],
+    *,
+    value_name: str,
+) -> None:
+    """Validate one immutable typed regional feature set."""
+
+    if not isinstance(features, frozenset):
+        raise TypeError(f"{value_name} must use an immutable frozenset.")
+    if not all(isinstance(feature, RegionalFeature) for feature in features):
+        raise TypeError(f"{value_name} must contain RegionalFeature values.")
+
+
+EMPTY_REGIONAL_FEATURE_REQUEST = RegionalFeatureRequest()
+EMPTY_REGIONAL_CAPABILITY_ADMISSION = RegionalCapabilityAdmission(
+    request=EMPTY_REGIONAL_FEATURE_REQUEST,
+    admitted_features=frozenset(),
+    model_capabilities=None,
+)
+CONTEXTUAL_DIFFUSION_REGIONAL_SAMPLER_CAPABILITIES = RegionalSamplerCapabilities(
+    frozenset(
+        {
+            RegionalFeature.FULL_CONTEXT_MASKED_CONDITIONING,
+            RegionalFeature.ATTENTION_COUPLING,
+        }
+    )
+)
+TILED_DIFFUSION_REGIONAL_SAMPLER_CAPABILITIES = RegionalSamplerCapabilities(
+    frozenset(
+        {
+            RegionalFeature.FULL_CONTEXT_MASKED_CONDITIONING,
+            RegionalFeature.ATTENTION_COUPLING,
+        }
+    )
+)

simple_syrup/domain/regional_inversion_geometry.py

@@ -0,0 +1,57 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Project semantic regional-detailing ownership into each inversion resolution."""
+
+from __future__ import annotations
+
+import math
+
+import torch.nn.functional as functional
+
+from .regional_detailing import LatentBox, LatentRegion
+
+
+def project_inversion_regions(
+    regions: tuple[LatentRegion, ...],
+    *,
+    source_width: int,
+    source_height: int,
+    target_width: int,
+    target_height: int,
+) -> tuple[LatentRegion, ...]:
+    """Preserve region identity and conditioning while scaling masks and bounds."""
+    if min(source_width, source_height, target_width, target_height) < 1:
+        raise ValueError("Regional inversion canvases must have positive dimensions.")
+    if (source_width, source_height) == (target_width, target_height):
+        return regions
+    projected: list[LatentRegion] = []
+    for region in regions:
+        box = region.latent_box
+        if tuple(region.latent_mask.shape) != (source_height, source_width):
+            raise ValueError("Regional inversion mask must match its canonical canvas.")
+        if not (
+            0 <= box.x < box.x + box.width <= source_width
+            and 0 <= box.y < box.y + box.height <= source_height
+        ):
+            raise ValueError("Regional inversion bounds must remain inside the canvas.")
+        left = math.floor(box.x * target_width / source_width)
+        top = math.floor(box.y * target_height / source_height)
+        right = math.ceil((box.x + box.width) * target_width / source_width)
+        bottom = math.ceil((box.y + box.height) * target_height / source_height)
+        mask = functional.interpolate(
+            region.latent_mask[None, None].float(),
+            size=(target_height, target_width),
+            mode="nearest",
+        )[0, 0].to(region.latent_mask)
+        projected.append(
+            LatentRegion(
+                region.index,
+                region.label,
+                LatentBox(left, top, right - left, bottom - top),
+                mask,
+                region.positive,
+            )
+        )
+    return tuple(projected)

simple_syrup/domain/regional_lora_plan.py

@@ -0,0 +1,161 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Own immutable regional model-side LoRA composition plans."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class RegionalLoraBranch(StrEnum):
+    """Identify the conditioning branch that owns one regional adapter use."""
+
+    POSITIVE = "positive"
+    NEGATIVE = "negative"
+
+
+@dataclass(frozen=True)
+class RegionalLoraAdapterIdentity:
+    """Retain the caller-supplied stable identity of one LoRA artifact."""
+
+    value: str
+
+    def __post_init__(self) -> None:
+        """Reject identities that cannot distinguish an adapter."""
+
+        if not isinstance(self.value, str) or not self.value.strip():
+            raise ValueError(
+                "Regional LoRA adapter identity must be a non-empty string."
+            )
+
+
+@dataclass(frozen=True)
+class RegionalLoraScheduleBoundary:
+    """Retain one ordered Comfy HookKeyframe boundary exactly."""
+
+    start_percent: float
+    start_sigma: float
+    strength_multiplier: float
+    guarantee_steps: int
+
+    def __post_init__(self) -> None:
+        """Validate one finite normalized schedule boundary."""
+
+        _require_finite_float(self.start_percent, name="start_percent")
+        if not 0.0 <= self.start_percent <= 1.0:
+            raise ValueError("Regional LoRA schedule start_percent must be in [0, 1].")
+        _require_finite_float(self.start_sigma, name="start_sigma")
+        if self.start_sigma < 0.0:
+            raise ValueError("Regional LoRA schedule start_sigma must be non-negative.")
+        _require_finite_float(
+            self.strength_multiplier,
+            name="strength_multiplier",
+        )
+        if isinstance(self.guarantee_steps, bool) or not isinstance(
+            self.guarantee_steps, int
+        ):
+            raise TypeError("Regional LoRA guarantee_steps must be an integer.")
+        if self.guarantee_steps < 0:
+            raise ValueError("Regional LoRA guarantee_steps must be non-negative.")
+
+
+@dataclass(frozen=True)
+class RegionalLoraAdapterPlan:
+    """Describe one ordered regional use of a model-side LoRA adapter."""
+
+    adapter_identity: RegionalLoraAdapterIdentity
+    composition_index: int
+    region_index: int
+    branch: RegionalLoraBranch
+    model_strength: float
+    schedule: tuple[RegionalLoraScheduleBoundary, ...]
+
+    def __post_init__(self) -> None:
+        """Validate adapter ownership, strength, and ordered schedule."""
+
+        if not isinstance(self.adapter_identity, RegionalLoraAdapterIdentity):
+            raise TypeError("Regional LoRA adapter_identity has an invalid type.")
+        _require_non_negative_index(self.composition_index, name="composition_index")
+        _require_non_negative_index(self.region_index, name="region_index")
+        if not isinstance(self.branch, RegionalLoraBranch):
+            raise TypeError("Regional LoRA branch has an invalid type.")
+        _require_finite_float(self.model_strength, name="model_strength")
+        if not isinstance(self.schedule, tuple) or not self.schedule:
+            raise ValueError(
+                "Regional LoRA schedule must contain at least one boundary."
+            )
+        if any(
+            not isinstance(boundary, RegionalLoraScheduleBoundary)
+            for boundary in self.schedule
+        ):
+            raise TypeError("Regional LoRA schedule contains an invalid boundary.")
+        starts = tuple(boundary.start_percent for boundary in self.schedule)
+        if starts != tuple(sorted(starts)):
+            raise ValueError("Regional LoRA schedule boundaries must be ordered.")
+        sigmas = tuple(boundary.start_sigma for boundary in self.schedule)
+        if sigmas != tuple(sorted(sigmas, reverse=True)):
+            raise ValueError(
+                "Regional LoRA converted schedule boundaries must be descending."
+            )
+
+    @property
+    def is_time_invariant(self) -> bool:
+        """Report whether every keyframe retains one effective multiplier."""
+
+        first_multiplier = self.schedule[0].strength_multiplier
+        return all(
+            boundary.strength_multiplier == first_multiplier
+            for boundary in self.schedule[1:]
+        )
+
+
+@dataclass(frozen=True)
+class RegionalLoraPlan:
+    """Store all adapter uses in authoritative global composition order."""
+
+    adapters: tuple[RegionalLoraAdapterPlan, ...]
+
+    def __post_init__(self) -> None:
+        """Require immutable entries with contiguous composition indices."""
+
+        if not isinstance(self.adapters, tuple):
+            raise TypeError("Regional LoRA plan adapters must be a tuple.")
+        if any(
+            not isinstance(adapter, RegionalLoraAdapterPlan)
+            for adapter in self.adapters
+        ):
+            raise TypeError("Regional LoRA plan contains an invalid adapter entry.")
+        observed_indices = tuple(adapter.composition_index for adapter in self.adapters)
+        if observed_indices != tuple(range(len(self.adapters))):
+            raise ValueError(
+                "Regional LoRA composition indices must be contiguous and ordered."
+            )
+
+    @property
+    def is_time_invariant(self) -> bool:
+        """Report whether every regional adapter retains one effective strength."""
+
+        return all(adapter.is_time_invariant for adapter in self.adapters)
+
+
+def _require_finite_float(value: object, *, name: str) -> None:
+    """Require one exact finite floating-point value."""
+
+    if not isinstance(value, float) or not math.isfinite(value):
+        raise TypeError(f"Regional LoRA {name} must be a finite float.")
+
+
+def _require_non_negative_index(value: object, *, name: str) -> None:
+    """Require one non-negative integer index."""
+
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise TypeError(f"Regional LoRA {name} must be an integer.")
+    if value < 0:
+        raise ValueError(f"Regional LoRA {name} must be non-negative.")
+
+
+EMPTY_REGIONAL_LORA_PLAN = RegionalLoraPlan(adapters=())

simple_syrup/domain/regional_mask_bank.py

@@ -0,0 +1,75 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define the immutable full-canvas authority for regional masks."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+
+
+@dataclass(frozen=True, slots=True)
+class RegionalMaskBank:
+    """Hold separate planning and conditioning masks on one latent canvas."""
+
+    planning_masks: torch.Tensor
+    conditioning_masks: torch.Tensor
+    canvas_width: int
+    canvas_height: int
+
+    def __post_init__(self) -> None:
+        """Reject malformed, divergent, or aliased canonical mask tensors."""
+
+        if self.canvas_width < 1 or self.canvas_height < 1:
+            raise ValueError("Regional mask canvas dimensions must be positive.")
+        self._validate_mask_batch(self.planning_masks, name="Planning")
+        self._validate_mask_batch(self.conditioning_masks, name="Conditioning")
+        if self.planning_masks.shape != self.conditioning_masks.shape:
+            raise ValueError(
+                "Regional planning and conditioning mask shapes must match."
+            )
+        if self.planning_masks.dtype != self.conditioning_masks.dtype:
+            raise ValueError(
+                "Regional planning and conditioning mask dtypes must match."
+            )
+        if self.planning_masks.device != self.conditioning_masks.device:
+            raise ValueError(
+                "Regional planning and conditioning mask devices must match."
+            )
+        if (
+            self.planning_masks.untyped_storage().data_ptr()
+            == self.conditioning_masks.untyped_storage().data_ptr()
+        ):
+            raise ValueError(
+                "Regional planning and conditioning masks must not share storage."
+            )
+
+    @property
+    def region_count(self) -> int:
+        """Return the number of ordered authored regions."""
+
+        return int(self.planning_masks.shape[0])
+
+    def _validate_mask_batch(self, masks: torch.Tensor, *, name: str) -> None:
+        """Validate one normalized floating-point BHW mask batch."""
+
+        if not isinstance(masks, torch.Tensor):
+            raise TypeError(f"{name} regional masks must be a torch.Tensor.")
+        if masks.ndim != 3:
+            raise ValueError(f"{name} regional masks must use BHW layout.")
+        if int(masks.shape[0]) < 1:
+            raise ValueError(f"{name} regional masks require at least one region.")
+        if tuple(masks.shape[1:]) != (self.canvas_height, self.canvas_width):
+            raise ValueError(
+                f"{name} regional masks must match the full latent canvas "
+                f"{self.canvas_width}x{self.canvas_height}."
+            )
+        if not masks.is_floating_point():
+            raise TypeError(f"{name} regional masks must use a floating-point dtype.")
+        if not bool(torch.isfinite(masks).all()):
+            raise ValueError(f"{name} regional masks must contain only finite values.")
+        if not bool(((masks >= 0.0) & (masks <= 1.0)).all()):
+            raise ValueError(f"{name} regional masks must stay within [0, 1].")

simple_syrup/domain/regional_model_capabilities.py

@@ -0,0 +1,173 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define immutable capability values for regional attention backends."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class RegionalModelFamily(StrEnum):
+    """Identify a defensively admitted regional model family."""
+
+    ANIMA = "anima"
+    STANDARD_UNET = "standard_unet"
+
+
+class RegionalAttentionBackend(StrEnum):
+    """Identify the model-specific attention patch backend."""
+
+    ANIMA_OBJECT_PATCH = "anima_object_patch"
+    UNET_ATTN2_PATCH = "unet_attn2_patch"
+
+
+class RegionalAttentionTopology(StrEnum):
+    """Identify the image/context token roles owned by an attention backend."""
+
+    SEPARATE_IMAGE_AND_CONTEXT = "separate_image_and_context"
+    SINGLETON_FRAME_SPATIOTEMPORAL = "singleton_frame_spatiotemporal"
+
+
+class RegionalLatentLayout(StrEnum):
+    """Identify the latent rank and temporal layout admitted by a backend."""
+
+    ANIMA_SINGLE_FRAME_BCTHW = "anima_single_frame_bcthw"
+    STANDARD_IMAGE_BCHW = "standard_image_bchw"
+
+
+class RegionalSpatialPatchSupport(StrEnum):
+    """Report whether one backend can consume canonical spatial views."""
+
+    FULL_AND_SPATIAL_VIEWS = "full_and_spatial_views"
+
+
+class RegionalControlGligenPolicy(StrEnum):
+    """Report control and GLIGEN admission for attention coupling."""
+
+    REJECT = "reject"
+
+
+class RegionalReferenceLatentPolicy(StrEnum):
+    """Report reference-latent admission for attention coupling."""
+
+    REJECT = "reject"
+
+
+class RegionalPatchConflict(StrEnum):
+    """Identify a patch surface that must be collision-free before mutation."""
+
+    DIFFUSION_MODEL_WRAPPER = "diffusion_model_wrapper"
+    CROSS_ATTENTION_OBJECT_PATCH = "cross_attention_object_patch"
+    ATTN2_INPUT_PATCH = "attn2_input_patch"
+    ATTN2_OUTPUT_PATCH = "attn2_output_patch"
+
+
+@dataclass(frozen=True, slots=True)
+class RegionalModelCapabilities:
+    """Describe one admitted backend and every relevant compatibility policy."""
+
+    model_family: RegionalModelFamily
+    attention_backend: RegionalAttentionBackend
+    attention_topology: RegionalAttentionTopology
+    latent_layout: RegionalLatentLayout
+    spatial_patch_support: RegionalSpatialPatchSupport
+    control_gligen_policy: RegionalControlGligenPolicy
+    reference_latent_policy: RegionalReferenceLatentPolicy
+    known_patch_conflicts: tuple[RegionalPatchConflict, ...]
+
+    def __post_init__(self) -> None:
+        """Reject mutable, duplicate, or internally inconsistent capabilities."""
+
+        enum_fields = (
+            ("model family", self.model_family, RegionalModelFamily),
+            ("attention backend", self.attention_backend, RegionalAttentionBackend),
+            (
+                "attention topology",
+                self.attention_topology,
+                RegionalAttentionTopology,
+            ),
+            ("latent layout", self.latent_layout, RegionalLatentLayout),
+            (
+                "spatial patch support",
+                self.spatial_patch_support,
+                RegionalSpatialPatchSupport,
+            ),
+            (
+                "control/GLIGEN policy",
+                self.control_gligen_policy,
+                RegionalControlGligenPolicy,
+            ),
+            (
+                "reference-latent policy",
+                self.reference_latent_policy,
+                RegionalReferenceLatentPolicy,
+            ),
+        )
+        for name, value, enum_type in enum_fields:
+            if not isinstance(value, enum_type):
+                raise TypeError(
+                    f"Regional {name} must be a {enum_type.__name__} value."
+                )
+        if not isinstance(self.known_patch_conflicts, tuple):
+            raise TypeError(
+                "Known regional patch conflicts must be an immutable tuple."
+            )
+        if not self.known_patch_conflicts:
+            raise ValueError("Regional capabilities require known patch conflicts.")
+        if not all(
+            isinstance(conflict, RegionalPatchConflict)
+            for conflict in self.known_patch_conflicts
+        ):
+            raise TypeError(
+                "Known regional patch conflicts must contain "
+                "RegionalPatchConflict values."
+            )
+        if len(set(self.known_patch_conflicts)) != len(self.known_patch_conflicts):
+            raise ValueError(
+                "Known regional patch conflicts must be unique and ordered."
+            )
+        self._validate_family_contract()
+
+    def _validate_family_contract(self) -> None:
+        """Require the exact backend, layout, and conflict surface for a family."""
+
+        expected: tuple[
+            RegionalAttentionBackend,
+            RegionalAttentionTopology,
+            RegionalLatentLayout,
+            tuple[RegionalPatchConflict, ...],
+        ]
+        if self.model_family is RegionalModelFamily.ANIMA:
+            expected = (
+                RegionalAttentionBackend.ANIMA_OBJECT_PATCH,
+                RegionalAttentionTopology.SINGLETON_FRAME_SPATIOTEMPORAL,
+                RegionalLatentLayout.ANIMA_SINGLE_FRAME_BCTHW,
+                (
+                    RegionalPatchConflict.DIFFUSION_MODEL_WRAPPER,
+                    RegionalPatchConflict.CROSS_ATTENTION_OBJECT_PATCH,
+                    RegionalPatchConflict.ATTN2_INPUT_PATCH,
+                    RegionalPatchConflict.ATTN2_OUTPUT_PATCH,
+                ),
+            )
+        else:
+            expected = (
+                RegionalAttentionBackend.UNET_ATTN2_PATCH,
+                RegionalAttentionTopology.SEPARATE_IMAGE_AND_CONTEXT,
+                RegionalLatentLayout.STANDARD_IMAGE_BCHW,
+                (
+                    RegionalPatchConflict.ATTN2_INPUT_PATCH,
+                    RegionalPatchConflict.ATTN2_OUTPUT_PATCH,
+                ),
+            )
+        if (
+            self.attention_backend,
+            self.attention_topology,
+            self.latent_layout,
+            self.known_patch_conflicts,
+        ) != expected:
+            raise ValueError(
+                "Regional model capabilities do not match the model-family contract."
+            )

simple_syrup/domain/regional_tiled_diffusion.py

@@ -0,0 +1,108 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Constrain semantic tiled diffusion by authored regional composition masks."""
+
+from __future__ import annotations
+
+import torch
+
+from .segs import coerce_segs
+from .segs_tiled_diffusion import segs_ownership_masks, validate_segs_aspect_ratio
+from .semantic_tiled_diffusion import build_semantic_tiled_diffusion_plan
+from .tiled_diffusion import TiledDiffusionPlan
+
+REGIONAL_PLANNING_THRESHOLD = 0.5
+
+
+def build_region_constrained_tiled_diffusion_plan(
+    *,
+    region_masks: torch.Tensor,
+    segs: object | None,
+    latent_width: int,
+    latent_height: int,
+    tile_width: int,
+    tile_height: int,
+    overlap: int,
+    tile_batch_size: int,
+    segs_canvas: tuple[int, int] | None = None,
+) -> TiledDiffusionPlan:
+    """Build tiles split wherever regional composition or optional SEGS change."""
+
+    region_ownership = regional_composition_ownership_masks(
+        region_masks,
+        latent_height=latent_height,
+        latent_width=latent_width,
+    )
+    ownership_masks = region_ownership
+    if segs is not None:
+        native_segs = coerce_segs(segs)
+        canvas_height, canvas_width = segs_canvas or (latent_height, latent_width)
+        validate_segs_aspect_ratio(native_segs, canvas_height, canvas_width)
+        semantic_ownership = segs_ownership_masks(
+            native_segs,
+            latent_height=latent_height,
+            latent_width=latent_width,
+        )
+        ownership_masks = _intersect_partitions(
+            region_ownership,
+            semantic_ownership,
+        )
+    return build_semantic_tiled_diffusion_plan(
+        ownership_masks=ownership_masks,
+        latent_width=latent_width,
+        latent_height=latent_height,
+        tile_width=tile_width,
+        tile_height=tile_height,
+        overlap=overlap,
+        tile_batch_size=tile_batch_size,
+        merge_across_masks=False,
+    )
+
+
+def regional_composition_ownership_masks(
+    region_masks: torch.Tensor,
+    *,
+    latent_height: int,
+    latent_width: int,
+) -> tuple[torch.Tensor, ...]:
+    """Partition the canvas by every distinct active regional-mask combination."""
+
+    if region_masks.ndim != 3:
+        raise ValueError("Regional tile planning requires a BHW mask batch.")
+    if tuple(region_masks.shape[1:]) != (latent_height, latent_width):
+        raise ValueError(
+            "Regional tile planning masks must match latent shape "
+            f"{latent_height}x{latent_width}."
+        )
+    membership = (region_masks.detach().cpu() >= REGIONAL_PLANNING_THRESHOLD).permute(
+        1, 2, 0
+    )
+    flattened = membership.reshape(latent_height * latent_width, -1)
+    signatures, inverse = torch.unique(
+        flattened,
+        dim=0,
+        sorted=True,
+        return_inverse=True,
+    )
+    del signatures
+    labels = inverse.reshape(latent_height, latent_width)
+    return tuple(labels == index for index in range(int(labels.max().item()) + 1))
+
+
+def _intersect_partitions(
+    first: tuple[torch.Tensor, ...],
+    second: tuple[torch.Tensor, ...],
+) -> tuple[torch.Tensor, ...]:
+    """Return non-empty intersections of two complete ownership partitions."""
+
+    intersections = tuple(
+        intersection
+        for first_mask in first
+        for second_mask in second
+        if bool((intersection := torch.logical_and(first_mask, second_mask)).any())
+    )
+    if not intersections:
+        raise ValueError("Regional and SEGS ownership produced no tile coverage.")
+    return intersections

simple_syrup/domain/resolved_regional_lora.py

@@ -0,0 +1,347 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define model-neutral resolved regional ordinary-LoRA operation contracts."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from enum import StrEnum
+
+from .regional_lora_plan import RegionalLoraAdapterPlan
+
+
+class ResolvedLoraOperationClass(StrEnum):
+    """Classify normalized low-rank tensor organization before module binding."""
+
+    MATRIX_PAIR = "matrix_pair"
+    CONVOLUTION_1D = "convolution_1d"
+    CONVOLUTION_2D = "convolution_2d"
+    CONVOLUTION_3D = "convolution_3d"
+    UNSUPPORTED = "unsupported"
+
+
+class RegionalLoraGeometryClass(StrEnum):
+    """Declare the activation geometry an execution contract requires."""
+
+    TARGET_OPERATION = "target_operation"
+    DIRECT_CONVOLUTION_1D = "direct_convolution_1d"
+    DIRECT_CONVOLUTION_2D = "direct_convolution_2d"
+    DIRECT_CONVOLUTION_3D = "direct_convolution_3d"
+    UNSUPPORTED = "unsupported"
+
+
+class RegionalLoraExecutionContract(StrEnum):
+    """Declare exact rank-activation execution or explicit rejection."""
+
+    MATRIX_OR_RESHAPED_CONVOLUTION = "matrix_or_reshaped_convolution"
+    DIRECT_CONVOLUTION = "direct_convolution"
+    UNSUPPORTED = "unsupported"
+
+
+@dataclass(frozen=True, slots=True)
+class RegionalLoraTensorShape:
+    """Retain one immutable positive tensor shape without tensor ownership."""
+
+    dimensions: tuple[int, ...]
+
+    def __post_init__(self) -> None:
+        """Require a nonempty tuple of strictly positive integer dimensions."""
+
+        if not isinstance(self.dimensions, tuple) or not self.dimensions:
+            raise ValueError("Regional LoRA tensor shape must be a nonempty tuple.")
+        if any(
+            isinstance(dimension, bool)
+            or not isinstance(dimension, int)
+            or dimension <= 0
+            for dimension in self.dimensions
+        ):
+            raise ValueError(
+                "Regional LoRA tensor shape dimensions must be positive integers."
+            )
+
+    @property
+    def rank(self) -> int:
+        """Return the tensor dimensionality."""
+
+        return len(self.dimensions)
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedRegionalLoraTarget:
+    """Retain one model-relative parameter path and optional Comfy tensor slice."""
+
+    model_target: str
+    parameter_name: str
+    offset: tuple[int, ...] | None
+
+    def __post_init__(self) -> None:
+        """Require an explicit module target, parameter, and valid optional slice."""
+
+        if not isinstance(self.model_target, str) or not self.model_target.strip():
+            raise ValueError("Resolved regional LoRA model target must be nonempty.")
+        if not isinstance(self.parameter_name, str) or not self.parameter_name.strip():
+            raise ValueError("Resolved regional LoRA parameter name must be nonempty.")
+        if self.offset is not None and (
+            not isinstance(self.offset, tuple)
+            or not self.offset
+            or any(
+                isinstance(part, bool) or not isinstance(part, int) or part < 0
+                for part in self.offset
+            )
+        ):
+            raise ValueError(
+                "Resolved regional LoRA target offset must contain "
+                "non-negative integers."
+            )
+
+    @property
+    def parameter_path(self) -> str:
+        """Return the complete model-relative parameter path."""
+
+        return f"{self.model_target}.{self.parameter_name}"
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedRegionalLoraOperation:
+    """Describe one supported operation or one explicit target rejection."""
+
+    adapter: RegionalLoraAdapterPlan
+    target_index: int
+    target: ResolvedRegionalLoraTarget
+    normalized_operation_type: str
+    operation_class: ResolvedLoraOperationClass
+    down_shape: RegionalLoraTensorShape | None
+    up_shape: RegionalLoraTensorShape | None
+    middle_shape: RegionalLoraTensorShape | None
+    reshape_shape: RegionalLoraTensorShape | None
+    rank: int | None
+    intrinsic_scale: float | None
+    required_geometry: RegionalLoraGeometryClass
+    execution_contract: RegionalLoraExecutionContract
+    rejection_reason: str | None
+
+    def __post_init__(self) -> None:
+        """Reject mutable, incomplete, or mathematically inconsistent metadata."""
+
+        if not isinstance(self.adapter, RegionalLoraAdapterPlan):
+            raise TypeError("Resolved regional LoRA operation requires an adapter.")
+        _require_non_negative_index(self.target_index, name="target_index")
+        if not isinstance(self.target, ResolvedRegionalLoraTarget):
+            raise TypeError("Resolved regional LoRA operation requires a target.")
+        if (
+            not isinstance(self.normalized_operation_type, str)
+            or not self.normalized_operation_type.strip()
+        ):
+            raise ValueError(
+                "Normalized regional LoRA operation type must be nonempty."
+            )
+        if not isinstance(self.operation_class, ResolvedLoraOperationClass):
+            raise TypeError("Resolved regional LoRA operation class is invalid.")
+        if not isinstance(self.required_geometry, RegionalLoraGeometryClass):
+            raise TypeError("Resolved regional LoRA geometry class is invalid.")
+        if not isinstance(self.execution_contract, RegionalLoraExecutionContract):
+            raise TypeError("Resolved regional LoRA execution contract is invalid.")
+        if self.execution_contract is RegionalLoraExecutionContract.UNSUPPORTED:
+            self._validate_rejection()
+            return
+        self._validate_supported()
+
+    def _validate_rejection(self) -> None:
+        """Require one reason and no misleading supported-operation metadata."""
+
+        if self.operation_class is not ResolvedLoraOperationClass.UNSUPPORTED:
+            raise ValueError(
+                "Rejected regional LoRA operation class must be unsupported."
+            )
+        if self.required_geometry is not RegionalLoraGeometryClass.UNSUPPORTED:
+            raise ValueError("Rejected regional LoRA geometry must be unsupported.")
+        if (
+            not isinstance(self.rejection_reason, str)
+            or not self.rejection_reason.strip()
+        ):
+            raise ValueError("Rejected regional LoRA operation requires a reason.")
+        if any(
+            value is not None
+            for value in (
+                self.down_shape,
+                self.up_shape,
+                self.middle_shape,
+                self.reshape_shape,
+                self.rank,
+                self.intrinsic_scale,
+            )
+        ):
+            raise ValueError(
+                "Rejected regional LoRA operation cannot claim executable metadata."
+            )
+
+    def _validate_supported(self) -> None:
+        """Require complete shape, scale, geometry, and execution consistency."""
+
+        if self.operation_class is ResolvedLoraOperationClass.UNSUPPORTED:
+            raise ValueError("Supported regional LoRA operation cannot be unsupported.")
+        if self.required_geometry is RegionalLoraGeometryClass.UNSUPPORTED:
+            raise ValueError("Supported regional LoRA geometry cannot be unsupported.")
+        if self.rejection_reason is not None:
+            raise ValueError(
+                "Supported regional LoRA operation cannot have a rejection."
+            )
+        if self.down_shape is None or self.up_shape is None:
+            raise ValueError(
+                "Supported regional LoRA operation requires down/up shapes."
+            )
+        if self.down_shape.rank < 2 or self.up_shape.rank < 2:
+            raise ValueError(
+                "Regional LoRA down/up shapes need at least two dimensions."
+            )
+        if (
+            isinstance(self.rank, bool)
+            or not isinstance(self.rank, int)
+            or self.rank <= 0
+        ):
+            raise ValueError("Supported regional LoRA rank must be a positive integer.")
+        if not isinstance(self.intrinsic_scale, float) or not math.isfinite(
+            self.intrinsic_scale
+        ):
+            raise ValueError("Regional LoRA intrinsic scale must be finite.")
+        if self.down_shape.dimensions[0] != self.rank:
+            raise ValueError("Regional LoRA down shape must begin with its rank.")
+        if (
+            len(self.up_shape.dimensions) < 2
+            or self.up_shape.dimensions[1] != self.rank
+        ):
+            raise ValueError(
+                "Regional LoRA up shape must contain its rank at index one."
+            )
+        if self.middle_shape is not None:
+            if self.middle_shape.rank < 2:
+                raise ValueError(
+                    "Regional LoRA middle shape needs at least two dimensions."
+                )
+            if (
+                self.middle_shape.dimensions[0] != self.rank
+                or self.middle_shape.dimensions[1] != self.rank
+            ):
+                raise ValueError(
+                    "Regional LoRA middle shape must preserve rank channels."
+                )
+        self._validate_operation_shape_contract()
+
+    def _validate_operation_shape_contract(self) -> None:
+        """Match operation, tensor dimensionality, geometry, and execution policy."""
+
+        if self.operation_class is ResolvedLoraOperationClass.MATRIX_PAIR:
+            if self.down_shape is None or self.up_shape is None:
+                raise AssertionError(
+                    "Supported shape validation requires down/up shapes."
+                )
+            if self.down_shape.rank != 2 or self.up_shape.rank != 2:
+                raise ValueError("Matrix-pair regional LoRA tensors must be rank two.")
+            if self.middle_shape is not None:
+                raise ValueError(
+                    "Matrix-pair regional LoRA cannot contain middle weights."
+                )
+            if self.required_geometry is not RegionalLoraGeometryClass.TARGET_OPERATION:
+                raise ValueError("Matrix-pair regional LoRA requires target geometry.")
+            if (
+                self.execution_contract
+                is not RegionalLoraExecutionContract.MATRIX_OR_RESHAPED_CONVOLUTION
+            ):
+                raise ValueError("Matrix-pair regional LoRA execution is inconsistent.")
+            return
+        spatial_rank = {
+            ResolvedLoraOperationClass.CONVOLUTION_1D: 3,
+            ResolvedLoraOperationClass.CONVOLUTION_2D: 4,
+            ResolvedLoraOperationClass.CONVOLUTION_3D: 5,
+        }[self.operation_class]
+        expected_geometry = {
+            3: RegionalLoraGeometryClass.DIRECT_CONVOLUTION_1D,
+            4: RegionalLoraGeometryClass.DIRECT_CONVOLUTION_2D,
+            5: RegionalLoraGeometryClass.DIRECT_CONVOLUTION_3D,
+        }[spatial_rank]
+        shapes = tuple(
+            shape
+            for shape in (self.down_shape, self.up_shape, self.middle_shape)
+            if shape is not None
+        )
+        if any(shape.rank not in (2, spatial_rank) for shape in shapes):
+            raise ValueError("Convolutional regional LoRA tensor rank is inconsistent.")
+        if not any(shape.rank == spatial_rank for shape in shapes):
+            raise ValueError("Convolutional regional LoRA needs one spatial tensor.")
+        if self.required_geometry is not expected_geometry:
+            raise ValueError("Convolutional regional LoRA geometry is inconsistent.")
+        if (
+            self.execution_contract
+            is not RegionalLoraExecutionContract.DIRECT_CONVOLUTION
+        ):
+            raise ValueError("Convolutional regional LoRA execution is inconsistent.")
+
+    @property
+    def authored_strength(self) -> float:
+        """Return the authored model strength from the authoritative plan owner."""
+
+        return self.adapter.model_strength
+
+    @property
+    def supported(self) -> bool:
+        """Report whether this target has an executable ordinary-LoRA contract."""
+
+        return self.execution_contract is not RegionalLoraExecutionContract.UNSUPPORTED
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedRegionalLoraOperationSet:
+    """Retain canonical adapter/target order across supported and rejected entries."""
+
+    entries: tuple[ResolvedRegionalLoraOperation, ...]
+
+    def __post_init__(self) -> None:
+        """Require immutable entries in contiguous per-adapter target order."""
+
+        if not isinstance(self.entries, tuple):
+            raise TypeError("Resolved regional LoRA entries must be a tuple.")
+        if any(
+            not isinstance(entry, ResolvedRegionalLoraOperation)
+            for entry in self.entries
+        ):
+            raise TypeError("Resolved regional LoRA set contains an invalid entry.")
+        observed = tuple(
+            (entry.adapter.composition_index, entry.target_index)
+            for entry in self.entries
+        )
+        if observed != tuple(sorted(observed)):
+            raise ValueError(
+                "Resolved regional LoRA entries must retain declared order."
+            )
+        indices_by_adapter: dict[int, list[int]] = {}
+        for composition_index, target_index in observed:
+            indices_by_adapter.setdefault(composition_index, []).append(target_index)
+        if any(
+            target_indices != list(range(len(target_indices)))
+            for target_indices in indices_by_adapter.values()
+        ):
+            raise ValueError(
+                "Resolved regional LoRA target indices must be contiguous per adapter."
+            )
+
+    @property
+    def supported(self) -> tuple[ResolvedRegionalLoraOperation, ...]:
+        """Return supported entries without changing canonical relative order."""
+
+        return tuple(entry for entry in self.entries if entry.supported)
+
+    @property
+    def rejected(self) -> tuple[ResolvedRegionalLoraOperation, ...]:
+        """Return rejected entries without changing canonical relative order."""
+
+        return tuple(entry for entry in self.entries if not entry.supported)
+
+
+def _require_non_negative_index(value: object, *, name: str) -> None:
+    """Require one non-negative non-boolean integer index."""
+
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise ValueError(f"Resolved regional LoRA {name} must be non-negative.")

simple_syrup/domain/sampler_options.py

@@ -0,0 +1,162 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Assemble immutable, order-independent sampler capability configuration."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, replace
+from typing import TypeAlias
+
+from .noise_inversion import NoiseInversionOptions
+from .regional_prompting import validate_regional_prompt_weight
+from .tiled_diffusion import validate_tiled_diffusion_mode
+
+
+@dataclass(frozen=True, slots=True)
+class TilingOptions:
+    """Own the single local tile layout and blending configuration."""
+
+    diffusion_mode: str = "multidiffusion"
+    width: int = 128
+    height: int = 128
+    overlap: int = 32
+    batch_size: int = 4
+    differential_diffusion: bool = False
+
+    def __post_init__(self) -> None:
+        """Reject tile settings that cannot form a bounded prediction plan."""
+        validate_tiled_diffusion_mode(self.diffusion_mode)
+        for name, value in (("width", self.width), ("height", self.height)):
+            if type(value) is not int or not 16 <= value <= 512:
+                raise ValueError(
+                    f"Tile {name} must be between 16 and 512 latent pixels."
+                )
+        if type(self.overlap) is not int or not 0 <= self.overlap < min(
+            self.width, self.height
+        ):
+            raise ValueError(
+                "Tile overlap must be nonnegative and smaller than both dimensions."
+            )
+        if type(self.batch_size) is not int or self.batch_size < 1:
+            raise ValueError("Tile batch size must be a positive integer.")
+        if type(self.differential_diffusion) is not bool:
+            raise TypeError("Differential diffusion must be a boolean.")
+
+
+@dataclass(frozen=True, slots=True)
+class ContextualDiffusionOptions:
+    """Own global context and square local sampling geometry independently of tiling."""
+
+    context_size: int = 96
+    global_weight: float = 1.0
+    global_steps: int = 1
+    global_decay: float = 0.5
+    diffusion_mode: str = "multidiffusion"
+    overlap: int = 32
+    batch_size: int = 4
+    differential_diffusion: bool = False
+
+    def __post_init__(self) -> None:
+        """Reject invalid global schedules and square local sampling settings."""
+        if type(self.context_size) is not int or not 16 <= self.context_size <= 512:
+            raise ValueError("Context size must be between 16 and 512 latent pixels.")
+        if not math.isfinite(self.global_weight) or not 0 <= self.global_weight <= 2:
+            raise ValueError("Global context weight must be between 0 and 2.")
+        if type(self.global_steps) is not int or self.global_steps < 0:
+            raise ValueError("Global context steps must be a nonnegative integer.")
+        if not math.isfinite(self.global_decay) or not 0 <= self.global_decay <= 1:
+            raise ValueError("Global context decay must be between 0 and 1.")
+        self.local_tiling()
+
+    def local_tiling(self) -> TilingOptions:
+        """Use context size for both dimensions of the sole local sampling plan."""
+        return TilingOptions(
+            diffusion_mode=self.diffusion_mode,
+            width=self.context_size,
+            height=self.context_size,
+            overlap=self.overlap,
+            batch_size=self.batch_size,
+            differential_diffusion=self.differential_diffusion,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class AttentionCouplingOptions:
+    """Configure regional attention strength without binding masks or a model."""
+
+    regional_prompt_weight: float = 1.0
+    region_mask_feather: int = 0
+
+    def __post_init__(self) -> None:
+        """Require valid regional attention strengths and feathering controls."""
+        validate_regional_prompt_weight(self.regional_prompt_weight)
+        if type(self.region_mask_feather) is not int or self.region_mask_feather < 0:
+            raise ValueError("Region mask feather must be a nonnegative integer.")
+
+
+SamplerCapability: TypeAlias = (
+    TilingOptions
+    | ContextualDiffusionOptions
+    | NoiseInversionOptions
+    | AttentionCouplingOptions
+)
+
+
+@dataclass(frozen=True, slots=True)
+class SamplerOptions:
+    """Own one immutable setting per capability, independent of graph order."""
+
+    tiling: TilingOptions | None = None
+    contextual_diffusion: ContextualDiffusionOptions | None = None
+    noise_inversion: NoiseInversionOptions | None = None
+    attention_coupling: AttentionCouplingOptions | None = None
+
+    def __post_init__(self) -> None:
+        """Reject malformed connection payloads at the typed configuration boundary."""
+        for name, expected in (
+            ("tiling", TilingOptions),
+            ("contextual_diffusion", ContextualDiffusionOptions),
+            ("noise_inversion", NoiseInversionOptions),
+            ("attention_coupling", AttentionCouplingOptions),
+        ):
+            value = getattr(self, name)
+            if value is not None and not isinstance(value, expected):
+                raise TypeError(f"Sampler option {name} must be {expected.__name__}.")
+
+    def with_capability(self, capability: SamplerCapability) -> SamplerOptions:
+        """Return a fresh configuration or reject an ambiguous duplicate feature."""
+        names: dict[type[object], str] = {
+            TilingOptions: "tiling",
+            ContextualDiffusionOptions: "contextual_diffusion",
+            NoiseInversionOptions: "noise_inversion",
+            AttentionCouplingOptions: "attention_coupling",
+        }
+        name = names.get(type(capability))
+        if name is None:
+            raise TypeError("Unsupported sampler capability configuration.")
+        if getattr(self, name) is not None:
+            raise ValueError(
+                f"Duplicate sampler capability: {name}. Bypass or remove one node."
+            )
+        if isinstance(capability, TilingOptions):
+            return replace(self, tiling=capability)
+        if isinstance(capability, ContextualDiffusionOptions):
+            return replace(self, contextual_diffusion=capability)
+        if isinstance(capability, NoiseInversionOptions):
+            return replace(self, noise_inversion=capability)
+        return replace(self, attention_coupling=capability)
+
+
+def append_sampler_capability(
+    options: SamplerOptions | None, capability: SamplerCapability | None
+) -> SamplerOptions:
+    """Append a capability or pass through a disabled contribution after validation."""
+    if options is not None and not isinstance(options, SamplerOptions):
+        raise TypeError(
+            "Options input must be a SimpleSyrup sampler options connection."
+        )
+    current = options if options is not None else SamplerOptions()
+    return current if capability is None else current.with_capability(capability)

simple_syrup/domain/seed_variation.py

@@ -0,0 +1,54 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define validated seed-variation sampling settings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import isfinite
+
+MIN_SEED = 0
+MAX_SEED = 0xFFFFFFFFFFFFFFFF
+MIN_VARIATION_STRENGTH = 0.0
+MAX_VARIATION_STRENGTH = 1.0
+
+
+@dataclass(frozen=True, slots=True)
+class SeedVariationSettings:
+    """Hold one deterministic initial-noise interpolation request."""
+
+    variation_seed: int
+    strength: float
+
+    def __post_init__(self) -> None:
+        """Reject settings outside ComfyUI's public seed and strength ranges."""
+
+        if isinstance(self.variation_seed, bool) or not isinstance(
+            self.variation_seed,
+            int,
+        ):
+            raise TypeError("Variation seed must be an integer.")
+        if not MIN_SEED <= self.variation_seed <= MAX_SEED:
+            raise ValueError(
+                f"Variation seed must be between {MIN_SEED} and {MAX_SEED}."
+            )
+        if isinstance(self.strength, bool) or not isinstance(
+            self.strength,
+            (int, float),
+        ):
+            raise TypeError("Variation strength must be a number.")
+        normalized_strength = float(self.strength)
+        if not isfinite(normalized_strength):
+            raise ValueError("Variation strength must be finite.")
+        if (
+            not MIN_VARIATION_STRENGTH
+            <= normalized_strength
+            <= (MAX_VARIATION_STRENGTH)
+        ):
+            raise ValueError(
+                "Variation strength must be between "
+                f"{MIN_VARIATION_STRENGTH} and {MAX_VARIATION_STRENGTH}."
+            )
+        object.__setattr__(self, "strength", normalized_strength)

simple_syrup/domain/seg_preview.py

@@ -0,0 +1,51 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define renderer-neutral SEG preview documents."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+
+from .segs import CropRegion
+
+
+@dataclass(frozen=True)
+class AtlasPlacement:
+    """Locate one region mask inside the packed mask atlas."""
+
+    left: int
+    top: int
+    width: int
+    height: int
+
+
+@dataclass(frozen=True)
+class SegPreviewRegion:
+    """Describe one interactive region and its packed mask geometry."""
+
+    region_id: str
+    index: int
+    label: str
+    confidence: float
+    active_area: int
+    color: str
+    crop: CropRegion
+    atlas: AtlasPlacement
+
+
+@dataclass(frozen=True)
+class SegPreviewDocument:
+    """Carry bounded image assets and interaction metadata to a UI adapter."""
+
+    source_width: int
+    source_height: int
+    preview_width: int
+    preview_height: int
+    image: torch.Tensor
+    atlas: torch.Tensor
+    region_images: tuple[torch.Tensor, ...]
+    regions: tuple[SegPreviewRegion, ...]

simple_syrup/domain/segs_mask_ops.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 import torch
 import torch.nn.functional as F
 
-from ..domain.segs import BoundingBox, CropRegion
+from .segs import BoundingBox, CropRegion
 
 
 def validate_single_image(image: object, operation: str) -> torch.Tensor:

simple_syrup/domain/segs_tiled_diffusion.py

@@ -6,27 +6,11 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
-
 import torch
-import torch.nn.functional as functional
 
 from .segs import NativeSegs, Segment, coerce_segment_mask, coerce_segs
-from .tiled_diffusion import (
-    LatentTile,
-    TiledDiffusionPlan,
-    batch_latent_tiles,
-    build_tiled_diffusion_plan,
-)
-
-
-@dataclass(frozen=True)
-class _OwnershipCore:
-    """Represent a non-overlapping latent ownership region before window placement."""
-
-    mask: torch.Tensor
-    bounds: tuple[int, int, int, int]
-    area: int
+from .semantic_tiled_diffusion import build_semantic_tiled_diffusion_plan
+from .tiled_diffusion import TiledDiffusionPlan
 
 
 def build_segs_guided_tiled_diffusion_plan(
@@ -38,72 +22,34 @@ def build_segs_guided_tiled_diffusion_plan(
     tile_height: int,
     overlap: int,
     tile_batch_size: int,
+    segs_canvas: tuple[int, int] | None = None,
 ) -> TiledDiffusionPlan:
     """Build bounded sampling windows whose irregular cores follow supplied SEGS.
 
     Every latent pixel receives exactly one ownership core.  Each core is sampled
     through a rectangular window, while its local blend mask retains the irregular
     boundary and shares a feathered overlap with neighboring cores.
+    A reduced inversion stage validates proportions against its original canvas
+    because rounding the reduced dimensions can change their aspect ratio.
     """
 
-    base_plan = build_tiled_diffusion_plan(
+    native_segs = coerce_segs(segs)
+    canvas_height, canvas_width = segs_canvas or (latent_height, latent_width)
+    validate_segs_aspect_ratio(native_segs, canvas_height, canvas_width)
+    ownership_masks = segs_ownership_masks(
+        native_segs,
+        latent_height=latent_height,
+        latent_width=latent_width,
+    )
+    return build_semantic_tiled_diffusion_plan(
+        ownership_masks=ownership_masks,
         latent_width=latent_width,
         latent_height=latent_height,
         tile_width=tile_width,
         tile_height=tile_height,
         overlap=overlap,
         tile_batch_size=tile_batch_size,
-    )
-    native_segs = coerce_segs(segs)
-    validate_segs_aspect_ratio(native_segs, latent_height, latent_width)
-    ownership = _build_ownership_cores(
-        native_segs,
-        latent_height=latent_height,
-        latent_width=latent_width,
-    )
-    max_core_width = max(1, base_plan.tile_width - base_plan.overlap)
-    max_core_height = max(1, base_plan.tile_height - base_plan.overlap)
-    split_cores = tuple(
-        split_core
-        for core in ownership
-        for split_core in _split_core(
-            core,
-            max_width=max_core_width,
-            max_height=max_core_height,
-        )
-    )
-    merged_cores = _merge_small_cores(
-        split_cores,
-        max_width=max_core_width,
-        max_height=max_core_height,
-    )
-    tiles = tuple(
-        sorted(
-            (
-                _tile_for_core(
-                    core,
-                    latent_width=latent_width,
-                    latent_height=latent_height,
-                    tile_width=base_plan.tile_width,
-                    tile_height=base_plan.tile_height,
-                    overlap=base_plan.overlap,
-                )
-                for core in merged_cores
-            ),
-            key=lambda tile: (tile.y, tile.x),
-        )
-    )
-    batches, effective_batch_size = batch_latent_tiles(tiles, tile_batch_size)
-    return TiledDiffusionPlan(
-        latent_width=latent_width,
-        latent_height=latent_height,
-        tile_width=base_plan.tile_width,
-        tile_height=base_plan.tile_height,
-        overlap=base_plan.overlap,
-        requested_tile_batch_size=tile_batch_size,
-        tile_batch_size=effective_batch_size,
-        tiles=tiles,
-        batches=batches,
+        merge_across_masks=True,
     )
 
 
@@ -126,13 +72,13 @@ def validate_segs_aspect_ratio(
     )
 
 
-def _build_ownership_cores(
+def segs_ownership_masks(
     segs: NativeSegs,
     *,
     latent_height: int,
     latent_width: int,
-) -> tuple[_OwnershipCore, ...]:
-    """Resolve overlapping SEGS into one deterministic latent ownership partition."""
+) -> tuple[torch.Tensor, ...]:
+    """Resolve overlapping SEGS into a deterministic latent ownership partition."""
 
     source_height, source_width = segs[0]
     segment_masks = tuple(
@@ -154,20 +100,18 @@ def _build_ownership_cores(
         ),
     )
     occupied = torch.zeros((latent_height, latent_width), dtype=torch.bool)
-    cores: list[_OwnershipCore] = []
+    ownership_masks: list[torch.Tensor] = []
     for index in ranked_indexes:
         owned = torch.logical_and(segment_masks[index], torch.logical_not(occupied))
         if bool(owned.any()):
-            cores.append(_core_from_mask(owned))
+            ownership_masks.append(owned)
         occupied = torch.logical_or(occupied, segment_masks[index])
     background = torch.logical_not(occupied)
     if bool(background.any()):
-        cores.append(_core_from_mask(background))
-    if cores:
-        return tuple(cores)
-    return (
-        _core_from_mask(torch.ones((latent_height, latent_width), dtype=torch.bool)),
-    )
+        ownership_masks.append(background)
+    if ownership_masks:
+        return tuple(ownership_masks)
+    return (torch.ones((latent_height, latent_width), dtype=torch.bool),)
 
 
 def segment_mask_to_latent(
@@ -259,223 +203,6 @@ def segment_weight_to_latent(
     return latent_mask
 
 
-def _split_core(
-    core: _OwnershipCore,
-    *,
-    max_width: int,
-    max_height: int,
-) -> tuple[_OwnershipCore, ...]:
-    """Recursively divide a core into balanced pieces that fit its tile budget."""
-
-    left, top, right, bottom = core.bounds
-    width = right - left
-    height = bottom - top
-    if width <= max_width and height <= max_height:
-        return (core,)
-    split_x = width / max_width >= height / max_height
-    first, second = _split_mask_at_balanced_axis(core.mask, core.bounds, split_x)
-    return _split_core(
-        _core_from_mask(first), max_width=max_width, max_height=max_height
-    ) + _split_core(_core_from_mask(second), max_width=max_width, max_height=max_height)
-
-
-def _split_mask_at_balanced_axis(
-    mask: torch.Tensor,
-    bounds: tuple[int, int, int, int],
-    split_x: bool,
-) -> tuple[torch.Tensor, torch.Tensor]:
-    """Split one non-empty mask near its active-pixel median on one axis."""
-
-    left, top, right, bottom = bounds
-    counts = (
-        mask[top:bottom, left:right].sum(dim=0)
-        if split_x
-        else mask[top:bottom, left:right].sum(dim=1)
-    )
-    cumulative = torch.cumsum(counts, dim=0)
-    midpoint = int(torch.searchsorted(cumulative, cumulative[-1] / 2, right=False))
-    axis_start = left if split_x else top
-    axis_end = right if split_x else bottom
-    split_at = min(axis_end - 1, max(axis_start + 1, axis_start + midpoint + 1))
-    first = mask.clone()
-    second = mask.clone()
-    if split_x:
-        first[:, split_at:] = False
-        second[:, :split_at] = False
-    else:
-        first[split_at:, :] = False
-        second[:split_at, :] = False
-    if not bool(first.any()) or not bool(second.any()):
-        raise ValueError("Unable to split an oversized SEGS-guided tile core.")
-    return first, second
-
-
-def _merge_small_cores(
-    cores: tuple[_OwnershipCore, ...],
-    *,
-    max_width: int,
-    max_height: int,
-) -> tuple[_OwnershipCore, ...]:
-    """Greedily combine small nearby cores when one bounded window can hold both."""
-
-    pending = list(cores)
-    minimum_area = max(1, (max_width * max_height) // 4)
-    merged = True
-    while merged:
-        merged = False
-        for index, core in enumerate(tuple(pending)):
-            if core.area >= minimum_area:
-                continue
-            candidate_index = _best_merge_candidate_index(
-                core,
-                pending,
-                excluded_index=index,
-                max_width=max_width,
-                max_height=max_height,
-            )
-            if candidate_index is None:
-                continue
-            candidate = pending[candidate_index]
-            pending[index] = _OwnershipCore(
-                mask=torch.logical_or(core.mask, candidate.mask),
-                bounds=_union_bounds(core.bounds, candidate.bounds),
-                area=core.area + candidate.area,
-            )
-            pending.pop(candidate_index)
-            merged = True
-            break
-    return tuple(pending)
-
-
-def _best_merge_candidate_index(
-    core: _OwnershipCore,
-    candidates: list[_OwnershipCore],
-    *,
-    excluded_index: int,
-    max_width: int,
-    max_height: int,
-) -> int | None:
-    """Return a candidate index whose combined bounds fit one ownership budget."""
-
-    eligible: list[tuple[int, int, int]] = []
-    for index, candidate in enumerate(candidates):
-        if index == excluded_index:
-            continue
-        bounds = _union_bounds(core.bounds, candidate.bounds)
-        left, top, right, bottom = bounds
-        width = right - left
-        height = bottom - top
-        if width > max_width or height > max_height:
-            continue
-        distance = _bounds_distance(core.bounds, candidate.bounds)
-        eligible.append((width * height, distance, index))
-    if not eligible:
-        return None
-    return min(eligible, key=lambda item: (item[0], item[1]))[2]
-
-
-def _bounds_distance(
-    first: tuple[int, int, int, int],
-    second: tuple[int, int, int, int],
-) -> int:
-    """Return the axis-aligned gap between two mask bounding boxes."""
-
-    left, top, right, bottom = first
-    other_left, other_top, other_right, other_bottom = second
-    horizontal = max(0, other_left - right, left - other_right)
-    vertical = max(0, other_top - bottom, top - other_bottom)
-    return horizontal + vertical
-
-
-def _union_bounds(
-    first: tuple[int, int, int, int],
-    second: tuple[int, int, int, int],
-) -> tuple[int, int, int, int]:
-    """Return the tight rectangle containing both ownership-core bounds."""
-
-    return (
-        min(first[0], second[0]),
-        min(first[1], second[1]),
-        max(first[2], second[2]),
-        max(first[3], second[3]),
-    )
-
-
-def _tile_for_core(
-    core: _OwnershipCore,
-    *,
-    latent_width: int,
-    latent_height: int,
-    tile_width: int,
-    tile_height: int,
-    overlap: int,
-) -> LatentTile:
-    """Place one bounded sampling window around an irregular ownership core."""
-
-    left, top, right, bottom = core.bounds
-    center_x = (left + right) / 2.0
-    center_y = (top + bottom) / 2.0
-    x = _clamp_window_start(center_x, tile_width, latent_width)
-    y = _clamp_window_start(center_y, tile_height, latent_height)
-    weight_mask = _feathered_tile_weight(
-        core.mask,
-        x=x,
-        y=y,
-        width=tile_width,
-        height=tile_height,
-        overlap=overlap,
-    )
-    if not bool((weight_mask > 0).any()):
-        raise ValueError("SEGS-guided tiled diffusion generated an empty tile weight.")
-    return LatentTile(x, y, tile_width, tile_height, weight_mask)
-
-
-def _clamp_window_start(center: float, window_size: int, limit: int) -> int:
-    """Center a fixed sampling window while keeping it inside the latent bounds."""
-
-    desired = round(center - window_size / 2.0)
-    return min(max(0, desired), limit - window_size)
-
-
-def _feathered_tile_weight(
-    mask: torch.Tensor,
-    *,
-    x: int,
-    y: int,
-    width: int,
-    height: int,
-    overlap: int,
-) -> torch.Tensor:
-    """Build one feathered tile weight without blurring the full latent mask."""
-
-    if overlap == 0:
-        return mask[y : y + height, x : x + width].float().contiguous()
-    radius = max(1, overlap // 2)
-    source_left = max(0, x - radius)
-    source_top = max(0, y - radius)
-    source_right = min(int(mask.shape[1]), x + width + radius)
-    source_bottom = min(int(mask.shape[0]), y + height + radius)
-    local_weight = (
-        functional.avg_pool2d(
-            mask[source_top:source_bottom, source_left:source_right]
-            .float()
-            .unsqueeze(0)
-            .unsqueeze(0),
-            kernel_size=radius * 2 + 1,
-            stride=1,
-            padding=radius,
-            count_include_pad=False,
-        )
-        .squeeze(0)
-        .squeeze(0)
-    )
-    local_y = y - source_top
-    local_x = x - source_left
-    return local_weight[
-        local_y : local_y + height, local_x : local_x + width
-    ].contiguous()
-
-
 def _latent_sample_range(
     source_start: int,
     source_end: int,
@@ -487,30 +214,3 @@ def _latent_sample_range(
     start = (source_start * latent_limit + source_limit - 1) // source_limit
     end = (source_end * latent_limit + source_limit - 1) // source_limit
     return max(0, min(latent_limit, start)), max(0, min(latent_limit, end))
-
-
-def _core_from_mask(mask: torch.Tensor) -> _OwnershipCore:
-    """Build one core with bounds and area computed exactly once."""
-
-    bounds = _mask_bounds(mask)
-    if bounds is None:
-        raise ValueError("SEGS-guided tiled diffusion cannot use an empty core.")
-    return _OwnershipCore(
-        mask=mask,
-        bounds=bounds,
-        area=int(mask.sum().item()),
-    )
-
-
-def _mask_bounds(mask: torch.Tensor) -> tuple[int, int, int, int] | None:
-    """Return left, top, right, bottom bounds for one non-empty boolean mask."""
-
-    y_coords, x_coords = torch.where(mask)
-    if y_coords.numel() == 0:
-        return None
-    return (
-        int(x_coords.min().item()),
-        int(y_coords.min().item()),
-        int(x_coords.max().item()) + 1,
-        int(y_coords.max().item()) + 1,
-    )

simple_syrup/domain/semantic_tiled_diffusion.py

@@ -0,0 +1,384 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Build tiled diffusion plans from non-overlapping latent ownership masks."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+import torch
+import torch.nn.functional as functional
+
+from .tiled_diffusion import (
+    LatentTile,
+    TiledDiffusionPlan,
+    batch_latent_tiles,
+    build_tiled_diffusion_plan,
+)
+
+
+@dataclass(frozen=True)
+class _OwnershipCore:
+    """Represent one latent ownership region before sampling-window placement."""
+
+    mask: torch.Tensor
+    bounds: tuple[int, int, int, int]
+    area: int
+
+
+def build_semantic_tiled_diffusion_plan(
+    *,
+    ownership_masks: Sequence[torch.Tensor],
+    latent_width: int,
+    latent_height: int,
+    tile_width: int,
+    tile_height: int,
+    overlap: int,
+    tile_batch_size: int,
+    merge_across_masks: bool,
+) -> TiledDiffusionPlan:
+    """Build bounded windows whose write weights follow ownership masks."""
+
+    base_plan = build_tiled_diffusion_plan(
+        latent_width=latent_width,
+        latent_height=latent_height,
+        tile_width=tile_width,
+        tile_height=tile_height,
+        overlap=overlap,
+        tile_batch_size=tile_batch_size,
+    )
+    normalized_masks = _validate_ownership_masks(
+        ownership_masks,
+        latent_height=latent_height,
+        latent_width=latent_width,
+    )
+    max_core_width = max(1, base_plan.tile_width - base_plan.overlap)
+    max_core_height = max(1, base_plan.tile_height - base_plan.overlap)
+    split_groups = tuple(
+        tuple(
+            split_core
+            for split_core in _split_core(
+                _core_from_mask(mask),
+                max_width=max_core_width,
+                max_height=max_core_height,
+            )
+        )
+        for mask in normalized_masks
+    )
+    if merge_across_masks:
+        cores = _merge_small_cores(
+            tuple(core for group in split_groups for core in group),
+            max_width=max_core_width,
+            max_height=max_core_height,
+        )
+    else:
+        cores = tuple(
+            core
+            for group in split_groups
+            for core in _merge_small_cores(
+                group,
+                max_width=max_core_width,
+                max_height=max_core_height,
+            )
+        )
+    tiles = tuple(
+        sorted(
+            (
+                _tile_for_core(
+                    core,
+                    latent_width=latent_width,
+                    latent_height=latent_height,
+                    tile_width=base_plan.tile_width,
+                    tile_height=base_plan.tile_height,
+                    overlap=base_plan.overlap,
+                )
+                for core in cores
+            ),
+            key=lambda tile: (tile.y, tile.x),
+        )
+    )
+    batches, effective_batch_size = batch_latent_tiles(tiles, tile_batch_size)
+    return TiledDiffusionPlan(
+        latent_width=latent_width,
+        latent_height=latent_height,
+        tile_width=base_plan.tile_width,
+        tile_height=base_plan.tile_height,
+        overlap=base_plan.overlap,
+        requested_tile_batch_size=tile_batch_size,
+        tile_batch_size=effective_batch_size,
+        tiles=tiles,
+        batches=batches,
+    )
+
+
+def _validate_ownership_masks(
+    masks: Sequence[torch.Tensor],
+    *,
+    latent_height: int,
+    latent_width: int,
+) -> tuple[torch.Tensor, ...]:
+    """Return non-empty boolean masks that cover the complete latent canvas."""
+
+    normalized: list[torch.Tensor] = []
+    coverage = torch.zeros((latent_height, latent_width), dtype=torch.bool)
+    for index, mask in enumerate(masks):
+        if mask.ndim != 2 or tuple(mask.shape) != (latent_height, latent_width):
+            raise ValueError(
+                "Semantic ownership mask "
+                f"{index} must match latent shape {latent_height}x{latent_width}."
+            )
+        boolean_mask = mask.detach().cpu().bool()
+        if not bool(boolean_mask.any()):
+            continue
+        if bool(torch.logical_and(coverage, boolean_mask).any()):
+            raise ValueError("Semantic ownership masks must not overlap.")
+        normalized.append(boolean_mask)
+        coverage = torch.logical_or(coverage, boolean_mask)
+    if not normalized:
+        raise ValueError("Semantic tiled diffusion requires non-empty ownership.")
+    if not bool(coverage.all()):
+        raise ValueError("Semantic ownership masks must cover the latent canvas.")
+    return tuple(normalized)
+
+
+def _split_core(
+    core: _OwnershipCore,
+    *,
+    max_width: int,
+    max_height: int,
+) -> tuple[_OwnershipCore, ...]:
+    """Recursively divide a core into balanced pieces within its tile budget."""
+
+    left, top, right, bottom = core.bounds
+    width = right - left
+    height = bottom - top
+    if width <= max_width and height <= max_height:
+        return (core,)
+    split_x = width / max_width >= height / max_height
+    first, second = _split_mask_at_balanced_axis(core.mask, core.bounds, split_x)
+    return _split_core(
+        _core_from_mask(first), max_width=max_width, max_height=max_height
+    ) + _split_core(_core_from_mask(second), max_width=max_width, max_height=max_height)
+
+
+def _split_mask_at_balanced_axis(
+    mask: torch.Tensor,
+    bounds: tuple[int, int, int, int],
+    split_x: bool,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Split one non-empty mask near its active-pixel median on one axis."""
+
+    left, top, right, bottom = bounds
+    counts = (
+        mask[top:bottom, left:right].sum(dim=0)
+        if split_x
+        else mask[top:bottom, left:right].sum(dim=1)
+    )
+    cumulative = torch.cumsum(counts, dim=0)
+    midpoint = int(torch.searchsorted(cumulative, cumulative[-1] / 2, right=False))
+    axis_start = left if split_x else top
+    axis_end = right if split_x else bottom
+    split_at = min(axis_end - 1, max(axis_start + 1, axis_start + midpoint + 1))
+    first = mask.clone()
+    second = mask.clone()
+    if split_x:
+        first[:, split_at:] = False
+        second[:, :split_at] = False
+    else:
+        first[split_at:, :] = False
+        second[:split_at, :] = False
+    if not bool(first.any()) or not bool(second.any()):
+        raise ValueError("Unable to split an oversized semantic tile core.")
+    return first, second
+
+
+def _merge_small_cores(
+    cores: tuple[_OwnershipCore, ...],
+    *,
+    max_width: int,
+    max_height: int,
+) -> tuple[_OwnershipCore, ...]:
+    """Greedily combine nearby cores when one bounded window can hold both."""
+
+    pending = list(cores)
+    minimum_area = max(1, (max_width * max_height) // 4)
+    merged = True
+    while merged:
+        merged = False
+        for index, core in enumerate(tuple(pending)):
+            if core.area >= minimum_area:
+                continue
+            candidate_index = _best_merge_candidate_index(
+                core,
+                pending,
+                excluded_index=index,
+                max_width=max_width,
+                max_height=max_height,
+            )
+            if candidate_index is None:
+                continue
+            candidate = pending[candidate_index]
+            pending[index] = _OwnershipCore(
+                mask=torch.logical_or(core.mask, candidate.mask),
+                bounds=_union_bounds(core.bounds, candidate.bounds),
+                area=core.area + candidate.area,
+            )
+            pending.pop(candidate_index)
+            merged = True
+            break
+    return tuple(pending)
+
+
+def _best_merge_candidate_index(
+    core: _OwnershipCore,
+    candidates: list[_OwnershipCore],
+    *,
+    excluded_index: int,
+    max_width: int,
+    max_height: int,
+) -> int | None:
+    """Return a candidate whose combined bounds fit one ownership budget."""
+
+    eligible: list[tuple[int, int, int]] = []
+    for index, candidate in enumerate(candidates):
+        if index == excluded_index:
+            continue
+        bounds = _union_bounds(core.bounds, candidate.bounds)
+        left, top, right, bottom = bounds
+        width = right - left
+        height = bottom - top
+        if width > max_width or height > max_height:
+            continue
+        distance = _bounds_distance(core.bounds, candidate.bounds)
+        eligible.append((width * height, distance, index))
+    if not eligible:
+        return None
+    return min(eligible, key=lambda item: (item[0], item[1]))[2]
+
+
+def _bounds_distance(
+    first: tuple[int, int, int, int],
+    second: tuple[int, int, int, int],
+) -> int:
+    """Return the axis-aligned gap between two mask bounding boxes."""
+
+    left, top, right, bottom = first
+    other_left, other_top, other_right, other_bottom = second
+    horizontal = max(0, other_left - right, left - other_right)
+    vertical = max(0, other_top - bottom, top - other_bottom)
+    return horizontal + vertical
+
+
+def _union_bounds(
+    first: tuple[int, int, int, int],
+    second: tuple[int, int, int, int],
+) -> tuple[int, int, int, int]:
+    """Return the tight rectangle containing both ownership-core bounds."""
+
+    return (
+        min(first[0], second[0]),
+        min(first[1], second[1]),
+        max(first[2], second[2]),
+        max(first[3], second[3]),
+    )
+
+
+def _tile_for_core(
+    core: _OwnershipCore,
+    *,
+    latent_width: int,
+    latent_height: int,
+    tile_width: int,
+    tile_height: int,
+    overlap: int,
+) -> LatentTile:
+    """Place one bounded sampling window around an irregular ownership core."""
+
+    left, top, right, bottom = core.bounds
+    center_x = (left + right) / 2.0
+    center_y = (top + bottom) / 2.0
+    x = _clamp_window_start(center_x, tile_width, latent_width)
+    y = _clamp_window_start(center_y, tile_height, latent_height)
+    weight_mask = _feathered_tile_weight(
+        core.mask,
+        x=x,
+        y=y,
+        width=tile_width,
+        height=tile_height,
+        overlap=overlap,
+    )
+    if not bool((weight_mask > 0).any()):
+        raise ValueError("Semantic tiled diffusion generated an empty tile weight.")
+    return LatentTile(x, y, tile_width, tile_height, weight_mask)
+
+
+def _clamp_window_start(center: float, window_size: int, limit: int) -> int:
+    """Center a fixed sampling window while keeping it inside latent bounds."""
+
+    desired = round(center - window_size / 2.0)
+    return min(max(0, desired), limit - window_size)
+
+
+def _feathered_tile_weight(
+    mask: torch.Tensor,
+    *,
+    x: int,
+    y: int,
+    width: int,
+    height: int,
+    overlap: int,
+) -> torch.Tensor:
+    """Build one feathered tile weight without blurring the full latent mask."""
+
+    if overlap == 0:
+        return mask[y : y + height, x : x + width].float().contiguous()
+    radius = max(1, overlap // 2)
+    source_left = max(0, x - radius)
+    source_top = max(0, y - radius)
+    source_right = min(int(mask.shape[1]), x + width + radius)
+    source_bottom = min(int(mask.shape[0]), y + height + radius)
+    local_weight = (
+        functional.avg_pool2d(
+            mask[source_top:source_bottom, source_left:source_right]
+            .float()
+            .unsqueeze(0)
+            .unsqueeze(0),
+            kernel_size=radius * 2 + 1,
+            stride=1,
+            padding=radius,
+            count_include_pad=False,
+        )
+        .squeeze(0)
+        .squeeze(0)
+    )
+    local_y = y - source_top
+    local_x = x - source_left
+    return local_weight[
+        local_y : local_y + height, local_x : local_x + width
+    ].contiguous()
+
+
+def _core_from_mask(mask: torch.Tensor) -> _OwnershipCore:
+    """Build one core with bounds and area computed exactly once."""
+
+    bounds = _mask_bounds(mask)
+    if bounds is None:
+        raise ValueError("Semantic tiled diffusion cannot use an empty core.")
+    return _OwnershipCore(mask=mask, bounds=bounds, area=int(mask.sum().item()))
+
+
+def _mask_bounds(mask: torch.Tensor) -> tuple[int, int, int, int] | None:
+    """Return left, top, right, bottom bounds for a non-empty boolean mask."""
+
+    y_coords, x_coords = torch.where(mask)
+    if y_coords.numel() == 0:
+        return None
+    return (
+        int(x_coords.min().item()),
+        int(y_coords.min().item()),
+        int(x_coords.max().item()) + 1,
+        int(y_coords.max().item()) + 1,
+    )

simple_syrup/domain/spatial_views.py

@@ -0,0 +1,164 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Define immutable spatial model views and view-major batch layouts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class SpatialViewKind(StrEnum):
+    """Identify how one model view relates to the canonical latent canvas."""
+
+    FULL = "full"
+    TILE = "tile"
+    CONTEXTUAL_GLOBAL = "contextual_global"
+
+
+@dataclass(frozen=True, slots=True)
+class SpatialView:
+    """Describe one source rectangle evaluated at one model spatial shape."""
+
+    kind: SpatialViewKind
+    source_x: int
+    source_y: int
+    source_width: int
+    source_height: int
+    model_width: int
+    model_height: int
+
+    def __post_init__(self) -> None:
+        """Reject invalid or internally inconsistent view geometry."""
+
+        if not isinstance(self.kind, SpatialViewKind):
+            raise TypeError("Spatial view kind must be a SpatialViewKind value.")
+        if self.source_x < 0 or self.source_y < 0:
+            raise ValueError("Spatial view source coordinates must be non-negative.")
+        if self.source_width < 1 or self.source_height < 1:
+            raise ValueError("Spatial view source dimensions must be positive.")
+        if self.model_width < 1 or self.model_height < 1:
+            raise ValueError("Spatial view model dimensions must be positive.")
+        if self.kind is SpatialViewKind.FULL and (
+            self.source_width != self.model_width
+            or self.source_height != self.model_height
+        ):
+            raise ValueError("A full spatial view must preserve its source dimensions.")
+
+    @property
+    def source_right(self) -> int:
+        """Return the exclusive source rectangle right edge."""
+
+        return self.source_x + self.source_width
+
+    @property
+    def source_bottom(self) -> int:
+        """Return the exclusive source rectangle bottom edge."""
+
+        return self.source_y + self.source_height
+
+
+@dataclass(frozen=True, slots=True)
+class SpatialBatchLayout:
+    """Describe ordered spatial views expanded over one source model batch."""
+
+    canvas_width: int
+    canvas_height: int
+    views: tuple[SpatialView, ...]
+    input_batch_size: int
+
+    def __post_init__(self) -> None:
+        """Validate canvas containment and homogeneous model-call semantics."""
+
+        if self.canvas_width < 1 or self.canvas_height < 1:
+            raise ValueError("Spatial layout canvas dimensions must be positive.")
+        if self.input_batch_size < 1:
+            raise ValueError("Spatial layout input batch size must be positive.")
+        if not isinstance(self.views, tuple):
+            raise TypeError("Spatial layout views must be an immutable tuple.")
+        if not self.views:
+            raise ValueError("Spatial layout requires at least one view.")
+        if not all(isinstance(view, SpatialView) for view in self.views):
+            raise TypeError("Spatial layout views must contain SpatialView values.")
+
+        view_kind = self.views[0].kind
+        if any(view.kind is not view_kind for view in self.views):
+            raise ValueError("One spatial model call cannot mix view kinds.")
+        for view in self.views:
+            if (
+                view.source_right > self.canvas_width
+                or view.source_bottom > self.canvas_height
+            ):
+                raise ValueError(
+                    "Spatial view source rectangle must remain inside the canvas."
+                )
+
+        if view_kind in {
+            SpatialViewKind.FULL,
+            SpatialViewKind.CONTEXTUAL_GLOBAL,
+        }:
+            if len(self.views) != 1:
+                raise ValueError("A full-source spatial layout requires one view.")
+            view = self.views[0]
+            if (
+                view.source_x != 0
+                or view.source_y != 0
+                or view.source_width != self.canvas_width
+                or view.source_height != self.canvas_height
+            ):
+                raise ValueError(
+                    "A full-source spatial view must cover the complete canvas."
+                )
+
+    @property
+    def view_count(self) -> int:
+        """Return the number of ordered spatial views."""
+
+        return len(self.views)
+
+    @property
+    def expanded_batch_size(self) -> int:
+        """Return the model batch size after view-major expansion."""
+
+        return self.view_count * self.input_batch_size
+
+    @property
+    def expanded_views(self) -> tuple[SpatialView, ...]:
+        """Repeat each view for its contiguous source-batch group."""
+
+        return tuple(
+            view
+            for view in self.views
+            for _source_batch_index in range(self.input_batch_size)
+        )
+
+    @property
+    def expanded_view_indices(self) -> tuple[int, ...]:
+        """Return the view index for every expanded model-batch entry."""
+
+        return tuple(
+            view_index
+            for view_index in range(self.view_count)
+            for _source_batch_index in range(self.input_batch_size)
+        )
+
+    @property
+    def expanded_source_batch_indices(self) -> tuple[int, ...]:
+        """Return the source-batch index for every expanded model-batch entry."""
+
+        return tuple(
+            source_batch_index
+            for _view in self.views
+            for source_batch_index in range(self.input_batch_size)
+        )
+
+    def expanded_index(self, view_index: int, source_batch_index: int) -> int:
+        """Return one view-major model-batch index after validating both axes."""
+
+        if not 0 <= view_index < self.view_count:
+            raise IndexError("Spatial view index is outside the layout.")
+        if not 0 <= source_batch_index < self.input_batch_size:
+            raise IndexError("Source batch index is outside the layout.")
+        return view_index * self.input_batch_size + source_batch_index

simple_syrup/domain/tile_segs.py

@@ -11,11 +11,6 @@ from dataclasses import dataclass
 
 import torch
 
-from ..masking.segs_mask_ops import (
-    crop_region_for_bbox,
-    resize_mask,
-    validate_single_image,
-)
 from ..shared.logging import get_logger
 from .segs import (
     BoundingBox,
@@ -23,6 +18,11 @@ from .segs import (
     NativeSegs,
     Segment,
 )
+from .segs_mask_ops import (
+    crop_region_for_bbox,
+    resize_mask,
+    validate_single_image,
+)
 
 LOGGER = get_logger(__name__)
 

simple_syrup/integration/__init__.py

@@ -0,0 +1,5 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Own inbound ComfyUI integration and transport composition."""

simple_syrup/integration/external_llm_routes.py

@@ -14,9 +14,9 @@ from typing import Any, Protocol, cast
 from aiohttp import web
 
 from ..domain.external_llm import ExternalLLMConfigError, ExternalLLMProviderError
+from ..runtime.external_llm_keyring import ExternalLLMKeyringError
 from ..services.external_llm_prompt_service import ExternalLLMPromptService
 from ..shared.logging import get_logger
-from .external_llm_keyring import ExternalLLMKeyringError
 
 LOGGER = get_logger(__name__)
 EXTERNAL_LLM_SETTINGS_ROUTE = "/simple-syrup/external-llm/settings"

simple_syrup/integration/quant_cache_routes.py

@@ -0,0 +1,143 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Expose global quant cache status and safe inactive-artifact clearing."""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable, Coroutine
+from typing import Any, Protocol, cast
+
+from aiohttp import web
+
+from ..runtime.quant_cache_settings import SettingsQuantCacheLimitProvider
+from ..services.quant_cache_service import (
+    QuantCacheEvictionResult,
+    QuantCacheService,
+    QuantCacheStatus,
+)
+from ..services.quantized_model_boundaries import QuantCacheLimitProvider
+
+QUANT_CACHE_ROUTE = "/simple-syrup/quant-cache"
+Handler = Callable[[Any], Coroutine[Any, Any, web.Response]]
+_REGISTERED_PROMPT_SERVERS: set[int] = set()
+
+
+class QuantCacheRoutesProtocol(Protocol):
+    """Describe the route decorators used by quant cache endpoints."""
+
+    def get(self, path: str) -> Callable[[Handler], Handler]:
+        """Return a GET route decorator."""
+
+    def delete(self, path: str) -> Callable[[Handler], Handler]:
+        """Return a DELETE route decorator."""
+
+    def post(self, path: str) -> Callable[[Handler], Handler]:
+        """Return a POST route decorator."""
+
+
+class QuantCachePromptServerProtocol(Protocol):
+    """Describe the PromptServer state required by cache routes."""
+
+    routes: QuantCacheRoutesProtocol
+
+
+class QuantCacheServiceBoundary(Protocol):
+    """Describe global cache operations exposed through HTTP."""
+
+    def status(self) -> QuantCacheStatus:
+        """Return current cache state."""
+
+    def clear_inactive(self) -> QuantCacheEvictionResult:
+        """Remove every inactive managed artifact."""
+
+    def enforce_limit(self, limit_bytes: int) -> QuantCacheEvictionResult:
+        """Apply the current global LRU budget."""
+
+
+class QuantCacheHandlers:
+    """Serve global quant cache state and explicit clear requests."""
+
+    def __init__(
+        self,
+        cache_service: QuantCacheServiceBoundary,
+        limit_provider: QuantCacheLimitProvider,
+    ) -> None:
+        """Create handlers with explicit authoritative collaborators."""
+
+        self._cache_service = cache_service
+        self._limit_provider = limit_provider
+
+    async def get_status(self, _request: Any) -> web.Response:
+        """Return current global cache usage and configured limit."""
+
+        status = self._cache_service.status()
+        return web.json_response(status.to_payload(self._limit_provider.limit_bytes()))
+
+    async def clear_inactive(self, _request: Any) -> web.Response:
+        """Clear inactive artifacts and return updated global cache status."""
+
+        eviction = self._cache_service.clear_inactive()
+        status = self._cache_service.status()
+        payload = status.to_payload(self._limit_provider.limit_bytes())
+        payload.update(
+            {
+                "removed_artifacts": eviction.removed_artifacts,
+                "removed_bytes": eviction.removed_bytes,
+            }
+        )
+        return web.json_response(payload)
+
+    async def enforce_limit(self, _request: Any) -> web.Response:
+        """Apply the persisted limit and return updated global cache status."""
+
+        limit_bytes = self._limit_provider.limit_bytes()
+        eviction = self._cache_service.enforce_limit(limit_bytes)
+        status = self._cache_service.status()
+        payload = status.to_payload(limit_bytes)
+        payload.update(
+            {
+                "removed_artifacts": eviction.removed_artifacts,
+                "removed_bytes": eviction.removed_bytes,
+            }
+        )
+        return web.json_response(payload)
+
+
+def register_quant_cache_routes(
+    cache_service: QuantCacheServiceBoundary | None = None,
+    limit_provider: QuantCacheLimitProvider | None = None,
+    prompt_server: QuantCachePromptServerProtocol | None = None,
+) -> bool:
+    """Register global cache routes with ComfyUI when PromptServer is available."""
+
+    server_instance = prompt_server or _prompt_server_instance()
+    if server_instance is None:
+        return False
+    server_key = id(server_instance)
+    if prompt_server is None and server_key in _REGISTERED_PROMPT_SERVERS:
+        return True
+    handlers = QuantCacheHandlers(
+        cache_service or QuantCacheService(),
+        limit_provider or SettingsQuantCacheLimitProvider(),
+    )
+    server_instance.routes.get(QUANT_CACHE_ROUTE)(handlers.get_status)
+    server_instance.routes.post(QUANT_CACHE_ROUTE)(handlers.enforce_limit)
+    server_instance.routes.delete(QUANT_CACHE_ROUTE)(handlers.clear_inactive)
+    if prompt_server is None:
+        _REGISTERED_PROMPT_SERVERS.add(server_key)
+    return True
+
+
+def _prompt_server_instance() -> QuantCachePromptServerProtocol | None:
+    """Return ComfyUI's PromptServer instance when available."""
+
+    try:
+        server_module = sys.modules["server"]
+        prompt_server = server_module.PromptServer
+        instance = prompt_server.instance
+    except (KeyError, AttributeError):
+        return None
+    return cast(QuantCachePromptServerProtocol, instance)

simple_syrup/integration/settings_routes.py

@@ -12,12 +12,12 @@ from typing import Any, Protocol, cast
 
 from aiohttp import web
 
-from ..shared.logging import get_logger
-from .settings import (
+from ..runtime.settings import (
     SimpleSyrupSettings,
     SimpleSyrupSettingsError,
-    SimpleSyrupSettingsRepository,
 )
+from ..runtime.settings_repository import SimpleSyrupSettingsRepository
+from ..shared.logging import get_logger
 
 LOGGER = get_logger(__name__)
 SETTINGS_ROUTE = "/simple-syrup/settings"
@@ -80,13 +80,22 @@ class SettingsHandlers:
         """Return validated settings while preserving omitted nested config."""
 
         settings = SimpleSyrupSettings.from_payload(payload)
-        if isinstance(payload, dict) and "external_llm" not in payload:
-            current = self._repository.load()
-            return SimpleSyrupSettings(
-                show_downloadable_models=settings.show_downloadable_models,
-                external_llm=current.external_llm,
-            )
-        return settings
+        if not isinstance(payload, dict):
+            return settings
+        current = self._repository.load()
+        return SimpleSyrupSettings(
+            show_downloadable_models=settings.show_downloadable_models,
+            quant_cache_limit_gib=(
+                settings.quant_cache_limit_gib
+                if "quant_cache_limit_gib" in payload
+                else current.quant_cache_limit_gib
+            ),
+            external_llm=(
+                settings.external_llm
+                if "external_llm" in payload
+                else current.external_llm
+            ),
+        )
 
 
 def register_settings_routes(

simple_syrup/masking/mask_components.py

@@ -2,18 +2,19 @@
 # Copyright (C) 2026  Artificial Sweetener and contributors
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
-"""Connected-component helpers for binary mask regions."""
+"""Extract deterministic connected components from binary mask regions."""
 
 from __future__ import annotations
 
 from dataclasses import dataclass
+from importlib import import_module
 
 import torch
 
 from ..domain.segs import BoundingBox
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, slots=True)
 class MaskComponent:
     """Represent one connected mask component and its full-image bbox."""
 
@@ -22,62 +23,30 @@ class MaskComponent:
 
 
 def connected_mask_components(active_mask: torch.Tensor) -> tuple[MaskComponent, ...]:
-    """Return 8-connected components from an HW active-pixel mask."""
+    """Return spatially ordered 8-connected components from one HW mask."""
 
-    if active_mask.ndim != 2:
+    if not isinstance(active_mask, torch.Tensor) or active_mask.ndim != 2:
         raise ValueError("active_mask must be an HW tensor.")
-
-    active = active_mask.detach().to(device="cpu", dtype=torch.bool)
-    height = int(active.shape[0])
-    width = int(active.shape[1])
-    visited = torch.zeros((height, width), dtype=torch.bool)
+    active = active_mask.detach().to(device="cpu", dtype=torch.uint8).numpy()
+    if not active.any():
+        return ()
+    cv2 = import_module("cv2")
+    component_count, labels, stats, _centroids = cv2.connectedComponentsWithStats(
+        active,
+        connectivity=8,
+    )
     components: list[MaskComponent] = []
-
-    for top in range(height):
-        for left in range(width):
-            if visited[top, left].item() or not active[top, left].item():
-                continue
-            components.append(_trace_component(active, visited, left, top))
-
-    return tuple(components)
-
-
-def _trace_component(
-    active: torch.Tensor,
-    visited: torch.Tensor,
-    start_left: int,
-    start_top: int,
-) -> MaskComponent:
-    """Trace one 8-connected component from its first active pixel."""
-
-    height = int(active.shape[0])
-    width = int(active.shape[1])
-    queue: list[tuple[int, int]] = [(start_top, start_left)]
-    visited[start_top, start_left] = True
-    pixels: list[tuple[int, int]] = []
-    index = 0
-
-    while index < len(queue):
-        top, left = queue[index]
-        index += 1
-        pixels.append((top, left))
-        for neighbor_top in range(max(0, top - 1), min(height, top + 2)):
-            for neighbor_left in range(max(0, left - 1), min(width, left + 2)):
-                if visited[neighbor_top, neighbor_left].item():
-                    continue
-                visited[neighbor_top, neighbor_left] = True
-                if active[neighbor_top, neighbor_left].item():
-                    queue.append((neighbor_top, neighbor_left))
-
-    top_values = [top for top, _left in pixels]
-    left_values = [left for _top, left in pixels]
-    bbox = BoundingBox(
-        min(left_values),
-        min(top_values),
-        max(left_values) + 1,
-        max(top_values) + 1,
+    for label in range(1, int(component_count)):
+        left = int(stats[label, cv2.CC_STAT_LEFT])
+        top = int(stats[label, cv2.CC_STAT_TOP])
+        width = int(stats[label, cv2.CC_STAT_WIDTH])
+        height = int(stats[label, cv2.CC_STAT_HEIGHT])
+        components.append(
+            MaskComponent(
+                bbox=BoundingBox(left, top, left + width, top + height),
+                mask=torch.from_numpy(labels == label),
+            )
+        )
+    return tuple(
+        sorted(components, key=lambda value: (value.bbox.top, value.bbox.left))
     )
-    component_mask = torch.zeros((height, width), dtype=torch.bool)
-    for top, left in pixels:
-        component_mask[top, left] = True
-    return MaskComponent(bbox=bbox, mask=component_mask)

simple_syrup/masking/prompt_segs_with_sam_service.py

@@ -15,8 +15,7 @@ from ..domain.segs import (
     NativeSegs,
     Segment,
 )
-from ..masking.mask_ops import MaskRefinementSettings, refine_prompt_mask
-from ..masking.segs_mask_ops import (
+from ..domain.segs_mask_ops import (
     crop_image,
     crop_mask,
     crop_region_for_bbox,
@@ -24,6 +23,7 @@ from ..masking.segs_mask_ops import (
     normalize_mask,
     validate_single_image,
 )
+from ..masking.mask_ops import MaskRefinementSettings, refine_prompt_mask
 from ..runtime.sam_segmenter import SAMBoxSegmenter, SAMModelSegmenter
 from ..runtime.text_box_detector import (
     GroundingDINOTextBoxDetector,

simple_syrup/masking/regional_activation_mask_projection.py

@@ -0,0 +1,194 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Project canonical masks into exact regional activation multiplier shapes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import torch
+
+from ..domain.regional_activation_geometry import (
+    RegionalActivationGeometry,
+    RegionalActivationLayout,
+)
+from ..domain.regional_mask_bank import RegionalMaskBank
+from ..domain.spatial_views import (
+    SpatialBatchLayout,
+    SpatialView,
+    SpatialViewKind,
+)
+from .regional_mask_projection import (
+    RegionalMaskForm,
+    RegionalMaskProjectionMode,
+    RegionalMaskProjector,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class RegionalActivationMaskBatch:
+    """Retain one finite region-major multiplier broadcast over rank activations."""
+
+    multipliers: torch.Tensor
+    geometry: RegionalActivationGeometry
+
+    def __post_init__(self) -> None:
+        """Require exact geometry shape and bounded finite floating multipliers."""
+
+        if not isinstance(self.multipliers, torch.Tensor):
+            raise TypeError("Regional activation multipliers must be a tensor.")
+        if not isinstance(self.geometry, RegionalActivationGeometry):
+            raise TypeError("Regional activation multipliers require geometry.")
+        if not self.multipliers.is_floating_point():
+            raise TypeError("Regional activation multipliers must use floating point.")
+        if self.multipliers.ndim != len(self.geometry.invocation_shape) + 1:
+            raise ValueError("Regional activation multiplier rank is inconsistent.")
+        expected = self.geometry.broadcast_mask_shape(int(self.multipliers.shape[0]))
+        if tuple(self.multipliers.shape) != expected:
+            raise ValueError(
+                "Regional activation multiplier shape must match its geometry."
+            )
+        if not bool(torch.isfinite(self.multipliers).all()):
+            raise ValueError("Regional activation multipliers must be finite.")
+        if not bool(((self.multipliers >= 0.0) & (self.multipliers <= 1.0)).all()):
+            raise ValueError("Regional activation multipliers must stay within [0, 1].")
+
+
+class RegionalActivationMaskProjector:
+    """Own geometry-shaped mask projection around existing crop/interpolation."""
+
+    def __init__(self, projector: RegionalMaskProjector | None = None) -> None:
+        """Retain the canonical mask crop and interpolation authority."""
+
+        self._projector = projector or RegionalMaskProjector()
+
+    def project(
+        self,
+        *,
+        bank: RegionalMaskBank,
+        geometry: RegionalActivationGeometry,
+        form: RegionalMaskForm,
+        mode: RegionalMaskProjectionMode,
+        device: torch.device,
+        dtype: torch.dtype,
+    ) -> RegionalActivationMaskBatch:
+        """Return masks in region/view/chunk/latent activation order."""
+
+        _validate_inputs(bank, geometry, form, mode, device, dtype)
+        layout = geometry.batch_alignment.spatial_layout or _full_layout(
+            bank,
+            input_batch_size=geometry.batch_alignment.base_batch_size,
+        )
+        projected_views = tuple(
+            self._projector.project_query_grid(
+                bank=bank,
+                layout=layout,
+                view_index=view_index,
+                query_height=geometry.spatial_height,
+                query_width=geometry.spatial_width,
+                form=form,
+                mode=mode,
+            )
+            for view_index in range(layout.view_count)
+        )
+        masks = torch.cat(
+            tuple(
+                projected.unsqueeze(1).expand(
+                    -1,
+                    layout.input_batch_size,
+                    -1,
+                    -1,
+                )
+                for projected in projected_views
+            ),
+            dim=1,
+        ).to(device=device, dtype=dtype)
+        multipliers = _reshape_for_activation(masks, geometry)
+        return RegionalActivationMaskBatch(multipliers, geometry)
+
+
+def _reshape_for_activation(
+    masks: torch.Tensor,
+    geometry: RegionalActivationGeometry,
+) -> torch.Tensor:
+    """Place projected H/W masks on the declared operation's non-feature axes."""
+
+    regions, batch, height, width = (int(value) for value in masks.shape)
+    if geometry.layout is RegionalActivationLayout.DIRECT_CONVOLUTION_1D:
+        if height != 1:
+            raise ValueError("Conv1d regional masks require projected height one.")
+        return masks.reshape(regions, batch, 1, width)
+    if geometry.layout is RegionalActivationLayout.DIRECT_CONVOLUTION_2D:
+        return masks.reshape(regions, batch, 1, height, width)
+    if geometry.layout is RegionalActivationLayout.DIRECT_CONVOLUTION_3D:
+        temporal_size = geometry.temporal_size
+        if temporal_size is None:
+            raise ValueError("Conv3d regional masks require explicit temporal size.")
+        return masks.reshape(regions, batch, 1, 1, height, width).expand(
+            -1,
+            -1,
+            -1,
+            temporal_size,
+            -1,
+            -1,
+        )
+    if geometry.layout in (
+        RegionalActivationLayout.FLATTENED_SPATIAL_TOKENS,
+        RegionalActivationLayout.CONSUMER_SPATIALIZED,
+    ):
+        return masks.flatten(start_dim=2).unsqueeze(-1)
+    raise AssertionError(f"Unhandled regional activation layout: {geometry.layout}")
+
+
+def _full_layout(
+    bank: RegionalMaskBank,
+    *,
+    input_batch_size: int,
+) -> SpatialBatchLayout:
+    """Represent one full-canvas invocation through the shared layout contract."""
+
+    return SpatialBatchLayout(
+        bank.canvas_width,
+        bank.canvas_height,
+        (
+            SpatialView(
+                SpatialViewKind.FULL,
+                0,
+                0,
+                bank.canvas_width,
+                bank.canvas_height,
+                bank.canvas_width,
+                bank.canvas_height,
+            ),
+        ),
+        input_batch_size,
+    )
+
+
+def _validate_inputs(
+    bank: object,
+    geometry: object,
+    form: object,
+    mode: object,
+    device: object,
+    dtype: object,
+) -> None:
+    """Validate typed projection inputs without moving or mutating source masks."""
+
+    if not isinstance(bank, RegionalMaskBank):
+        raise TypeError("Regional activation projection requires a mask bank.")
+    if not isinstance(geometry, RegionalActivationGeometry):
+        raise TypeError("Regional activation projection requires geometry.")
+    if not isinstance(form, RegionalMaskForm):
+        raise TypeError("Regional activation mask form has an invalid type.")
+    if not isinstance(mode, RegionalMaskProjectionMode):
+        raise TypeError("Regional activation projection mode has an invalid type.")
+    if not isinstance(device, torch.device):
+        raise TypeError("Regional activation mask device must be a torch.device.")
+    if not isinstance(dtype, torch.dtype) or not dtype.is_floating_point:
+        raise TypeError("Regional activation mask dtype must be floating point.")
+
+
+REGIONAL_ACTIVATION_MASK_PROJECTOR = RegionalActivationMaskProjector()

simple_syrup/masking/regional_detailing_masks.py

@@ -21,8 +21,8 @@ from ..domain.regional_detailing import (
     SegmentConditioningPair,
 )
 from ..domain.segs import CropRegion
+from ..domain.segs_mask_ops import feather_mask, resize_mask
 from .detailer_masks import gaussian_feather_mask
-from .segs_mask_ops import feather_mask, resize_mask
 
 OPERATION = "Detail SEGS as Regions"
 

simple_syrup/masking/regional_mask_activation.py

@@ -0,0 +1,125 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Classify active regional coverage on one projected query grid."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+import torch
+
+
+class RegionalCoverageClass(StrEnum):
+    """Identify model branches required by one regional mask projection."""
+
+    ALL_BASE = "all_base"
+    ALL_SINGLE_REGION = "all_single_region"
+    MIXED = "mixed"
+
+
+@dataclass(frozen=True, slots=True)
+class RegionalMaskActivation:
+    """Describe ordered active regions and an admitted coverage fast path."""
+
+    coverage_class: RegionalCoverageClass
+    active_region_indices: tuple[int, ...]
+    single_region_index: int | None
+
+    def __post_init__(self) -> None:
+        """Require one internally consistent immutable classification."""
+
+        if not isinstance(self.coverage_class, RegionalCoverageClass):
+            raise TypeError(
+                "Regional coverage class must be a RegionalCoverageClass value."
+            )
+        if not isinstance(self.active_region_indices, tuple):
+            raise TypeError("Active regional indices must be an immutable tuple.")
+        if any(index < 0 for index in self.active_region_indices):
+            raise ValueError("Active regional indices must be non-negative.")
+        if tuple(sorted(set(self.active_region_indices))) != self.active_region_indices:
+            raise ValueError("Active regional indices must be unique and ordered.")
+        if self.coverage_class is RegionalCoverageClass.ALL_BASE:
+            if self.active_region_indices or self.single_region_index is not None:
+                raise ValueError("All-base coverage cannot contain an active region.")
+            return
+        if self.coverage_class is RegionalCoverageClass.ALL_SINGLE_REGION:
+            if (
+                len(self.active_region_indices) != 1
+                or self.single_region_index != self.active_region_indices[0]
+            ):
+                raise ValueError(
+                    "All-single-region coverage requires its one active region index."
+                )
+            return
+        if not self.active_region_indices:
+            raise ValueError("Mixed regional coverage requires an active region.")
+        if self.single_region_index is not None:
+            raise ValueError(
+                "Mixed regional coverage cannot select a fast-path region."
+            )
+
+
+class RegionalMaskActivationClassifier:
+    """Own zero-coverage pruning and regional fast-path admission."""
+
+    def classify(
+        self,
+        masks: torch.Tensor,
+        *,
+        tolerance: float = 1e-6,
+    ) -> RegionalMaskActivation:
+        """Return ordered active regions and the exact coverage classification."""
+
+        self._validate_masks(masks)
+        if not 0.0 <= tolerance < 0.5:
+            raise ValueError(
+                "Regional activation tolerance must be at least 0 and below 0.5."
+            )
+        active_region_indices = tuple(
+            index
+            for index in range(int(masks.shape[0]))
+            if bool((masks[index] > tolerance).any())
+        )
+        if not active_region_indices:
+            return RegionalMaskActivation(
+                coverage_class=RegionalCoverageClass.ALL_BASE,
+                active_region_indices=(),
+                single_region_index=None,
+            )
+        if len(active_region_indices) == 1:
+            region_index = active_region_indices[0]
+            if bool((masks[region_index] >= 1.0 - tolerance).all()):
+                return RegionalMaskActivation(
+                    coverage_class=RegionalCoverageClass.ALL_SINGLE_REGION,
+                    active_region_indices=active_region_indices,
+                    single_region_index=region_index,
+                )
+        return RegionalMaskActivation(
+            coverage_class=RegionalCoverageClass.MIXED,
+            active_region_indices=active_region_indices,
+            single_region_index=None,
+        )
+
+    @staticmethod
+    def _validate_masks(masks: torch.Tensor) -> None:
+        """Validate a projected normalized floating-point BHW mask batch."""
+
+        if not isinstance(masks, torch.Tensor):
+            raise TypeError("Regional activation masks must be a torch.Tensor.")
+        if masks.ndim != 3:
+            raise ValueError("Regional activation masks must use BHW layout.")
+        if int(masks.shape[0]) < 1:
+            raise ValueError("Regional activation requires at least one region.")
+        if int(masks.shape[1]) < 1 or int(masks.shape[2]) < 1:
+            raise ValueError("Regional activation mask grids must be non-empty.")
+        if not masks.is_floating_point():
+            raise TypeError(
+                "Regional activation masks must use a floating-point dtype."
+            )
+        if not bool(torch.isfinite(masks).all()):
+            raise ValueError("Regional activation masks must contain finite values.")
+        if not bool(((masks >= 0.0) & (masks <= 1.0)).all()):
+            raise ValueError("Regional activation masks must stay within [0, 1].")

simple_syrup/masking/regional_mask_projection.py

@@ -0,0 +1,176 @@
+# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
+# Copyright (C) 2026  Artificial Sweetener and contributors
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+"""Project canonical regional masks into spatial views and query grids."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+import torch
+import torch.nn.functional as functional
+
+from ..domain.regional_mask_bank import RegionalMaskBank
+from ..domain.spatial_views import SpatialBatchLayout, SpatialView
+
+
+class RegionalMaskForm(StrEnum):
+    """Select one canonical regional mask representation."""
+
+    PLANNING = "planning"
+    CONDITIONING = "conditioning"
+
+
+class RegionalMaskProjectionMode(StrEnum):
+    """Select the interpolation semantics for one mask projection."""
+
+    CONTINUOUS_COVERAGE = "continuous_coverage"
+    SOFT = "soft"
+    HARD_PRESERVING = "hard_preserving"
+    NEAREST = "nearest"
+
+
+class RegionalMaskProjector:
+    """Own canonical-canvas crop and interpolation policy for regional masks."""
+
+    def project_view(
+        self,
+        *,
+        bank: RegionalMaskBank,
+        layout: SpatialBatchLayout,
+        view_index: int,
+        form: RegionalMaskForm,
+        mode: RegionalMaskProjectionMode,
+    ) -> torch.Tensor:
+        """Project one canonical mask form to a view's model dimensions."""
+
+        view = self._view(bank=bank, layout=layout, view_index=view_index)
+        return self.project_query_grid(
+            bank=bank,
+            layout=layout,
+            view_index=view_index,
+            query_height=view.model_height,
+            query_width=view.model_width,
+            form=form,
+            mode=mode,
+        )
+
+    def project_query_grid(
+        self,
+        *,
+        bank: RegionalMaskBank,
+        layout: SpatialBatchLayout,
+        view_index: int,
+        query_height: int,
+        query_width: int,
+        form: RegionalMaskForm,
+        mode: RegionalMaskProjectionMode,
+    ) -> torch.Tensor:
+        """Crop one spatial view and resample it directly to an attention grid."""
+
+        if query_height < 1 or query_width < 1:
+            raise ValueError("Regional mask query-grid dimensions must be positive.")
+        if not isinstance(form, RegionalMaskForm):
+            raise TypeError("Regional mask form must be a RegionalMaskForm value.")
+        if not isinstance(mode, RegionalMaskProjectionMode):
+            raise TypeError(
+                "Regional mask projection mode must be a "
+                "RegionalMaskProjectionMode value."
+            )
+        view = self._view(bank=bank, layout=layout, view_index=view_index)
+        masks = (
+            bank.planning_masks
+            if form is RegionalMaskForm.PLANNING
+            else bank.conditioning_masks
+        )
+        cropped = masks[
+            :,
+            view.source_y : view.source_bottom,
+            view.source_x : view.source_right,
+        ]
+        projected = self._resize(
+            cropped,
+            height=query_height,
+            width=query_width,
+            mode=mode,
+        ).clamp(0.0, 1.0)
+        if not bool(torch.isfinite(projected).all()):
+            raise ValueError("Projected regional masks contain non-finite values.")
+        return projected
+
+    @staticmethod
+    def _view(
+        *,
+        bank: RegionalMaskBank,
+        layout: SpatialBatchLayout,
+        view_index: int,
+    ) -> SpatialView:
+        """Validate canonical canvas identity and return one indexed view."""
+
+        if (
+            bank.canvas_width != layout.canvas_width
+            or bank.canvas_height != layout.canvas_height
+        ):
+            raise ValueError(
+                "Regional mask bank canvas must match the spatial batch layout."
+            )
+        if view_index < 0 or view_index >= layout.view_count:
+            raise IndexError("Regional mask spatial view index is outside the layout.")
+        return layout.views[view_index]
+
+    @staticmethod
+    def _resize(
+        masks: torch.Tensor,
+        *,
+        height: int,
+        width: int,
+        mode: RegionalMaskProjectionMode,
+    ) -> torch.Tensor:
+        """Apply explicit coverage, soft, or hard-preserving interpolation."""
+
+        source_height = int(masks.shape[-2])
+        source_width = int(masks.shape[-1])
+        if (source_height, source_width) == (height, width):
+            return masks
+        batched = masks.unsqueeze(1)
+        if mode is RegionalMaskProjectionMode.HARD_PRESERVING:
+            return functional.interpolate(
+                batched,
+                size=(height, width),
+                mode="nearest-exact",
+            ).squeeze(1)
+        if mode is RegionalMaskProjectionMode.NEAREST:
+            return functional.interpolate(
+                batched,
+                size=(height, width),
+                mode="nearest",
+            ).squeeze(1)
+        if mode is RegionalMaskProjectionMode.SOFT:
+            return functional.interpolate(
+                batched,
+                size=(height, width),
+                mode="bilinear",
+                align_corners=False,
+            ).squeeze(1)
+
+        downsample_height = min(source_height, height)
+        downsample_width = min(source_width, width)
+        projected = batched
+        if (downsample_height, downsample_width) != (
+            source_height,
+            source_width,
+        ):
+            projected = functional.interpolate(
+                projected,
+                size=(downsample_height, downsample_width),
+                mode="area",
+            )
+        if tuple(projected.shape[-2:]) != (height, width):
+            projected = functional.interpolate(
+                projected,
+                size=(height, width),
+                mode="bilinear",
+                align_corners=False,
+            )
+        return projected.squeeze(1)

simple_syrup/masking/regional_prompt_masks.py

@@ -7,13 +7,53 @@
 from __future__ import annotations
 
 import torch
+import torch.nn.functional as functional
 
+from ..domain.regional_mask_bank import RegionalMaskBank
 from .detailer_masks import gaussian_feather_mask
 
 
 def prepare_regional_mask_batch(mask: object, feather: int) -> torch.Tensor:
     """Return a validated and optionally feathered BHW mask batch."""
 
+    _, conditioning = _prepare_regional_masks(mask, feather)
+    return conditioning
+
+
+def build_regional_mask_bank(
+    mask: object,
+    *,
+    feather: int,
+    canvas_height: int,
+    canvas_width: int,
+) -> RegionalMaskBank:
+    """Build separate planning and conditioning masks on one latent canvas."""
+
+    authored, feathered = _prepare_regional_masks(mask, feather)
+    planning_masks = resize_regional_mask_batch(
+        authored,
+        height=canvas_height,
+        width=canvas_width,
+    )
+    conditioning_masks = resize_regional_mask_batch(
+        feathered,
+        height=canvas_height,
+        width=canvas_width,
+    )
+    return RegionalMaskBank(
+        planning_masks=planning_masks,
+        conditioning_masks=conditioning_masks,
+        canvas_width=canvas_width,
+        canvas_height=canvas_height,
+    )
+
+
+def _prepare_regional_masks(
+    mask: object,
+    feather: int,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Return normalized authored masks and a separate feathered tensor."""
+
     if not isinstance(mask, torch.Tensor):
         raise TypeError("regional prompting requires a torch MASK tensor.")
     if feather < 0:
@@ -30,9 +70,44 @@ def prepare_regional_mask_batch(mask: object, feather: int) -> torch.Tensor:
         raise ValueError("regional masks must have non-empty height and width.")
 
     normalized = working.clamp(0.0, 1.0)
-    if feather == 0:
-        return normalized
-    return gaussian_feather_mask(normalized, feather)
+    conditioning = (
+        normalized.to(device=normalized.device, dtype=normalized.dtype, copy=True)
+        if feather == 0
+        else gaussian_feather_mask(normalized, feather)
+    )
+    return normalized, conditioning
+
+
+def resize_regional_mask_batch(
+    mask_batch: torch.Tensor,
+    *,
+    height: int,
+    width: int,
+) -> torch.Tensor:
+    """Resize BHW masks while preserving authored area during downscaling."""
+
+    if height < 1 or width < 1:
+        raise ValueError("regional mask target height and width must be positive.")
+    if tuple(mask_batch.shape[1:]) == (height, width):
+        return mask_batch
+    source_height, source_width = map(int, mask_batch.shape[1:])
+    downscaled_height = min(height, source_height)
+    downscaled_width = min(width, source_width)
+    working = mask_batch.unsqueeze(1)
+    if (downscaled_height, downscaled_width) != (source_height, source_width):
+        working = functional.interpolate(
+            working,
+            size=(downscaled_height, downscaled_width),
+            mode="area",
+        )
+    if (downscaled_height, downscaled_width) != (height, width):
+        working = functional.interpolate(
+            working,
+            size=(height, width),
+            mode="bilinear",
+            align_corners=False,
+        )
+    return working.squeeze(1)
 
 
 def regional_mask(mask_batch: torch.Tensor, index: int) -> torch.Tensor:

simple_syrup/nodes/detail_segs_as_regions.py

@@ -10,6 +10,7 @@ from typing import Any, ClassVar
 
 import torch
 
+from ..domain.noise_inversion import NoiseInversionOptions
 from ..domain.segs import coerce_segs_group
 from ..nodes import tooltips
 from ..nodes.detailer_input_adapters import (
@@ -64,10 +65,6 @@ class DetailSEGSAsRegions:
                 "image": ("IMAGE", {"tooltip": tooltips.DETAIL_IMAGE}),
                 "model": ("MODEL", {"tooltip": tooltips.DETAIL_MODEL}),
                 "vae": ("VAE", {"tooltip": tooltips.DETAIL_VAE}),
-                "negative": (
-                    "CONDITIONING",
-                    {"tooltip": tooltips.REGIONAL_GLOBAL_NEGATIVE},
-                ),
                 "positive": (
                     "CONDITIONING",
                     {"tooltip": tooltips.REGIONAL_GLOBAL_POSITIVE},
@@ -187,7 +184,13 @@ class DetailSEGSAsRegions:
                         "tooltip": tooltips.DETAIL_TILED_DECODE,
                     },
                 ),
-            }
+            },
+            "optional": {
+                "negative": (
+                    "CONDITIONING",
+                    {"tooltip": tooltips.REGIONAL_GLOBAL_NEGATIVE},
+                ),
+            },
         }
 
     def detail(
@@ -195,24 +198,25 @@ class DetailSEGSAsRegions:
         image: object,
         model: Any,
         vae: Any,
-        negative: Any,
-        positive: Any,
-        segs: object,
-        region_positive: object,
-        global_prompt_weight: object,
-        scale_factor: object,
-        upscale_method: object,
-        seed: object,
-        steps: object,
-        cfg: object,
-        sampler_name: object,
-        scheduler: object,
-        denoise: object,
-        feather: object,
-        noise_mask: object,
-        noise_mask_feather: object,
-        tiled_encode: object,
-        tiled_decode: object,
+        negative: Any | None = None,
+        positive: Any = None,
+        segs: object = None,
+        region_positive: object = None,
+        global_prompt_weight: object = 0.25,
+        scale_factor: object = 1.0,
+        upscale_method: object = "lanczos",
+        seed: object = 0,
+        steps: object = 20,
+        cfg: object = 8.0,
+        sampler_name: object = "euler",
+        scheduler: object = "normal",
+        denoise: object = 0.5,
+        feather: object = 5,
+        noise_mask: object = True,
+        noise_mask_feather: object = 20,
+        tiled_encode: object = False,
+        tiled_decode: object = False,
+        noise_inversion: NoiseInversionOptions | None = None,
     ) -> tuple[object]:
         """Run regional detailing and return the detailed image."""
 
@@ -235,6 +239,7 @@ class DetailSEGSAsRegions:
             strict=True,
         ):
             result = service.detail(
+                noise_inversion=noise_inversion,
                 image=single_image,
                 segs=single_segs,
                 model=single_input(model, "model", list_mode, OPERATION),

simple_syrup/nodes/detail_segs_by_scale_factor.py

@@ -61,10 +61,6 @@ class DetailSEGSByScaleFactor:
                     "CONDITIONING,CONDITIONING_BATCH",
                     {"tooltip": tooltips.DETAIL_POSITIVE},
                 ),
-                "negative": (
-                    "CONDITIONING,CONDITIONING_BATCH",
-                    {"tooltip": tooltips.DETAIL_NEGATIVE},
-                ),
                 "scale_factor": (
                     "FLOAT",
                     scale_factor_options(default=1.5),
@@ -171,7 +167,13 @@ class DetailSEGSByScaleFactor:
                         "tooltip": tooltips.DETAIL_TILED_DECODE,
                     },
                 ),
-            }
+            },
+            "optional": {
+                "negative": (
+                    "CONDITIONING,CONDITIONING_BATCH",
+                    {"tooltip": tooltips.DETAIL_NEGATIVE},
+                ),
+            },
         }
 
     def detail(
@@ -181,21 +183,21 @@ class DetailSEGSByScaleFactor:
         model: Any,
         vae: Any,
         positive: Any,
-        negative: Any,
-        scale_factor: object,
-        upscale_method: object,
-        clamp_size: object,
-        seed: object,
-        steps: object,
-        cfg: object,
-        sampler_name: object,
-        scheduler: object,
-        denoise: object,
-        feather: object,
-        noise_mask: object,
-        noise_mask_feather: object,
-        tiled_encode: object,
-        tiled_decode: object,
+        negative: Any | None = None,
+        scale_factor: object = 1.5,
+        upscale_method: object = "lanczos",
+        clamp_size: object = 0,
+        seed: object = 0,
+        steps: object = 20,
+        cfg: object = 8.0,
+        sampler_name: object = "euler",
+        scheduler: object = "normal",
+        denoise: object = 0.5,
+        feather: object = 5,
+        noise_mask: object = True,
+        noise_mask_feather: object = 20,
+        tiled_encode: object = False,
+        tiled_decode: object = False,
     ) -> tuple[object]:
         """Run scale-factor detailing and return the detailed image."""
 

simple_syrup/nodes/detail_segs_by_scale_factor_tiled_diffusion.py

@@ -10,6 +10,7 @@ from typing import Any, ClassVar
 
 import torch
 
+from ..domain.noise_inversion import NoiseInversionOptions
 from ..domain.segs import coerce_segs_group
 from ..domain.tiled_diffusion import TILED_DIFFUSION_MODES
 from ..nodes import tooltips
@@ -70,10 +71,6 @@ class DetailSEGSByScaleFactorTiledDiffusion:
                     "CONDITIONING,CONDITIONING_BATCH",
                     {"tooltip": tooltips.DETAIL_POSITIVE},
                 ),
-                "negative": (
-                    "CONDITIONING,CONDITIONING_BATCH",
-                    {"tooltip": tooltips.DETAIL_NEGATIVE},
-                ),
                 "scale_factor": (
                     "FLOAT",
                     scale_factor_options(default=1.5),
@@ -231,7 +228,13 @@ class DetailSEGSByScaleFactorTiledDiffusion:
                         "tooltip": tooltips.LATENT_TILE_BATCH_SIZE,
                     },
                 ),
-            }
+            },
+            "optional": {
+                "negative": (
+                    "CONDITIONING,CONDITIONING_BATCH",
+                    {"tooltip": tooltips.DETAIL_NEGATIVE},
+                ),
+            },
         }
 
     def detail(
@@ -241,26 +244,27 @@ class DetailSEGSByScaleFactorTiledDiffusion:
         model: Any,
         vae: Any,
         positive: Any,
-        negative: Any,
-        scale_factor: object,
-        upscale_method: object,
-        clamp_size: object,
-        seed: object,
-        steps: object,
-        cfg: object,
-        sampler_name: object,
-        scheduler: object,
-        denoise: object,
-        feather: object,
-        noise_mask: object,
-        noise_mask_feather: object,
-        tiled_encode: object,
-        tiled_decode: object,
-        diffusion_mode: object,
-        latent_tile_width: object,
-        latent_tile_height: object,
-        latent_tile_overlap: object,
-        latent_tile_batch_size: object,
+        negative: Any | None = None,
+        scale_factor: object = 1.5,
+        upscale_method: object = "lanczos",
+        clamp_size: object = 0,
+        seed: object = 0,
+        steps: object = 20,
+        cfg: object = 8.0,
+        sampler_name: object = "euler",
+        scheduler: object = "normal",
+        denoise: object = 0.5,
+        feather: object = 5,
+        noise_mask: object = True,
+        noise_mask_feather: object = 20,
+        tiled_encode: object = False,
+        tiled_decode: object = False,
+        diffusion_mode: object = "multidiffusion",
+        latent_tile_width: object = 128,
+        latent_tile_height: object = 128,
+        latent_tile_overlap: object = 16,
+        latent_tile_batch_size: object = 4,
+        noise_inversion: NoiseInversionOptions | None = None,
     ) -> tuple[object]:
         """Run tiled diffusion scale-factor detailing and return the image."""
 
@@ -273,6 +277,7 @@ class DetailSEGSByScaleFactorTiledDiffusion:
         outputs: list[torch.Tensor] = []
         for single_image, single_segs in zip(images, segs_group, strict=True):
             result = service.detail(
+                noise_inversion=noise_inversion,
                 image=single_image,
                 segs=single_segs,
                 model=single_input(model, "model", list_mode, OPERATION),

simple_syrup/nodes/detailer_input_adapters.py

@@ -12,7 +12,7 @@ import torch
 
 from ..domain.conditioning_batch import ConditioningBatch
 from ..domain.segs import NativeSegs
-from ..masking.segs_mask_ops import iter_single_images, validate_image_batch
+from ..domain.segs_mask_ops import iter_single_images, validate_image_batch
 
 
 def image_inputs(image: object, operation_name: str) -> tuple[torch.Tensor, ...]:

simple_syrup/nodes/detect_segs_with_ultralytics.py

@@ -16,8 +16,8 @@ from ..domain.segs import (
     SORT_ORDER_OPTIONS,
     NativeSegs,
 )
-from ..masking.segs_mask_ops import iter_single_images, validate_image_batch
-from ..runtime.ultralytics_loader import UltralyticsDetectorModel
+from ..domain.segs_mask_ops import iter_single_images, validate_image_batch
+from ..runtime.ultralytics_model_adapter import UltralyticsDetectorModel
 from ..services.segs_detection_service import (
     SegsDetectionService,
 )

simple_syrup/nodes/grounded_sam_model_info.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from ..runtime.model_catalog import grounding_dino_choices, sam_choices
+from ..runtime.model_choices import ModelChoiceService, default_choice
 from ..runtime.model_metadata import GroundedSAMModelMetadata
 from . import tooltips
 
@@ -17,6 +17,7 @@ class GroundedSAMModelInfo:
     """Expose selected grounded SAM source and local path metadata."""
 
     _metadata = GroundedSAMModelMetadata()
+    _choices = ModelChoiceService()
 
     RETURN_TYPES = ("STRING",)
     RETURN_NAMES = ("model_info",)
@@ -31,19 +32,27 @@ class GroundedSAMModelInfo:
     def INPUT_TYPES(cls) -> dict[str, dict[str, tuple[Any, ...]]]:
         """Declare deterministic model metadata inputs."""
 
+        sam_model_choices = cls._choices.sam_choices()
+        grounding_dino_model_choices = cls._choices.grounding_dino_choices()
         return {
             "required": {
                 "sam_model": (
-                    sam_choices(),
+                    sam_model_choices,
                     {
-                        "default": "sam_hq_vit_b (379MB)",
+                        "default": default_choice(
+                            sam_model_choices,
+                            "sam_hq_vit_b (379MB)",
+                        ),
                         "tooltip": tooltips.SAM_MODEL_INPUT,
                     },
                 ),
                 "grounding_dino_model": (
-                    grounding_dino_choices(),
+                    grounding_dino_model_choices,
                     {
-                        "default": "GroundingDINO_SwinT_OGC (694MB)",
+                        "default": default_choice(
+                            grounding_dino_model_choices,
+                            "GroundingDINO_SwinT_OGC (694MB)",
+                        ),
                         "tooltip": tooltips.GROUNDING_DINO_MODEL_INPUT,
                     },
                 ),
@@ -53,4 +62,6 @@ class GroundedSAMModelInfo:
     def describe(self, sam_model: str, grounding_dino_model: str) -> tuple[str]:
         """Return JSON metadata for selected model entries."""
 
+        self._choices.reject_sentinel(sam_model)
+        self._choices.reject_sentinel(grounding_dino_model)
         return (self._metadata.describe_selection(sam_model, grounding_dino_model),)

simple_syrup/nodes/ksampler_contextual_diffusion.py

@@ -1,232 +0,0 @@
-# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
-# Copyright (C) 2026  Artificial Sweetener and contributors
-# SPDX-License-Identifier: AGPL-3.0-or-later
-
-"""ComfyUI node declaration for contextual diffusion sampling."""
-
-from __future__ import annotations
-
-from typing import Any, ClassVar, TypeAlias
-
-from ..domain.tiled_diffusion import TILED_DIFFUSION_MODES
-from ..runtime import sampling_samplers, sampling_schedulers
-from ..services.contextual_diffusion_sampling_service import (
-    ContextualDiffusionSamplingService,
-)
-from . import tooltips
-
-Latent: TypeAlias = dict[str, Any]
-MAX_LATENT_CONTEXT_SIZE = 512
-
-
-class KSamplerContextualDiffusion:
-    """Edit large latents through coordinated global and detailed contexts."""
-
-    RETURN_TYPES = ("LATENT", "SEGS")
-    RETURN_NAMES = ("latent", "contexts_segs")
-    OUTPUT_TOOLTIPS = (
-        tooltips.DENOISED_LATENT_OUTPUT,
-        tooltips.CONTEXTUAL_DIFFUSION_CONTEXTS_OUTPUT,
-    )
-    FUNCTION = "sample"
-    CATEGORY = "SimpleSyrup/Sampling"
-    DESCRIPTION = (
-        "Preserves composition while applying appearance and subject-detail edits "
-        "to large latents through global context and optional SEGS-guided tiles."
-    )
-    SEARCH_ALIASES = [
-        "ksampler",
-        "contextual diffusion",
-        "contextual tiled diffusion",
-        "high resolution edit",
-        "sam tiled diffusion",
-    ]
-
-    service_class: ClassVar[type[ContextualDiffusionSamplingService]] = (
-        ContextualDiffusionSamplingService
-    )
-
-    @classmethod
-    def INPUT_TYPES(cls) -> dict[str, dict[str, tuple[Any, ...]]]:
-        """Declare KSampler inputs and bounded contextual controls."""
-
-        return {
-            "required": {
-                "model": ("MODEL", {"tooltip": tooltips.SAMPLING_MODEL}),
-                "seed": (
-                    "INT",
-                    {
-                        "default": 0,
-                        "min": 0,
-                        "max": 0xFFFFFFFFFFFFFFFF,
-                        "control_after_generate": True,
-                        "tooltip": tooltips.SAMPLING_SEED,
-                    },
-                ),
-                "steps": (
-                    "INT",
-                    {
-                        "default": 4,
-                        "min": 1,
-                        "max": 10000,
-                        "tooltip": tooltips.SAMPLING_STEPS,
-                    },
-                ),
-                "cfg": (
-                    "FLOAT",
-                    {
-                        "default": 1.0,
-                        "min": 0.0,
-                        "max": 100.0,
-                        "step": 0.1,
-                        "round": 0.01,
-                        "tooltip": tooltips.SAMPLING_CFG,
-                    },
-                ),
-                "sampler_name": (
-                    sampling_samplers.available_samplers(),
-                    {"tooltip": tooltips.SAMPLER_NAME},
-                ),
-                "scheduler": (
-                    sampling_schedulers.available_schedulers(),
-                    {"tooltip": tooltips.SCHEDULER},
-                ),
-                "positive": (
-                    "CONDITIONING,CONDITIONING_BATCH",
-                    {"tooltip": tooltips.POSITIVE_CONDITIONING},
-                ),
-                "negative": (
-                    "CONDITIONING,CONDITIONING_BATCH",
-                    {"tooltip": tooltips.NEGATIVE_CONDITIONING},
-                ),
-                "latent_image": ("LATENT", {"tooltip": tooltips.LATENT_IMAGE}),
-                "denoise": (
-                    "FLOAT",
-                    {
-                        "default": 1.0,
-                        "min": 0.0,
-                        "max": 1.0,
-                        "step": 0.01,
-                        "tooltip": tooltips.DENOISE_STRENGTH,
-                    },
-                ),
-                "diffusion_mode": (
-                    list(TILED_DIFFUSION_MODES),
-                    {
-                        "default": "multidiffusion",
-                        "tooltip": tooltips.TILED_DIFFUSION_MODE,
-                    },
-                ),
-                "latent_context_size": (
-                    "INT",
-                    {
-                        "default": 96,
-                        "min": 16,
-                        "max": MAX_LATENT_CONTEXT_SIZE,
-                        "step": 16,
-                        "tooltip": tooltips.LATENT_CONTEXT_SIZE,
-                    },
-                ),
-                "latent_context_overlap": (
-                    "INT",
-                    {
-                        "default": 32,
-                        "min": 0,
-                        "max": 256,
-                        "step": 4,
-                        "tooltip": tooltips.LATENT_CONTEXT_OVERLAP,
-                    },
-                ),
-                "latent_context_batch_size": (
-                    "INT",
-                    {
-                        "default": 4,
-                        "min": 1,
-                        "max": 8,
-                        "step": 1,
-                        "tooltip": tooltips.LATENT_CONTEXT_BATCH_SIZE,
-                    },
-                ),
-                "global_weight": (
-                    "FLOAT",
-                    {
-                        "default": 1.0,
-                        "min": 0.0,
-                        "max": 2.0,
-                        "step": 0.05,
-                        "tooltip": tooltips.GLOBAL_CONTEXT_WEIGHT,
-                    },
-                ),
-                "global_steps": (
-                    "INT",
-                    {
-                        "default": 1,
-                        "min": 0,
-                        "max": 10000,
-                        "step": 1,
-                        "tooltip": tooltips.GLOBAL_CONTEXT_STEPS,
-                    },
-                ),
-                "global_decay": (
-                    "FLOAT",
-                    {
-                        "default": 0.5,
-                        "min": 0.0,
-                        "max": 1.0,
-                        "step": 0.05,
-                        "tooltip": tooltips.GLOBAL_CONTEXT_DECAY,
-                    },
-                ),
-            },
-            "optional": {
-                "segs": (
-                    "SEGS",
-                    {"tooltip": tooltips.CONTEXTUAL_DIFFUSION_SEGS},
-                )
-            },
-        }
-
-    def sample(
-        self,
-        model: Any,
-        seed: int,
-        steps: int,
-        cfg: float,
-        sampler_name: str,
-        scheduler: str,
-        positive: Any,
-        negative: Any,
-        latent_image: Latent,
-        denoise: float = 1.0,
-        diffusion_mode: str = "multidiffusion",
-        latent_context_size: int = 96,
-        latent_context_overlap: int = 32,
-        latent_context_batch_size: int = 4,
-        global_weight: float = 1.0,
-        global_steps: int = 1,
-        global_decay: float = 0.5,
-        segs: object | None = None,
-    ) -> tuple[Latent, object]:
-        """Delegate contextual diffusion sampling to its application service."""
-
-        result = self.service_class().sample(
-            model=model,
-            seed=seed,
-            steps=steps,
-            cfg=cfg,
-            sampler_name=sampler_name,
-            scheduler=scheduler,
-            positive=positive,
-            negative=negative,
-            latent_image=latent_image,
-            denoise=denoise,
-            diffusion_mode=diffusion_mode,
-            latent_context_size=latent_context_size,
-            latent_context_overlap=latent_context_overlap,
-            latent_context_batch_size=latent_context_batch_size,
-            global_weight=global_weight,
-            global_steps=global_steps,
-            global_decay=global_decay,
-            segs=segs,
-        )
-        return result.latent, result.contexts

simple_syrup/nodes/ksampler_extras.py

@@ -78,10 +78,6 @@ class KSamplerExtras:
                     "CONDITIONING,CONDITIONING_BATCH",
                     {"tooltip": tooltips.POSITIVE_CONDITIONING},
                 ),
-                "negative": (
-                    "CONDITIONING,CONDITIONING_BATCH",
-                    {"tooltip": tooltips.NEGATIVE_CONDITIONING},
-                ),
                 "latent_image": ("LATENT", {"tooltip": tooltips.LATENT_IMAGE}),
                 "denoise": (
                     "FLOAT",
@@ -93,7 +89,13 @@ class KSamplerExtras:
                         "tooltip": tooltips.DENOISE_STRENGTH,
                     },
                 ),
-            }
+            },
+            "optional": {
+                "negative": (
+                    "CONDITIONING,CONDITIONING_BATCH",
+                    {"tooltip": tooltips.NEGATIVE_CONDITIONING},
+                ),
+            },
         }
 
     def sample(
@@ -105,12 +107,14 @@ class KSamplerExtras:
         sampler_name: str,
         scheduler: str,
         positive: Any,
-        negative: Any,
-        latent_image: Latent,
+        negative: Any | None = None,
+        latent_image: Latent | None = None,
         denoise: float = 1.0,
     ) -> tuple[Latent]:
         """Sample a latent with ComfyUI samplers and extra scheduler sigmas."""
 
+        if latent_image is None:
+            raise TypeError("KSampler Extras requires a latent_image input.")
         output = self.service_class().sample(
             model=model,
             seed=seed,

simple_syrup/nodes/ksampler_tiled_diffusion.py

@@ -1,206 +0,0 @@
-# SimpleSyrup - workflow-focused ComfyUI extensions for image generation
-# Copyright (C) 2026  Artificial Sweetener and contributors
-# SPDX-License-Identifier: AGPL-3.0-or-later
-
-"""ComfyUI node declaration for selectable tiled diffusion sampling."""
-
-from __future__ import annotations
-
-from typing import Any, ClassVar
-
-from ..domain.tiled_diffusion import TILED_DIFFUSION_MODES
-from ..runtime import sampling_samplers, sampling_schedulers
-from ..services.tiled_diffusion_sampling_service import TiledDiffusionSamplingService
-from . import tooltips
-
-Latent = dict[str, Any]
-MAX_LATENT_TILE_SIZE = 512
-
-
-class KSamplerTiledDiffusion:
-    """Sample latents with selectable tiled diffusion denoising."""
-
-    RETURN_TYPES = ("LATENT",)
-    OUTPUT_TOOLTIPS = (tooltips.DENOISED_LATENT_OUTPUT,)
-    FUNCTION = "sample"
-    CATEGORY = "SimpleSyrup/Sampling"
-    DESCRIPTION = "Denoises latents with selectable tiled diffusion sampling."
-    SEARCH_ALIASES = [
-        "ksampler",
-        "sampler",
-        "tiled diffusion",
-        "multidiffusion",
-        "multi diffusion",
-        "mixture of diffusers",
-    ]
-
-    service_class: ClassVar[type[TiledDiffusionSamplingService]] = (
-        TiledDiffusionSamplingService
-    )
-
-    @classmethod
-    def INPUT_TYPES(cls) -> dict[str, dict[str, tuple[Any, ...]]]:
-        """Declare ComfyUI inputs for selectable tiled diffusion sampling."""
-
-        return {
-            "required": {
-                "model": ("MODEL", {"tooltip": tooltips.SAMPLING_MODEL}),
-                "seed": (
-                    "INT",
-                    {
-                        "default": 0,
-                        "min": 0,
-                        "max": 0xFFFFFFFFFFFFFFFF,
-                        "control_after_generate": True,
-                        "tooltip": tooltips.SAMPLING_SEED,
-                    },
-                ),
-                "steps": (
-                    "INT",
-                    {
-                        "default": 20,
-                        "min": 1,
-                        "max": 10000,
-                        "tooltip": tooltips.SAMPLING_STEPS,
-                    },
-                ),
-                "cfg": (
-                    "FLOAT",
-                    {
-                        "default": 8.0,
-                        "min": 0.0,
-                        "max": 100.0,
-                        "step": 0.1,
-                        "round": 0.01,
-                        "tooltip": tooltips.SAMPLING_CFG,
-                    },
-                ),
-                "sampler_name": (
-                    sampling_samplers.available_samplers(),
-                    {"tooltip": tooltips.SAMPLER_NAME},
-                ),
-                "scheduler": (
-                    sampling_schedulers.available_schedulers(),
-                    {"tooltip": tooltips.SCHEDULER},
-                ),
-                "positive": (
-                    "CONDITIONING,CONDITIONING_BATCH",
-                    {"tooltip": tooltips.POSITIVE_CONDITIONING},
-                ),
-                "negative": (
-                    "CONDITIONING,CONDITIONING_BATCH",
-                    {"tooltip": tooltips.NEGATIVE_CONDITIONING},
-                ),
-                "latent_image": ("LATENT", {"tooltip": tooltips.LATENT_IMAGE}),
-                "denoise": (
-                    "FLOAT",
-                    {
-                        "default": 1.0,
-                        "min": 0.0,
-                        "max": 1.0,
-                        "step": 0.01,
-                        "tooltip": tooltips.DENOISE_STRENGTH,
-                    },
-                ),
-                "diffusion_mode": (
-                    list(TILED_DIFFUSION_MODES),
-                    {
-                        "default": "multidiffusion",
-                        "tooltip": tooltips.TILED_DIFFUSION_MODE,
-                    },
-                ),
-                "latent_tile_width": (
-                    "INT",
-                    {
-                        "default": 128,
-                        "min": 16,
-                        "max": MAX_LATENT_TILE_SIZE,
-                        "step": 16,
-                        "tooltip": tooltips.LATENT_TILE_WIDTH,
-                    },
-                ),
-                "latent_tile_height": (
-                    "INT",
-                    {
-                        "default": 128,
-                        "min": 16,
-                        "max": MAX_LATENT_TILE_SIZE,
-                        "step": 16,
-                        "tooltip": tooltips.LATENT_TILE_HEIGHT,
-                    },
-                ),
-                "latent_tile_overlap": (
-                    "INT",
-                    {
-                        "default": 16,
-                        "min": 0,
-                        "max": 256,
-                        "step": 4,
-                        "tooltip": tooltips.LATENT_TILE_OVERLAP,
-                    },
-                ),
-                "latent_tile_batch_size": (
-                    "INT",
-                    {
-                        "default": 4,
-                        "min": 1,
-                        "max": 8,
-                        "step": 1,
-                        "tooltip": tooltips.LATENT_TILE_BATCH_SIZE,
-                    },
-                ),
-            },
-            "optional": {
-                "segs": (
-                    "SEGS",
-                    {
-                        "tooltip": (
-                            "Optional image regions that guide irregular tile "
-                            "boundaries while preserving the configured overlap."
-                        ),
-                    },
-                ),
-            },
-        }
-
-    def sample(
-        self,
-        model: Any,
-        seed: int,
-        steps: int,
-        cfg: float,
-        sampler_name: str,
-        scheduler: str,
-        positive: Any,
-        negative: Any,
-        latent_image: Latent,
-        denoise: float = 1.0,
-        diffusion_mode: str = "multidiffusion",
-        latent_tile_width: int = 128,
-        latent_tile_height: int = 128,
-        latent_tile_overlap: int = 16,
-        latent_tile_batch_size: int = 4,
-        segs: object | None = None,
-    ) -> tuple[Latent]:
-        """Sample a latent with the selected tiled diffusion method."""
-
-        output = self.service_class().sample(
-            diffusion_mode=diffusion_mode,
-            model=model,
-            seed=seed,
-            steps=steps,
-            cfg=cfg,
-            sampler_name=sampler_name,
-            scheduler=scheduler,
-            positive=positive,
-            negative=negative,
-            latent_image=latent_image,
-            denoise=denoise,
-            latent_tile_width=latent_tile_width,
-            latent_tile_height=latent_tile_height,
-            latent_tile_overlap=latent_tile_overlap,
-            latent_tile_batch_size=latent_tile_batch_size,
-            preview_context=None,
-            segs=segs,
-        )
-        return (output,)

simple_syrup/nodes/load_ultralytics_model.py

@@ -8,7 +8,8 @@ from __future__ import annotations
 
 from typing import Any, ClassVar
 
-from ..runtime.ultralytics_loader import UltralyticsLoaderService
+from ..runtime.model_downloads import ComfyProgressReporter
+from ..services.ultralytics_loader_service import UltralyticsLoaderService
 
 
 class LoadUltralyticsModel:
@@ -40,7 +41,8 @@ class LoadUltralyticsModel:
                     {
                         "default": choices[0],
                         "tooltip": (
-                            "Ultralytics model file in the ComfyUI models folder."
+                            "A local Ultralytics model or a curated model that "
+                            "downloads to ComfyUI's Impact Pack-compatible folders."
                         ),
                     },
                 )
@@ -50,5 +52,8 @@ class LoadUltralyticsModel:
     def load(self, model_name: str) -> tuple[object, object, object]:
         """Load the selected detector and paired compatibility facades."""
 
-        loaded = self.service_class().load(model_name)
+        loaded = self.service_class().load(
+            model_name,
+            progress=ComfyProgressReporter(),
+        )
         return loaded.detector_model, loaded.bbox_detector, loaded.segm_detector

simple_syrup/nodes/prompt_segs_with_sam.py

@@ -16,9 +16,9 @@ from ..domain.segs import (
     SORT_ORDER_OPTIONS,
     NativeSegs,
 )
+from ..domain.segs_mask_ops import iter_single_images, validate_image_batch
 from ..masking.mask_ops import DETAIL_METHODS
 from ..masking.prompt_segs_with_sam_service import PromptSEGSWithSAMService
-from ..masking.segs_mask_ops import iter_single_images, validate_image_batch
 from ..services.segs_output_service import (
     CombinedSegsResult,
     build_combined_segs_result,

simple_syrup/nodes/schedule_and_encode_prompts_with_prompt_control.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from ..runtime.prompt_control_schedule_encode_graph import (
+from ..services.prompt_control_schedule_encode_graph import (
     PromptControlScheduleEncodeGraphBuilder,
 )
 
@@ -74,20 +74,21 @@ class ScheduleAndEncodePromptsWithPromptControl:
                         ),
                     },
                 ),
+            },
+            "optional": {
                 "negative_prompt": (
                     "STRING",
                     {
                         "default": "",
                         "multiline": False,
                         "tooltip": (
-                            "Negative Prompt-Control text; [SEP] or [SEP|name] "
-                            "creates ordered entries, and global text fills missing "
-                            "negative regions."
+                            "Optional negative Prompt-Control text; [SEP] or "
+                            "[SEP|name] creates ordered entries, and global text "
+                            "fills missing negative regions. Leave disconnected "
+                            "to encode an empty negative prompt."
                         ),
                     },
                 ),
-            },
-            "optional": {
                 "encode_style": (
                     "STRING",
                     {
@@ -107,7 +108,7 @@ class ScheduleAndEncodePromptsWithPromptControl:
         model: Any,
         clip: Any,
         positive_prompt: str,
-        negative_prompt: str,
+        negative_prompt: str = "",
         encode_style: str = "",
     ) -> Any:
         """Build lazy Prompt-Control graph expansion for prompts."""

simple_syrup/nodes/segs_from_sam_output.py

@@ -11,7 +11,7 @@ from typing import Any, ClassVar
 
 import torch
 
-from ..masking.segs_mask_ops import iter_single_images, validate_image_batch
+from ..domain.segs_mask_ops import iter_single_images, validate_image_batch
 from ..runtime.progress import PhaseProgressReporter, create_comfy_phase_progress
 from ..services.segs_from_sam_output_service import SEGSFromSAMOutputService
 

simple_syrup/nodes/simple_load_anima.py

@@ -10,14 +10,20 @@ import importlib
 from types import ModuleType
 from typing import Any
 
-from ..runtime.anima_loader import (
+from ..domain.anima_quantization import AnimaQuantizationRecipe
+from ..runtime.anima_artifacts import ANIMA_QWEN_TEXT_ENCODER
+from ..runtime.auto_model_choices import automatic_component_choices
+from ..runtime.diffusion_model_loader import DIFFUSION_WEIGHT_DTYPES
+from ..runtime.model_downloads import ComfyProgressReporter
+from ..runtime.quantization_capabilities import QuantizationCapabilityCatalog
+from ..runtime.quantization_progress import ComfyQuantizationProgressReporter
+from ..runtime.qwen_artifacts import QWEN_IMAGE_VAE
+from ..runtime.vae_loader import vae_choices
+from ..services.anima_loader_service import (
     AUTO_CHOICE,
     CLIP_DEVICES,
-    DIFFUSION_WEIGHT_DTYPES,
     AnimaLoaderService,
 )
-from ..runtime.model_downloads import ComfyProgressReporter
-from ..runtime.vae_loader import vae_choices
 from . import tooltips
 
 
@@ -25,6 +31,8 @@ class SimpleLoadAnima:
     """Expose Anima diffusion, text encoder, and VAE loading as one node."""
 
     _service = AnimaLoaderService()
+    _quantization_recipe = AnimaQuantizationRecipe()
+    _quantization_capabilities = QuantizationCapabilityCatalog()
 
     RETURN_TYPES = ("MODEL", "CLIP", "VAE")
     RETURN_NAMES = ("model", "clip", "vae")
@@ -53,19 +61,38 @@ class SimpleLoadAnima:
                         )
                     },
                 ),
+                "quantization": (
+                    cls._quantization_capabilities.selection_labels(
+                        cls._quantization_recipe.profiles
+                    ),
+                    {
+                        "default": "Original",
+                        "advanced": True,
+                        "tooltip": (
+                            "Creates or reuses a GPU-supported quantized copy in the "
+                            "global models/SyrupQuants cache; Original loads the "
+                            "selected model unchanged."
+                        ),
+                    },
+                ),
                 "diffusion_weight_dtype": (
                     list(DIFFUSION_WEIGHT_DTYPES),
                     {
                         "default": "default",
                         "advanced": True,
                         "tooltip": (
-                            "Weight precision for Anima. Lower precision can reduce "
-                            "memory use but may slightly change results."
+                            "Load-time weight precision used with Original; cached "
+                            "quantized copies use their stored quantization format."
                         ),
                     },
                 ),
                 "text_encoder": (
-                    _choices_with_auto(folder_paths.get_filename_list("text_encoders")),
+                    automatic_component_choices(
+                        installed=folder_paths.get_filename_list("text_encoders"),
+                        artifacts=(ANIMA_QWEN_TEXT_ENCODER,),
+                        leading_choices=(AUTO_CHOICE,),
+                        folder_paths_module=folder_paths,
+                    ),
                     {
                         "default": AUTO_CHOICE,
                         "advanced": True,
@@ -87,7 +114,12 @@ class SimpleLoadAnima:
                     },
                 ),
                 "vae": (
-                    _choices_with_auto(vae_choices(folder_paths)),
+                    automatic_component_choices(
+                        installed=vae_choices(folder_paths),
+                        artifacts=(QWEN_IMAGE_VAE,),
+                        leading_choices=(AUTO_CHOICE,),
+                        folder_paths_module=folder_paths,
+                    ),
                     {
                         "default": AUTO_CHOICE,
                         "advanced": True,
@@ -103,6 +135,7 @@ class SimpleLoadAnima:
     def load_models(
         self,
         diffusion_model: str,
+        quantization: str,
         diffusion_weight_dtype: str,
         text_encoder: str,
         text_encoder_device: str,
@@ -112,20 +145,16 @@ class SimpleLoadAnima:
 
         return self._service.load_models(
             diffusion_model=diffusion_model,
+            quantization=quantization,
             diffusion_weight_dtype=diffusion_weight_dtype,
             text_encoder=text_encoder,
             text_encoder_device=text_encoder_device,
             vae=vae,
             progress=ComfyProgressReporter(),
+            quantization_progress=ComfyQuantizationProgressReporter(),
         )
 
 
-def _choices_with_auto(choices: list[str]) -> list[str]:
-    """Return choices with the automatic selection first and deduplicated."""
-
-    return [AUTO_CHOICE, *(choice for choice in choices if choice != AUTO_CHOICE)]
-
-
 def _folder_paths() -> ModuleType:
     """Import ComfyUI folder paths lazily."""