From 217773fe4856a9b374369f076cb166a3aa850f9d Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 23 Oct 2026 01:10:21 -0700 Subject: [PATCH 1/7] FE-3470 fix(agent): prove the widget form against the post-hook values `widgets_values_form` is authoritative: a node carrying one consults no catalog on any leg, so a wrong form is worse than no form. The producer derived the order from the live widget list and checked it only against the values it had already filtered, which cannot see what the extension serialize hook did. It does drift. `LGraphNode.serializeFromStoreState` writes `widgets_values` and `widgets_values_named` from `node.widgets` and *then* runs `runExtensionSerializeHook`, which copies an extension's own writes back over both because they are canonical fields. A pack that rewrites the positional array, or adds a key for a `serialize: false` widget, previously still got a form proven against values no other reader of that workflow sees. Move the decision into one module and state the five invariants there, all read post-hook: the order names live serialised widgets; the positional array still has one slot per serialised widget; order and value keys agree in both directions; the hook did not change which widgets core serialises; and object-shaped values with no declared form are reported once per class and reason, which is the only way to learn which classes still declare nothing. Suppression is the gate in every environment and the assert is the channel, so a third-party pack cannot stop the Agent minting in a dev browser. `widgetValuesFormVerdict` plus the per-class tally give a corpus pass the same classification with no telemetry and no side effects. ADR: docs/adr/WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md --- .../agent/agentWidgetFormHookDrift.spec.ts | 104 ++++ ...-wire-widget-form-is-proven-not-derived.md | 175 +++++++ .../extensions/agent/crdt/docOpMinter.ts | 70 +-- .../agent/crdt/widgetValuesForm.test.ts | 446 ++++++++++++++++++ .../extensions/agent/crdt/widgetValuesForm.ts | Bin 0 -> 15918 bytes 5 files changed, 734 insertions(+), 61 deletions(-) create mode 100644 browser_tests/tests/agent/agentWidgetFormHookDrift.spec.ts create mode 100644 docs/adr/WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md create mode 100644 src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts create mode 100644 src/workbench/extensions/agent/crdt/widgetValuesForm.ts diff --git a/browser_tests/tests/agent/agentWidgetFormHookDrift.spec.ts b/browser_tests/tests/agent/agentWidgetFormHookDrift.spec.ts new file mode 100644 index 00000000000..1b754a0da89 --- /dev/null +++ b/browser_tests/tests/agent/agentWidgetFormHookDrift.spec.ts @@ -0,0 +1,104 @@ +import { expect } from '@playwright/test' + +import type { ComfyNodeDef } from '@/schemas/nodeDefSchema' + +import { agentConversationTest as test } from '@e2e/fixtures/agentConversationFixture' + +const NODE_TYPE = 'AgentWidgetFormDriftProbe' + +const nodeDef: ComfyNodeDef = { + name: NODE_TYPE, + display_name: 'Agent Widget Form Drift Probe', + description: '', + category: 'testing', + python_module: 'browser_tests.agent_widget_form_drift', + output_node: false, + output: ['STRING'], + output_is_list: [false], + output_name: ['text'], + input: { + required: { + text: ['STRING', { default: 'initial value', multiline: false }] + } + }, + input_order: { required: ['text'] } +} + +test.describe( + 'Agent widget form under a third-party serializer', + { tag: ['@cloud', '@agent', '@widget', '@vue-nodes'] }, + () => { + test.use({ + conversationCase: 'agent-rec-text-only-answer', + extraNodeDefs: { [NODE_TYPE]: nodeDef }, + humanOpsHost: 'apply' + }) + + test('declares no widget form for a node whose values a pack rewrites after serialization', async ({ + agentConversation, + page + }) => { + test.setTimeout(90_000) + + await test.step('bind the seeded workflow', async () => { + await agentConversation.runTurns() + }) + + const control = + await test.step('publish a node nothing interferes with', async () => { + const nodeId = await agentConversation.addNodeOfType( + NODE_TYPE, + [400, 400] + ) + const outcomes = await agentConversation.waitForHumanOps(1) + expect(outcomes[0]?.outcome).toBe('applied') + expect(agentConversation.hostNode(nodeId)).toMatchObject({ + widgets_values: { text: 'initial value' }, + widgets_values_form: { order: ['text'] } + }) + return nodeId + }) + + await test.step('install a pack that appends its own entry after the hook', async () => { + // The shape third-party packs actually use: an `onSerialize` that + // appends private state to the positional array. It runs AFTER core + // wrote `widgets_values` from the live widget list, and + // `runExtensionSerializeHook` copies it back because the field is + // canonical — so the order core derived no longer describes the + // values any other reader of this workflow will see. + await page.evaluate((type) => { + const proto = window.LiteGraph!.registered_node_types[type].prototype + proto.onSerialize = function (data) { + data.widgets_values = ['initial value', 'pack private state'] + } + }, NODE_TYPE) + }) + + await test.step('the drifted node reaches the host with no form, and is refused', async () => { + const nodeId = await agentConversation.addNodeOfType( + NODE_TYPE, + [700, 400] + ) + expect(nodeId).not.toBe(control) + + const outcomes = await agentConversation.waitForHumanOps(2) + // Fail closed: with no form this class is uncatalogued, so the host + // refuses the write instead of storing an order nobody proved. + expect(outcomes[1]).toMatchObject({ + outcome: 'rejected', + reason: { code: 'uncatalogued_widget_write' } + }) + expect(agentConversation.hostNode(nodeId)).toBeUndefined() + await expect( + agentConversation.vueNodes.getNodeLocator(nodeId) + ).toBeHidden() + }) + + await test.step('the undrifted node is untouched by the refusal', () => { + expect(agentConversation.hostNode(control)).toMatchObject({ + widgets_values_form: { order: ['text'] } + }) + }) + }) + } +) diff --git a/docs/adr/WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md b/docs/adr/WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md new file mode 100644 index 00000000000..4b8bb221f82 --- /dev/null +++ b/docs/adr/WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md @@ -0,0 +1,175 @@ +# ADR-WIDGET-SERIALIZATION-0047: The Agent wire's widget form is proven, not derived + +Date: 2026-10-23 + +## Status + +Proposed + +## Context + +A workflow stores widget **values** but not the **schema** needed to interpret +them. Three systems reconstruct that schema independently — this frontend from +its own registrations, `comfy-cli` from `object_info` plus a set of +hand-maintained guesses, the doc host from a pinned catalogue — and they drift. +`widgets_values_form` is the minimal self-describing step: it declares the +order the node's named widget values belong in, so the reader needs no +catalogue for that node. + +That makes a form **authoritative**. `comfy-multi-player`'s +`widgetStorageFor` picks self-described storage whenever a form is present, +ahead of the catalogue; `projectWidgets` projects from the form with no +catalogue lookup; and `validateWidgetName` treats the form as closed. A node +that carries a wrong form is therefore worse off than a node that carries +none: there is no later leg at which the mistake can be caught. + +The frontend emits the form at one place only, the Agent wire boundary +(`wireNodeSnapshot` in `src/workbench/extensions/agent/crdt/docOpMinter.ts`). +An ordinary save carries no form. That boundary was chosen deliberately: a +core-serialization producer was reviewed and rejected, because shared +serialization would then be compensating for one consumer's closed-form +interpretation. + +### The claim this ADR exists to refute + +The producer was originally justified by "the values and the order come out of +the same loop, so they cannot drift." That is false, and the falsifier is +specific. `LGraphNode.serializeFromStoreState` does: + +```ts +Object.assign(o, serialiseWidgetValues(widgets)) // core writes both fields +// ... +runExtensionSerializeHook(this, o, NODE_CANONICAL_FIELDS, this.onSerialize) +``` + +`widgets_values` and `widgets_values_named` are both in +`NODE_CANONICAL_FIELDS`, so `runExtensionSerializeHook` copies an extension's +writes to either one back over what core produced. The hook runs **after** +core wrote the values, and a node's `onSerialize` can also mutate +`node.widgets` while it runs. So the values a form would describe can be +replaced, truncated or extended between the derivation and the wire — and in +exactly the population the hook exists for, third-party packs with custom +serializers. A check placed before the hook asserts the one thing that was +never in doubt. + +`SubgraphNode.serializeFromStoreState` is the in-repo instance of the same +shape: it calls `super.serializeFromStoreState(state)`, which already includes +the hook, and then replaces `widgets_values` itself. "Post-hook" is necessary +and not sufficient — the base post-hook is not always the last writer. + +## Decision + +1. **The form is a proof, not a derivation.** The wire declares a form only + where it can prove the final serialized values are the ones core produced + from the live widget list. Where it cannot, it declares nothing. "Declare + nothing" is the behaviour in every environment; see decision 4. +2. **Every check reads the post-hook payload.** The classifier takes the + serialized node returned by `node.serialize()` — hook already run — and + compares it against the live widget list, rather than inspecting state + core holds before the hook. +3. **Five invariants, stated once and asserted at that one site.** They are + the contract; the list below is the normative text and the assertion + messages name the broken entry. +4. **Suppression is the gate; `assert` is the channel.** `assert` from + `src/base/assert.ts` throws under DEV only, so it cannot be the mechanism + that keeps a wrong form off the wire. Returning no form is. The DEV throw + is deliberately swallowed at this seam, because every one of these + invariants is breakable by a third-party pack: a pack must not be able to + stop the Agent from minting in a developer's browser, only to be unable to + make us publish a form describing the wrong values. The console line and + the production reporter still fire. +5. **Invariant 5 is a signal, not a failure.** "Object-shaped values with no + declared form" is the expected state for much of the ecosystem today. It + reports rather than asserts, and it is the only way to learn _which_ + classes still declare nothing, which is what decides whether the form path + generalises. + +### The five invariants + +Let _live_ be `node.widgets`, _serialised_ those of _live_ with +`serialize !== false` (what `serialiseWidgetValues` emits), _values_ the +name-keyed object the wire ships, and _order_ the declared sequence. + +| # | Invariant | Reason slug | +| --- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | +| 1 | Every `order` entry names a live widget with `serialize !== false`. | `order_names_unserialized_widget` | +| 2 | Array case — the post-hook positional `widgets_values` has one entry per _serialised_ widget. | `positional_arity_disagrees` | +| 3 | Object case — `order` and `Object.keys(values)` agree as a set difference in **both** directions. | `declared_keys_disagree` | +| 4 | The form survived the hook: the post-hook `widgets_values_named` key set equals the key set core produces from the live serialised widgets. | `hook_changed_serialized_widgets` | +| 5 | Object-shaped values with no declared form are reported, once per class and reason. | `agent_widget_form_undeclared` | + +Three of these need their exact form recorded, because the obvious version of +each is wrong: + +- **Invariant 2 is stated against the positional array, not against the + order.** The wire ships the object, so `order.length === widgets_values.length` + is unreachable there as written. The reachable and load-bearing claim is that + the array the hook left behind still has one slot per serialised widget: if a + pack rewrote it to a different arity, the order was proven against values no + other reader of that workflow will see. +- **Invariant 3 is bidirectional.** `order` ⊆ `keys(values)` alone misses + residue — a stored value outside the order, which the host would keep and + never project. The VideoHelperSuite shape is the in-ecosystem instance: it + keys its dict from the _unfiltered_ widget list, so its keys and a derived + order differ by exactly the one widget carrying `serialize = false`. +- **Invariant 4 compares key sets, not key sequences.** Key order inside + `widgets_values_named` is not meaningful — an integer-like widget name is + enumeration-reordered by the object itself, which is the reason the form + exists. A pack that reorders keys and changes nothing else has not broken + anything. + +### Shapes that are suppressed without being violations + +A value-dependent layout (`COMFY_AUTOGROW_V3`, `COMFY_DYNAMICCOMBO_V3`, +`COMFY_DYNAMICGROUP_V3`) keeps its order in the catalogue, which expands it +with the selection; a closed form would freeze it. A missing-node shell +(`last_serialization` set) round-trips a stored payload for a class this build +cannot see, so its live widget list — empty or fabricated — cannot order it. A +value with no live widget at all, an unnamed widget, and two value widgets +sharing a name are all shapes a correct producer cannot describe. These report +under invariant 5 with their own reason and never assert. + +A node whose only widgets are buttons is the one suppression that is **not** +reported: it has no named value for a form to order, so counting it as a +declaration gap would bury the signal under every such class in the ecosystem. + +## Consequences + +- One behaviour change relative to the previous derivation: a node whose + post-hook positional array or named key set was rewritten by an extension no + longer gets a form. It previously could, because the closure test looked only + at the derived order and the filtered values, neither of which sees the + rewrite. +- Invariant 5 turns "what fraction of the ecosystem declares a form" from an + unanswerable question into a queryable one: `error_type` + `agent_widget_form_undeclared`, tagged `node_type` and `reason`, + fingerprinted on all three, one report per class and reason per page session. +- A bulk pass does not go through telemetry at all. + `widgetValuesFormVerdict(node)` classifies a node with no side effects and + `widgetFormSuppressionTally()` returns the per-class counts, so a corpus run + over the Custom Nodes Ecosystem Matrix yields a class-by-class breakdown + without perturbing the production signal it is measuring. +- The frontend follower has no read-back handling for the form, so the round + trip remains the host's. That is unchanged by this ADR and is why the form + stays on the Agent wire rather than in ordinary saves. + +## Alternatives considered + +**Emit the form from core serialization.** Rejected on review: it puts a +consumer's closed-form interpretation into shared serialization, and it needs a +core policy suppressing forms for dynamic combos, groups and autogrow to +compensate. The Agent adapter is the smallest boundary that owns the decision. + +**A stable per-widget UUID instead of an order.** Right idea, wrong boundary. +ECS ids are process-local and minted at graph join, while workflow JSON is +durable, portable and cross-tool: a random id means nothing to a reader that +did not mint it, a derived one is only as stable as what it derives from, and +persisting the mapping re-invents the form plus a layer no human can read in a +diff. `(name, occurrence)` was already rejected for adding a second +widget-identity format; a hash would be a third. + +**Assert and keep emitting.** Rejected. A wrong form is authoritative on every +leg, so the only safe response to an unproven form is not to send one. + +**Throw under DEV.** Rejected for this seam specifically; see decision 4. The +unit suite is what pins each invariant, including that each one still fires. diff --git a/src/workbench/extensions/agent/crdt/docOpMinter.ts b/src/workbench/extensions/agent/crdt/docOpMinter.ts index bf31cc9b016..3ad8c259555 100644 --- a/src/workbench/extensions/agent/crdt/docOpMinter.ts +++ b/src/workbench/extensions/agent/crdt/docOpMinter.ts @@ -15,7 +15,6 @@ import type { NodeId as WireNodeId, PromotedHostWrite, SubgraphDefinition, - WidgetValuesForm, WorkflowNode } from '@comfyorg/comfy-multi-player' import { isEqual } from 'es-toolkit' @@ -32,7 +31,6 @@ import type { Subgraph } from '@/lib/litegraph/src/subgraph/Subgraph' import type { SubgraphNode } from '@/lib/litegraph/src/subgraph/SubgraphNode' import type { ISerialisedNode } from '@/lib/litegraph/src/types/serialisation' import { isWidgetValue } from '@/lib/litegraph/src/types/widgets' -import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets' import { reportError } from '@/platform/telemetry/reportError' import { useNodeDefStore } from '@/stores/nodeDefStore' import type { DynamicComboSelection } from '@/stores/nodeDefStore' @@ -40,7 +38,6 @@ import { useWidgetValueStore } from '@/stores/widgetValueStore' import type { RootGraphId } from '@/types/graphScopeId' import type { NodeId } from '@/types/nodeId' import { widgetId } from '@/types/widgetId' -import type { WidgetState } from '@/types/widgetState' import { findNodeInHierarchy, findSubgraphByUuid, @@ -55,6 +52,11 @@ import { import type { GraphOperation } from './graphOperations' import type { DocPromotedWidgets } from './agentSubgraphDefinitions' import { reportLostEdit } from './reportLostEdit' +import { + isValueWidget, + provenWidgetValuesForm, + valueWidgetsOnly +} from './widgetValuesForm' export interface DocOpMinterDeps { /** Slice 00's product gate. */ @@ -204,69 +206,15 @@ export function wireNodeSnapshot(node: LGraphNode): WorkflowNode | null { const snapshot = { ...rest, flags } satisfies WorkflowNode if (!named || node.isVirtualNode) return snapshot const values = valueWidgetsOnly(node, named) - const form = nodeLocalWidgetForm(node, values) + // The form is proven against the POST-HOOK serialization, not derived from + // the live widget list alone: `serialize()` above already ran the extension + // serialize hook, which may have replaced either widget-values field. + const form = provenWidgetValuesForm(node, values, serialized) return form ? { ...snapshot, widgets_values: values, widgets_values_form: form } : { ...snapshot, widgets_values: values } } -const VALUE_DEPENDENT_LAYOUT_INPUT_TYPES = new Set([ - 'COMFY_AUTOGROW_V3', - 'COMFY_DYNAMICCOMBO_V3', - 'COMFY_DYNAMICGROUP_V3' -]) - -function nodeLocalWidgetForm( - node: LGraphNode, - values: Record -): WidgetValuesForm | undefined { - const definition = useNodeDefStore().fromLGraphNode(node) - const layoutDependsOnValues = Object.values(definition?.inputs ?? {}).some( - (spec) => VALUE_DEPENDENT_LAYOUT_INPUT_TYPES.has(spec.type) - ) - if (layoutDependsOnValues) return undefined - const order = (node.widgets ?? []) - .map((widget) => widget.name) - .filter((name) => Object.hasOwn(values, name)) - const isClosed = - order.length > 0 && - order.length === Object.keys(values).length && - order.every((name) => name.length > 0) && - new Set(order).size === order.length - return isClosed ? { order } : undefined -} - -function valueWidgetsOnly( - node: LGraphNode, - named: object -): Record { - const filtered: Record = {} - const rootGraphId = node.graph?.rootGraph.id - const widgetValueStore = useWidgetValueStore() - for (const [name, value] of Object.entries(named)) { - const widget = node.widgets?.find((candidate) => candidate.name === name) - const stored = rootGraphId - ? widgetValueStore.getWidget(widgetId(rootGraphId, node.id, name)) - : undefined - if (isValueWidget(widget, stored)) filtered[name] = value - } - return filtered -} - -function isValueWidget( - widget: IBaseWidget | undefined, - stored?: WidgetState -): boolean { - if (!widget && !stored) return false - // A destructuring default fires on absent AND present-but-undefined alike, - // which is what `IBaseWidget`'s own optional fields mean: the live widget - // did not state this, so the registration the intent was keyed by answers. - // One construct for both fields, so the two halves of the guard cannot - // drift apart again. - const { type = stored?.type, serialize = stored?.serialize } = widget ?? {} - return type !== 'button' && serialize !== false -} - function nodeKey(graphId: string, nodeId: NodeId): string { return `${graphId}:${String(nodeId)}` } diff --git a/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts b/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts new file mode 100644 index 00000000000..60edcc081e0 --- /dev/null +++ b/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts @@ -0,0 +1,446 @@ +import { fromPartial } from '@total-typescript/shoehorn' +import { beforeEach, describe, expect, it, vi } from 'vitest' + +import { setAssertReporter } from '@/base/assert' +import { LGraph, LGraphNode } from '@/lib/litegraph/src/litegraph' +import type { ISerialisedNode } from '@/lib/litegraph/src/types/serialisation' +import { reportError } from '@/platform/telemetry/reportError' +import type { ComfyNodeDef as ComfyNodeDefV1 } from '@/schemas/nodeDefSchema' +import { useNodeDefStore } from '@/stores/nodeDefStore' + +import { + classifyWidgetValuesForm, + provenWidgetValuesForm, + resetWidgetFormSuppressionTally, + widgetFormSuppressionTally, + widgetValuesFormVerdict +} from './widgetValuesForm' + +vi.mock(import('@/platform/telemetry/reportError')) + +function nodeDef( + name: string, + required: NonNullable['required'] +): ComfyNodeDefV1 { + return { + name, + display_name: name, + category: 'test', + python_module: 'custom_nodes.test', + description: '', + input: { required }, + output: [], + output_name: [], + output_is_list: [], + output_node: false + } +} + +function nodeWith(type: string, build: (node: LGraphNode) => void): LGraphNode { + const node = detachedNodeWith(type, build) + new LGraph().add(node) + return node +} + +/** + * Graph registration collapses two widgets that share a name, so a node that + * carries the duplicate has to be built outside a graph. + */ +function detachedNodeWith( + type: string, + build: (node: LGraphNode) => void +): LGraphNode { + const node = new LGraphNode(type, type) + node.serialize_widgets = true + build(node) + return node +} + +/** The post-hook serialization, as `wireNodeSnapshot` reads it. */ +function serializedOf(node: LGraphNode): ISerialisedNode { + return node.serialize() +} + +beforeEach(() => { + resetWidgetFormSuppressionTally() + useNodeDefStore().updateNodeDefs([]) +}) + +describe('the proven widget form', () => { + it('declares the live order for a node nothing interfered with', () => { + const node = nodeWith('Plain', (n) => { + n.addWidget('number', 'steps', 20, () => {}) + n.addWidget('text', 'prompt', 'hello', () => {}) + }) + + expect(widgetValuesFormVerdict(node)).toEqual({ + declared: true, + form: { order: ['steps', 'prompt'] } + }) + expect(widgetFormSuppressionTally()).toEqual([]) + }) + + it('declares nothing for a value-dependent layout, which the catalog owns', () => { + useNodeDefStore().addNodeDef( + nodeDef('Dynamic', { mode: ['COMFY_DYNAMICCOMBO_V3', {}] }) + ) + const node = nodeWith('Dynamic', (n) => { + n.addWidget('combo', 'mode', 'a', () => {}, { values: ['a'] }) + n.addWidget('number', 'mode.steps', 4, () => {}) + }) + + expect(widgetValuesFormVerdict(node)).toMatchObject({ + declared: false, + reason: 'value_dependent_layout' + }) + }) + + it('declares nothing for a missing-node shell that round-trips a stored payload', () => { + const node = nodeWith('Uninstalled', (n) => { + n.addWidget('text', 'UNKNOWN', 'fabricated', () => {}) + }) + node.last_serialization = fromPartial({ + id: 1, + type: 'Uninstalled', + widgets_values: ['real value'], + widgets_values_named: { real_name: 'real value' } + }) + + expect(widgetValuesFormVerdict(node)).toMatchObject({ + declared: false, + reason: 'shell_last_serialization' + }) + }) +}) + +describe('invariant 4 — the form survived the extension serialize hook', () => { + it('declares nothing when the hook adds a value core refused to serialise', () => { + // The VideoHelperSuite shape: the pack keys its own dict from the + // UNFILTERED widget list, so its keys and a derived order differ by + // exactly the widget carrying `serialize = false`. + const node = nodeWith('VHS_Probe', (n) => { + n.addWidget('text', 'filename', 'clip', () => {}) + const hidden = n.addWidget('text', 'vhslatentpreview', 'x', () => {}) + hidden.serialize = false + n.onSerialize = (data: ISerialisedNode) => { + data.widgets_values_named = { + ...data.widgets_values_named, + vhslatentpreview: 'x' + } + } + }) + + expect(widgetValuesFormVerdict(node)).toMatchObject({ + declared: false, + reason: 'hook_changed_serialized_widgets' + }) + }) + + it('declares nothing when the hook drops a widget mid-serialization', () => { + const node = nodeWith('Shrinking', (n) => { + n.addWidget('text', 'prompt', 'a', () => {}) + n.addWidget('text', 'extra', 'b', () => {}) + n.onSerialize = () => { + n.widgets?.pop() + } + }) + + expect(widgetValuesFormVerdict(node)).toMatchObject({ + declared: false, + reason: 'hook_changed_serialized_widgets' + }) + }) + + it('still declares a form when the hook only reorders the named keys', () => { + // Key order inside `widgets_values_named` is not meaningful — an + // integer-like name is enumeration-reordered by the object itself, which + // is the reason the form exists. Comparing sequences here would refuse a + // pack that broke nothing. + const node = nodeWith('Reordering', (n) => { + n.addWidget('text', '2', 'two', () => {}) + n.addWidget('text', '1', 'one', () => {}) + n.onSerialize = (data: ISerialisedNode) => { + data.widgets_values_named = { '1': 'one', '2': 'two' } + } + }) + + expect(widgetValuesFormVerdict(node)).toEqual({ + declared: true, + form: { order: ['2', '1'] } + }) + }) +}) + +describe('invariant 2 — the post-hook positional array still fits the widgets', () => { + it('declares nothing when the hook rewrites widgets_values to a shorter array', () => { + const node = nodeWith('Rewriting', (n) => { + n.addWidget('text', 'prompt', 'a', () => {}) + n.addWidget('text', 'extra', 'b', () => {}) + n.onSerialize = (data: ISerialisedNode) => { + data.widgets_values = ['only one'] + } + }) + + expect(widgetValuesFormVerdict(node)).toMatchObject({ + declared: false, + reason: 'positional_arity_disagrees', + detail: { positional: 1, serialised: 2 } + }) + }) + + it('counts button widgets, which core serialises and the wire drops', () => { + // A button is serialised positionally but is not a document value, so a + // check written against the value count would refuse every node with one. + const node = nodeWith('Buttoned', (n) => { + n.addWidget('text', 'prompt', 'a', () => {}) + n.addWidget('button', 'refresh', 'refresh', () => {}) + }) + + expect(widgetValuesFormVerdict(node)).toEqual({ + declared: true, + form: { order: ['prompt'] } + }) + }) +}) + +describe('invariants 1 and 3 — guards on the value filter', () => { + // Neither is reachable through `valueWidgetsOnly` today: it drops a + // `serialize: false` widget and derives the order from the same object it + // filtered. Both are asserted against hand-built values, so the guard goes + // red if a later change to that filter stops holding them. + + it('refuses an order entry naming a widget core would not serialise', () => { + const node = nodeWith('Hiding', (n) => { + n.addWidget('text', 'prompt', 'a', () => {}) + const hidden = n.addWidget('text', 'hidden', 'b', () => {}) + hidden.serialize = false + }) + + expect( + classifyWidgetValuesForm( + node, + { prompt: 'a', hidden: 'b' }, + serializedOf(node) + ) + ).toMatchObject({ + declared: false, + reason: 'order_names_unserialized_widget', + detail: { names: ['hidden'] } + }) + }) + + it('refuses an order entry whose value will not travel on the wire', () => { + // `values` goes out as JSON, so only enumerable own keys arrive. An order + // entry backed by a key `Object.hasOwn` can see and `Object.keys` cannot + // would order a value the host never receives. + const node = nodeWith('Residual', (n) => { + n.addWidget('text', 'prompt', 'a', () => {}) + n.addWidget('text', 'residue', 'b', () => {}) + }) + const values: Record = { prompt: 'a' } + Object.defineProperty(values, 'residue', { + value: 'b', + enumerable: false + }) + + expect( + classifyWidgetValuesForm(node, values, serializedOf(node)) + ).toMatchObject({ + declared: false, + reason: 'declared_keys_disagree', + detail: { unvalued: ['residue'] } + }) + }) +}) + +describe('the legitimate shapes a producer cannot describe', () => { + it('reports a value whose widget is gone but whose store entry is not', () => { + const node = nodeWith('Vanishing', (n) => { + n.addWidget('text', 'prompt', 'a', () => {}) + }) + + expect( + classifyWidgetValuesForm( + node, + { prompt: 'a', vanished: 'b' }, + serializedOf(node) + ) + ).toMatchObject({ + declared: false, + reason: 'value_has_no_live_widget', + detail: { names: ['vanished'] } + }) + }) + + it('reports an unnamed value widget', () => { + const node = nodeWith('Unnamed', (n) => { + n.addWidget('text', 'prompt', 'a', () => {}) + n.addWidget('text', '', 'b', () => {}) + }) + + expect(widgetValuesFormVerdict(node)).toMatchObject({ + declared: false, + reason: 'unnamed_value_widget' + }) + }) + + it('reports two value widgets sharing a name', () => { + const node = detachedNodeWith('Duplicated', (n) => { + n.addWidget('text', 'prompt', 'a', () => {}) + n.addWidget('text', 'prompt', 'b', () => {}) + }) + + expect(widgetValuesFormVerdict(node)).toMatchObject({ + declared: false, + reason: 'duplicate_widget_name' + }) + }) + + it('has nothing to declare for a node whose only widget is a button', () => { + const node = nodeWith('OnlyButton', (n) => { + n.addWidget('button', 'refresh', 'refresh', () => {}) + }) + + expect(widgetValuesFormVerdict(node)).toMatchObject({ + declared: false, + reason: 'no_value_widgets' + }) + }) +}) + +describe('the invariant channel', () => { + it('routes a broken invariant through assert without stopping the mint', () => { + const node = nodeWith('Rewriting', (n) => { + n.addWidget('text', 'prompt', 'a', () => {}) + n.addWidget('text', 'extra', 'b', () => {}) + n.onSerialize = (data: ISerialisedNode) => { + data.widgets_values = ['only one'] + } + }) + const serialized = serializedOf(node) + + // The DEV throw is swallowed on purpose: a third-party pack must not be + // able to stop the Agent minting in a developer's browser. + expect( + provenWidgetValuesForm(node, { prompt: 'a', extra: 'b' }, serialized) + ).toBeUndefined() + expect(console.error).toHaveBeenCalledWith( + expect.stringContaining('Agent widget form invariant 2') + ) + }) + + it('names the invariant and the ADR, and keeps values out of the message', () => { + vi.stubEnv('DEV', false) + const reporter = vi.fn() + setAssertReporter(reporter) + const node = nodeWith('Shrinking', (n) => { + n.addWidget('text', 'prompt', 'a', () => {}) + n.addWidget('text', 'extra', 'b', () => {}) + n.onSerialize = () => { + n.widgets?.pop() + } + }) + const serialized = serializedOf(node) + + provenWidgetValuesForm(node, { prompt: 'a' }, serialized) + + expect(reporter).toHaveBeenCalledWith( + expect.stringContaining('Agent widget form invariant 4'), + expect.objectContaining({ nodeType: 'Shrinking' }) + ) + const [message] = reporter.mock.calls[0] as [string] + expect(message).toContain( + 'docs/adr/WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md' + ) + expect(message).not.toContain('Shrinking') + setAssertReporter(null) + }) +}) + +describe('invariant 5 — the undeclared-form production signal', () => { + it('reports the class and the reason, once per pair', () => { + useNodeDefStore().addNodeDef( + nodeDef('Dynamic', { mode: ['COMFY_DYNAMICCOMBO_V3', {}] }) + ) + const build = (n: LGraphNode) => { + n.addWidget('combo', 'mode', 'a', () => {}, { values: ['a'] }) + n.addWidget('number', 'mode.steps', 4, () => {}) + } + + for (const node of [nodeWith('Dynamic', build), nodeWith('Dynamic', build)]) + provenWidgetValuesForm( + node, + { mode: 'a', 'mode.steps': 4 }, + serializedOf(node) + ) + + expect(reportError).toHaveBeenCalledTimes(1) + expect(reportError).toHaveBeenCalledWith( + expect.objectContaining({ + message: expect.stringContaining( + 'object-shaped widget values with no declared form' + ) + }), + expect.objectContaining({ + errorType: 'agent_widget_form_undeclared', + surface: 'agent', + level: 'warning', + tags: { node_type: 'Dynamic', reason: 'value_dependent_layout' }, + fingerprint: [ + 'agent_widget_form_undeclared', + 'value_dependent_layout', + 'Dynamic' + ] + }) + ) + }) + + it('does not report a node that has nothing to declare', () => { + const node = nodeWith('OnlyButton', (n) => { + n.addWidget('button', 'refresh', 'refresh', () => {}) + }) + + expect(provenWidgetValuesForm(node, {}, serializedOf(node))).toBeUndefined() + expect(reportError).not.toHaveBeenCalled() + }) + + it('keeps a per-class tally a bulk pass can read without telemetry', () => { + useNodeDefStore().addNodeDef( + nodeDef('Dynamic', { mode: ['COMFY_DYNAMICCOMBO_V3', {}] }) + ) + const dynamic = () => + nodeWith('Dynamic', (n) => { + n.addWidget('combo', 'mode', 'a', () => {}, { values: ['a'] }) + }) + const duplicated = detachedNodeWith('Duplicated', (n) => { + n.addWidget('text', 'prompt', 'a', () => {}) + n.addWidget('text', 'prompt', 'b', () => {}) + }) + + for (const node of [dynamic(), dynamic()]) + provenWidgetValuesForm(node, { mode: 'a' }, serializedOf(node)) + provenWidgetValuesForm( + duplicated, + { prompt: 'b' }, + serializedOf(duplicated) + ) + + expect(widgetFormSuppressionTally()).toEqual([ + { nodeType: 'Dynamic', reason: 'value_dependent_layout', count: 2 }, + { nodeType: 'Duplicated', reason: 'duplicate_widget_name', count: 1 } + ]) + }) + + it('classifies for a bulk pass without reporting or tallying', () => { + useNodeDefStore().addNodeDef( + nodeDef('Dynamic', { mode: ['COMFY_DYNAMICCOMBO_V3', {}] }) + ) + const node = nodeWith('Dynamic', (n) => { + n.addWidget('combo', 'mode', 'a', () => {}, { values: ['a'] }) + }) + + expect(widgetValuesFormVerdict(node)).toMatchObject({ declared: false }) + expect(reportError).not.toHaveBeenCalled() + expect(widgetFormSuppressionTally()).toEqual([]) + }) +}) diff --git a/src/workbench/extensions/agent/crdt/widgetValuesForm.ts b/src/workbench/extensions/agent/crdt/widgetValuesForm.ts new file mode 100644 index 0000000000000000000000000000000000000000..c3fdaa6273e1c33cb5cb7d2d3a62f6d239e74035 GIT binary patch literal 15918 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 an3pXsmImZzj}JGBrg4q5y2%Je^8W#MDq~^* literal 0 HcmV?d00001 From 56b1e1e8ac1b0c0ef915e6d8d319ebc89faf478f Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 23 Oct 2026 01:16:58 -0700 Subject: [PATCH 2/7] fix(agent): key the widget-form tally with text, not a NUL byte MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The separator was written as a literal control byte, which made git treat the whole file as binary — so `adr-links` could not read the ADR reference out of it and reported it as dangling. --- .../extensions/agent/crdt/widgetValuesForm.ts | Bin 15918 -> 15929 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/src/workbench/extensions/agent/crdt/widgetValuesForm.ts b/src/workbench/extensions/agent/crdt/widgetValuesForm.ts index c3fdaa6273e1c33cb5cb7d2d3a62f6d239e74035..711aebb0d7e017c4770fa490ccc3b567c6ef20c4 100644 GIT binary patch delta 47 zcmZ2iv$JM{wz!g4u)m*PaY<2TUV3I)rABmKeoAUcWkITrLQ!gBaeiK`=4L1HH);U5 C4iWwU delta 36 rcmdm4v#w@?wzznLN_Ad-N@_@DL2507N_A0cVsU<6ZNg?>@i%G!3~LTr From 948f3c9313c735c64683ed81919a2bcf6c236376 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 23 Oct 2026 01:20:04 -0700 Subject: [PATCH 3/7] refactor(agent): give each widget-form invariant its own named probe One 83-line classifier at cyclomatic 16 was over the repo's complexity threshold, and the invariant a reader is looking for was buried in the middle of it. Each leg of the proof is now a named predicate carrying its own rationale, and the ordering comment says why the sequence is most-specific-cause first. No behaviour change. --- .../extensions/agent/crdt/widgetValuesForm.ts | 220 ++++++++++++------ 1 file changed, 148 insertions(+), 72 deletions(-) diff --git a/src/workbench/extensions/agent/crdt/widgetValuesForm.ts b/src/workbench/extensions/agent/crdt/widgetValuesForm.ts index 711aebb0d7e..8715df82af9 100644 --- a/src/workbench/extensions/agent/crdt/widgetValuesForm.ts +++ b/src/workbench/extensions/agent/crdt/widgetValuesForm.ts @@ -211,98 +211,174 @@ export function valueWidgetsOnly( return filtered } -/** - * Classifies a node's form without declaring, asserting or reporting - * anything. Pure apart from the node-definition read, so a bulk pass can call - * it per node and keep the reason. - * - * Checks run most-specific-cause first, so the reason names the thing that - * actually happened rather than its downstream shadow: the hook changing the - * serialised widget set shows up as a key disagreement too, and attributing - * it to the key disagreement would send a reader looking in the wrong place. - */ -export function classifyWidgetValuesForm( +/** The post-hook payload and the live widget list, read once. */ +interface FormProof { + /** Every live widget's name, serialised or not. */ + readonly liveNames: readonly string[] + /** The names core serialises: `serialize === false` is skipped. */ + readonly serialisedNames: readonly string[] + /** The post-hook named keys, which the hook may have replaced. */ + readonly namedKeys: readonly string[] + /** The post-hook positional array, or undefined if there is none. */ + readonly positional: readonly unknown[] | undefined + /** The enumerable keys of the object the wire ships. */ + readonly valueNames: readonly string[] + /** The order the form would declare. */ + readonly order: readonly string[] +} + +function formProof( node: LGraphNode, values: Record, serialized: SerializedWidgetValues -): WidgetFormVerdict { - // The catalogue owns a value-dependent order; declaring one would close a - // list that is supposed to expand with the selection. - if (layoutDependsOnValues(node)) return suppressed('value_dependent_layout') - - // A missing-node shell round-trips its stored payload verbatim, so the - // serialized values describe a class this build cannot see and the live - // widget list — fabricated or empty — cannot order them. - if (node.last_serialization) return suppressed('shell_last_serialization') - +): FormProof { const live = node.widgets ?? [] - const liveNames = live.map((widget) => widget.name) - const serialisedNames = live - .filter((widget) => widget.serialize !== false) - .map((widget) => widget.name) - const valueNames = Object.keys(values) - const order = live - .map((widget) => widget.name) - .filter((name) => Object.hasOwn(values, name)) - - // 4 — the hook may replace either field after core wrote it. Compare key - // sets, not sequences: `widgets_values_named` is an object, and an - // integer-like widget name is enumeration-reordered inside it, which is the - // reason the form exists in the first place. const named = serialized.widgets_values_named - if (!sameNames(named ? Object.keys(named) : [], serialisedNames)) - return suppressed('hook_changed_serialized_widgets', { - serialised: named ? Object.keys(named) : [], - live: serialisedNames - }) - - // 2 — the array case. The wire ships the named object, so the arity claim - // is made against the positional array the hook left behind: one slot per - // serialised widget, or the order was proven against values no other reader - // of this workflow will see. const positional = serialized.widgets_values - if (Array.isArray(positional) && positional.length !== serialisedNames.length) - return suppressed('positional_arity_disagrees', { - positional: positional.length, - serialised: serialisedNames.length - }) + return { + liveNames: live.map((widget) => widget.name), + serialisedNames: live + .filter((widget) => widget.serialize !== false) + .map((widget) => widget.name), + namedKeys: named ? Object.keys(named) : [], + positional: Array.isArray(positional) ? positional : undefined, + valueNames: Object.keys(values), + order: live + .map((widget) => widget.name) + .filter((name) => Object.hasOwn(values, name)) + } +} - // A document value with no live widget at all is the stored-state family, - // not a broken invariant: the node shed the widget, or was never - // registered. Checked before invariant 1 so the two are not conflated — - // "there is no widget" and "there is one core refuses to serialise" have - // different causes and different fixes. +/** Returns a suppression when this leg of the proof fails, else nothing. */ +type FormProbe = (proof: FormProof) => WidgetFormVerdict | undefined + +/** + * Invariant 4 — the hook may replace either widget-values field after core + * wrote it. Compare key SETS, not sequences: `widgets_values_named` is an + * object, and an integer-like widget name is enumeration-reordered inside it, + * which is the reason the form exists in the first place. A pack that + * reorders keys and changes nothing else has not broken anything. + */ +const hookKeptTheSerialisedWidgets: FormProbe = ({ + namedKeys, + serialisedNames +}) => + sameNames(namedKeys, serialisedNames) + ? undefined + : suppressed('hook_changed_serialized_widgets', { + serialised: namedKeys, + live: serialisedNames + }) + +/** + * Invariant 2 — the array case. The wire ships the named object, so the arity + * claim is made against the positional array the hook left behind: one slot + * per serialised widget, or the order was proven against values no other + * reader of this workflow will see. Buttons count here: core serialises one + * positionally and the wire drops it as a non-value, so a check written + * against the value count would refuse every node that has one. + */ +const positionalArityFits: FormProbe = ({ positional, serialisedNames }) => + !positional || positional.length === serialisedNames.length + ? undefined + : suppressed('positional_arity_disagrees', { + positional: positional.length, + serialised: serialisedNames.length + }) + +/** + * A document value with no live widget at all is the stored-state family, not + * a broken invariant: the node shed the widget, or was never registered. + * Checked before invariant 1 so the two are not conflated — "there is no + * widget" and "there is one core refuses to serialise" have different causes + * and different fixes. + */ +const everyValueHasALiveWidget: FormProbe = ({ valueNames, liveNames }) => { const unbacked = valueNames.filter((name) => !liveNames.includes(name)) - if (unbacked.length) - return suppressed('value_has_no_live_widget', { names: unbacked }) + return unbacked.length + ? suppressed('value_has_no_live_widget', { names: unbacked }) + : undefined +} - // 1 — an order entry must name a live widget core serialises. Reachable - // only if a value for a `serialize: false` widget gets into `values`, which - // `isValueWidget` currently refuses: this is the guard on that filter. +/** + * Invariant 1 — an order entry must name a live widget core serialises. + * Reachable only if a value for a `serialize: false` widget gets into + * `values`, which `isValueWidget` currently refuses: this is the guard on + * that filter. + */ +const orderNamesSerialisedWidgets: FormProbe = ({ order, serialisedNames }) => { const unserialized = order.filter((name) => !serialisedNames.includes(name)) - if (unserialized.length) - return suppressed('order_names_unserialized_widget', { - names: unserialized - }) + return unserialized.length + ? suppressed('order_names_unserialized_widget', { names: unserialized }) + : undefined +} - // 3 — the object case, as a set difference in BOTH directions. Order - // without a value orders nothing; a value outside the order is residue the - // host would store and never project. Stated against the enumerable keys, - // because those are what travel: the wire ships `values` as JSON, so an own - // property `Object.hasOwn` can see and `Object.keys` cannot is an order - // entry whose value never arrives. +/** + * Invariant 3 — the object case, as a set difference in BOTH directions. + * Order without a value orders nothing; a value outside the order is residue + * the host would store and never project. Stated against the enumerable keys, + * because those are what travel: the wire ships `values` as JSON, so an own + * property `Object.hasOwn` can see and `Object.keys` cannot is an order entry + * whose value never arrives. + */ +const declaredKeysAgree: FormProbe = ({ valueNames, order }) => { const undeclared = valueNames.filter((name) => !order.includes(name)) const unvalued = order.filter((name) => !valueNames.includes(name)) - if (undeclared.length || unvalued.length) - return suppressed('declared_keys_disagree', { undeclared, unvalued }) + return undeclared.length || unvalued.length + ? suppressed('declared_keys_disagree', { undeclared, unvalued }) + : undefined +} +/** Shapes a name-keyed order cannot address, whatever the values say. */ +const orderIsAddressable: FormProbe = ({ order }) => { if (!order.length) return suppressed('no_value_widgets') if (order.some((name) => !name.length)) return suppressed('unnamed_value_widget') if (new Set(order).size !== order.length) return suppressed('duplicate_widget_name', { order }) + return undefined +} + +/** + * Ordered most-specific-cause first, so the reason names the thing that + * actually happened rather than its downstream shadow: the hook changing the + * serialised widget set shows up as a key disagreement too, and attributing + * it to the key disagreement would send a reader looking in the wrong place. + */ +const FORM_PROBES: readonly FormProbe[] = [ + hookKeptTheSerialisedWidgets, + positionalArityFits, + everyValueHasALiveWidget, + orderNamesSerialisedWidgets, + declaredKeysAgree, + orderIsAddressable +] + +/** + * Classifies a node's form without declaring, asserting or reporting + * anything. Pure apart from the node-definition read, so a bulk pass can call + * it per node and keep the reason. + */ +export function classifyWidgetValuesForm( + node: LGraphNode, + values: Record, + serialized: SerializedWidgetValues +): WidgetFormVerdict { + // The catalogue owns a value-dependent order; declaring one would close a + // list that is supposed to expand with the selection. + if (layoutDependsOnValues(node)) return suppressed('value_dependent_layout') - return { declared: true, form: { order } } + // A missing-node shell round-trips its stored payload verbatim, so the + // serialized values describe a class this build cannot see and the live + // widget list — fabricated or empty — cannot order them. + if (node.last_serialization) return suppressed('shell_last_serialization') + + const proof = formProof(node, values, serialized) + for (const probe of FORM_PROBES) { + const failed = probe(proof) + if (failed) return failed + } + return { declared: true, form: { order: [...proof.order] } } } /** From f1bd7e3ce7f2e54aa057ec4b2c9a141634b363ab Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 23 Oct 2026 01:24:34 -0700 Subject: [PATCH 4/7] test(agent): restore the assert reporter on failure, drop the test-body loops Addresses two CodeRabbit findings. `setAssertReporter(null)` sat after the assertions, so a failing assertion left a stale module-level reporter installed and hid itself behind the secondary failures it caused; it moves to `onTestFinished`. The two repeat-the-call loops become named first/repeat calls, per the repo's no-loops-in-a-test-body guideline, which also makes it read as what it checks. https://github.com/Comfy-Org/ComfyUI_frontend/pull/21790#discussion_r4356383128 --- .../agent/crdt/widgetValuesForm.test.ts | 31 ++++++++++--------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts b/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts index 60edcc081e0..4be1ccf23da 100644 --- a/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts +++ b/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts @@ -1,5 +1,5 @@ import { fromPartial } from '@total-typescript/shoehorn' -import { beforeEach, describe, expect, it, vi } from 'vitest' +import { beforeEach, describe, expect, it, onTestFinished, vi } from 'vitest' import { setAssertReporter } from '@/base/assert' import { LGraph, LGraphNode } from '@/lib/litegraph/src/litegraph' @@ -333,6 +333,10 @@ describe('the invariant channel', () => { vi.stubEnv('DEV', false) const reporter = vi.fn() setAssertReporter(reporter) + // Module-level state, so the restore cannot sit after the assertions: a + // failure there would leave a stale reporter installed and hide itself + // behind the secondary failures it causes in later tests. + onTestFinished(() => setAssertReporter(null)) const node = nodeWith('Shrinking', (n) => { n.addWidget('text', 'prompt', 'a', () => {}) n.addWidget('text', 'extra', 'b', () => {}) @@ -353,7 +357,6 @@ describe('the invariant channel', () => { 'docs/adr/WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md' ) expect(message).not.toContain('Shrinking') - setAssertReporter(null) }) }) @@ -366,13 +369,12 @@ describe('invariant 5 — the undeclared-form production signal', () => { n.addWidget('combo', 'mode', 'a', () => {}, { values: ['a'] }) n.addWidget('number', 'mode.steps', 4, () => {}) } + const values = { mode: 'a', 'mode.steps': 4 } + const first = nodeWith('Dynamic', build) + const repeat = nodeWith('Dynamic', build) - for (const node of [nodeWith('Dynamic', build), nodeWith('Dynamic', build)]) - provenWidgetValuesForm( - node, - { mode: 'a', 'mode.steps': 4 }, - serializedOf(node) - ) + provenWidgetValuesForm(first, values, serializedOf(first)) + provenWidgetValuesForm(repeat, values, serializedOf(repeat)) expect(reportError).toHaveBeenCalledTimes(1) expect(reportError).toHaveBeenCalledWith( @@ -408,17 +410,18 @@ describe('invariant 5 — the undeclared-form production signal', () => { useNodeDefStore().addNodeDef( nodeDef('Dynamic', { mode: ['COMFY_DYNAMICCOMBO_V3', {}] }) ) - const dynamic = () => - nodeWith('Dynamic', (n) => { - n.addWidget('combo', 'mode', 'a', () => {}, { values: ['a'] }) - }) + const dynamic = (n: LGraphNode) => { + n.addWidget('combo', 'mode', 'a', () => {}, { values: ['a'] }) + } + const first = nodeWith('Dynamic', dynamic) + const repeat = nodeWith('Dynamic', dynamic) const duplicated = detachedNodeWith('Duplicated', (n) => { n.addWidget('text', 'prompt', 'a', () => {}) n.addWidget('text', 'prompt', 'b', () => {}) }) - for (const node of [dynamic(), dynamic()]) - provenWidgetValuesForm(node, { mode: 'a' }, serializedOf(node)) + provenWidgetValuesForm(first, { mode: 'a' }, serializedOf(first)) + provenWidgetValuesForm(repeat, { mode: 'a' }, serializedOf(repeat)) provenWidgetValuesForm( duplicated, { prompt: 'b' }, From 0bb9a3ea01f9484725a9c05611b90e8f71516c0a Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 23 Oct 2026 02:34:12 -0700 Subject: [PATCH 5/7] fix(agent): prove widget forms against wire values Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/21790#discussion_r4357582065 Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/21790#discussion_r4357582071 Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/21790#discussion_r4357582080 Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/21790#discussion_r4357582092 Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/21790#discussion_r4357582101 Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/21790#discussion_r4357582108 Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/21790#discussion_r4357582113 Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/21790#discussion_r4357639291 Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/21790#discussion_r4357639304 --- .../agent/agentWidgetFormHookDrift.spec.ts | 24 +-- ...-wire-widget-form-is-proven-not-derived.md | 65 +++---- .../agent/crdt/widgetValuesForm.test.ts | 106 +++++----- .../extensions/agent/crdt/widgetValuesForm.ts | 182 ++++++++++-------- 4 files changed, 197 insertions(+), 180 deletions(-) diff --git a/browser_tests/tests/agent/agentWidgetFormHookDrift.spec.ts b/browser_tests/tests/agent/agentWidgetFormHookDrift.spec.ts index 1b754a0da89..db173d514af 100644 --- a/browser_tests/tests/agent/agentWidgetFormHookDrift.spec.ts +++ b/browser_tests/tests/agent/agentWidgetFormHookDrift.spec.ts @@ -34,7 +34,7 @@ test.describe( humanOpsHost: 'apply' }) - test('declares no widget form for a node whose values a pack rewrites after serialization', async ({ + test('ignores serializer-private positional state outside the Agent wire', async ({ agentConversation, page }) => { @@ -60,12 +60,6 @@ test.describe( }) await test.step('install a pack that appends its own entry after the hook', async () => { - // The shape third-party packs actually use: an `onSerialize` that - // appends private state to the positional array. It runs AFTER core - // wrote `widgets_values` from the live widget list, and - // `runExtensionSerializeHook` copies it back because the field is - // canonical — so the order core derived no longer describes the - // values any other reader of this workflow will see. await page.evaluate((type) => { const proto = window.LiteGraph!.registered_node_types[type].prototype proto.onSerialize = function (data) { @@ -74,7 +68,7 @@ test.describe( }, NODE_TYPE) }) - await test.step('the drifted node reaches the host with no form, and is refused', async () => { + await test.step('the node reaches the host with its named value and form', async () => { const nodeId = await agentConversation.addNodeOfType( NODE_TYPE, [700, 400] @@ -82,19 +76,19 @@ test.describe( expect(nodeId).not.toBe(control) const outcomes = await agentConversation.waitForHumanOps(2) - // Fail closed: with no form this class is uncatalogued, so the host - // refuses the write instead of storing an order nobody proved. expect(outcomes[1]).toMatchObject({ - outcome: 'rejected', - reason: { code: 'uncatalogued_widget_write' } + outcome: 'applied' + }) + expect(agentConversation.hostNode(nodeId)).toMatchObject({ + widgets_values: { text: 'initial value' }, + widgets_values_form: { order: ['text'] } }) - expect(agentConversation.hostNode(nodeId)).toBeUndefined() await expect( agentConversation.vueNodes.getNodeLocator(nodeId) - ).toBeHidden() + ).toBeVisible() }) - await test.step('the undrifted node is untouched by the refusal', () => { + await test.step('the undrifted node remains intact', () => { expect(agentConversation.hostNode(control)).toMatchObject({ widgets_values_form: { order: ['text'] } }) diff --git a/docs/adr/WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md b/docs/adr/WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md index 4b8bb221f82..ba237950928 100644 --- a/docs/adr/WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md +++ b/docs/adr/WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md @@ -60,14 +60,16 @@ and not sufficient — the base post-hook is not always the last writer. ## Decision 1. **The form is a proof, not a derivation.** The wire declares a form only - where it can prove the final serialized values are the ones core produced - from the live widget list. Where it cannot, it declares nothing. "Declare - nothing" is the behaviour in every environment; see decision 4. + where it can prove the declared order describes every named value the Agent + wire carries. Positional compatibility data and extension-private values + that the wire filters out are outside that claim. Where the order cannot be + proven, the wire declares nothing. "Declare nothing" is the behaviour in + every environment; see decision 4. 2. **Every check reads the post-hook payload.** The classifier takes the serialized node returned by `node.serialize()` — hook already run — and compares it against the live widget list, rather than inspecting state core holds before the hook. -3. **Five invariants, stated once and asserted at that one site.** They are +3. **Four invariants, stated once and asserted at that one site.** They are the contract; the list below is the normative text and the assertion messages name the broken entry. 4. **Suppression is the gate; `assert` is the channel.** `assert` from @@ -78,41 +80,34 @@ and not sufficient — the base post-hook is not always the last writer. stop the Agent from minting in a developer's browser, only to be unable to make us publish a form describing the wrong values. The console line and the production reporter still fire. -5. **Invariant 5 is a signal, not a failure.** "Object-shaped values with no +5. **Invariant 4 is a signal, not a failure.** "Object-shaped values with no declared form" is the expected state for much of the ecosystem today. It reports rather than asserts, and it is the only way to learn _which_ classes still declare nothing, which is what decides whether the form path generalises. -### The five invariants +### The four invariants -Let _live_ be `node.widgets`, _serialised_ those of _live_ with -`serialize !== false` (what `serialiseWidgetValues` emits), _values_ the -name-keyed object the wire ships, and _order_ the declared sequence. +Let _live_ be `node.widgets`, _value widgets_ be those whose values survive the +Agent wire filter, _values_ the name-keyed object the wire ships, and _order_ +the declared sequence. -| # | Invariant | Reason slug | -| --- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | -| 1 | Every `order` entry names a live widget with `serialize !== false`. | `order_names_unserialized_widget` | -| 2 | Array case — the post-hook positional `widgets_values` has one entry per _serialised_ widget. | `positional_arity_disagrees` | -| 3 | Object case — `order` and `Object.keys(values)` agree as a set difference in **both** directions. | `declared_keys_disagree` | -| 4 | The form survived the hook: the post-hook `widgets_values_named` key set equals the key set core produces from the live serialised widgets. | `hook_changed_serialized_widgets` | -| 5 | Object-shaped values with no declared form are reported, once per class and reason. | `agent_widget_form_undeclared` | +| # | Invariant | Reason slug | +| --- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------- | +| 1 | Every `order` entry names a live value widget. | `order_names_unserialized_widget` | +| 2 | `order` and `Object.keys(values)` agree as a set difference in **both** directions. | `declared_keys_disagree` | +| 3 | The filtered post-hook named-value key set equals the live value-widget key set. | `hook_changed_serialized_widgets` | +| 4 | Object-shaped values with no declared form are reported, once per class and reason, with 100 distinct keys maximum. | `agent_widget_form_undeclared` | -Three of these need their exact form recorded, because the obvious version of +Two of these need their exact form recorded, because the obvious version of each is wrong: -- **Invariant 2 is stated against the positional array, not against the - order.** The wire ships the object, so `order.length === widgets_values.length` - is unreachable there as written. The reachable and load-bearing claim is that - the array the hook left behind still has one slot per serialised widget: if a - pack rewrote it to a different arity, the order was proven against values no - other reader of that workflow will see. -- **Invariant 3 is bidirectional.** `order` ⊆ `keys(values)` alone misses +- **Invariant 2 is bidirectional.** `order` ⊆ `keys(values)` alone misses residue — a stored value outside the order, which the host would keep and never project. The VideoHelperSuite shape is the in-ecosystem instance: it keys its dict from the _unfiltered_ widget list, so its keys and a derived order differ by exactly the one widget carrying `serialize = false`. -- **Invariant 4 compares key sets, not key sequences.** Key order inside +- **Invariant 3 compares key sets, not key sequences.** Key order inside `widgets_values_named` is not meaningful — an integer-like widget name is enumeration-reordered by the object itself, which is the reason the form exists. A pack that reorders keys and changes nothing else has not broken @@ -127,7 +122,7 @@ with the selection; a closed form would freeze it. A missing-node shell cannot see, so its live widget list — empty or fabricated — cannot order it. A value with no live widget at all, an unnamed widget, and two value widgets sharing a name are all shapes a correct producer cannot describe. These report -under invariant 5 with their own reason and never assert. +under invariant 4 with their own reason and never assert. A node whose only widgets are buttons is the one suppression that is **not** reported: it has no named value for a form to order, so counting it as a @@ -136,19 +131,19 @@ declaration gap would bury the signal under every such class in the ecosystem. ## Consequences - One behaviour change relative to the previous derivation: a node whose - post-hook positional array or named key set was rewritten by an extension no - longer gets a form. It previously could, because the closure test looked only - at the derived order and the filtered values, neither of which sees the - rewrite. -- Invariant 5 turns "what fraction of the ecosystem declares a form" from an + filtered post-hook named-value key set was rewritten by an extension no + longer gets a form. Positional or private state the Agent wire does not send + does not suppress the form. +- Invariant 4 turns "what fraction of the ecosystem declares a form" from an unanswerable question into a queryable one: `error_type` `agent_widget_form_undeclared`, tagged `node_type` and `reason`, fingerprinted on all three, one report per class and reason per page session. - A bulk pass does not go through telemetry at all. - `widgetValuesFormVerdict(node)` classifies a node with no side effects and - `widgetFormSuppressionTally()` returns the per-class counts, so a corpus run - over the Custom Nodes Ecosystem Matrix yields a class-by-class breakdown - without perturbing the production signal it is measuring. + `widgetValuesFormVerdict(node)` runs the node's serialization hook, classifies + and tallies the result, and `widgetFormSuppressionTally()` returns up to 100 + distinct per-class counts. The hook can mutate extension state, so the corpus + runner must use disposable nodes. A thrown hook is classified separately as + `serialization_failed`. - The frontend follower has no read-back handling for the form, so the round trip remains the host's. That is unchanged by this ADR and is why the form stays on the Agent wire rather than in ordinary saves. diff --git a/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts b/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts index 4be1ccf23da..cb6bc49c4f3 100644 --- a/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts +++ b/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts @@ -12,6 +12,7 @@ import { classifyWidgetValuesForm, provenWidgetValuesForm, resetWidgetFormSuppressionTally, + valueWidgetsOnly, widgetFormSuppressionTally, widgetValuesFormVerdict } from './widgetValuesForm' @@ -113,11 +114,8 @@ describe('the proven widget form', () => { }) }) -describe('invariant 4 — the form survived the extension serialize hook', () => { - it('declares nothing when the hook adds a value core refused to serialise', () => { - // The VideoHelperSuite shape: the pack keys its own dict from the - // UNFILTERED widget list, so its keys and a derived order differ by - // exactly the widget carrying `serialize = false`. +describe('invariant 3 — the wire values still fit the live widgets', () => { + it('ignores a hook value the Agent wire filters out', () => { const node = nodeWith('VHS_Probe', (n) => { n.addWidget('text', 'filename', 'clip', () => {}) const hidden = n.addWidget('text', 'vhslatentpreview', 'x', () => {}) @@ -130,13 +128,13 @@ describe('invariant 4 — the form survived the extension serialize hook', () => } }) - expect(widgetValuesFormVerdict(node)).toMatchObject({ - declared: false, - reason: 'hook_changed_serialized_widgets' + expect(widgetValuesFormVerdict(node)).toEqual({ + declared: true, + form: { order: ['filename'] } }) }) - it('declares nothing when the hook drops a widget mid-serialization', () => { + it('uses the post-hook widget list when the hook drops a widget', () => { const node = nodeWith('Shrinking', (n) => { n.addWidget('text', 'prompt', 'a', () => {}) n.addWidget('text', 'extra', 'b', () => {}) @@ -145,9 +143,9 @@ describe('invariant 4 — the form survived the extension serialize hook', () => } }) - expect(widgetValuesFormVerdict(node)).toMatchObject({ - declared: false, - reason: 'hook_changed_serialized_widgets' + expect(widgetValuesFormVerdict(node)).toEqual({ + declared: true, + form: { order: ['prompt'] } }) }) @@ -171,8 +169,8 @@ describe('invariant 4 — the form survived the extension serialize hook', () => }) }) -describe('invariant 2 — the post-hook positional array still fits the widgets', () => { - it('declares nothing when the hook rewrites widgets_values to a shorter array', () => { +describe('positional compatibility data', () => { + it('ignores positional values because the Agent wire sends named values', () => { const node = nodeWith('Rewriting', (n) => { n.addWidget('text', 'prompt', 'a', () => {}) n.addWidget('text', 'extra', 'b', () => {}) @@ -181,16 +179,13 @@ describe('invariant 2 — the post-hook positional array still fits the widgets' } }) - expect(widgetValuesFormVerdict(node)).toMatchObject({ - declared: false, - reason: 'positional_arity_disagrees', - detail: { positional: 1, serialised: 2 } + expect(widgetValuesFormVerdict(node)).toEqual({ + declared: true, + form: { order: ['prompt', 'extra'] } }) }) it('counts button widgets, which core serialises and the wire drops', () => { - // A button is serialised positionally but is not a document value, so a - // check written against the value count would refuse every node with one. const node = nodeWith('Buttoned', (n) => { n.addWidget('text', 'prompt', 'a', () => {}) n.addWidget('button', 'refresh', 'refresh', () => {}) @@ -203,12 +198,36 @@ describe('invariant 2 — the post-hook positional array still fits the widgets' }) }) -describe('invariants 1 and 3 — guards on the value filter', () => { - // Neither is reachable through `valueWidgetsOnly` today: it drops a - // `serialize: false` widget and derives the order from the same object it - // filtered. Both are asserted against hand-built values, so the guard goes - // red if a later change to that filter stops holding them. +describe('the Agent wire value filter', () => { + it('preserves an own __proto__ value', () => { + const node = nodeWith('PrototypeNamed', (n) => { + n.addWidget('text', '__proto__', 'safe', () => {}) + }) + const named = Object.create(null) as Record + Object.defineProperty(named, '__proto__', { + value: 'safe', + enumerable: true + }) + const values = valueWidgetsOnly(node, named) + + expect(Object.hasOwn(values, '__proto__')).toBe(true) + expect(values.__proto__).toBe('safe') + }) + + it('keeps a value widget when a same-named button appears first', () => { + const node = detachedNodeWith('ButtonTwin', (n) => { + n.addWidget('button', 'shared', 'refresh', () => {}) + n.addWidget('text', 'shared', 'value', () => {}) + }) + + expect(valueWidgetsOnly(node, { shared: 'value' })).toEqual({ + shared: 'value' + }) + }) +}) + +describe('guards on the value filter', () => { it('refuses an order entry naming a widget core would not serialise', () => { const node = nodeWith('Hiding', (n) => { n.addWidget('text', 'prompt', 'a', () => {}) @@ -224,8 +243,8 @@ describe('invariants 1 and 3 — guards on the value filter', () => { ) ).toMatchObject({ declared: false, - reason: 'order_names_unserialized_widget', - detail: { names: ['hidden'] } + reason: 'declared_keys_disagree', + detail: { undeclared: ['hidden'] } }) }) @@ -314,18 +333,15 @@ describe('the invariant channel', () => { n.addWidget('text', 'prompt', 'a', () => {}) n.addWidget('text', 'extra', 'b', () => {}) n.onSerialize = (data: ISerialisedNode) => { - data.widgets_values = ['only one'] + data.widgets_values_named = { prompt: 'a' } } }) const serialized = serializedOf(node) + const values = valueWidgetsOnly(node, serialized.widgets_values_named!) - // The DEV throw is swallowed on purpose: a third-party pack must not be - // able to stop the Agent minting in a developer's browser. - expect( - provenWidgetValuesForm(node, { prompt: 'a', extra: 'b' }, serialized) - ).toBeUndefined() + expect(provenWidgetValuesForm(node, values, serialized)).toBeUndefined() expect(console.error).toHaveBeenCalledWith( - expect.stringContaining('Agent widget form invariant 2') + expect.stringContaining('Agent widget form invariant 3') ) }) @@ -333,23 +349,21 @@ describe('the invariant channel', () => { vi.stubEnv('DEV', false) const reporter = vi.fn() setAssertReporter(reporter) - // Module-level state, so the restore cannot sit after the assertions: a - // failure there would leave a stale reporter installed and hide itself - // behind the secondary failures it causes in later tests. onTestFinished(() => setAssertReporter(null)) const node = nodeWith('Shrinking', (n) => { n.addWidget('text', 'prompt', 'a', () => {}) n.addWidget('text', 'extra', 'b', () => {}) - n.onSerialize = () => { - n.widgets?.pop() + n.onSerialize = (data: ISerialisedNode) => { + data.widgets_values_named = { prompt: 'a' } } }) const serialized = serializedOf(node) + const values = valueWidgetsOnly(node, serialized.widgets_values_named!) - provenWidgetValuesForm(node, { prompt: 'a' }, serialized) + provenWidgetValuesForm(node, values, serialized) expect(reporter).toHaveBeenCalledWith( - expect.stringContaining('Agent widget form invariant 4'), + expect.stringContaining('Agent widget form invariant 3'), expect.objectContaining({ nodeType: 'Shrinking' }) ) const [message] = reporter.mock.calls[0] as [string] @@ -360,7 +374,7 @@ describe('the invariant channel', () => { }) }) -describe('invariant 5 — the undeclared-form production signal', () => { +describe('invariant 4 — the undeclared-form production signal', () => { it('reports the class and the reason, once per pair', () => { useNodeDefStore().addNodeDef( nodeDef('Dynamic', { mode: ['COMFY_DYNAMICCOMBO_V3', {}] }) @@ -410,7 +424,7 @@ describe('invariant 5 — the undeclared-form production signal', () => { useNodeDefStore().addNodeDef( nodeDef('Dynamic', { mode: ['COMFY_DYNAMICCOMBO_V3', {}] }) ) - const dynamic = (n: LGraphNode) => { + function dynamic(n: LGraphNode) { n.addWidget('combo', 'mode', 'a', () => {}, { values: ['a'] }) } const first = nodeWith('Dynamic', dynamic) @@ -434,7 +448,7 @@ describe('invariant 5 — the undeclared-form production signal', () => { ]) }) - it('classifies for a bulk pass without reporting or tallying', () => { + it('classifies and tallies for a bulk pass without reporting', () => { useNodeDefStore().addNodeDef( nodeDef('Dynamic', { mode: ['COMFY_DYNAMICCOMBO_V3', {}] }) ) @@ -444,6 +458,8 @@ describe('invariant 5 — the undeclared-form production signal', () => { expect(widgetValuesFormVerdict(node)).toMatchObject({ declared: false }) expect(reportError).not.toHaveBeenCalled() - expect(widgetFormSuppressionTally()).toEqual([]) + expect(widgetFormSuppressionTally()).toEqual([ + { nodeType: 'Dynamic', reason: 'value_dependent_layout', count: 1 } + ]) }) }) diff --git a/src/workbench/extensions/agent/crdt/widgetValuesForm.ts b/src/workbench/extensions/agent/crdt/widgetValuesForm.ts index 8715df82af9..c717862312d 100644 --- a/src/workbench/extensions/agent/crdt/widgetValuesForm.ts +++ b/src/workbench/extensions/agent/crdt/widgetValuesForm.ts @@ -1,5 +1,5 @@ /** - * Whether the Agent wire may declare a node's widget form, and the five + * Whether the Agent wire may declare a node's widget form, and the four * invariants that decide it. * * `widgets_values_form` tells the host which order its name-keyed registers @@ -32,30 +32,27 @@ import type { WidgetState } from '@/types/widgetState' import { widgetId } from '@/types/widgetId' /** The post-hook halves of a serialized node this module reads. */ -type SerializedWidgetValues = Pick< - ISerialisedNode, - 'widgets_values' | 'widgets_values_named' -> +type SerializedWidgetValues = Pick /** * Why no form was declared. The first four are invariant violations: the * values and the order disagree, so declaring either would publish a state no * other reader sees. The rest are shapes a correct producer legitimately - * cannot describe, and they are the population invariant 5 counts. + * cannot describe, and they are the population invariant 4 counts. */ type WidgetFormSuppression = /** Invariant 1 — an entry names no live widget core would serialise. */ | 'order_names_unserialized_widget' - /** Invariant 2 — the post-hook positional array has a different arity. */ - | 'positional_arity_disagrees' - /** Invariant 3 — declared order and value keys differ in either direction. */ + /** Invariant 2 — declared order and value keys differ in either direction. */ | 'declared_keys_disagree' - /** Invariant 4 — the hook changed which widgets core serialises. */ + /** Invariant 3 — the hook changed the values carried by the Agent wire. */ | 'hook_changed_serialized_widgets' /** The catalogue owns this order: it is a function of the values. */ | 'value_dependent_layout' /** A missing-node shell round-trips a stored payload, not live widgets. */ | 'shell_last_serialization' + /** A custom serialization hook threw before producing a payload. */ + | 'serialization_failed' /** A value the document carries has no live widget to order. */ | 'value_has_no_live_widget' /** Nothing to declare. */ @@ -68,19 +65,21 @@ type WidgetFormSuppression = /** * Nothing to declare is not a declaration gap: a node whose only widgets are * buttons has no named value for a form to order, so counting it would bury - * invariant 5's signal under every such class in the ecosystem. + * invariant 4's signal under every such class in the ecosystem. */ const UNREPORTED: ReadonlySet = new Set([ 'no_value_widgets' ]) +type SuppressedWidgetFormVerdict = { + readonly declared: false + readonly reason: WidgetFormSuppression + readonly detail?: Record +} + export type WidgetFormVerdict = | { readonly declared: true; readonly form: WidgetValuesForm } - | { - readonly declared: false - readonly reason: WidgetFormSuppression - readonly detail?: Record - } + | SuppressedWidgetFormVerdict const ADR = 'docs/adr/WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md' @@ -96,19 +95,16 @@ const INVARIANT_MESSAGES: Partial> = { order_names_unserialized_widget: '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 — ' + `see ${ADR}`, - positional_arity_disagrees: - 'Agent widget form invariant 2: the post-hook positional widgets_values array no longer has one entry per serialised widget, so an extension replaced the values the order was proven against — ' + - `see ${ADR}`, declared_keys_disagree: - 'Agent widget form invariant 3: 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 — ' + + '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 — ' + `see ${ADR}`, hook_changed_serialized_widgets: - 'Agent widget form invariant 4: the extension serialize hook changed which widgets are serialised, so the form core would have written no longer describes the final values — ' + + '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 — ' + `see ${ADR}` } const UNDECLARED_FORM_MESSAGE = - 'Agent widget form invariant 5: object-shaped widget values with no declared form' + 'Agent widget form invariant 4: object-shaped widget values with no declared form' const VALUE_DEPENDENT_LAYOUT_INPUT_TYPES = new Set([ 'COMFY_AUTOGROW_V3', @@ -127,12 +123,15 @@ const tally = new Map< string, { nodeType: string; reason: WidgetFormSuppression; count: number } >() +const reported = new Set() +const MAX_SUPPRESSION_KEYS = 100 const tallyKey = (nodeType: string, reason: WidgetFormSuppression): string => JSON.stringify([nodeType, reason]) /** - * Every suppression this page session saw, by class and reason. + * Up to the first 100 distinct suppressions this page session saw, by class + * and reason. * * This is the bulk instrument. A corpus run reads it once at the end instead * of scraping telemetry, and `nodeType` makes the answer a class-by-class @@ -148,21 +147,28 @@ export function resetWidgetFormSuppressionTally(): void { tally.clear() } -function record(nodeType: string, reason: WidgetFormSuppression): boolean { +function record(nodeType: string, reason: WidgetFormSuppression): void { const key = tallyKey(nodeType, reason) const seen = tally.get(key) if (seen) { seen.count += 1 - return false + return } + if (tally.size >= MAX_SUPPRESSION_KEYS) return tally.set(key, { nodeType, reason, count: 1 }) +} + +function firstReport(nodeType: string, reason: WidgetFormSuppression): boolean { + const key = tallyKey(nodeType, reason) + if (reported.has(key) || reported.size >= MAX_SUPPRESSION_KEYS) return false + reported.add(key) return true } function suppressed( reason: WidgetFormSuppression, detail?: Record -): WidgetFormVerdict { +): SuppressedWidgetFormVerdict { return detail ? { declared: false, reason, detail } : { declared: false, reason } @@ -198,15 +204,23 @@ export function valueWidgetsOnly( node: LGraphNode, named: object ): Record { - const filtered: Record = {} + const filtered: Record = Object.create(null) const rootGraphId = node.graph?.rootGraph.id const widgetValueStore = useWidgetValueStore() for (const [name, value] of Object.entries(named)) { - const widget = node.widgets?.find((candidate) => candidate.name === name) const stored = rootGraphId ? widgetValueStore.getWidget(widgetId(rootGraphId, node.id, name)) : undefined - if (isValueWidget(widget, stored)) filtered[name] = value + const carriesValue = node.widgets?.some( + (candidate) => candidate.name === name && isValueWidget(candidate, stored) + ) + if (carriesValue) + Object.defineProperty(filtered, name, { + value, + writable: true, + enumerable: true, + configurable: true + }) } return filtered } @@ -215,12 +229,8 @@ export function valueWidgetsOnly( interface FormProof { /** Every live widget's name, serialised or not. */ readonly liveNames: readonly string[] - /** The names core serialises: `serialize === false` is skipped. */ - readonly serialisedNames: readonly string[] - /** The post-hook named keys, which the hook may have replaced. */ - readonly namedKeys: readonly string[] - /** The post-hook positional array, or undefined if there is none. */ - readonly positional: readonly unknown[] | undefined + /** The names of live widgets whose values the Agent wire carries. */ + readonly valueWidgetNames: readonly string[] /** The enumerable keys of the object the wire ships. */ readonly valueNames: readonly string[] /** The order the form would declare. */ @@ -230,22 +240,26 @@ interface FormProof { function formProof( node: LGraphNode, values: Record, - serialized: SerializedWidgetValues + _serialized: SerializedWidgetValues ): FormProof { const live = node.widgets ?? [] - const named = serialized.widgets_values_named - const positional = serialized.widgets_values + const rootGraphId = node.graph?.rootGraph.id + const widgetValueStore = useWidgetValueStore() + const valueWidgetNames = live + .filter((widget) => { + const stored = rootGraphId + ? widgetValueStore.getWidget( + widgetId(rootGraphId, node.id, widget.name) + ) + : undefined + return isValueWidget(widget, stored) + }) + .map((widget) => widget.name) return { liveNames: live.map((widget) => widget.name), - serialisedNames: live - .filter((widget) => widget.serialize !== false) - .map((widget) => widget.name), - namedKeys: named ? Object.keys(named) : [], - positional: Array.isArray(positional) ? positional : undefined, + valueWidgetNames, valueNames: Object.keys(values), - order: live - .map((widget) => widget.name) - .filter((name) => Object.hasOwn(values, name)) + order: valueWidgetNames.filter((name) => Object.hasOwn(values, name)) } } @@ -253,37 +267,19 @@ function formProof( type FormProbe = (proof: FormProof) => WidgetFormVerdict | undefined /** - * Invariant 4 — the hook may replace either widget-values field after core - * wrote it. Compare key SETS, not sequences: `widgets_values_named` is an - * object, and an integer-like widget name is enumeration-reordered inside it, - * which is the reason the form exists in the first place. A pack that - * reorders keys and changes nothing else has not broken anything. + * Invariant 3 — compare the key set that survives the Agent wire's value + * filter with the live value widgets. Positional values and extension-private + * entries are not sent, so neither can invalidate this proof. */ const hookKeptTheSerialisedWidgets: FormProbe = ({ - namedKeys, - serialisedNames + valueNames, + valueWidgetNames }) => - sameNames(namedKeys, serialisedNames) + sameNames(valueNames, valueWidgetNames) ? undefined : suppressed('hook_changed_serialized_widgets', { - serialised: namedKeys, - live: serialisedNames - }) - -/** - * Invariant 2 — the array case. The wire ships the named object, so the arity - * claim is made against the positional array the hook left behind: one slot - * per serialised widget, or the order was proven against values no other - * reader of this workflow will see. Buttons count here: core serialises one - * positionally and the wire drops it as a non-value, so a check written - * against the value count would refuse every node that has one. - */ -const positionalArityFits: FormProbe = ({ positional, serialisedNames }) => - !positional || positional.length === serialisedNames.length - ? undefined - : suppressed('positional_arity_disagrees', { - positional: positional.length, - serialised: serialisedNames.length + wire: valueNames, + live: valueWidgetNames }) /** @@ -306,15 +302,18 @@ const everyValueHasALiveWidget: FormProbe = ({ valueNames, liveNames }) => { * `values`, which `isValueWidget` currently refuses: this is the guard on * that filter. */ -const orderNamesSerialisedWidgets: FormProbe = ({ order, serialisedNames }) => { - const unserialized = order.filter((name) => !serialisedNames.includes(name)) +const orderNamesSerialisedWidgets: FormProbe = ({ + order, + valueWidgetNames +}) => { + const unserialized = order.filter((name) => !valueWidgetNames.includes(name)) return unserialized.length ? suppressed('order_names_unserialized_widget', { names: unserialized }) : undefined } /** - * Invariant 3 — the object case, as a set difference in BOTH directions. + * Invariant 2 — the object case, as a set difference in BOTH directions. * Order without a value orders nothing; a value outside the order is residue * the host would store and never project. Stated against the enumerable keys, * because those are what travel: the wire ships `values` as JSON, so an own @@ -346,11 +345,10 @@ const orderIsAddressable: FormProbe = ({ order }) => { * it to the key disagreement would send a reader looking in the wrong place. */ const FORM_PROBES: readonly FormProbe[] = [ - hookKeptTheSerialisedWidgets, - positionalArityFits, everyValueHasALiveWidget, orderNamesSerialisedWidgets, declaredKeysAgree, + hookKeptTheSerialisedWidgets, orderIsAddressable ] @@ -383,23 +381,36 @@ export function classifyWidgetValuesForm( /** * Classifies a node end to end, for a bulk pass that holds a node and not a - * serialization. Side-effect free: it neither asserts, reports, nor tallies, - * so a corpus run cannot perturb the production signal it is measuring. + * serialization. It runs the node's serialization hook and tallies the + * result, but does not assert or report. */ export function widgetValuesFormVerdict(node: LGraphNode): WidgetFormVerdict { + if (node.last_serialization) { + const verdict = suppressed('shell_last_serialization') + record(node.type, verdict.reason) + return verdict + } let serialized: ISerialisedNode try { serialized = node.serialize() } catch { - return suppressed('shell_last_serialization') + const verdict = suppressed('serialization_failed') + record(node.type, verdict.reason) + return verdict } const named = serialized.widgets_values_named - if (!named) return suppressed('no_value_widgets') - return classifyWidgetValuesForm( + if (!named) { + const verdict = suppressed('no_value_widgets') + record(node.type, verdict.reason) + return verdict + } + const verdict = classifyWidgetValuesForm( node, valueWidgetsOnly(node, named), serialized ) + if (!verdict.declared) record(node.type, verdict.reason) + return verdict } /** @@ -421,10 +432,11 @@ export function provenWidgetValuesForm( if (verdict.declared) return verdict.form const nodeType = node.type - const first = record(nodeType, verdict.reason) + record(nodeType, verdict.reason) + const first = firstReport(nodeType, verdict.reason) const invariantMessage = INVARIANT_MESSAGES[verdict.reason] - if (invariantMessage) { + if (first && invariantMessage) { try { assert(false, invariantMessage, { nodeType, ...verdict.detail }) } catch { @@ -432,7 +444,7 @@ export function provenWidgetValuesForm( } } - // Invariant 5. One report per class and reason: the question is "which + // Invariant 4. One report per class and reason: the question is "which // classes still declare no form, and why", and a corpus pass that mints // thousands of nodes must answer it without thousands of reports. if (first && !UNREPORTED.has(verdict.reason)) { From d77331bd2549555b9e603413f54f955242830402 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 23 Oct 2026 03:05:30 -0700 Subject: [PATCH 6/7] fix(agent): preserve widget form report budget --- .../agent/crdt/widgetValuesForm.test.ts | 31 +++++++++++++++++++ .../extensions/agent/crdt/widgetValuesForm.ts | 6 ++-- 2 files changed, 35 insertions(+), 2 deletions(-) diff --git a/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts b/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts index cb6bc49c4f3..896315f7272 100644 --- a/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts +++ b/src/workbench/extensions/agent/crdt/widgetValuesForm.test.ts @@ -62,6 +62,16 @@ function serializedOf(node: LGraphNode): ISerialisedNode { return node.serialize() } +function recordNoValueClasses(count: number): void { + Array.from({ length: count }, (_, index) => + nodeWith(`OnlyButton${index}`, (node) => { + node.addWidget('button', 'refresh', 'refresh', () => {}) + }) + ).forEach((node) => { + provenWidgetValuesForm(node, {}, serializedOf(node)) + }) +} + beforeEach(() => { resetWidgetFormSuppressionTally() useNodeDefStore().updateNodeDefs([]) @@ -420,6 +430,27 @@ describe('invariant 4 — the undeclared-form production signal', () => { expect(reportError).not.toHaveBeenCalled() }) + it('does not spend the report budget on classes with nothing to declare', () => { + recordNoValueClasses(100) + const node = detachedNodeWith('DuplicatedAfterButtons', (n) => { + n.addWidget('text', 'prompt', 'a', () => {}) + n.addWidget('text', 'prompt', 'b', () => {}) + }) + + provenWidgetValuesForm(node, { prompt: 'b' }, serializedOf(node)) + + expect(reportError).toHaveBeenCalledTimes(1) + expect(reportError).toHaveBeenCalledWith( + expect.any(Error), + expect.objectContaining({ + tags: { + node_type: 'DuplicatedAfterButtons', + reason: 'duplicate_widget_name' + } + }) + ) + }) + it('keeps a per-class tally a bulk pass can read without telemetry', () => { useNodeDefStore().addNodeDef( nodeDef('Dynamic', { mode: ['COMFY_DYNAMICCOMBO_V3', {}] }) diff --git a/src/workbench/extensions/agent/crdt/widgetValuesForm.ts b/src/workbench/extensions/agent/crdt/widgetValuesForm.ts index c717862312d..c6556091a06 100644 --- a/src/workbench/extensions/agent/crdt/widgetValuesForm.ts +++ b/src/workbench/extensions/agent/crdt/widgetValuesForm.ts @@ -145,6 +145,7 @@ export function widgetFormSuppressionTally(): WidgetFormSuppressionTally[] { /** Drops the accumulated tally. For tests and for a fresh corpus pass. */ export function resetWidgetFormSuppressionTally(): void { tally.clear() + reported.clear() } function record(nodeType: string, reason: WidgetFormSuppression): void { @@ -433,7 +434,8 @@ export function provenWidgetValuesForm( const nodeType = node.type record(nodeType, verdict.reason) - const first = firstReport(nodeType, verdict.reason) + const first = + !UNREPORTED.has(verdict.reason) && firstReport(nodeType, verdict.reason) const invariantMessage = INVARIANT_MESSAGES[verdict.reason] if (first && invariantMessage) { @@ -447,7 +449,7 @@ export function provenWidgetValuesForm( // Invariant 4. One report per class and reason: the question is "which // classes still declare no form, and why", and a corpus pass that mints // thousands of nodes must answer it without thousands of reports. - if (first && !UNREPORTED.has(verdict.reason)) { + if (first) { reportError(new Error(UNDECLARED_FORM_MESSAGE), { errorType: 'agent_widget_form_undeclared', surface: 'agent', From cd7258a399bf93f5d89070e723597065ddd4c281 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 23 Oct 2026 03:08:07 -0700 Subject: [PATCH 7/7] test(agent): align widget form with sent values --- .../extensions/agent/crdt/docOpMinter.test.ts | 29 +++++++++++-------- 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/src/workbench/extensions/agent/crdt/docOpMinter.test.ts b/src/workbench/extensions/agent/crdt/docOpMinter.test.ts index 4fea9bca919..0663bc74be0 100644 --- a/src/workbench/extensions/agent/crdt/docOpMinter.test.ts +++ b/src/workbench/extensions/agent/crdt/docOpMinter.test.ts @@ -3212,18 +3212,6 @@ describe('wireNodeSnapshot widget form (schema A24)', () => { n.addWidget('text', 'prompt', 'a', () => {}) n.addWidget('text', 'prompt', 'b', () => {}) } - }, - { - case: 'a stored value whose widget its serializer removed', - definition: nodeDef('Dynamic', {}), - build: (n: LGraphNode) => { - n.addWidget('text', 'prompt', 'a', () => {}) - n.addWidget('text', 'extra', 'b', () => {}) - new LGraph().add(n) - n.onSerialize = () => { - n.widgets?.pop() - } - } } ])('declares no form for a node with $case', ({ definition, build }) => { useNodeDefStore().addNodeDef(definition) @@ -3232,6 +3220,23 @@ describe('wireNodeSnapshot widget form (schema A24)', () => { expect(wireNodeSnapshot(node)).not.toHaveProperty('widgets_values_form') }) + it('declares the filtered form when serialization removes a widget', () => { + useNodeDefStore().addNodeDef(nodeDef('Dynamic', {})) + const node = nodeWith('Dynamic', (n) => { + n.addWidget('text', 'prompt', 'a', () => {}) + n.addWidget('text', 'extra', 'b', () => {}) + new LGraph().add(n) + n.onSerialize = () => { + n.widgets?.pop() + } + }) + + expect(wireNodeSnapshot(node)).toMatchObject({ + widgets_values: { prompt: 'a' }, + widgets_values_form: { order: ['prompt'] } + }) + }) + it('declares the form for a node built by the real widget constructors', () => { const required = { seed: ['INT', { default: 1, control_after_generate: true }],