HEL-892: add explicit PreviewAny and promoted scalar reference conversion

Co-authored-by: multica-agent <github@multica.ai>
This commit is contained in:
leefer
2026-10-30 00:54:36 +08:00
co-authored by multica-agent
parent 5e5cc03395
commit 7d4e3941ed
5 changed files with 848 additions and 34 deletions
@@ -19,12 +19,14 @@ from calliope.comfyui.companions import load_companions
from calliope.comfyui.delivery_scope import exclusion_for
from calliope.comfyui.serialization_reference import (
AUX_PROFILE,
PREVIEW_PROFILE,
PRIMITIVE_PROFILE,
PROFILE,
resolve_reference_link,
serialize_promoted_node,
serialize_reference_widgets,
)
from calliope.comfyui.structure_reference import STRUCTURE_PROFILES
from calliope.comfyui.structure_reference import PROMOTED_PROFILES, STRUCTURE_PROFILES
from calliope.comfyui.ui2api import convert, convert_reference
@@ -41,7 +43,7 @@ def audit(repo: Path, profile: str = PROFILE) -> dict:
source, api = json.loads(raw), json.loads(record["raw"])
assert convert(api).prompt is not None
selected = profile
if profile == "structure-batch-reference":
if profile in ("structure-batch-reference", "promoted-batch-reference"):
version = source.get("extra", {}).get("frontendVersion")
structural = f"comfy-frontend-{version}-structure-reference"
selected = (
@@ -52,6 +54,15 @@ def audit(repo: Path, profile: str = PROFILE) -> dict:
if any(n.get("type") == "PrimitiveNode" for n in source["nodes"])
else AUX_PROFILE
)
if profile == "promoted-batch-reference":
selected = (
selected.replace("-structure-reference", "-promoted-reference")
if selected.replace("-structure-reference", "-promoted-reference")
in PROMOTED_PROFILES
else PREVIEW_PROFILE
if selected == PRIMITIVE_PROFILE
else selected
)
candidate = convert_reference(source, selected)
projected = candidate.diagnostic_graph or source
nodes = {str(n["id"]): n for n in projected["nodes"]}
@@ -65,7 +76,14 @@ def audit(repo: Path, profile: str = PROFILE) -> dict:
if node.get("type") in ("Reroute", "Note", "MarkdownNote"):
continue
try:
values = serialize_reference_widgets(node, selected)
values = (
serialize_promoted_node(node, PROMOTED_PROFILES[selected])
if selected in PROMOTED_PROFILES
else serialize_reference_widgets(node, selected)
)
for boundary in candidate.resolved_boundaries:
if boundary["node_id"] == nid:
values[boundary["input_name"]] = boundary["value"]
except ValueError as exc:
unsupported.append({"node_id": nid, "type": node["type"], "reason": str(exc)})
else:
@@ -77,7 +95,12 @@ def audit(repo: Path, profile: str = PROFILE) -> dict:
"field": name,
"source_reference": value,
"api": expected,
"differences": differences(expected, value),
"differences": (
differences({}, {name: value})
if selected in (PREVIEW_PROFILE, *PROMOTED_PROFILES)
and name not in api.get(nid, {}).get("inputs", {})
else differences(expected, value)
),
}
)
linked = {s["name"] for s in node.get("inputs", []) if s.get("link") is not None}
@@ -139,6 +162,9 @@ def audit(repo: Path, profile: str = PROFILE) -> dict:
"source_frontend_version": source.get("extra", {}).get("frontendVersion"),
"export_frontend_version": binding["frontend_version"],
"whole_prompt_available": candidate.prompt is not None,
"candidate_prompt": candidate.prompt
if profile == "promoted-batch-reference"
else None,
"whole_prompt_differences": differences(api, candidate.prompt)
if candidate.prompt is not None
else None,
@@ -149,6 +175,17 @@ def audit(repo: Path, profile: str = PROFILE) -> dict:
"unsupported_widget_nodes": unsupported,
"diagnostic_graph": candidate.diagnostic_graph,
"unresolved_boundaries": candidate.unresolved_boundaries,
"resolved_boundaries": [
{
**v,
"api": api.get(v["node_id"], {}).get("inputs", {}).get(v["input_name"]),
"differences": differences(
api.get(v["node_id"], {}).get("inputs", {}).get(v["input_name"]),
v["value"],
),
}
for v in candidate.resolved_boundaries
],
"node_types": node_types,
"metadata": metadata,
"api_only_fields_for_supported_nodes": api_only,
@@ -164,6 +201,10 @@ def audit(repo: Path, profile: str = PROFILE) -> dict:
"diagnostic structures never prove widget values, full equivalence or execution",
"reference_conditions": {
"unmodified_frontend_widgets_assumed": True,
"promoted_named_positional": "1.53.6 requires both representations to agree when named values exist; 1.48.7 ignores unknown named keys",
"promoted_missing_or_null": "no silent default; typed scalar consumption rejects null",
"primitive_inside_promoted_profile": "unsupported; whole prompt remains closed",
"combo_availability": "not evaluated; fixed scalar constructor only",
"ue_extension_serializer_match": "unknown",
"aux_release_artifact_commit_match": "unknown"
if profile == AUX_PROFILE
@@ -189,7 +230,10 @@ def main():
PROFILE,
AUX_PROFILE,
PRIMITIVE_PROFILE,
PREVIEW_PROFILE,
*STRUCTURE_PROFILES,
*PROMOTED_PROFILES,
"promoted-batch-reference",
"structure-batch-reference",
),
default=PROFILE,
@@ -1,6 +1,7 @@
"""Small, explicit public-reference contract, never a target object_info snapshot.
Sources and limits: docs/hel-892/{serialization-evidence,controlnet-reference}/sources.json.
Sources: docs/hel-892/{serialization-evidence,controlnet-reference,
promoted-reference,structure-reference}/sources.json.
Only explicitly pinned scalar layouts are covered. The subtitle opt-in also
folds direct Primitive STRING bindings. No seed controller, bypass, dynamic
extension or target installation is inferred.
@@ -13,6 +14,7 @@ from typing import Any
PROFILE = "comfy-frontend-1.37.11-core-reference"
AUX_PROFILE = "comfy-frontend-1.37.11-controlnet-aux-e8b689a-reference"
AUX_COMMIT = "e8b689a513c3e6b63edc44066560ca5919c0576e"
PREVIEW_PROFILE = "comfy-frontend-1.37.11-preview-reference"
PRIMITIVE_PROFILE = "comfy-frontend-1.37.11-qwen-b037d7be-reference"
# Explicit earlier Qwen schema, not a claim about the installed plugin. Its
# 14 widgets differ from the newer reference's added normalize_text field.
@@ -77,7 +79,7 @@ def reference_definitions(profile: str = PROFILE) -> dict[str, Any]:
"output": outputs,
}
if profile not in (PROFILE, AUX_PROFILE, PRIMITIVE_PROFILE):
if profile not in (PROFILE, AUX_PROFILE, PRIMITIVE_PROFILE, PREVIEW_PROFILE):
raise ValueError("未知参考版本")
definitions = {
"Canny": spec(
@@ -105,7 +107,7 @@ def reference_definitions(profile: str = PROFILE) -> dict[str, Any]:
["IMAGE"],
{name: "INT" if kind is int else "COMBO" for name, kind in layout},
)
if profile == PRIMITIVE_PROFILE:
if profile in (PRIMITIVE_PROFILE, PREVIEW_PROFILE):
definitions["LoadAudio"] = spec({"audio": "COMBO"}, ["AUDIO"], {"audioUI": "AUDIO_UI"})
definitions["AILab_Qwen3ASRSubtitle"] = spec(
{"audio": "AUDIO"},
@@ -125,15 +127,22 @@ def reference_definitions(profile: str = PROFILE) -> dict[str, Any]:
for name, kind in _SUBTITLE_LAYOUT
},
)
if profile == PREVIEW_PROFILE:
definitions["PreviewAny"] = spec({"source": "*"}, [])
return definitions
def serialize_reference_widgets(node: dict[str, Any], profile: str = PROFILE) -> dict[str, Any]:
"""Apply only the pinned identity serializers; reject any extra/missing value."""
if profile not in (PROFILE, AUX_PROFILE, PRIMITIVE_PROFILE):
if profile not in (PROFILE, AUX_PROFILE, PRIMITIVE_PROFILE, PREVIEW_PROFILE):
raise ValueError("未知参考版本")
if profile == PRIMITIVE_PROFILE and node.get("type") in ("LoadAudio", "AILab_Qwen3ASRSubtitle"):
if profile in (PRIMITIVE_PROFILE, PREVIEW_PROFILE) and node.get("type") in (
"LoadAudio",
"AILab_Qwen3ASRSubtitle",
):
return _serialize_subtitle(node)
if profile == PREVIEW_PROFILE and node.get("type") == "PreviewAny":
return _serialize_preview(node)
if profile == AUX_PROFILE and node.get("type") in _AUX_LAYOUTS:
return _serialize_aux(node)
if node.get("mode", 0) != 0:
@@ -239,7 +248,7 @@ def fold_reference_primitives(source, profile):
primitives = [n for n in nodes.values() if n.get("type") == "PrimitiveNode"]
if not primitives:
return graph
if profile != PRIMITIVE_PROFILE:
if profile not in (PRIMITIVE_PROFILE, PREVIEW_PROFILE):
raise ValueError("Primitive 需要显式字幕/具名字符串参考契约")
# Validate all links before removing a virtual node or consuming a value.
for lid in links:
@@ -387,3 +396,154 @@ def resolve_reference_link(nodes, links, link_id) -> list[Any]:
link_id = upstream["inputs"][0].get("link")
if link_id is None:
raise ValueError("Reroute 无上游连线")
def _serialize_preview(node):
"""v1.37.11 configure skips the two serialize=false DOM widgets.
graphToPrompt instead checks options.serialize, so both named preview DOM
widgets participate (the second overwrites the first) and previewMode is
retained. The first persisted element restores previewMode; the two trailing
nulls are legacy workflow placeholders, NOT three fields to omit from API.
No DOM interaction or extension override is modelled by this profile.
"""
properties = node.get("properties") or {}
if (
node.get("mode", 0) != 0
or properties.get("cnr_id") != "comfy-core"
or properties.get("ver") != "0.11.0"
):
raise ValueError("PreviewAny 提供方/版本/模式不符合固定参考")
if any(k in node for k in ("widgets", "widgets_values_named", "serializeValue")):
raise ValueError("PreviewAny 自定义控件/具名恢复未证明")
values = node.get("widgets_values")
if (
not isinstance(values, list)
or len(values) != 3
or values[1:] != [None, None]
or (values[0] is not None and type(values[0]) is not bool)
):
raise ValueError("PreviewAny 仅覆盖布尔/null模式和两个null旧式占位")
sockets = node.get("inputs", [])
if (
len(sockets) != 1
or sockets[0].get("name") != "source"
or sockets[0].get("type") != "*"
or sockets[0].get("widget") is not None
):
raise ValueError("PreviewAny source 绑定不符")
return {"preview": "", "previewMode": values[0]}
# Direct scalar contracts proved by fixed core 0.31.0/0.38.0 schemas and
# corresponding frontend constructors. Binding a field is deliberately weaker
# than proving the whole node's serializer (e.g. TextGenerate dynamic combo).
_DIRECT = {
"UNETLoader": {"unet_name": "COMBO", "weight_dtype": "COMBO"},
"CLIPLoader": {"clip_name": "COMBO", "type": "COMBO", "device": "COMBO"},
"VAELoader": {"vae_name": "COMBO"},
"EmptyLatentImage": {"width": "INT", "height": "INT", "batch_size": "INT"},
"KSampler": {
"seed": "INT",
"steps": "INT",
"cfg": "FLOAT",
"sampler_name": "COMBO",
"scheduler": "COMBO",
"denoise": "FLOAT",
},
"ComfySwitchNode": {"switch": "BOOLEAN"},
"PrimitiveStringMultiline": {"value": "STRING"},
"PrimitiveBoolean": {"value": "BOOLEAN"},
"TextGenerate": {"prompt": "STRING", "thinking": "BOOLEAN"},
"TextEncodeQwenImage21": {"prompt": "STRING", "negative_prompt": "STRING", "resolution": "INT"},
"QwenImage21Cache": {"device": "COMBO", "dtype": "COMBO"},
}
_SIMPLE_LAYOUTS = {
"UNETLoader": ("unet_name", "weight_dtype"),
"CLIPLoader": ("clip_name", "type", "device"),
"VAELoader": ("vae_name",),
"EmptyLatentImage": ("width", "height", "batch_size"),
"PrimitiveStringMultiline": ("value",),
"PrimitiveBoolean": ("value",),
"QwenImage21Cache": ("device", "dtype"),
}
_SIMPLE_OUTPUTS = {
"UNETLoader": ["MODEL"],
"CLIPLoader": ["CLIP"],
"VAELoader": ["VAE"],
"EmptyLatentImage": ["LATENT"],
"PrimitiveStringMultiline": ["STRING"],
"QwenImage21Cache": ["MODEL"],
"PrimitiveBoolean": ["BOOLEAN"],
}
def direct_widget_type(node, socket, version):
"""Prove a named scalar binding, never infer one from source array order."""
props = node.get("properties") or {}
expected = "0.31.0" if version == "1.48.7" else "0.38.0"
ct, name = node.get("type"), socket.get("name")
if (
props.get("cnr_id") != "comfy-core"
or props.get("ver") != expected
or node.get("mode", 0) != 0
):
raise ValueError("内部节点提供方/版本/模式不符合固定参考")
if ct in ("TextGenerate", "TextEncodeQwenImage21", "QwenImage21Cache") and expected != "0.38.0":
raise ValueError("此节点未在固定0.31.0来源中证明")
kind = _DIRECT.get(ct, {}).get(name)
if kind is None or socket.get("type") != kind or socket.get("widget") != {"name": name}:
raise ValueError(f"未证明内部字段绑定:{ct}.{name}")
if any(k in node for k in ("widgets", "serializeValue")):
raise ValueError("自定义控件或具名恢复不在参考契约内")
return kind
def validate_direct_value(value, kind):
expected = {"COMBO": str, "STRING": str, "BOOLEAN": bool, "INT": int, "FLOAT": float}[kind]
if (expected is float and type(value) not in (float, int)) or (
expected is not float and type(value) is not expected
):
raise ValueError(f"边界值类型不符:{kind};null不等于缺项/false/0")
def promoted_definitions():
return {
ct: {
"input": {"required": {n: [t] for n, t in _DIRECT[ct].items()}, "optional": {}},
"output": _SIMPLE_OUTPUTS[ct],
}
for ct in _SIMPLE_LAYOUTS
} | {
"QwenImage21Cache": {
"input": {"required": {"model": ["MODEL"], "device": ["COMBO"], "dtype": ["COMBO"]}},
"output": ["MODEL"],
}
}
def serialize_promoted_node(node, version):
"""Only complete simple scalar layouts; no seed/dynamic/autogrow serializer."""
ct = node.get("type")
layout = _SIMPLE_LAYOUTS.get(ct)
values = node.get("widgets_values", [])
if layout is None or not isinstance(values, list) or len(values) != len(layout):
raise ValueError("未证明完整内部控件构造/序列化布局")
named = node.get("widgets_values_named")
if version == "1.53.6" and named is not None:
if (
not isinstance(named, dict)
or set(named) != set(layout)
or any(type(named[n]) is not type(v) or named[n] != v for n, v in zip(layout, values))
):
raise ValueError("具名/位置控件不一致;namedValuesRestore开关未知")
result = {}
for name, value in zip(layout, values):
# A widget can exist without an exposed input socket; its definition is
# pinned independently of the stored sockets.
kind = direct_widget_type(
node, {"name": name, "type": _DIRECT[ct][name], "widget": {"name": name}}, version
)
validate_direct_value(value, kind)
result[name] = value
return result
@@ -1,7 +1,8 @@
"""Pinned frontend structural projection, for diagnostics only.
"""Pinned frontend structure and opt-in direct promoted scalar projection.
Sources: docs/hel-892/structure-reference/sources.json. Does not serialize
promoted widgets, interpret third-party nodes, or establish execution eligibility.
Sources: docs/hel-892/{structure-reference,promoted-reference}/sources.json.
Structure profiles remain diagnostic. Direct values never prove complete ordinary
node serializers, third-party behavior, target versions or execution eligibility.
"""
from __future__ import annotations
@@ -17,12 +18,16 @@ STRUCTURE_PROFILES = {
}
PROMOTED_PROFILES = {f"comfy-frontend-{v}-promoted-reference": v for v in ("1.48.7", "1.53.6")}
@dataclass
class Structure:
graph: dict[str, Any] | None
issues: list[dict[str, Any]] = field(default_factory=list)
# These are boundary inputs whose frontend widget store cannot be reconstructed.
unresolved: list[dict[str, Any]] = field(default_factory=list)
resolved: list[dict[str, Any]] = field(default_factory=list)
def _id(value):
@@ -39,7 +44,7 @@ def _uuid(value):
return False
def expand_reference_subgraphs(source: dict, profile: str) -> Structure:
def expand_reference_subgraphs(source: dict, profile: str, *, widgets: bool = False) -> Structure:
"""Expand scoped nodes/links without consuming positional boundary widgets.
A returned graph is diagnostic data, never an executable prompt. Unbound
@@ -47,12 +52,12 @@ def expand_reference_subgraphs(source: dict, profile: str) -> Structure:
returns no graph, including malformed unused branches/definitions.
"""
try:
return _expand(source, profile)
return _expand(source, profile, widgets)
except (ValueError, TypeError, KeyError, AttributeError, IndexError, RecursionError) as exc:
return Structure(None, [{"code": "reference_structure_invalid", "message": str(exc)}])
def _expand(source, profile):
def _expand(source, profile, widgets=False):
version = STRUCTURE_PROFILES.get(profile)
if version is None or (source.get("extra") or {}).get("frontendVersion") != version:
raise ValueError("源前端声明与结构参考版本不符")
@@ -237,6 +242,152 @@ def _expand(source, profile):
return resolve(child, link[1], link[2], seen)
return [":".join((*path, str(nid))), slot]
resolved = []
if widgets:
from .serialization_reference import direct_widget_type, validate_direct_value
def targets(key, slot, stack=()):
marker = (key, slot)
if marker in stack:
raise ValueError("递归控件绑定")
definition = definitions[key]
found = []
for lid in definition["inputs"][slot]["linkIds"]:
edge = networks[key][1][str(lid)]
target = networks[key][0][str(edge[3])]
socket = target["inputs"][edge[4]]
if target["type"] in definitions:
found.extend(targets(target["type"], edge[4], stack + (marker,)))
elif socket.get("widget") is not None:
try:
kind = direct_widget_type(target, socket, version)
except ValueError:
kind = None
found.append((target, socket, kind))
return found
host_cache = {}
def host_values(path):
if path in host_cache:
return host_cache[path]
key, _, parent, instance = contexts[path]
definition = definitions[key]
props = instance.get("properties") or {}
if (
props.get("proxyWidgetErrorQuarantine")
or props.get("proxyWidgets")
or any(k in instance for k in ("widgets", "serializeValue"))
):
raise ValueError("隔离/代理/自定义控件覆盖不在promoted参考契约内")
names = [s["name"] for s in definition["inputs"]]
if len(names) != len(set(names)):
raise ValueError("重名稳定输入标识")
bindings = []
for slot, socket in enumerate(instance.get("inputs", [])):
bound = targets(key, slot)
if not bound:
if socket.get("widget") is not None:
raise ValueError("实例控件缺少可证明的内部绑定")
continue
kind = bound[0][2]
if kind is None:
raise ValueError(
f"首个内部绑定 {bound[0][0]['type']}.{bound[0][1]['name']} "
"无固定构造契约;无法重建host控件顺序"
)
compatible = all(
t == kind
and (n["type"], s["name"]) == (bound[0][0]["type"], bound[0][1]["name"])
for n, s, t in bound
)
# Differently constrained fanouts need their own compatibility
# proof; never propagate a value just because types coincide.
if socket.get("widget") != {"name": names[slot]} or socket.get("type") != kind:
raise ValueError("实例稳定widget.name或类型不符")
bindings.append((slot, kind, compatible))
values = instance.get("widgets_values", [])
if not isinstance(values, list) or len(values) != len(bindings):
raise ValueError("promoted控件数量不符;不静默回退内部默认值")
# Array offset is justified only after reconstructing every host
# widget via interior named bindings (SubgraphNode._resolveInputWidget).
result = {}
local_nodes = list(networks[parent[0]][0])
prefix = "/nodes/" + str(local_nodes.index(str(instance["id"])))
if parent[0] is not None:
prefix = (
"/definitions/subgraphs/" + str(list(definitions).index(parent[0])) + prefix
)
for index, (slot, kind, compatible) in enumerate(bindings):
value = values[index]
# Retain the persisted value for provenance. Type validation
# happens on scalar consumption; external links always win.
result[slot] = {
"value": value,
"value_pointer": prefix + "/widgets_values/" + str(index),
"binding_name": names[slot],
"binding_type": kind,
"compatible": compatible,
"boundary_instance": ":".join(path),
}
named = instance.get("widgets_values_named")
if version == "1.53.6" and named is not None:
if (
not isinstance(named, dict)
or set(named) != {v["binding_name"] for v in result.values()}
or any(
type(named[v["binding_name"]]) is not type(v["value"])
or named[v["binding_name"]] != v["value"]
for v in result.values()
)
):
raise ValueError("具名/位置host值不一致;namedValuesRestore开关未知")
for v in result.values():
name = v["binding_name"].replace("~", "~0").replace("/", "~1")
v["named_value_pointer"] = prefix + "/widgets_values_named/" + name
host_cache[path] = result
return result
def scalar(endpoint, node, socket):
path = tuple(endpoint["boundary_instance"].split(":"))
values = host_values(path)
slot = endpoint["slot"]
if slot not in values:
raise ValueError("无稳定promoted控件绑定;不采用内部现值")
value = values[slot]
if not value["compatible"]:
raise ValueError("多目标控件约束未知或不兼容")
kind = direct_widget_type(node, socket, version)
validate_direct_value(value["value"], kind)
if kind != value["binding_type"]:
raise ValueError("边界到内部字段类型不兼容")
return value
store_keys = {}
for path in contexts:
if not path:
continue
try:
values = host_values(path)
for value in values.values():
# Pinned store identity uses local instance ID, not the
# composite execution path. Conflicting nested definitions
# must not be advertised as isolated store values.
key = (path[-1], value["binding_name"])
previous = store_keys.get(key)
identity = (value["binding_type"], type(value["value"]), value["value"])
if previous is not None and previous != identity:
raise ValueError("嵌套host的局部widgetId冲突;存储值优先顺序未证明")
store_keys[key] = identity
except ValueError as exc:
issues.append(
{
"code": "promoted_host_unverified",
"node_id": ":".join(path),
"message": str(exc),
}
)
projected = []
for full, node in flat.items():
path = tuple(full.split(":"))
@@ -249,9 +400,40 @@ def _expand(source, profile):
original = networks[ctx[0]][1][str(lid)]
endpoint = resolve(ctx, original[1], original[2], set())
if isinstance(endpoint, dict):
unresolved.append(
{"node_id": full, "input_slot": slot, "input_name": socket["name"], **endpoint}
)
boundary = {
"node_id": full,
"input_slot": slot,
"input_name": socket["name"],
**endpoint,
}
if widgets:
try:
value = scalar(endpoint, node, socket)
except ValueError as exc:
unresolved.append({**boundary, "reason": str(exc)})
else:
local = list(networks[ctx[0]][0]).index(full.split(":")[-1])
prefix = "/nodes/" + str(local)
if ctx[0] is not None:
prefix = (
"/definitions/subgraphs/"
+ str(list(definitions).index(ctx[0]))
+ prefix
)
resolved.append(
{
**boundary,
**deepcopy(value),
"target_pointer": prefix + "/inputs/" + str(slot),
"precedence": [
"external_link",
"promoted_value",
"internal_serializer",
],
}
)
else:
unresolved.append(boundary)
continue
new_id = len(projected) + 1
projected.append([new_id, *endpoint, full, slot, original[5]])
@@ -285,4 +467,4 @@ def _expand(source, profile):
"links": projected,
"extra": deepcopy(source.get("extra", {})),
}
return Structure(graph, issues, unresolved)
return Structure(graph, issues, unresolved, resolved)
+63 -14
View File
@@ -15,15 +15,18 @@ from typing import Any
from .serialization_reference import (
AUX_PROFILE,
PREVIEW_PROFILE,
PRIMITIVE_PROFILE,
PROFILE,
fold_reference_primitives,
promoted_definitions,
reference_definitions,
resolve_reference_link,
serialize_promoted_node,
serialize_reference_widgets,
validate_reroute,
)
from .structure_reference import STRUCTURE_PROFILES, expand_reference_subgraphs
from .structure_reference import PROMOTED_PROFILES, STRUCTURE_PROFILES, expand_reference_subgraphs
@dataclass
@@ -33,6 +36,7 @@ class Conversion:
reference_only: bool = False
diagnostic_graph: dict[str, Any] | None = None
unresolved_boundaries: list[dict[str, Any]] = field(default_factory=list)
resolved_boundaries: list[dict[str, Any]] = field(default_factory=list)
def convert(source: Any, object_info: dict[str, Any] | None = None) -> Conversion:
@@ -46,7 +50,15 @@ def convert_reference(source: Any, profile: str = PROFILE) -> Conversion:
Public reference definitions cannot establish target execution eligibility.
"""
if (
profile not in (PROFILE, AUX_PROFILE, PRIMITIVE_PROFILE, *STRUCTURE_PROFILES)
profile
not in (
PROFILE,
AUX_PROFILE,
PRIMITIVE_PROFILE,
PREVIEW_PROFILE,
*STRUCTURE_PROFILES,
*PROMOTED_PROFILES,
)
or not isinstance(source, dict)
or "nodes" not in source
):
@@ -56,34 +68,51 @@ def convert_reference(source: Any, profile: str = PROFILE) -> Conversion:
True,
)
try:
if profile in STRUCTURE_PROFILES:
structure = expand_reference_subgraphs(source, profile)
if profile in (*STRUCTURE_PROFILES, *PROMOTED_PROFILES):
promoted = profile in PROMOTED_PROFILES
structure_profile = profile.replace("-promoted-reference", "-structure-reference")
structure = expand_reference_subgraphs(source, structure_profile, widgets=promoted)
if structure.graph is None:
return Conversion(None, structure.issues, True)
# Structural scope never supplies widget contracts for newer versions.
# List the concrete remaining node gaps instead of one subgraph error.
result = _convert(structure.graph, {}, reference=True, reference_profile=profile)
result = _convert(
structure.graph,
promoted_definitions() if promoted else {},
reference=True,
reference_profile=profile,
boundary_values=structure.resolved,
)
result.issues = structure.issues + result.issues
for boundary in structure.unresolved:
result.issues.append(
{
"code": "boundary_widget_unverified",
**boundary,
"message": "边界无外部连线;不按位置猜 promoted widget 值",
"message": boundary.get(
"reason", "边界无外部连线;不按位置猜 promoted widget 值"
),
}
)
result.prompt = None
if not promoted or result.issues:
result.prompt = None
result.reference_only = True
result.diagnostic_graph = structure.graph
result.unresolved_boundaries = structure.unresolved
result.resolved_boundaries = structure.resolved
return result
if (
profile == PREVIEW_PROFILE
and (source.get("extra") or {}).get("frontendVersion") != "1.37.11"
):
raise ValueError("PreviewAny 需要显式1.37.11前端声明")
original = source
if profile == PRIMITIVE_PROFILE:
if profile in (PRIMITIVE_PROFILE, PREVIEW_PROFILE):
source = fold_reference_primitives(source, profile)
result = _convert(
source, reference_definitions(profile), reference=True, reference_profile=profile
)
if profile == PRIMITIVE_PROFILE and source != original:
if profile in (PRIMITIVE_PROFILE, PREVIEW_PROFILE) and source != original:
result.diagnostic_graph = source
except (ValueError, TypeError, KeyError, AttributeError, IndexError) as exc:
return Conversion(None, [{"code": "invalid_reference_contract", "message": str(exc)}], True)
@@ -91,7 +120,9 @@ def convert_reference(source: Any, profile: str = PROFILE) -> Conversion:
return result
def _convert(source, object_info=None, *, reference=False, reference_profile=PROFILE) -> Conversion:
def _convert(
source, object_info=None, *, reference=False, reference_profile=PROFILE, boundary_values=()
) -> Conversion:
issues: list[dict[str, Any]] = []
def fail(code: str, message: str, node_id: Any = "") -> None:
@@ -141,7 +172,9 @@ def _convert(source, object_info=None, *, reference=False, reference_profile=PRO
links[str(link[0])] = link
if reference:
frontend_version = (source.get("extra") or {}).get("frontendVersion")
expected_version = STRUCTURE_PROFILES.get(reference_profile, "1.37.11")
expected_version = {**STRUCTURE_PROFILES, **PROMOTED_PROFILES}.get(
reference_profile, "1.37.11"
)
if frontend_version is not None and frontend_version != expected_version:
fail("reference_frontend_mismatch", "源图声明的前端版本与固定参考不一致")
# Validate every stored link, even unused branches: never silently drop
@@ -194,12 +227,16 @@ def _convert(source, object_info=None, *, reference=False, reference_profile=PRO
inputs = {}
if reference:
try:
inputs.update(serialize_reference_widgets(node, reference_profile))
inputs.update(
serialize_promoted_node(node, PROMOTED_PROFILES[reference_profile])
if reference_profile in PROMOTED_PROFILES
else serialize_reference_widgets(node, reference_profile)
)
if [s.get("type") for s in node.get("outputs", [])] != spec["output"]:
raise ValueError("源输出槽不符合固定参考契约")
names = [s.get("name") for s in node.get("inputs", [])]
allowed = set(declared) | ({"upload"} if ct == "LoadImage" else set())
if reference_profile == PRIMITIVE_PROFILE and ct == "LoadAudio":
if reference_profile in (PRIMITIVE_PROFILE, PREVIEW_PROFILE) and ct == "LoadAudio":
allowed |= {"upload", "audioUI"}
if len(names) != len(set(names)) or set(names) - allowed:
raise ValueError("额外或重复输入槽不在固定参考契约内")
@@ -217,6 +254,12 @@ def _convert(source, object_info=None, *, reference=False, reference_profile=PRO
nid,
)
continue
# graphToPrompt writes resolved promoted widgetInfo after the ordinary
# serializer, before/alongside resolved links. Values bypass the inner
# custom serializeValue; external links still take priority below.
for boundary in boundary_values:
if boundary["node_id"] == nid:
inputs[boundary["input_name"]] = boundary["value"]
for name, socket in sockets.items():
lid = socket.get("link")
if lid is None:
@@ -249,7 +292,13 @@ def _convert(source, object_info=None, *, reference=False, reference_profile=PRO
expected = declared[name][0] if declared[name] else None
actual = outputs[link[2]]
# Custom unions/wildcards need frontend evidence; do not guess coercions.
if expected != actual:
if expected != actual and not (
reference
and reference_profile == PREVIEW_PROFILE
and ct == "PreviewAny"
and name == "source"
and expected == "*"
):
fail(
"link_type_unverified",
f"输入 {name} 的槽类型不一致:{actual} → {expected}",
@@ -0,0 +1,379 @@
"""Mutation fixtures are synthetic; real source/API comparisons are separate."""
import json
from copy import deepcopy
from pathlib import Path
import pytest
from calliope.comfyui.serialization_reference import PREVIEW_PROFILE
from calliope.comfyui.ui2api import convert, convert_reference
def real(case):
repo = Path(__file__).resolve().parents[2]
cases = json.loads((repo / "docs/hel-892/golden-cases.json").read_text())["cases"]
row = next(c for c in cases if c["id"] == case)
return json.loads((repo / row["source_path"]).read_text())
PROFILE = "comfy-frontend-1.53.6-promoted-reference"
D = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"
E = "aaaaaaaa-bbbb-cccc-dddd-ffffffffffff"
def fixture(value="external", *, boolean=False):
kind = "BOOLEAN" if boolean else "STRING"
ct = "PrimitiveBoolean" if boolean else "PrimitiveStringMultiline"
definition = {
"id": D,
"inputNode": {"id": -10},
"outputNode": {"id": -20},
"inputs": [{"name": "stable", "type": kind, "linkIds": [10]}],
"outputs": [{"name": "out", "type": kind, "linkIds": [11]}],
"nodes": [
{
"id": 3,
"type": ct,
"properties": {"cnr_id": "comfy-core", "ver": "0.38.0"},
"widgets_values": [True if boolean else "internal"],
"inputs": [
{"name": "value", "type": kind, "widget": {"name": "value"}, "link": 10}
],
"outputs": [{"type": kind, "links": [11]}],
}
],
"links": [[10, -10, 0, 3, 0, kind], [11, 3, 0, -20, 0, kind]],
}
return {
"nodes": [
{
"id": 5,
"type": D,
"widgets_values": [value],
"inputs": [
{
"name": "stable",
"label": "value",
"type": kind,
"widget": {"name": "stable"},
"link": None,
}
],
"outputs": [{"name": "out", "type": kind, "links": []}],
}
],
"links": [],
"definitions": {"subgraphs": [definition]},
"extra": {"frontendVersion": "1.53.6"},
}
def test_real_preview_candidate_keeps_all_proven_serializer_differences():
source = real("02")
before = deepcopy(source)
result = convert_reference(source, PREVIEW_PROFILE)
assert result.prompt is not None and result.reference_only
for nid in ("1", "2", "3", "4"):
assert result.prompt[nid]["inputs"]["preview"] == ""
assert result.prompt[nid]["inputs"]["previewMode"] is None
assert result.prompt[nid]["inputs"]["source"][0] == "9"
assert result.prompt["6"]["inputs"]["audioUI"] == ""
assert "normalize_text" not in result.prompt["9"]["inputs"]
assert "7" not in result.prompt and source == before
assert convert(source).prompt is None
@pytest.mark.parametrize("value", [True, False, None])
def test_preview_first_persisted_element_restores_mode_not_a_dom_text(value):
source = real("02")
source["nodes"][0]["widgets_values"][0] = value
result = convert_reference(source, PREVIEW_PROFILE)
assert result.prompt["2"]["inputs"]["previewMode"] is value
assert result.prompt["2"]["inputs"]["preview"] == ""
@pytest.mark.parametrize(
"mutation",
[
"count",
"bad_mode_type",
"bad_placeholder",
"provider",
"version",
"frontend",
"missing_frontend",
"custom",
"port",
],
)
def test_preview_unknown_contract_fails_entire_graph(mutation):
source = real("02")
node = source["nodes"][0]
if mutation == "count":
node["widgets_values"].pop()
elif mutation == "bad_mode_type":
node["widgets_values"][0] = 0
elif mutation == "bad_placeholder":
node["widgets_values"][1] = "saved text"
elif mutation == "provider":
node["properties"]["cnr_id"] = "override"
elif mutation == "version":
node["properties"]["ver"] = "0.38.0"
elif mutation == "frontend":
source["extra"]["frontendVersion"] = "1.53.6"
elif mutation == "missing_frontend":
source["extra"].pop("frontendVersion")
elif mutation == "custom":
node["serializeValue"] = "override"
else:
node["inputs"][0]["name"] = "other"
assert convert_reference(source, PREVIEW_PROFILE).prompt is None
@pytest.mark.parametrize("value,boolean", [("changed", False), ("", False), (False, True)])
def test_promoted_wins_over_internal_value_and_keeps_exact_scalar(value, boolean):
source = fixture(value, boolean=boolean)
before = deepcopy(source)
result = convert_reference(source, PROFILE)
assert result.prompt["5:3"]["inputs"]["value"] == value
assert type(result.prompt["5:3"]["inputs"]["value"]) is type(value)
row = result.resolved_boundaries[0]
assert row["value_pointer"] == "/nodes/0/widgets_values/0"
assert row["binding_name"] == "stable"
assert row["target_pointer"] == "/definitions/subgraphs/0/nodes/0/inputs/0"
assert source == before and convert(source).prompt is None
def test_zero_and_boolean_are_not_conflated():
source = fixture(0)
inner = source["definitions"]["subgraphs"][0]["nodes"][0]
inner.update(type="EmptyLatentImage", widgets_values=[64, 64, 1])
inner["inputs"][0].update(name="width", type="INT", widget={"name": "width"})
inner["outputs"][0]["type"] = "LATENT"
definition = source["definitions"]["subgraphs"][0]
definition["inputs"][0]["type"] = "INT"
definition["outputs"][0]["type"] = "LATENT"
definition["links"][0][5] = "INT"
definition["links"][1][5] = "LATENT"
source["nodes"][0]["inputs"][0]["type"] = "INT"
source["nodes"][0]["outputs"][0]["type"] = "LATENT"
assert convert_reference(source, PROFILE).prompt["5:3"]["inputs"]["width"] == 0
source["nodes"][0]["widgets_values"] = [False]
assert convert_reference(source, PROFILE).prompt is None
def test_external_link_has_priority_over_both_host_and_internal_scalars():
source = fixture("host")
inner = deepcopy(source["definitions"]["subgraphs"][0]["nodes"][0])
inner.update(id=9, widgets_values=["upstream"], inputs=[])
inner["outputs"][0]["links"] = [1]
source["nodes"].append(inner)
source["nodes"][0]["inputs"][0]["link"] = 1
source["links"] = [[1, 9, 0, 5, 0, "STRING"]]
result = convert_reference(source, PROFILE)
assert result.prompt["5:3"]["inputs"]["value"] == ["9", 0]
assert result.resolved_boundaries == []
def test_multi_instance_and_nested_boundary_values_do_not_cross_scopes():
source = fixture("left")
other = deepcopy(source["nodes"][0])
other.update(id=6, widgets_values=["right"])
source["nodes"].append(other)
outer = source["definitions"]["subgraphs"][0]
nested = deepcopy(outer)
nested["id"] = E
outer["nodes"] = [
{
"id": 3,
"type": E,
"widgets_values": ["nested-default"],
"inputs": [
{"name": "stable", "type": "STRING", "widget": {"name": "stable"}, "link": 10}
],
"outputs": [{"name": "out", "type": "STRING", "links": [11]}],
}
]
source["definitions"]["subgraphs"].append(nested)
result = convert_reference(source, PROFILE)
assert result.prompt["5:3:3"]["inputs"]["value"] == "left"
assert result.prompt["6:3:3"]["inputs"]["value"] == "right"
source["nodes"][1]["widgets_values"][0] = "mutated"
second = convert_reference(source, PROFILE)
assert second.prompt["5:3:3"]["inputs"]["value"] == "left"
assert second.prompt["6:3:3"]["inputs"]["value"] == "mutated"
@pytest.mark.parametrize(
"mutation",
[
"null",
"missing",
"extra",
"binding",
"duplicate",
"version",
"provider",
"named_conflict",
"quarantine",
"host_custom",
"unknown",
],
)
def test_bad_promoted_contract_never_falls_back_to_internal_default(mutation):
source = fixture()
instance = source["nodes"][0]
inner = source["definitions"]["subgraphs"][0]["nodes"][0]
if mutation == "null":
instance["widgets_values"] = [None]
elif mutation == "missing":
instance["widgets_values"] = []
elif mutation == "extra":
instance["widgets_values"].append("extra")
elif mutation == "binding":
instance["inputs"][0]["widget"]["name"] = "value"
elif mutation == "duplicate":
inner["inputs"].append(deepcopy(inner["inputs"][0]))
elif mutation == "version":
inner["properties"]["ver"] = "0.31.0"
elif mutation == "provider":
inner["properties"]["cnr_id"] = "third-party"
elif mutation == "named_conflict":
instance["widgets_values_named"] = {"stable": "different"}
elif mutation == "host_custom":
instance["widgets"] = [{"name": "stable", "serializeValue": "override"}]
elif mutation == "quarantine":
instance["properties"] = {"proxyWidgetErrorQuarantine": [{"hostValue": "override"}]}
else:
inner["type"] = "Unknown"
assert convert_reference(source, PROFILE).prompt is None
def test_same_binding_fanout_and_type_constraint_conflict():
source = fixture("fanout")
d = source["definitions"]["subgraphs"][0]
other = deepcopy(d["nodes"][0])
other["id"] = 4
other["inputs"][0]["link"] = 12
other["outputs"][0]["links"] = []
d["nodes"].append(other)
d["inputs"][0]["linkIds"].append(12)
d["links"].append([12, -10, 0, 4, 0, "STRING"])
result = convert_reference(source, PROFILE)
assert result.prompt["5:3"]["inputs"]["value"] == "fanout"
assert result.prompt["5:4"]["inputs"]["value"] == "fanout"
other["type"] = "PrimitiveBoolean"
other["inputs"][0]["type"] = "BOOLEAN"
other["outputs"][0]["type"] = "BOOLEAN"
other["widgets_values"] = [True]
assert convert_reference(source, PROFILE).prompt is None
def test_real04_resolves_proven_boundaries_without_completing_unknown_nodes():
source = real("04")
result = convert_reference(source, PROFILE)
assert result.prompt is None
values = {(v["node_id"], v["input_name"]): v for v in result.resolved_boundaries}
assert values["459:474", "switch"]["value"] is True
assert values["459:471", "thinking"]["value"] is False
assert {(v["node_id"], v["input_name"]) for v in result.unresolved_boundaries} == {
("459:458", "seed"),
("459:471", "sampling_mode.seed"),
}
# Change both representations: setting namedValuesRestore is deliberately unknown.
instance = source["nodes"][1]
instance["widgets_values"][1] = False
instance["widgets_values_named"]["switch"] = False
changed = convert_reference(source, PROFILE)
assert (
next(
v["value"]
for v in changed.resolved_boundaries
if v["node_id"] == "459:474" and v["input_name"] == "switch"
)
is False
)
def test_real03_keeps_missing_core_version_contract_explicit():
result = convert_reference(real("03"), "comfy-frontend-1.48.7-promoted-reference")
assert result.prompt is None and result.unresolved_boundaries
assert any(i["node_id"] == "37:13" for i in result.issues)
def test_parent_boundary_does_not_overwrite_unrelated_same_name_root_field():
source = fixture("parent")
root = deepcopy(source["definitions"]["subgraphs"][0]["nodes"][0])
root.update(id=9, inputs=[], widgets_values=["root"])
root["outputs"][0]["links"] = []
source["nodes"].append(root)
result = convert_reference(source, PROFILE)
assert result.prompt["5:3"]["inputs"]["value"] == "parent"
assert result.prompt["9"]["inputs"]["value"] == "root"
def test_simple_named_restore_disagreement_rejects_and_agreement_is_safe_for_both_settings():
source = fixture("host")
inner = source["definitions"]["subgraphs"][0]["nodes"][0]
inner["widgets_values_named"] = {"value": "internal"}
source["nodes"][0]["widgets_values_named"] = {"stable": "host"}
assert convert_reference(source, PROFILE).prompt["5:3"]["inputs"]["value"] == "host"
inner["widgets_values_named"]["value"] = "other"
assert convert_reference(source, PROFILE).prompt is None
def test_promoted_link_resolution_bypasses_inner_dynamic_prompt_serializer():
source = real("04")
instance = source["nodes"][1]
names = [s["name"] for s in instance["inputs"]]
index = names.index("negative_prompt")
instance["widgets_values"][index] = "{raw|not sampled}"
instance["widgets_values_named"]["negative_prompt"] = "{raw|not sampled}"
result = convert_reference(source, PROFILE)
resolved = next(
r
for r in result.resolved_boundaries
if (r["node_id"], r["input_name"]) == ("459:452", "negative_prompt")
)
assert resolved["value"] == "{raw|not sampled}"
assert result.prompt is None # unknown whole node/dynamic serializers remain closed
def test_primitive_inside_promoted_profile_remains_a_concrete_blocker():
source = fixture()
inner = source["definitions"]["subgraphs"][0]["nodes"][0]
inner["type"] = "PrimitiveNode"
result = convert_reference(source, PROFILE)
assert result.prompt is None
assert any(i["code"] == "reference_node_unsupported" for i in result.issues)
def test_conflicting_nested_store_identity_is_not_assumed_to_be_scoped_by_execution_id():
source = fixture("outer-a")
base = source["definitions"]["subgraphs"][0]
nested_a = deepcopy(base)
nested_a["id"] = E
nested_b = deepcopy(base)
nested_b["id"] = "aaaaaaaa-bbbb-cccc-dddd-111111111111"
outer_b = deepcopy(base)
outer_b["id"] = "aaaaaaaa-bbbb-cccc-dddd-222222222222"
for outer, inner, value in ((base, nested_a, "a"), (outer_b, nested_b, "b")):
outer["nodes"] = [
{
"id": 3,
"type": inner["id"],
"widgets_values": [value],
"inputs": [
{"name": "stable", "type": "STRING", "widget": {"name": "stable"}, "link": 10}
],
"outputs": [{"name": "out", "type": "STRING", "links": [11]}],
}
]
instance_b = deepcopy(source["nodes"][0])
instance_b.update(id=6, type=outer_b["id"], widgets_values=["outer-b"])
source["nodes"].append(instance_b)
source["definitions"]["subgraphs"].extend([outer_b, nested_a, nested_b])
result = convert_reference(source, PROFILE)
assert result.prompt is None
assert any("widgetId冲突" in i["message"] for i in result.issues)