comfy-preflight 1.0.0__py3-none-any.whl

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.
@@ -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__
@@ -0,0 +1,200 @@
1
+ """`preflight()` — the aggregator. One call, every registered check, one structured result.
2
+
3
+ This is the function the adoption contract names. **Call it in-process on the submit path.**
4
+
5
+ from comfy_preflight import preflight
6
+
7
+ preflight(graph, register, input_dims=(1072, 1024)) # raises PreflightHalt
8
+ submit(graph) # only reached if nothing raised
9
+
10
+ ## There is exactly one entry point, and that is the design
11
+
12
+ A second, non-raising `preflight_report()` for the CLI and the MCP to call would be a skip flag
13
+ under another name: a caller on the submit path could reach for it and get a value back where
14
+ the gate should have stopped them. So `preflight()` raises on HALT and the **halt carries the
15
+ whole report** (`PreflightHalt.report`). The renderers catch it and print; the submit path lets
16
+ it propagate. Nothing in this module takes a `skip`, `force`, `warn_only` or `enabled`
17
+ parameter, and a test reads the signature rather than trusting this paragraph.
18
+
19
+ ## What the optional parameters are, and what they are not
20
+
21
+ Every optional parameter is an **askability** parameter, in the shape Amendment 1 ruled for
22
+ check 5: supplying it makes a clause askable; omitting it makes the check decline and name what
23
+ it could not see. None of them turns a firing check off. A run with none of them supplied still
24
+ runs checks 1, 5 and 8 in full, and reports precisely which clauses it could not ask.
25
+
26
+ ## The merge
27
+
28
+ `HALT > ADVISORY > NOT_APPLICABLE > PASS`, per Amendment 2. The rung that surprises people is
29
+ NOT_APPLICABLE outranking PASS, and it is deliberate: a run where one check declined has not
30
+ checked everything, and reporting PASS would let the declined clause vanish behind the passing
31
+ ones. On the recorded corpus, a run with no input dimensions and no saved sidecar aggregates to
32
+ NOT_APPLICABLE — which is the honest headline for a run where two checks could not be asked.
33
+ """
34
+
35
+ from __future__ import annotations
36
+
37
+ import dataclasses
38
+ from collections.abc import Mapping, Sequence
39
+ from typing import Any
40
+
41
+ from comfy_preflight.checks.c1_link_topology import NodeSchema
42
+ from comfy_preflight.envelope import ENVELOPE, EnvelopeEntry
43
+ from comfy_preflight.errors import Defect, PreflightHalt, Verdict, merge_verdicts
44
+ from comfy_preflight.graph import Graph
45
+ from comfy_preflight.register import AdapterRegister
46
+ from comfy_preflight.registry import (
47
+ NOT_REGISTERED,
48
+ REGISTRY,
49
+ CheckInputs,
50
+ CheckOutcome,
51
+ RegisteredCheck,
52
+ )
53
+
54
+ AGGREGATE_NAME = "preflight"
55
+
56
+
57
+ @dataclasses.dataclass(frozen=True)
58
+ class PreflightResult:
59
+ """Every registered check's outcome, plus the merged verdict.
60
+
61
+ `checks_run` and `checks_not_registered` are carried so the report can answer *what did you
62
+ actually check* without the reader inferring it. A report that cannot enumerate its own
63
+ coverage makes a check silently dropping out look exactly like a check that passed.
64
+ """
65
+
66
+ verdict: Verdict
67
+ outcomes: tuple[CheckOutcome, ...]
68
+ checks_run: tuple[int, ...]
69
+ checks_not_registered: tuple[tuple[int, str], ...]
70
+
71
+ @property
72
+ def defects(self) -> tuple[Defect, ...]:
73
+ """Every halting defect, from every check, in registry order."""
74
+ return tuple(
75
+ d
76
+ for outcome in self.outcomes
77
+ if outcome.verdict is Verdict.HALT
78
+ for d in outcome.defects
79
+ )
80
+
81
+ @property
82
+ def advisories(self) -> tuple[Defect, ...]:
83
+ """Every non-halting finding. These are facts to see, not grounds to stop."""
84
+ return tuple(
85
+ d
86
+ for outcome in self.outcomes
87
+ if outcome.verdict is Verdict.ADVISORY
88
+ for d in outcome.defects
89
+ )
90
+
91
+ @property
92
+ def declined(self) -> tuple[tuple[str, str, str], ...]:
93
+ """Every clause no check could ask, as (check_id, clause, why)."""
94
+ return tuple(
95
+ (outcome.check_id, clause, why)
96
+ for outcome in self.outcomes
97
+ for clause, why in outcome.clauses_declined
98
+ )
99
+
100
+ def outcome_for(self, number: int) -> CheckOutcome | None:
101
+ return next((o for o in self.outcomes if o.number == number), None)
102
+
103
+ def to_dict(self) -> dict[str, Any]:
104
+ """A JSON-safe rendering, for the CLI's `--json` and for the MCP tool's return value.
105
+
106
+ The MCP returns this **verbatim**. It is a transport over the same in-process function,
107
+ not a second implementation with its own opinion about what matters.
108
+ """
109
+ return {
110
+ "verdict": self.verdict.value,
111
+ "checks_run": list(self.checks_run),
112
+ "checks_not_registered": [
113
+ {"check": number, "reason": reason}
114
+ for number, reason in self.checks_not_registered
115
+ ],
116
+ "checks": [
117
+ {
118
+ "check": outcome.number,
119
+ "id": outcome.check_id,
120
+ "title": outcome.title,
121
+ "verdict": outcome.verdict.value,
122
+ "clauses_evaluated": list(outcome.clauses_evaluated),
123
+ "clauses_declined": [
124
+ {"clause": clause, "why": why}
125
+ for clause, why in outcome.clauses_declined
126
+ ],
127
+ "findings": [_defect_dict(d) for d in outcome.defects],
128
+ "notes": list(outcome.notes),
129
+ }
130
+ for outcome in self.outcomes
131
+ ],
132
+ }
133
+
134
+
135
+ def _defect_dict(defect: Defect) -> dict[str, Any]:
136
+ return {
137
+ "code": defect.code,
138
+ "message": defect.message,
139
+ "hint": defect.hint,
140
+ "node_id": defect.node_id,
141
+ "input_name": defect.input_name,
142
+ }
143
+
144
+
145
+ def preflight(
146
+ graph: Graph,
147
+ register_profile: AdapterRegister | None,
148
+ input_dims: tuple[int, int] | None = None,
149
+ *,
150
+ saved_graph: Graph | None = None,
151
+ schema: NodeSchema | None = None,
152
+ consumer_input: tuple[str, str] | None = None,
153
+ family: str = "qwen",
154
+ envelope_table: Mapping[str, EnvelopeEntry] = ENVELOPE,
155
+ checks: Sequence[RegisteredCheck] = REGISTRY,
156
+ ) -> PreflightResult:
157
+ """Run every registered check and merge their verdicts.
158
+
159
+ `register_profile` is **required and may be None** — deliberately not defaulted. The
160
+ signature is Amendment 2's, and the shape earns itself: passing `None` is a caller stating
161
+ that it has no subject profile, which check 2 then reports as a declined clause. A default
162
+ would let the same situation arrive by omission, and the difference between "I have no
163
+ profile" and "I forgot the profile" is exactly what this repo's declined clauses exist to
164
+ keep visible.
165
+
166
+ Raises `PreflightHalt` if the merged verdict is HALT, carrying **every defect from every
167
+ check** — not just the first check's — with the full `PreflightResult` attached as
168
+ `.report`. Returns the result otherwise.
169
+
170
+ ADVISORY and NOT_APPLICABLE do not raise. An advisory that stopped a submission would be a
171
+ halt wearing a softer name, and the studio ran an out-of-band value deliberately.
172
+
173
+ There is no skip parameter. `checks` exists so a caller can supply an extended registry;
174
+ it cannot be used to disable a check without the caller constructing a different registry,
175
+ which is an explicit act in the caller's own code rather than a flag at the call site.
176
+ """
177
+ inputs = CheckInputs(
178
+ graph=graph,
179
+ register=register_profile,
180
+ input_dims=input_dims,
181
+ saved_graph=saved_graph,
182
+ schema=schema,
183
+ consumer_input=consumer_input,
184
+ family=family,
185
+ envelope_table=envelope_table,
186
+ )
187
+
188
+ outcomes = tuple(spec.run(inputs) for spec in checks)
189
+ result = PreflightResult(
190
+ verdict=merge_verdicts([o.verdict for o in outcomes]),
191
+ outcomes=outcomes,
192
+ checks_run=tuple(o.number for o in outcomes),
193
+ checks_not_registered=tuple(sorted(NOT_REGISTERED.items())),
194
+ )
195
+
196
+ if result.verdict is Verdict.HALT:
197
+ # One raise, carrying everything. A caller fixing defects one rerun at a time is a
198
+ # caller running a gate five times before an act it was meant to gate once.
199
+ raise PreflightHalt(AGGREGATE_NAME, list(result.defects), report=result)
200
+ return result
@@ -0,0 +1,45 @@
1
+ """The checks. Each one halts by raising; none takes a skip parameter.
2
+
3
+ Build state is in the README's table and is the honest state of the repo.
4
+
5
+ Each check exports its own `CheckResult` because the checks decompose by what they know:
6
+ 1, 4 and 5 are graph-structural and know nothing about subjects; 2 and 3 resolve against a
7
+ profile; 6 is transport-side. Their results carry the same three accounting fields —
8
+ `verdict`, `clauses_evaluated`, `clauses_declined` — so an aggregator can read any of them,
9
+ plus whatever else that check measured.
10
+ """
11
+
12
+ from comfy_preflight.checks import (
13
+ c1_link_topology,
14
+ c2_register,
15
+ c4_saved_is_submitted,
16
+ c5_frame,
17
+ c8_envelope,
18
+ )
19
+ from comfy_preflight.checks.c1_link_topology import NodeSchema, check_link_topology
20
+ from comfy_preflight.checks.c2_register import check_register_scan
21
+ from comfy_preflight.checks.c4_saved_is_submitted import check_saved_is_submitted
22
+ from comfy_preflight.checks.c5_frame import (
23
+ DECLARED_ABSENT_FAMILIES,
24
+ FAMILIES,
25
+ FrameConstraint,
26
+ check_generator_legal_frame,
27
+ )
28
+ from comfy_preflight.checks.c8_envelope import check_declared_envelope
29
+
30
+ __all__ = [
31
+ "NodeSchema",
32
+ "FrameConstraint",
33
+ "FAMILIES",
34
+ "DECLARED_ABSENT_FAMILIES",
35
+ "check_link_topology",
36
+ "check_register_scan",
37
+ "check_saved_is_submitted",
38
+ "check_generator_legal_frame",
39
+ "check_declared_envelope",
40
+ "c1_link_topology",
41
+ "c2_register",
42
+ "c4_saved_is_submitted",
43
+ "c5_frame",
44
+ "c8_envelope",
45
+ ]
@@ -0,0 +1,180 @@
1
+ """Check 1 — link topology. The product's founding case.
2
+
3
+ The incident: a hand-retyped payload carried `VAEDecode.samples = ["14", 0]` — node 14's input
4
+ reading node 14 — and Comfy Cloud's `dry_run` returned `status: validated`. The provider's
5
+ validator answers *is this well-formed enough to run*, not *is this the graph you meant*.
6
+
7
+ Three clauses, and they are not equally buildable:
8
+
9
+ | clause | asks | needs |
10
+ |---|---|---|
11
+ | `self_link` | does any input read its own node? | nothing |
12
+ | `dangling_link` | does any link name a node id absent from the graph? | nothing |
13
+ | `undeclared_input` | does any node carry an input its class does not declare? | **a node schema** |
14
+
15
+ **`undeclared_input` takes an injected schema and returns NOT_APPLICABLE without one.** ComfyUI
16
+ serves the schema at `/object_info`; this package makes no network calls by design, so the
17
+ schema arrives as a parameter or the clause declines. It is not inferred from the corpus:
18
+ deriving the reference from the graphs being checked would make the gate a tautology that
19
+ passes review because the numbers look fine.
20
+
21
+ **Out of scope, named rather than silently absent:** orphan detection (a node whose output
22
+ nothing reads). The record checks it alongside these three in hand-driven runs, but the spec
23
+ lists exactly three clauses for check 1 and a non-terminal orphan is a different property —
24
+ a graph may legitimately carry a node whose output is unused. It is a candidate clause, not an
25
+ omission.
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ import dataclasses
31
+
32
+ from comfy_preflight.errors import Defect, PreflightHalt, Verdict
33
+ from comfy_preflight.graph import Graph
34
+
35
+ CHECK_NAME = "check_1_link_topology"
36
+
37
+
38
+ @dataclasses.dataclass(frozen=True)
39
+ class NodeSchema:
40
+ """The declared input names per class type, as served by ComfyUI's `/object_info`.
41
+
42
+ `inputs_by_class` maps a `class_type` to every input name that class declares — required
43
+ and optional together. A class absent from the mapping is reported as unknown rather than
44
+ treated as either passing or failing: a schema that does not cover a node cannot answer for
45
+ it, and guessing in either direction is worse than saying so.
46
+ """
47
+
48
+ inputs_by_class: dict[str, frozenset[str]]
49
+
50
+ def declares(self, class_type: str) -> frozenset[str] | None:
51
+ return self.inputs_by_class.get(class_type)
52
+
53
+
54
+ @dataclasses.dataclass(frozen=True)
55
+ class CheckResult:
56
+ verdict: Verdict
57
+ clauses_evaluated: tuple[str, ...]
58
+ clauses_declined: tuple[tuple[str, str], ...]
59
+ links_examined: int
60
+ nodes_examined: int
61
+ classes_not_in_schema: tuple[str, ...] = ()
62
+ notes: tuple[str, ...] = ()
63
+
64
+
65
+ def check_link_topology(
66
+ graph: Graph,
67
+ *,
68
+ schema: NodeSchema | None = None,
69
+ ) -> CheckResult:
70
+ """Run check 1. Returns a CheckResult on PASS; raises PreflightHalt on a defect.
71
+
72
+ There is no skip parameter. `schema` is the injected node schema for the third clause;
73
+ without it that clause declines and says so.
74
+ """
75
+ defects: list[Defect] = []
76
+ evaluated: list[str] = []
77
+ declined: list[tuple[str, str]] = []
78
+ notes: list[str] = []
79
+
80
+ node_ids = graph.node_ids
81
+ links = list(graph.links())
82
+
83
+ # ---- clause 1a: a node input reading its own node -----------------------
84
+ evaluated.append("self_link")
85
+ for link in links:
86
+ if link.source_id == link.node_id:
87
+ defects.append(
88
+ Defect(
89
+ code="SELF_LINK",
90
+ message=(
91
+ f"input reads slot {link.source_slot} of its own node "
92
+ f"({link.node_id}); a node cannot be its own producer"
93
+ ),
94
+ hint=(
95
+ "repoint this input at the node that actually produces the value. "
96
+ "A provider dry_run has returned `validated` on exactly this defect, "
97
+ "so a passing pre-flight elsewhere is not evidence against it"
98
+ ),
99
+ node_id=link.node_id,
100
+ input_name=link.input_name,
101
+ )
102
+ )
103
+
104
+ # ---- clause 1b: a link naming a node id not in the graph ----------------
105
+ evaluated.append("dangling_link")
106
+ for link in links:
107
+ if link.source_id == link.node_id:
108
+ continue # already reported as a self-link; one defect per cause
109
+ if link.source_id not in node_ids:
110
+ defects.append(
111
+ Defect(
112
+ code="DANGLING_LINK",
113
+ message=(
114
+ f"input reads node {link.source_id!r}, which is not in the graph"
115
+ ),
116
+ hint=(
117
+ "the producing node was renumbered or removed; repoint the input or "
118
+ "restore the node"
119
+ ),
120
+ node_id=link.node_id,
121
+ input_name=link.input_name,
122
+ )
123
+ )
124
+
125
+ # ---- clause 1c: an input the class does not declare ---------------------
126
+ unknown_classes: set[str] = set()
127
+ if schema is None:
128
+ declined.append(
129
+ (
130
+ "undeclared_input",
131
+ "no node schema was supplied, so 'an input the class does not declare' is "
132
+ "not askable. ComfyUI serves one at /object_info; this package makes no "
133
+ "network calls, so the caller injects it. It is deliberately NOT inferred "
134
+ "from the graphs being checked - that would make the gate a tautology",
135
+ )
136
+ )
137
+ else:
138
+ evaluated.append("undeclared_input")
139
+ for node in graph.nodes.values():
140
+ declared = schema.declares(node.class_type)
141
+ if declared is None:
142
+ unknown_classes.add(node.class_type)
143
+ continue
144
+ for input_name in node.inputs:
145
+ if input_name not in declared:
146
+ defects.append(
147
+ Defect(
148
+ code="UNDECLARED_INPUT",
149
+ message=(
150
+ f"class {node.class_type!r} does not declare an input named "
151
+ f"{input_name!r}"
152
+ ),
153
+ hint=(
154
+ "a misspelled or renamed input is silently ignored by the "
155
+ "runtime, so the value you set never reaches the node. Check "
156
+ "the input name against the class, or update the schema if the "
157
+ "node version changed"
158
+ ),
159
+ node_id=node.node_id,
160
+ input_name=input_name,
161
+ )
162
+ )
163
+ for class_type in sorted(unknown_classes):
164
+ notes.append(
165
+ f"class {class_type!r} is not in the supplied schema; its inputs were not "
166
+ "checked against a declaration"
167
+ )
168
+
169
+ if defects:
170
+ raise PreflightHalt(CHECK_NAME, defects)
171
+
172
+ return CheckResult(
173
+ verdict=Verdict.PASS if evaluated else Verdict.NOT_APPLICABLE,
174
+ clauses_evaluated=tuple(evaluated),
175
+ clauses_declined=tuple(declined),
176
+ links_examined=len(links),
177
+ nodes_examined=len(node_ids),
178
+ classes_not_in_schema=tuple(sorted(unknown_classes)),
179
+ notes=tuple(notes),
180
+ )