LCOV - code coverage report
Current view: top level - src/workbench/extensions/agent/crdt - widgetValuesForm.ts Coverage Total Hit
Test: ComfyUI E2E Coverage Lines: 16.9 % 89 15
Test Date: 2026-11-17 04:17:53

            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              : }
        

Generated by: LCOV version 2.0-1