comfy-preflight 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. comfy_preflight-1.0.0/LICENSE +21 -0
  2. comfy_preflight-1.0.0/PKG-INFO +225 -0
  3. comfy_preflight-1.0.0/README.md +179 -0
  4. comfy_preflight-1.0.0/pyproject.toml +57 -0
  5. comfy_preflight-1.0.0/setup.cfg +4 -0
  6. comfy_preflight-1.0.0/src/comfy_preflight/__init__.py +27 -0
  7. comfy_preflight-1.0.0/src/comfy_preflight/_assert_probe.py +47 -0
  8. comfy_preflight-1.0.0/src/comfy_preflight/aggregate.py +200 -0
  9. comfy_preflight-1.0.0/src/comfy_preflight/checks/__init__.py +45 -0
  10. comfy_preflight-1.0.0/src/comfy_preflight/checks/c1_link_topology.py +180 -0
  11. comfy_preflight-1.0.0/src/comfy_preflight/checks/c2_register.py +390 -0
  12. comfy_preflight-1.0.0/src/comfy_preflight/checks/c4_saved_is_submitted.py +186 -0
  13. comfy_preflight-1.0.0/src/comfy_preflight/checks/c5_frame.py +293 -0
  14. comfy_preflight-1.0.0/src/comfy_preflight/checks/c8_envelope.py +281 -0
  15. comfy_preflight-1.0.0/src/comfy_preflight/cli.py +360 -0
  16. comfy_preflight-1.0.0/src/comfy_preflight/envelope.py +377 -0
  17. comfy_preflight-1.0.0/src/comfy_preflight/errors.py +136 -0
  18. comfy_preflight-1.0.0/src/comfy_preflight/graph.py +179 -0
  19. comfy_preflight-1.0.0/src/comfy_preflight/mcp_server.py +195 -0
  20. comfy_preflight-1.0.0/src/comfy_preflight/register.py +184 -0
  21. comfy_preflight-1.0.0/src/comfy_preflight/registry.py +228 -0
  22. comfy_preflight-1.0.0/src/comfy_preflight.egg-info/PKG-INFO +225 -0
  23. comfy_preflight-1.0.0/src/comfy_preflight.egg-info/SOURCES.txt +38 -0
  24. comfy_preflight-1.0.0/src/comfy_preflight.egg-info/dependency_links.txt +1 -0
  25. comfy_preflight-1.0.0/src/comfy_preflight.egg-info/entry_points.txt +2 -0
  26. comfy_preflight-1.0.0/src/comfy_preflight.egg-info/requires.txt +7 -0
  27. comfy_preflight-1.0.0/src/comfy_preflight.egg-info/top_level.txt +1 -0
  28. comfy_preflight-1.0.0/tests/test_aggregate.py +441 -0
  29. comfy_preflight-1.0.0/tests/test_c1_link_topology.py +222 -0
  30. comfy_preflight-1.0.0/tests/test_c2_register.py +395 -0
  31. comfy_preflight-1.0.0/tests/test_c4_saved_is_submitted.py +234 -0
  32. comfy_preflight-1.0.0/tests/test_c5_frame.py +303 -0
  33. comfy_preflight-1.0.0/tests/test_c8_envelope.py +628 -0
  34. comfy_preflight-1.0.0/tests/test_cli.py +380 -0
  35. comfy_preflight-1.0.0/tests/test_errors.py +222 -0
  36. comfy_preflight-1.0.0/tests/test_fixtures_are_self_contained.py +165 -0
  37. comfy_preflight-1.0.0/tests/test_mcp_surface.py +251 -0
  38. comfy_preflight-1.0.0/tests/test_no_assert_in_library.py +125 -0
  39. comfy_preflight-1.0.0/tests/test_packaging.py +153 -0
  40. comfy_preflight-1.0.0/tests/test_registry.py +225 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 mcp-tool-shop
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,225 @@
1
+ Metadata-Version: 2.4
2
+ Name: comfy-preflight
3
+ Version: 1.0.0
4
+ Summary: A gate that runs on a ComfyUI workflow graph in the seconds before submission, and halts a submission that would spend credits producing a known-wrong result.
5
+ Author-email: mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>
6
+ License: MIT License
7
+
8
+ Copyright (c) 2026 mcp-tool-shop
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ Project-URL: Homepage, https://github.com/mcp-tool-shop-org/comfy-preflight
29
+ Project-URL: Issues, https://github.com/mcp-tool-shop-org/comfy-preflight/issues
30
+ Keywords: comfyui,workflow,preflight,validation,gate
31
+ Classifier: Development Status :: 4 - Beta
32
+ Classifier: Intended Audience :: Developers
33
+ Classifier: License :: OSI Approved :: MIT License
34
+ Classifier: Programming Language :: Python :: 3.11
35
+ Classifier: Programming Language :: Python :: 3.12
36
+ Classifier: Topic :: Multimedia :: Graphics
37
+ Requires-Python: >=3.11
38
+ Description-Content-Type: text/markdown
39
+ License-File: LICENSE
40
+ Provides-Extra: mcp
41
+ Requires-Dist: mcp>=2.0; extra == "mcp"
42
+ Provides-Extra: dev
43
+ Requires-Dist: pytest>=8.0; extra == "dev"
44
+ Requires-Dist: mcp>=2.0; extra == "dev"
45
+ Dynamic: license-file
46
+
47
+ <p align="center">
48
+ <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
49
+ </p>
50
+
51
+ <p align="center">
52
+ <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/comfy-preflight/readme.png" alt="comfy-preflight" width="600">
53
+ </p>
54
+
55
+ <p align="center">
56
+ <a href="https://github.com/mcp-tool-shop-org/comfy-preflight/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/comfy-preflight/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
57
+ <a href="https://pypi.org/project/comfy-preflight/"><img src="https://img.shields.io/pypi/v/comfy-preflight?color=3775a9&label=pypi" alt="PyPI"></a>
58
+ <a href="https://www.npmjs.com/package/@mcptoolshop/comfy-preflight"><img src="https://img.shields.io/npm/v/@mcptoolshop/comfy-preflight?color=cb3837&label=npm" alt="npm"></a>
59
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
60
+ <a href="https://mcp-tool-shop-org.github.io/comfy-preflight/"><img src="https://img.shields.io/badge/landing%20page-live-2ea043" alt="Landing page"></a>
61
+ </p>
62
+
63
+ <p align="center">
64
+ <strong>A gate that runs on a ComfyUI workflow graph in the seconds before it is submitted,</strong><br>
65
+ and halts a submission that would spend credits producing a known-wrong result.<br>
66
+ It does not submit. It does not fix your graph.
67
+ </p>
68
+
69
+ ---
70
+
71
+ ## The gap it lives in
72
+
73
+ > **A Comfy Cloud `dry_run` PASS does not prove link sanity.**
74
+ > A hand-retyped payload with a self-referencing node link — `VAEDecode.samples = ["14", 0]`,
75
+ > the node pointing at itself — returned `status: validated`.
76
+
77
+ The provider's validator answers *is this graph well-formed enough to run.* It does not answer
78
+ *is this the graph you meant.* Every check here lives in that gap, and each one was paid for by
79
+ a run that got past `dry_run`.
80
+
81
+ **Submission is the irreversible act with no real undo, and a preflight is a compensator you run
82
+ BEFORE instead of after.** A completed cloud job is billed; the only compensator afterwards is
83
+ *cancel it if it is still queued, otherwise none.* That is the whole argument for this package.
84
+
85
+ ## Install
86
+
87
+ ```bash
88
+ npx @mcptoolshop/comfy-preflight check graph.json # no Python needed
89
+ pip install comfy-preflight # for the in-process gate
90
+ pip install "comfy-preflight[mcp]" # + the MCP stdio server
91
+ ```
92
+
93
+ The npx launcher downloads a binary from this repo's GitHub Release and **verifies its SHA256**
94
+ against the checksums in that same release before running it. Python ≥ 3.11; binaries for
95
+ linux-x64 and win-x64 (macOS installs via `pip`).
96
+
97
+ ## Use it
98
+
99
+ **The production gate — in-process, on the submit path:**
100
+
101
+ ```python
102
+ from comfy_preflight import preflight
103
+
104
+ # Inside the function that submits. Not in a shell step before it.
105
+ preflight(graph, register, input_dims=(width, height)) # raises PreflightHalt
106
+ submit(graph) # only reached if nothing raised
107
+ ```
108
+
109
+ **The development door:**
110
+
111
+ ```bash
112
+ comfy-preflight check graph.json \
113
+ --input-dims 1072x1024 --register subject.json --saved sidecar.json --json
114
+ ```
115
+
116
+ | exit | meaning |
117
+ |---|---|
118
+ | `0` | nothing halted — PASS, ADVISORY or NOT_APPLICABLE, **each named in the output** |
119
+ | `1` | HALT |
120
+ | `2` | **nothing was examined** — bad arguments, unreadable file, or an internal error |
121
+
122
+ ADVISORY exits `0` on purpose: a nonzero status stops a `&&` chain, which would turn an advisory
123
+ into a halt in every shell that runs one.
124
+
125
+ ## What it checks
126
+
127
+ | # | check | halts on |
128
+ |---|---|---|
129
+ | 1 | **Link topology** | a node input reading its own node; a link to a node id not in the graph |
130
+ | 2 | **The inverted register scan** | a declared register that does not match the graph's construction — **in both directions** |
131
+ | 4 | **Saved-is-submitted** | the saved sidecar and the submitted payload differing **as parsed graphs** |
132
+ | 5 | **Generator-legal frame** | a dimension the effective frame's VAE cannot decode at |
133
+ | 8 | **Declared envelope** | **nothing — it never halts.** Out-of-band is an ADVISORY |
134
+
135
+ Three checks from the original design are **not built**, and are named rather than quietly
136
+ missing: recipe-vs-profile agreement (no subject-profile fixture exists), estimate-before-submit
137
+ (transport-side — no graph-structural operand), and anchor reproduction (needs the graph
138
+ *builder*; the corpus holds outputs, not the scripts that made them).
139
+
140
+ ### Check 2 — the one that names the method
141
+
142
+ When a subject's register declares **no style adapter**, the claim being asserted is *not* "the
143
+ weight is 0.0". It is that **no loader node and no adapter card reference exist anywhere in the
144
+ graph**.
145
+
146
+ > *A weight of 0.0 is not a weight of zero on a loaded card; it is no card.*
147
+
148
+ **And it asserts the mirror image.** A decided positive weight with **no loader node** is
149
+ *silently inert*: the run completes, costs money, and produces base-model output while every log
150
+ line says the adapter was requested. That direction produces no signal a human could notice —
151
+ which is exactly where a gate earns its place over a person looking.
152
+
153
+ ### Check 5 — the effective frame, not the declared one
154
+
155
+ `1066 / 8 = 133.25` encodes to 133 latent columns and decodes to **1064**, putting every output
156
+ 2 px off its control image and breaking every downstream pairing.
157
+
158
+ **The defect happened upstream of the graph.** The 1066 was derived correctly from a mesh, the
159
+ image was rendered at that width and uploaded, and the graph never declared it — so a check
160
+ reading graph literals could not have caught the incident that motivates it. The operand is the
161
+ frame the run will actually produce, which on an img2img graph is the input image's dimensions.
162
+
163
+ ÷8 halts. ÷16 advises. A floor and a preference, not two floors.
164
+
165
+ ### Check 8 — advisory, and honest about what it cannot say
166
+
167
+ For each checkpoint the graph loads, parameters are compared against a **cited** envelope table.
168
+ Every entry carries its band, source URL, retrieval date and a quote of the card's own words —
169
+ and the constructor refuses to build an entry that does not.
170
+
171
+ The day-one entry is `Qwen-Image-InstantX-ControlNet-Union`. It carries the
172
+ `controlnet_conditioning_scale` band its card documents, and a **declared absence** for denoise,
173
+ because that card publishes no denoise range at all — verified against the live card rather than
174
+ recalled. So a run on a graph at `denoise=0.92` reports the 0.92, names the parameter, and says
175
+ plainly that it cannot judge it and why.
176
+
177
+ Reporting the value it cannot judge is the honest half of the finding. Inventing a band to judge
178
+ it against would be the dishonest half.
179
+
180
+ ## The adoption contract
181
+
182
+ **Call it in-process on the submit path. There is no skip flag.**
183
+
184
+ *The check lives inside the tool that performs the irreversible step.* A preflight in a shell
185
+ chain before a submit is a **transport, not a guard** — in the incident that produced this rule,
186
+ 47,020 texels were committed after a gate had already fired, because a PowerShell chain walked
187
+ past a failing exit code. Nobody decided to proceed; the construction was incapable of stopping.
188
+
189
+ **The CLI and the MCP server are both transports, not gates.** Reading a HALT from either and
190
+ then submitting from somewhere else is that same chain with a nicer interface.
191
+
192
+ No function here takes a `skip`, `force`, `warn_only` or `enabled` parameter, and tests read each
193
+ signature rather than trusting the docs. **Every gate `raise`s; none is a bare `assert`** —
194
+ `python -O` deletes `assert` silently, and CI runs the whole suite under `-O` and
195
+ `PYTHONOPTIMIZE=1` to prove the gates survive it.
196
+
197
+ ## Over MCP
198
+
199
+ ```bash
200
+ python -m comfy_preflight.mcp_server # stdio
201
+ npx @mcptoolshop/comfy-preflight mcp # same server, no Python required
202
+ ```
203
+
204
+ One tool, `preflight`, returning the same structured result the library returns — a test asserts
205
+ byte-identity. A HALT is a *successful* call returning `{"verdict": "halt", ...}`, because
206
+ reporting it as a protocol error would throw away the structure the caller needs.
207
+
208
+ ## Security
209
+
210
+ No network calls, no credentials, no telemetry, and it writes nothing anywhere. It reads a graph
211
+ and a profile, and returns a verdict. Full threat model — data touched, data *not* touched, and
212
+ the permissions required — in [SECURITY.md](SECURITY.md).
213
+
214
+ ## Documentation
215
+
216
+ 📖 **[The handbook](https://mcp-tool-shop-org.github.io/comfy-preflight/handbook/)** — getting
217
+ started, every check in detail, the adoption contract, and the envelope table.
218
+
219
+ ## License
220
+
221
+ MIT — see [LICENSE](LICENSE).
222
+
223
+ <p align="center">
224
+ Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
225
+ </p>
@@ -0,0 +1,179 @@
1
+ <p align="center">
2
+ <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
3
+ </p>
4
+
5
+ <p align="center">
6
+ <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/comfy-preflight/readme.png" alt="comfy-preflight" width="600">
7
+ </p>
8
+
9
+ <p align="center">
10
+ <a href="https://github.com/mcp-tool-shop-org/comfy-preflight/actions/workflows/ci.yml"><img src="https://github.com/mcp-tool-shop-org/comfy-preflight/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
11
+ <a href="https://pypi.org/project/comfy-preflight/"><img src="https://img.shields.io/pypi/v/comfy-preflight?color=3775a9&label=pypi" alt="PyPI"></a>
12
+ <a href="https://www.npmjs.com/package/@mcptoolshop/comfy-preflight"><img src="https://img.shields.io/npm/v/@mcptoolshop/comfy-preflight?color=cb3837&label=npm" alt="npm"></a>
13
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
14
+ <a href="https://mcp-tool-shop-org.github.io/comfy-preflight/"><img src="https://img.shields.io/badge/landing%20page-live-2ea043" alt="Landing page"></a>
15
+ </p>
16
+
17
+ <p align="center">
18
+ <strong>A gate that runs on a ComfyUI workflow graph in the seconds before it is submitted,</strong><br>
19
+ and halts a submission that would spend credits producing a known-wrong result.<br>
20
+ It does not submit. It does not fix your graph.
21
+ </p>
22
+
23
+ ---
24
+
25
+ ## The gap it lives in
26
+
27
+ > **A Comfy Cloud `dry_run` PASS does not prove link sanity.**
28
+ > A hand-retyped payload with a self-referencing node link — `VAEDecode.samples = ["14", 0]`,
29
+ > the node pointing at itself — returned `status: validated`.
30
+
31
+ The provider's validator answers *is this graph well-formed enough to run.* It does not answer
32
+ *is this the graph you meant.* Every check here lives in that gap, and each one was paid for by
33
+ a run that got past `dry_run`.
34
+
35
+ **Submission is the irreversible act with no real undo, and a preflight is a compensator you run
36
+ BEFORE instead of after.** A completed cloud job is billed; the only compensator afterwards is
37
+ *cancel it if it is still queued, otherwise none.* That is the whole argument for this package.
38
+
39
+ ## Install
40
+
41
+ ```bash
42
+ npx @mcptoolshop/comfy-preflight check graph.json # no Python needed
43
+ pip install comfy-preflight # for the in-process gate
44
+ pip install "comfy-preflight[mcp]" # + the MCP stdio server
45
+ ```
46
+
47
+ The npx launcher downloads a binary from this repo's GitHub Release and **verifies its SHA256**
48
+ against the checksums in that same release before running it. Python ≥ 3.11; binaries for
49
+ linux-x64 and win-x64 (macOS installs via `pip`).
50
+
51
+ ## Use it
52
+
53
+ **The production gate — in-process, on the submit path:**
54
+
55
+ ```python
56
+ from comfy_preflight import preflight
57
+
58
+ # Inside the function that submits. Not in a shell step before it.
59
+ preflight(graph, register, input_dims=(width, height)) # raises PreflightHalt
60
+ submit(graph) # only reached if nothing raised
61
+ ```
62
+
63
+ **The development door:**
64
+
65
+ ```bash
66
+ comfy-preflight check graph.json \
67
+ --input-dims 1072x1024 --register subject.json --saved sidecar.json --json
68
+ ```
69
+
70
+ | exit | meaning |
71
+ |---|---|
72
+ | `0` | nothing halted — PASS, ADVISORY or NOT_APPLICABLE, **each named in the output** |
73
+ | `1` | HALT |
74
+ | `2` | **nothing was examined** — bad arguments, unreadable file, or an internal error |
75
+
76
+ ADVISORY exits `0` on purpose: a nonzero status stops a `&&` chain, which would turn an advisory
77
+ into a halt in every shell that runs one.
78
+
79
+ ## What it checks
80
+
81
+ | # | check | halts on |
82
+ |---|---|---|
83
+ | 1 | **Link topology** | a node input reading its own node; a link to a node id not in the graph |
84
+ | 2 | **The inverted register scan** | a declared register that does not match the graph's construction — **in both directions** |
85
+ | 4 | **Saved-is-submitted** | the saved sidecar and the submitted payload differing **as parsed graphs** |
86
+ | 5 | **Generator-legal frame** | a dimension the effective frame's VAE cannot decode at |
87
+ | 8 | **Declared envelope** | **nothing — it never halts.** Out-of-band is an ADVISORY |
88
+
89
+ Three checks from the original design are **not built**, and are named rather than quietly
90
+ missing: recipe-vs-profile agreement (no subject-profile fixture exists), estimate-before-submit
91
+ (transport-side — no graph-structural operand), and anchor reproduction (needs the graph
92
+ *builder*; the corpus holds outputs, not the scripts that made them).
93
+
94
+ ### Check 2 — the one that names the method
95
+
96
+ When a subject's register declares **no style adapter**, the claim being asserted is *not* "the
97
+ weight is 0.0". It is that **no loader node and no adapter card reference exist anywhere in the
98
+ graph**.
99
+
100
+ > *A weight of 0.0 is not a weight of zero on a loaded card; it is no card.*
101
+
102
+ **And it asserts the mirror image.** A decided positive weight with **no loader node** is
103
+ *silently inert*: the run completes, costs money, and produces base-model output while every log
104
+ line says the adapter was requested. That direction produces no signal a human could notice —
105
+ which is exactly where a gate earns its place over a person looking.
106
+
107
+ ### Check 5 — the effective frame, not the declared one
108
+
109
+ `1066 / 8 = 133.25` encodes to 133 latent columns and decodes to **1064**, putting every output
110
+ 2 px off its control image and breaking every downstream pairing.
111
+
112
+ **The defect happened upstream of the graph.** The 1066 was derived correctly from a mesh, the
113
+ image was rendered at that width and uploaded, and the graph never declared it — so a check
114
+ reading graph literals could not have caught the incident that motivates it. The operand is the
115
+ frame the run will actually produce, which on an img2img graph is the input image's dimensions.
116
+
117
+ ÷8 halts. ÷16 advises. A floor and a preference, not two floors.
118
+
119
+ ### Check 8 — advisory, and honest about what it cannot say
120
+
121
+ For each checkpoint the graph loads, parameters are compared against a **cited** envelope table.
122
+ Every entry carries its band, source URL, retrieval date and a quote of the card's own words —
123
+ and the constructor refuses to build an entry that does not.
124
+
125
+ The day-one entry is `Qwen-Image-InstantX-ControlNet-Union`. It carries the
126
+ `controlnet_conditioning_scale` band its card documents, and a **declared absence** for denoise,
127
+ because that card publishes no denoise range at all — verified against the live card rather than
128
+ recalled. So a run on a graph at `denoise=0.92` reports the 0.92, names the parameter, and says
129
+ plainly that it cannot judge it and why.
130
+
131
+ Reporting the value it cannot judge is the honest half of the finding. Inventing a band to judge
132
+ it against would be the dishonest half.
133
+
134
+ ## The adoption contract
135
+
136
+ **Call it in-process on the submit path. There is no skip flag.**
137
+
138
+ *The check lives inside the tool that performs the irreversible step.* A preflight in a shell
139
+ chain before a submit is a **transport, not a guard** — in the incident that produced this rule,
140
+ 47,020 texels were committed after a gate had already fired, because a PowerShell chain walked
141
+ past a failing exit code. Nobody decided to proceed; the construction was incapable of stopping.
142
+
143
+ **The CLI and the MCP server are both transports, not gates.** Reading a HALT from either and
144
+ then submitting from somewhere else is that same chain with a nicer interface.
145
+
146
+ No function here takes a `skip`, `force`, `warn_only` or `enabled` parameter, and tests read each
147
+ signature rather than trusting the docs. **Every gate `raise`s; none is a bare `assert`** —
148
+ `python -O` deletes `assert` silently, and CI runs the whole suite under `-O` and
149
+ `PYTHONOPTIMIZE=1` to prove the gates survive it.
150
+
151
+ ## Over MCP
152
+
153
+ ```bash
154
+ python -m comfy_preflight.mcp_server # stdio
155
+ npx @mcptoolshop/comfy-preflight mcp # same server, no Python required
156
+ ```
157
+
158
+ One tool, `preflight`, returning the same structured result the library returns — a test asserts
159
+ byte-identity. A HALT is a *successful* call returning `{"verdict": "halt", ...}`, because
160
+ reporting it as a protocol error would throw away the structure the caller needs.
161
+
162
+ ## Security
163
+
164
+ No network calls, no credentials, no telemetry, and it writes nothing anywhere. It reads a graph
165
+ and a profile, and returns a verdict. Full threat model — data touched, data *not* touched, and
166
+ the permissions required — in [SECURITY.md](SECURITY.md).
167
+
168
+ ## Documentation
169
+
170
+ 📖 **[The handbook](https://mcp-tool-shop-org.github.io/comfy-preflight/handbook/)** — getting
171
+ started, every check in detail, the adoption contract, and the envelope table.
172
+
173
+ ## License
174
+
175
+ MIT — see [LICENSE](LICENSE).
176
+
177
+ <p align="center">
178
+ Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
179
+ </p>
@@ -0,0 +1,57 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "comfy-preflight"
7
+ version = "1.0.0"
8
+ description = "A gate that runs on a ComfyUI workflow graph in the seconds before submission, and halts a submission that would spend credits producing a known-wrong result."
9
+ readme = "README.md"
10
+ license = { file = "LICENSE" }
11
+ requires-python = ">=3.11"
12
+ authors = [{ name = "mcp-tool-shop", email = "64996768+mcp-tool-shop@users.noreply.github.com" }]
13
+ keywords = ["comfyui", "workflow", "preflight", "validation", "gate"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Intended Audience :: Developers",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Programming Language :: Python :: 3.11",
19
+ "Programming Language :: Python :: 3.12",
20
+ "Topic :: Multimedia :: Graphics",
21
+ ]
22
+
23
+ # ZERO runtime dependencies, and this is load-bearing rather than tidy.
24
+ # The npm door (@mcptoolshop/npm-launcher -> a SHA256-pinned PyInstaller binary) is only
25
+ # open to packages whose dependencies are stdlib + sqlite3 + mcp. Adding a third-party
26
+ # runtime dep closes it. The checks operate on parsed JSON; nothing here needs numpy.
27
+ dependencies = []
28
+
29
+ [project.optional-dependencies]
30
+ # mcp>=2.0, not >=1.0: the server class the surface is built on is `mcp.server.MCPServer`,
31
+ # and 2.0 removed the 1.x `mcp.server.fastmcp.FastMCP`. The bound was verified against the
32
+ # installed SDK rather than recalled - a >=1.0 bound would resolve to a version that
33
+ # ImportErrors on first use, which is the same defect class as a console script pointing at an
34
+ # absent module.
35
+ mcp = ["mcp>=2.0"]
36
+ dev = ["pytest>=8.0", "mcp>=2.0"]
37
+
38
+ # The console script, restored now that the CLI it names exists. The scaffold declared this
39
+ # entry before any CLI module did, which installs a command that raises ImportError on first
40
+ # use — a defect that surfaces for the person who installs the package, not for the person who
41
+ # wrote the entry. tests/test_packaging.py imports every declared target and fails if one does
42
+ # not resolve, so the entry can never again outrun the module.
43
+ [project.scripts]
44
+ comfy-preflight = "comfy_preflight.cli:main"
45
+
46
+ [project.urls]
47
+ Homepage = "https://github.com/mcp-tool-shop-org/comfy-preflight"
48
+ Issues = "https://github.com/mcp-tool-shop-org/comfy-preflight/issues"
49
+
50
+ [tool.setuptools.packages.find]
51
+ where = ["src"]
52
+
53
+ [tool.pytest.ini_options]
54
+ testpaths = ["tests"]
55
+ # -O / PYTHONOPTIMIZE strips `assert`. This project's gates `raise`; the test suite is
56
+ # also run under -O in CI to prove the gates survive it. See tests/test_gates_survive_O.py
57
+ addopts = "-q"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,27 @@
1
+ """comfy-preflight — a gate on a ComfyUI workflow graph, run before submission.
2
+
3
+ Submitting a graph is the one irreversible act in a generation pipeline: a completed cloud
4
+ job is billed, and the only compensator is "cancel it if it is still queued, otherwise
5
+ none." This package is a compensator you run *before* instead of after.
6
+
7
+ It does not submit, does not repair a graph, and never sees an output.
8
+
9
+ `preflight()` is the function the adoption contract names: call it **in-process on the submit
10
+ path**, and let it raise. See the README's build-state table for which checks it composes; that
11
+ table is the honest state of this repo.
12
+ """
13
+
14
+ __version__ = "1.0.0"
15
+
16
+ from comfy_preflight.aggregate import PreflightResult, preflight
17
+ from comfy_preflight.errors import Defect, PreflightHalt, Verdict, merge_verdicts
18
+
19
+ __all__ = [
20
+ "__version__",
21
+ "preflight",
22
+ "PreflightResult",
23
+ "Defect",
24
+ "PreflightHalt",
25
+ "Verdict",
26
+ "merge_verdicts",
27
+ ]
@@ -0,0 +1,47 @@
1
+ """A probe that measures whether a bare `assert` gates LIBRARY code in this interpreter.
2
+
3
+ Why this module exists, and why it is in `src/` rather than in `tests/`:
4
+
5
+ **pytest rewrites `assert` statements in test modules.** Its import hook transforms them into
6
+ explicit code that raises `AssertionError`, so a bare `assert False` written in a test file
7
+ still fires under `python -O` — not because the interpreter kept it, but because pytest
8
+ replaced it before the interpreter saw it. pytest says so itself when run under -O:
9
+
10
+ PytestConfigWarning: assertions not in test modules or plugins will be ignored because
11
+ assert statements are not executed by the underlying Python interpreter
12
+
13
+ Library code is **not** rewritten. So an assert in `comfy_preflight/*.py` really is deleted
14
+ under `-O`, while an assert in `tests/*.py` is not. A test that probes assert-stripping with
15
+ its own assert therefore measures a proxy — pytest's rewriting — instead of the property, and
16
+ reports the opposite of the truth. That mistake was made once here and caught by the -O CI
17
+ leg failing.
18
+
19
+ This module is the honest instrument: it lives where the gates live, so it is subject to the
20
+ same treatment they are.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+
26
+ def bare_assert_fires() -> bool:
27
+ """True if a bare `assert` raises in library code under the running interpreter.
28
+
29
+ Returns False when assertions are stripped (`python -O`, `PYTHONOPTIMIZE`), which is
30
+ exactly the condition under which a gate written as an `assert` would silently vanish and
31
+ let execution continue past it.
32
+ """
33
+ try:
34
+ assert False # noqa: B011 - deliberately bare; this is the measurement
35
+ return False
36
+ except AssertionError:
37
+ return True
38
+
39
+
40
+ def asserts_are_stripped() -> bool:
41
+ """True when this interpreter is discarding assertions.
42
+
43
+ Read from the interpreter rather than inferred, so it can be cross-checked against
44
+ `bare_assert_fires()`. If the two ever disagree, something is rewriting library code and
45
+ the gates' guarantee needs re-examining.
46
+ """
47
+ return not __debug__