Line data Source code
1 : /**
2 : * Whether the Agent wire may declare a node's widget form, and the four
3 : * invariants that decide it.
4 : *
5 : * `widgets_values_form` tells the host which order its name-keyed registers
6 : * belong in. A node that carries one consults no catalogue on any leg, so a
7 : * wrong form is authoritative and strictly worse than no form: the rule is a
8 : * proof, not a derivation. Where a leg cannot be proven, nothing is declared.
9 : *
10 : * Every check reads the POST-HOOK payload, and that is the whole point.
11 : * `LGraphNode.serializeFromStoreState` writes `widgets_values` /
12 : * `widgets_values_named` from `node.widgets` and *then* calls
13 : * `runExtensionSerializeHook`, which copies an extension's own writes back
14 : * over both fields because they are in `NODE_CANONICAL_FIELDS`. So "one loop
15 : * emits the values and the order, therefore they cannot drift" is false, and
16 : * it is false in exactly the population the hook exists for — third-party
17 : * packs with custom serializers. A pre-hook check would assert the one thing
18 : * that was never in doubt.
19 : *
20 : * See docs/adr/WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md
21 : */
22 : import type { WidgetValuesForm } from '@comfyorg/comfy-multi-player'
23 :
24 : import { assert } from '@/base/assert'
25 : import type { LGraphNode } from '@/lib/litegraph/src/LGraphNode'
26 : import type { ISerialisedNode } from '@comfyorg/graph-model/serialisation'
27 : import type { IBaseWidget } from '@comfyorg/graph-model/widgets'
28 : import { reportError } from '@comfyorg/telemetry/reportError'
29 : import { useNodeDefStore } from '@/stores/nodeDefStore'
30 : import { useWidgetValueStore } from '@/stores/widgetValueStore'
31 : import type { WidgetState } from '@comfyorg/graph-model/widgetState'
32 : import { widgetId } from '@comfyorg/graph-model/widgetId'
33 :
34 : /** The post-hook halves of a serialized node this module reads. */
35 : type SerializedWidgetValues = Pick<ISerialisedNode, 'widgets_values_named'>
36 :
37 : /**
38 : * Why no form was declared. The first four are invariant violations: the
39 : * values and the order disagree, so declaring either would publish a state no
40 : * other reader sees. The rest are shapes a correct producer legitimately
41 : * cannot describe, and they are the population invariant 4 counts.
42 : */
43 : type WidgetFormSuppression =
44 : /** Invariant 1 — an entry names no live widget core would serialise. */
45 : | 'order_names_unserialized_widget'
46 : /** Invariant 2 — declared order and value keys differ in either direction. */
47 : | 'declared_keys_disagree'
48 : /** Invariant 3 — the hook changed the values carried by the Agent wire. */
49 : | 'hook_changed_serialized_widgets'
50 : /** The catalogue owns this order: it is a function of the values. */
51 : | 'value_dependent_layout'
52 : /** A missing-node shell round-trips a stored payload, not live widgets. */
53 : | 'shell_last_serialization'
54 : /** A custom serialization hook threw before producing a payload. */
55 : | 'serialization_failed'
56 : /** A value the document carries has no live widget to order. */
57 : | 'value_has_no_live_widget'
58 : /** Nothing to declare. */
59 : | 'no_value_widgets'
60 : /** An unnamed widget cannot be addressed by name. */
61 : | 'unnamed_value_widget'
62 : /** Two value widgets share a name, so the order is ambiguous. */
63 : | 'duplicate_widget_name'
64 :
65 : /**
66 : * Nothing to declare is not a declaration gap: a node whose only widgets are
67 : * buttons has no named value for a form to order, so counting it would bury
68 : * invariant 4's signal under every such class in the ecosystem.
69 : */
70 2355 : const UNREPORTED: ReadonlySet<WidgetFormSuppression> = new Set([
71 : 'no_value_widgets'
72 : ])
73 :
74 : type SuppressedWidgetFormVerdict = {
75 : readonly declared: false
76 : readonly reason: WidgetFormSuppression
77 : readonly detail?: Record<string, unknown>
78 : }
79 :
80 : export type WidgetFormVerdict =
81 : | { readonly declared: true; readonly form: WidgetValuesForm }
82 : | SuppressedWidgetFormVerdict
83 :
84 2355 : const ADR =
85 : 'docs/adr/WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md'
86 :
87 : /**
88 : * Assertion text, one per broken invariant. Membership of this record is what
89 : * makes a reason an invariant violation rather than a shape we cannot
90 : * describe. `assert` forwards the message to external telemetry and groups on
91 : * it, so each is a static description of the invariant that broke plus where
92 : * it is written down — never a value.
93 : */
94 2355 : const INVARIANT_MESSAGES: Partial<Record<WidgetFormSuppression, string>> = {
95 : order_names_unserialized_widget:
96 : 'Agent widget form invariant 1: a declared order entry names no live widget with serialize !== false, so the form orders a widget core never serialises — ' +
97 : `see ${ADR}`,
98 : declared_keys_disagree:
99 : 'Agent widget form invariant 2: the declared order and the object-shaped widgets_values keys differ in one direction or the other, so the form either orders an absent value or drops a stored one — ' +
100 : `see ${ADR}`,
101 : hook_changed_serialized_widgets:
102 : 'Agent widget form invariant 3: the extension serialize hook changed which live value widgets reach the Agent wire, so the form no longer describes the values sent — ' +
103 : `see ${ADR}`
104 : }
105 :
106 2355 : const UNDECLARED_FORM_MESSAGE =
107 : 'Agent widget form invariant 4: object-shaped widget values with no declared form'
108 :
109 2355 : const VALUE_DEPENDENT_LAYOUT_INPUT_TYPES = new Set([
110 : 'COMFY_AUTOGROW_V3',
111 : 'COMFY_DYNAMICCOMBO_V3',
112 : 'COMFY_DYNAMICGROUP_V3'
113 : ])
114 :
115 : export interface WidgetFormSuppressionTally {
116 : /** The node class, so a population is attributable without a join. */
117 : readonly nodeType: string
118 : readonly reason: WidgetFormSuppression
119 : readonly count: number
120 : }
121 :
122 2355 : const tally = new Map<
123 : string,
124 : { nodeType: string; reason: WidgetFormSuppression; count: number }
125 : >()
126 2355 : const reported = new Set<string>()
127 2355 : const MAX_SUPPRESSION_KEYS = 100
128 :
129 2355 : const tallyKey = (nodeType: string, reason: WidgetFormSuppression): string =>
130 : JSON.stringify([nodeType, reason])
131 :
132 : /**
133 : * Up to the first 100 distinct suppressions this page session saw, by class
134 : * and reason.
135 : *
136 : * This is the bulk instrument. A corpus run reads it once at the end instead
137 : * of scraping telemetry, and `nodeType` makes the answer a class-by-class
138 : * breakdown rather than a pass/fail. Pair it with
139 : * {@link widgetValuesFormVerdict} to classify a node without minting anything.
140 : */
141 : export function widgetFormSuppressionTally(): WidgetFormSuppressionTally[] {
142 : return [...tally.values()].map((entry) => ({ ...entry }))
143 : }
144 :
145 : /** Drops the accumulated tally. For tests and for a fresh corpus pass. */
146 : export function resetWidgetFormSuppressionTally(): void {
147 : tally.clear()
148 : reported.clear()
149 : }
150 :
151 0 : function record(nodeType: string, reason: WidgetFormSuppression): void {
152 0 : const key = tallyKey(nodeType, reason)
153 0 : const seen = tally.get(key)
154 0 : if (seen) {
155 0 : seen.count += 1
156 0 : return
157 : }
158 0 : if (tally.size >= MAX_SUPPRESSION_KEYS) return
159 0 : tally.set(key, { nodeType, reason, count: 1 })
160 : }
161 :
162 0 : function firstReport(nodeType: string, reason: WidgetFormSuppression): boolean {
163 0 : const key = tallyKey(nodeType, reason)
164 0 : if (reported.has(key) || reported.size >= MAX_SUPPRESSION_KEYS) return false
165 0 : reported.add(key)
166 0 : return true
167 : }
168 :
169 0 : function suppressed(
170 : reason: WidgetFormSuppression,
171 : detail?: Record<string, unknown>
172 : ): SuppressedWidgetFormVerdict {
173 0 : return detail
174 : ? { declared: false, reason, detail }
175 : : { declared: false, reason }
176 : }
177 :
178 0 : function sameNames(left: readonly string[], right: readonly string[]): boolean {
179 0 : const a = new Set(left)
180 0 : const b = new Set(right)
181 0 : return a.size === b.size && [...a].every((name) => b.has(name))
182 : }
183 :
184 : /**
185 : * Whether the live widget, or the store metadata the intent was keyed by when
186 : * the live widget is missing or omits a field, identifies a value the document
187 : * carries. Unknown widgets fail closed.
188 : */
189 0 : export function isValueWidget(
190 : widget: IBaseWidget | undefined,
191 : stored?: WidgetState
192 : ): boolean {
193 0 : if (!widget && !stored) return false
194 : // A destructuring default fires on absent AND present-but-undefined alike,
195 : // which is what `IBaseWidget`'s own optional fields mean: the live widget
196 : // did not state this, so the registration the intent was keyed by answers.
197 : // One construct for both fields, so the two halves of the guard cannot
198 : // drift apart again.
199 0 : const { type = stored?.type, serialize = stored?.serialize } = widget ?? {}
200 0 : return type !== 'button' && serialize !== false
201 : }
202 :
203 : /** The named values the document carries, dropping non-value widgets. */
204 0 : export function valueWidgetsOnly(
205 : node: LGraphNode,
206 : named: object
207 : ): Record<string, unknown> {
208 0 : const filtered: Record<string, unknown> = Object.create(null)
209 0 : const rootGraphId = node.graph?.rootGraph.id
210 0 : const widgetValueStore = useWidgetValueStore()
211 0 : for (const [name, value] of Object.entries(named)) {
212 0 : const stored = rootGraphId
213 : ? widgetValueStore.getWidget(widgetId(rootGraphId, node.id, name))
214 : : undefined
215 : const carriesValue = node.widgets?.some(
216 : (candidate) => candidate.name === name && isValueWidget(candidate, stored)
217 : )
218 0 : if (carriesValue)
219 0 : Object.defineProperty(filtered, name, {
220 : value,
221 : writable: true,
222 : enumerable: true,
223 : configurable: true
224 : })
225 : }
226 0 : return filtered
227 : }
228 :
229 : /** The post-hook payload and the live widget list, read once. */
230 : interface FormProof {
231 : /** Every live widget's name, serialised or not. */
232 : readonly liveNames: readonly string[]
233 : /** The names of live widgets whose values the Agent wire carries. */
234 : readonly valueWidgetNames: readonly string[]
235 : /** The enumerable keys of the object the wire ships. */
236 : readonly valueNames: readonly string[]
237 : /** The order the form would declare. */
238 : readonly order: readonly string[]
239 : }
240 :
241 0 : function formProof(
242 : node: LGraphNode,
243 : values: Record<string, unknown>,
244 : _serialized: SerializedWidgetValues
245 : ): FormProof {
246 0 : const live = node.widgets ?? []
247 0 : const rootGraphId = node.graph?.rootGraph.id
248 0 : const widgetValueStore = useWidgetValueStore()
249 0 : const valueWidgetNames = live
250 : .filter((widget) => {
251 : const stored = rootGraphId
252 : ? widgetValueStore.getWidget(
253 : widgetId(rootGraphId, node.id, widget.name)
254 : )
255 : : undefined
256 0 : return isValueWidget(widget, stored)
257 : })
258 : .map((widget) => widget.name)
259 0 : return {
260 : liveNames: live.map((widget) => widget.name),
261 : valueWidgetNames,
262 : valueNames: Object.keys(values),
263 : order: valueWidgetNames.filter((name) => Object.hasOwn(values, name))
264 : }
265 : }
266 :
267 : /** Returns a suppression when this leg of the proof fails, else nothing. */
268 : type FormProbe = (proof: FormProof) => WidgetFormVerdict | undefined
269 :
270 : /**
271 : * Invariant 3 — compare the key set that survives the Agent wire's value
272 : * filter with the live value widgets. Positional values and extension-private
273 : * entries are not sent, so neither can invalidate this proof.
274 : */
275 2355 : const hookKeptTheSerialisedWidgets: FormProbe = ({
276 : valueNames,
277 : valueWidgetNames
278 : }) =>
279 : sameNames(valueNames, valueWidgetNames)
280 : ? undefined
281 : : suppressed('hook_changed_serialized_widgets', {
282 : wire: valueNames,
283 : live: valueWidgetNames
284 : })
285 :
286 : /**
287 : * A document value with no live widget at all is the stored-state family, not
288 : * a broken invariant: the node shed the widget, or was never registered.
289 : * Checked before invariant 1 so the two are not conflated — "there is no
290 : * widget" and "there is one core refuses to serialise" have different causes
291 : * and different fixes.
292 : */
293 2355 : const everyValueHasALiveWidget: FormProbe = ({ valueNames, liveNames }) => {
294 0 : const unbacked = valueNames.filter((name) => !liveNames.includes(name))
295 0 : return unbacked.length
296 : ? suppressed('value_has_no_live_widget', { names: unbacked })
297 : : undefined
298 : }
299 :
300 : /**
301 : * Invariant 1 — an order entry must name a live widget core serialises.
302 : * Reachable only if a value for a `serialize: false` widget gets into
303 : * `values`, which `isValueWidget` currently refuses: this is the guard on
304 : * that filter.
305 : */
306 2355 : const orderNamesSerialisedWidgets: FormProbe = ({
307 : order,
308 : valueWidgetNames
309 : }) => {
310 0 : const unserialized = order.filter((name) => !valueWidgetNames.includes(name))
311 0 : return unserialized.length
312 : ? suppressed('order_names_unserialized_widget', { names: unserialized })
313 : : undefined
314 : }
315 :
316 : /**
317 : * Invariant 2 — the object case, as a set difference in BOTH directions.
318 : * Order without a value orders nothing; a value outside the order is residue
319 : * the host would store and never project. Stated against the enumerable keys,
320 : * because those are what travel: the wire ships `values` as JSON, so an own
321 : * property `Object.hasOwn` can see and `Object.keys` cannot is an order entry
322 : * whose value never arrives.
323 : */
324 2355 : const declaredKeysAgree: FormProbe = ({ valueNames, order }) => {
325 0 : const undeclared = valueNames.filter((name) => !order.includes(name))
326 0 : const unvalued = order.filter((name) => !valueNames.includes(name))
327 0 : return undeclared.length || unvalued.length
328 : ? suppressed('declared_keys_disagree', { undeclared, unvalued })
329 : : undefined
330 : }
331 :
332 : /** Shapes a name-keyed order cannot address, whatever the values say. */
333 2355 : const orderIsAddressable: FormProbe = ({ order }) => {
334 0 : if (!order.length) return suppressed('no_value_widgets')
335 0 : if (order.some((name) => !name.length))
336 0 : return suppressed('unnamed_value_widget')
337 0 : if (new Set(order).size !== order.length)
338 0 : return suppressed('duplicate_widget_name', { order })
339 : return undefined
340 : }
341 :
342 : /**
343 : * Ordered most-specific-cause first, so the reason names the thing that
344 : * actually happened rather than its downstream shadow: the hook changing the
345 : * serialised widget set shows up as a key disagreement too, and attributing
346 : * it to the key disagreement would send a reader looking in the wrong place.
347 : */
348 2355 : const FORM_PROBES: readonly FormProbe[] = [
349 : everyValueHasALiveWidget,
350 : orderNamesSerialisedWidgets,
351 : declaredKeysAgree,
352 : hookKeptTheSerialisedWidgets,
353 : orderIsAddressable
354 : ]
355 :
356 : /**
357 : * Classifies a node's form without declaring, asserting or reporting
358 : * anything. Pure apart from the node-definition read, so a bulk pass can call
359 : * it per node and keep the reason.
360 : */
361 0 : export function classifyWidgetValuesForm(
362 : node: LGraphNode,
363 : values: Record<string, unknown>,
364 : serialized: SerializedWidgetValues
365 : ): WidgetFormVerdict {
366 : // The catalogue owns a value-dependent order; declaring one would close a
367 : // list that is supposed to expand with the selection.
368 0 : if (layoutDependsOnValues(node)) return suppressed('value_dependent_layout')
369 :
370 : // A missing-node shell round-trips its stored payload verbatim, so the
371 : // serialized values describe a class this build cannot see and the live
372 : // widget list — fabricated or empty — cannot order them.
373 0 : if (node.last_serialization) return suppressed('shell_last_serialization')
374 :
375 0 : const proof = formProof(node, values, serialized)
376 0 : for (const probe of FORM_PROBES) {
377 0 : const failed = probe(proof)
378 0 : if (failed) return failed
379 : }
380 0 : return { declared: true, form: { order: [...proof.order] } }
381 : }
382 :
383 : /**
384 : * Classifies a node end to end, for a bulk pass that holds a node and not a
385 : * serialization. It runs the node's serialization hook and tallies the
386 : * result, but does not assert or report.
387 : */
388 : export function widgetValuesFormVerdict(node: LGraphNode): WidgetFormVerdict {
389 : if (node.last_serialization) {
390 : const verdict = suppressed('shell_last_serialization')
391 : record(node.type, verdict.reason)
392 : return verdict
393 : }
394 : let serialized: ISerialisedNode
395 : try {
396 : serialized = node.serialize()
397 : } catch {
398 : const verdict = suppressed('serialization_failed')
399 : record(node.type, verdict.reason)
400 : return verdict
401 : }
402 : const named = serialized.widgets_values_named
403 : if (!named) {
404 : const verdict = suppressed('no_value_widgets')
405 : record(node.type, verdict.reason)
406 : return verdict
407 : }
408 : const verdict = classifyWidgetValuesForm(
409 : node,
410 : valueWidgetsOnly(node, named),
411 : serialized
412 : )
413 : if (!verdict.declared) record(node.type, verdict.reason)
414 : return verdict
415 : }
416 :
417 : /**
418 : * The form to put on the wire, or nothing.
419 : *
420 : * Suppression is the gate in every environment. `assert` throws under DEV
421 : * only, so it is the invariant channel and not the mechanism — and the throw
422 : * is swallowed here on purpose, because every one of these invariants is
423 : * breakable by a third-party pack. A pack must not be able to stop the Agent
424 : * from minting in a developer's browser; it must only be unable to make us
425 : * publish a form that describes the wrong values.
426 : */
427 0 : export function provenWidgetValuesForm(
428 : node: LGraphNode,
429 : values: Record<string, unknown>,
430 : serialized: SerializedWidgetValues
431 : ): WidgetValuesForm | undefined {
432 0 : const verdict = classifyWidgetValuesForm(node, values, serialized)
433 0 : if (verdict.declared) return verdict.form
434 :
435 0 : const nodeType = node.type
436 0 : record(nodeType, verdict.reason)
437 0 : const first =
438 : !UNREPORTED.has(verdict.reason) && firstReport(nodeType, verdict.reason)
439 :
440 0 : const invariantMessage = INVARIANT_MESSAGES[verdict.reason]
441 0 : if (first && invariantMessage) {
442 0 : try {
443 0 : assert(false, invariantMessage, { nodeType, ...verdict.detail })
444 : } catch {
445 : // Swallowed on purpose; see this function's contract above.
446 : }
447 : }
448 :
449 : // Invariant 4. One report per class and reason: the question is "which
450 : // classes still declare no form, and why", and a corpus pass that mints
451 : // thousands of nodes must answer it without thousands of reports.
452 0 : if (first) {
453 0 : reportError(new Error(UNDECLARED_FORM_MESSAGE), {
454 : errorType: 'agent_widget_form_undeclared',
455 : surface: 'agent',
456 : level: 'warning',
457 : tags: { node_type: nodeType, reason: verdict.reason },
458 : fingerprint: ['agent_widget_form_undeclared', verdict.reason, nodeType],
459 : context: { adr: ADR, ...verdict.detail }
460 : })
461 : }
462 :
463 : return undefined
464 : }
465 :
466 0 : function layoutDependsOnValues(node: LGraphNode): boolean {
467 0 : const definition = useNodeDefStore().fromLGraphNode(node)
468 0 : return Object.values(definition?.inputs ?? {}).some((spec) =>
469 : VALUE_DEPENDENT_LAYOUT_INPUT_TYPES.has(spec.type)
470 : )
471 : }
|