From 93da15218edee3f479f3f8718e8827ac3af2959e Mon Sep 17 00:00:00 2001 From: operator Date: Mon, 26 Oct 2026 13:35:20 -0700 Subject: [PATCH 01/11] feat(litegraph): prove a node's widget form rather than deriving it Adds the predicate that gates emitting `widgets_values_form`, plus the ADR amendment explaining why it is a proof and not a derivation. Nothing emits a form yet -- deliberately, so this can be landed and measured first. A node carrying a form is addressed through it and consults no widget catalog on any leg, so the error asymmetry is total: no form keeps today's behaviour, imperfect but loud, while a WRONG form is authoritative and misplaces values with nothing left downstream to disagree with. Hence: emit only where core can prove the final widgets_values is the array it produced from node.widgets. The obvious implementation -- derive the order after runExtensionSerializeHook, since that hook sees the final values -- is wrong twice over. LGraphNode.serialize is not the last writer: SubgraphNode.serializeFromStoreState calls super, hook included, then rebuilds widgets_values from `inputs` filtered to those carrying a widgetId, a different collection than node.widgets (promoted widgets are linked inputs, ADR-SUBGRAPH-PROMOTION-0009). And node.widgets is a public JS API that extensions splice, truncate, reorder and replace wholesale -- the contract ECS-WIDGETS-0023 already documents, not a defect to fix. The proof catches both on array IDENTITY, deliberately not deep equality, since a rebuilt equal-looking array came from a source core cannot see. The flag trap is the most likely way to get this wrong, so it is pinned as test literals. Three predicates look interchangeable: widget.serialize === false governs widgets_values; widget.options.serialize === false governs the API prompt only; promotion checks either. addWidget does not hoist the options-bag flag, so a widget flagged only there DOES occupy a positional slot -- which is why every KSampler serializes 7 values and every LoadImage 2. Both are asserted so a form built from the wrong flag fails rather than shipping one slot short. Seven refusals, each a shape measured in this repo or a shipping pack. Two worth naming: a replayed payload from an unregistered node type never reaches the hook and its widgets are synthesised FROM the stored values as UNKNOWN, UNKNOWN_1, ... so a form there would be valid, authoritative and meaningless; and two serializing widgets sharing a name collapse in the named projection via defineProperty while the document rejects the second address, so listing both would promise an address that does not resolve. Also adds needsFormButHasNone, identifying object-shaped widget values with no form -- the population a form would rescue and that nothing can currently count, which is much of why this gap stayed invisible. widgets_values is typed `unknown` rather than the serialised-node type's WidgetValue[] on purpose: every interesting input here violates that type, so typing the parameter as the expected shape would make the shapes being checked for unrepresentable and the checks dead. Tests: 16 cases. Typecheck, oxlint and the repo's pre-commit gates clean. --- ...023-widget-entities-with-a-legacy-layer.md | 78 +++++ .../src/node/widgetFormProof.test.ts | 284 ++++++++++++++++++ src/lib/litegraph/src/node/widgetFormProof.ts | 175 +++++++++++ 3 files changed, 537 insertions(+) create mode 100644 src/lib/litegraph/src/node/widgetFormProof.test.ts create mode 100644 src/lib/litegraph/src/node/widgetFormProof.ts diff --git a/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md b/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md index f00db0403ac..b23a8640459 100644 --- a/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md +++ b/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md @@ -161,3 +161,81 @@ the registration boundary instead of adding it to renderer inner loops. Bevy's [ECS callback example](https://bevy.org/examples/ecs-entity-component-system/callbacks/) shows a related behavior boundary: a component holds a registered system ID, and the ECS runs that system on demand. + +--- + +## Amended (2026-10-26): a per-node widget form is emitted only where it can be _proven_ + +`widgets_values_form` is a per-node declaration of which widgets serialize and in what order +(`comfy-multi-player` schema amendment A24). A node carrying one is addressed through that form +and **consults no widget catalog on any leg**. That makes the error asymmetry total: + +- A node with **no** form keeps today's catalog behaviour, which is imperfect but visible — a + name that does not resolve is refused loudly. +- A node with a **wrong** form is authoritative. Values are misplaced silently and nothing + downstream has anything left to disagree with. + +So the rule is not "derive the order from `node.widgets`". It is: + +> **Emit a form only where core can prove the final `widgets_values` is the array it itself +> produced from `node.widgets`. Where it cannot prove that, emit nothing.** + +Deriving is a guess dressed as a declaration; proving is not. `proveWidgetForm` +(`src/lib/litegraph/src/node/widgetFormProof.ts`) is that predicate, and it returns an order +**only** alongside `provable: true` — never a partial order beside a refusal. + +### Why deriving does not work, measured + +The obvious implementation — derive after `runExtensionSerializeHook`, since that hook sees the +final values — is wrong for two independent reasons. + +**`LGraphNode.serialize` is not the last writer.** `SubgraphNode.serializeFromStoreState` calls +`super.serializeFromStoreState(state)` — hook included — and _then_ replaces `widgets_values` +from `this.inputs` filtered to those carrying a `widgetId`, or deletes it. That is a different +collection from `node.widgets` (promoted widgets are linked inputs, per +[ADR-SUBGRAPH-PROMOTION-0009](SUBGRAPH-PROMOTION-0009-represent-promoted-widgets-as-linked-inputs.md)), +so a form written at the end of the base method is already stale when the subclass returns. The +proof catches this on **array identity**, deliberately not deep equality: a rebuilt +equal-looking array came from a source core cannot see, and a coincidental match is not evidence. + +**`node.widgets` is a public JavaScript API that extensions mutate**, as the ADR body above +already describes. Shipping packs splice it, truncate it (`this.widgets.length = n`), reorder +it, and replace it wholesale during `onNodeCreated`; `this.serialize_widgets = false` appears in +the low hundreds of repositories. None of that is a defect to fix — it is the contract this ADR +documents — so the form has to tolerate it rather than assume it away. + +### The flag trap, which is the most likely way to get this wrong + +Three predicates look interchangeable and are deliberately different: + +| predicate | effect on `widgets_values` | +| ------------------------------------ | --------------------------------------------- | +| `widget.serialize === false` | **excluded** — the only one that governs it | +| `widget.options.serialize === false` | **not excluded**; affects the API prompt only | +| either false | neither; governs promotion and preview | + +`addWidget` does not hoist the options-bag flag onto the widget, so a widget flagged only there +**does occupy a positional slot.** That is why every `KSampler` serializes 7 values +(`control_after_generate`) and every `LoadImage` serializes 2 (its upload button). A form built +from `options.serialize` is one slot short on both, and both lengths are pinned as literals in +`widgetFormProof.test.ts` so the mistake cannot land twice. + +### Refusals, each a measured shape + +`replayed_serialization` · `widgets_not_serialized` · `values_replaced` · +`values_not_positional` · `length_mismatch` · `duplicate_widget_name` · `unnameable_widget` + +Two are worth calling out. **`replayed_serialization`** covers an unregistered node type, whose +payload is replayed verbatim and never reaches the hook, and whose widgets are _synthesised from +the stored values_ with names `UNKNOWN`, `UNKNOWN_1`, … A form there would be syntactically +valid, authoritative, and meaningless, so it is refused before any other check can accept it. +**`duplicate_widget_name`** covers two serializing widgets sharing a name: the named projection +collapses them via `defineProperty`, and the document rejects the second address outright, so +listing both would promise an address that does not resolve. + +### Scope + +This amendment adds the predicate and a diagnostic (`needsFormButHasNone`, which identifies +object-shaped values with no form — the population a form would rescue and that nothing can +currently count). **Nothing emits a form yet.** The producer is deliberately a later change, so +the predicate can be landed, measured against the custom-node ecosystem, and trusted first. diff --git a/src/lib/litegraph/src/node/widgetFormProof.test.ts b/src/lib/litegraph/src/node/widgetFormProof.test.ts new file mode 100644 index 00000000000..6b9786ab512 --- /dev/null +++ b/src/lib/litegraph/src/node/widgetFormProof.test.ts @@ -0,0 +1,284 @@ +import { describe, expect, it } from 'vitest' + +import { + needsFormButHasNone, + proveWidgetForm +} from '@/lib/litegraph/src/node/widgetFormProof' +import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets' + +/** + * Each case below is a shape measured in the real frontend or in a shipping custom-node pack, + * not a hypothetical. The invariant under test is one-directional and is the whole point: + * + * **either no form, or a form that agrees. Never a form that disagrees.** + * + * A form-carrying node consults no widget catalog, so a wrong form is authoritative and + * cannot be detected downstream. Every `provable: false` assertion here is therefore a + * success, not a limitation. + */ + +function widget(name: string, extra: Partial = {}): IBaseWidget { + return { name, type: 'number', value: 0, ...extra } as IBaseWidget +} + +/** Serialize the way `serialiseWidgetValues` does, and hand back the array identity. */ +function produce(widgets: IBaseWidget[]) { + const values = widgets + .filter((w) => w.serialize !== false) + .map((w) => w.value as unknown) + return { values, serialised: { widgets_values: values } } +} + +describe('proveWidgetForm', () => { + it('proves an ordinary node whose values it produced itself', () => { + const widgets = [ + widget('seed', { value: 1 }), + widget('steps', { value: 20 }) + ] + const { values, serialised } = produce(widgets) + + const proof = proveWidgetForm(widgets, serialised, values, { + serializeWidgets: true + }) + + expect(proof.provable).toBe(true) + expect(proof.order).toEqual(['seed', 'steps']) + expect(proof.refusal).toBeNull() + }) + + it('counts a widget flagged only in its options bag, because widgets_values does', () => { + // The trap that would have shipped a wrong form. `options.serialize === false` excludes a + // widget from the API prompt but NOT from widgets_values, and `addWidget` does not hoist + // the flag. Reading the options bag here yields an order one slot short of the values. + // Measured: every KSampler serializes 7 values because `control_after_generate` is + // options-bag-only, and every LoadImage serializes 2 because its upload button is. + const widgets = [ + widget('seed', { value: 1 }), + widget('control_after_generate', { + value: 'randomize', + options: { serialize: false } + }) + ] + const { values, serialised } = produce(widgets) + + expect(values).toHaveLength(2) + const proof = proveWidgetForm(widgets, serialised, values, { + serializeWidgets: true + }) + + expect(proof.provable).toBe(true) + expect(proof.order).toEqual(['seed', 'control_after_generate']) + }) + + it('excludes a widget flagged on the widget itself, because widgets_values does too', () => { + const widgets = [ + widget('audio', { value: 'clip.mp3' }), + widget('audioUI', { serialize: false }) + ] + const { values, serialised } = produce(widgets) + + const proof = proveWidgetForm(widgets, serialised, values, { + serializeWidgets: true + }) + + expect(proof.provable).toBe(true) + expect(proof.order).toEqual(['audio']) + }) + + describe('refuses rather than guessing', () => { + it('when a subclass or extension replaced the array after we wrote it', () => { + // SubgraphNode.serializeFromStoreState calls super -- hook included -- and then + // rebuilds widgets_values from `inputs` filtered to those carrying a widgetId. That is + // a different collection from node.widgets, so an order derived from node.widgets + // describes the wrong thing. Identity, not deep equality, is what catches it. + const widgets = [widget('a', { value: 1 }), widget('b', { value: 2 })] + const { values } = produce(widgets) + const replaced = { widgets_values: [1, 2] } // equal-looking, different array + + const proof = proveWidgetForm(widgets, replaced, values, { + serializeWidgets: true + }) + + expect(proof.provable).toBe(false) + expect(proof.refusal).toBe('values_replaced') + expect(proof.order).toBeNull() + }) + + it('when a subgraph deleted the values entirely', () => { + // The `delete serialized.widgets_values` branch, taken when every promoted store value + // is undefined. A non-empty order beside no values would promise addresses for nothing. + const widgets = [widget('promoted_a'), widget('promoted_b')] + const { values } = produce(widgets) + + const proof = proveWidgetForm(widgets, {}, values, { + serializeWidgets: true + }) + + expect(proof.provable).toBe(false) + expect(proof.order).toBeNull() + }) + + it('when an extension replaced the array with an object', () => { + // The VHS family: onSerialize sets widgets_values to a dict keyed by every widget name, + // including ones flagged serialize === false, so the keys and any derived order differ. + const widgets = [ + widget('video', { value: 'clip.mp4' }), + widget('vhslatentpreview', { serialize: false }) + ] + const { values } = produce(widgets) + const dict = { + widgets_values: { video: 'clip.mp4', vhslatentpreview: {}, crf: 23 } + } + + const proof = proveWidgetForm(widgets, dict, values, { + serializeWidgets: true + }) + + expect(proof.provable).toBe(false) + expect(proof.refusal).toBe('values_not_positional') + }) + + it('when the payload was replayed from a previous save', () => { + // An unregistered node type is replayed verbatim and never reaches the hook, and its + // widgets are synthesised placeholders built FROM the stored values. A form there would + // read order: ['UNKNOWN', 'UNKNOWN_1'] -- valid, authoritative, meaningless. + const widgets = [ + widget('UNKNOWN', { value: 1 }), + widget('UNKNOWN_1', { value: 2 }) + ] + const { values, serialised } = produce(widgets) + + const proof = proveWidgetForm(widgets, serialised, values, { + serializeWidgets: true, + replayed: true + }) + + expect(proof.provable).toBe(false) + expect(proof.refusal).toBe('replayed_serialization') + expect(proof.order).toBeNull() + }) + + it('and also when the replay is signalled by has_errors', () => { + const widgets = [widget('UNKNOWN', { value: 1 })] + const { values, serialised } = produce(widgets) + + const proof = proveWidgetForm( + widgets, + { ...serialised, has_errors: true }, + values, + { serializeWidgets: true } + ) + + expect(proof.refusal).toBe('replayed_serialization') + }) + + it('when serialize_widgets is falsy', () => { + // `this.serialize_widgets = false` is in the low hundreds of repositories -- rgthree's + // group muters, was-node-suite's fast groups, Crystools' debugger. Widgets exist and no + // values are written. + const widgets = [widget('mode'), widget('filter')] + + const proof = proveWidgetForm(widgets, {}, undefined, { + serializeWidgets: false + }) + + expect(proof.provable).toBe(false) + expect(proof.refusal).toBe('widgets_not_serialized') + }) + + it('when the widget list was spliced after the values were written', () => { + const widgets = [widget('a', { value: 1 }), widget('b', { value: 2 })] + const { values, serialised } = produce(widgets) + widgets.pop() // a pack truncating node.widgets mid-serialize + + const proof = proveWidgetForm(widgets, serialised, values, { + serializeWidgets: true + }) + + expect(proof.provable).toBe(false) + expect(proof.refusal).toBe('length_mismatch') + }) + + it('when two serializing widgets share a name', () => { + // Measured in the corpus: RecordAudio stores 2 values under 1 name, LoadAudio 3 under + // 2. `serialiseWidgetValues` collapses them via defineProperty, and the document + // rejects the second address outright, so an order listing both promises an address + // that does not resolve. + const widgets = [ + widget('audio', { value: 'a' }), + widget('audio', { value: 'b' }) + ] + const { values, serialised } = produce(widgets) + + const proof = proveWidgetForm(widgets, serialised, values, { + serializeWidgets: true + }) + + expect(proof.provable).toBe(false) + expect(proof.refusal).toBe('duplicate_widget_name') + }) + + it('when a widget has no usable name', () => { + const widgets = [widget('ok', { value: 1 }), widget('', { value: 2 })] + const { values, serialised } = produce(widgets) + + const proof = proveWidgetForm(widgets, serialised, values, { + serializeWidgets: true + }) + + expect(proof.provable).toBe(false) + expect(proof.refusal).toBe('unnameable_widget') + }) + }) + + it('never returns an order alongside a refusal', () => { + // The one-directional invariant, asserted directly: no refusal path may leak a partial + // order, because a caller that reads `order` without checking `provable` would then emit + // a wrong form -- the exact outcome this module prevents. + const widgets = [widget('dup', { value: 1 }), widget('dup', { value: 2 })] + const { values, serialised } = produce(widgets) + + for (const proof of [ + proveWidgetForm(widgets, serialised, values, { serializeWidgets: true }), + proveWidgetForm(widgets, serialised, values, { + serializeWidgets: true, + replayed: true + }), + proveWidgetForm(widgets, { widgets_values: { a: 1 } }, values, { + serializeWidgets: true + }), + proveWidgetForm(widgets, {}, undefined, { serializeWidgets: false }), + proveWidgetForm(undefined, {}, undefined, { serializeWidgets: true }) + ]) { + expect(proof.provable).toBe(false) + expect(proof.order).toBeNull() + expect(proof.refusal).not.toBeNull() + } + }) +}) + +describe('needsFormButHasNone', () => { + it('flags an object-shaped payload with no form', () => { + // This is the population a form would rescue and that nothing can currently count: stored + // whole and opaquely, round-trips but is not name-addressable, and the follower drops it + // because it only accepts an array. + expect(needsFormButHasNone({ widgets_values: { video: 'clip.mp4' } })).toBe( + true + ) + }) + + it('does not flag one that already declares a form', () => { + expect( + needsFormButHasNone({ + widgets_values: { video: 'clip.mp4' }, + widgets_values_form: { order: ['video'] } + }) + ).toBe(false) + }) + + it('does not flag ordinary positional values, or an absent payload', () => { + expect(needsFormButHasNone({ widgets_values: [1, 2] })).toBe(false) + expect(needsFormButHasNone({})).toBe(false) + expect(needsFormButHasNone({ widgets_values: null })).toBe(false) + }) +}) diff --git a/src/lib/litegraph/src/node/widgetFormProof.ts b/src/lib/litegraph/src/node/widgetFormProof.ts new file mode 100644 index 00000000000..c92e1c48e30 --- /dev/null +++ b/src/lib/litegraph/src/node/widgetFormProof.ts @@ -0,0 +1,175 @@ +import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets' + +/** + * Whether a node's serialized widget values can be *proven* to describe its own widget list. + * + * This is the gate for emitting `widgets_values_form` — a per-node declaration of which + * widgets serialize and in what order. A node carrying a form is addressed through that form + * and consults no widget catalog on any leg, so **a wrong form is authoritative**: it would + * silently misplace values with no mismatch anywhere to detect it. A node with no form keeps + * today's catalog behaviour, which is merely imperfect. So the asymmetry is total, and the + * rule follows from it: + * + * **Emit only where we can prove the final `widgets_values` is the array we produced from + * `node.widgets`. Otherwise do not emit.** + * + * The naive version of this — "derive the order from `node.widgets` after the extension + * serialize hook" — is wrong, and measurably so. `node.widgets` is a public JavaScript API + * that extensions splice, truncate, reorder and replace wholesale (see ADR-ECS-WIDGETS-0023), + * and `LGraphNode.serialize` is not the last writer: `SubgraphNode.serializeFromStoreState` + * calls `super` — hook included — and then rebuilds `widgets_values` from a different + * collection entirely. Deriving an order is a guess dressed as a declaration. Proving one is + * not. + * + * Nothing here emits a form. This is the predicate and the diagnosis only, so it can be + * landed, measured and trusted before any producer depends on it. + */ + +/** Why a node's widget values could not be proven. `null` reason means they were. */ +export type WidgetFormRefusal = + /** Replayed verbatim from a previous save; this process never built these values. */ + | 'replayed_serialization' + /** `serialize_widgets` is falsy: widgets exist, values were never written. */ + | 'widgets_not_serialized' + /** Values are not the array we produced — an extension or subclass replaced them. */ + | 'values_replaced' + /** Values are an object; shape is the producer's own, not a positional array. */ + | 'values_not_positional' + /** Length disagrees with the serializable widget list. */ + | 'length_mismatch' + /** Two serializing widgets share a name, so a name-keyed order cannot address both. */ + | 'duplicate_widget_name' + /** A widget's name is absent or not a string, so it cannot be an address. */ + | 'unnameable_widget' + +export interface WidgetFormProof { + /** True only when every check below passed. Emit a form if and only if this is true. */ + provable: boolean + /** Set when `provable` is false. */ + refusal: WidgetFormRefusal | null + /** + * The order, present only when `provable`. Never returned alongside a refusal — a partial + * order is the failure mode this module exists to prevent. + */ + order: string[] | null +} + +function refuse(refusal: WidgetFormRefusal): WidgetFormProof { + return { provable: false, refusal, order: null } +} + +/** + * The widgets that contribute a positional value, in order. + * + * `widget.serialize === false` is the ONLY predicate that governs `widgets_values`, and that + * is easy to get wrong because two other spellings look interchangeable: + * `widget.options.serialize === false` excludes a widget from the API prompt but NOT from + * `widgets_values`, and promotion checks either. `addWidget` does not hoist the options-bag + * flag onto the widget, so widgets flagged only there DO occupy positional slots — which is + * why every `KSampler` serializes 7 values (`control_after_generate` is options-bag-only) and + * every `LoadImage` serializes 2 (the upload button is too). Reading `options.serialize` here + * would silently drop both and produce a form one slot short. + */ +function serializingWidgets(widgets: readonly IBaseWidget[]): IBaseWidget[] { + return widgets.filter((widget) => widget.serialize !== false) +} + +/** + * Prove — or refuse to prove — that `serialised.widgets_values` describes `widgets`. + * + * @param widgets the node's live widget list at serialization time + * @param serialised the node payload as it stands AFTER the extension serialize hook + * @param producedValues the array `serialiseWidgetValues` returned BEFORE the hook ran, or + * `undefined` if it never ran. Identity is the proof: if the post-hook value is not this + * same array, something replaced it and we know nothing about what the replacement means. + * @param options `serializeWidgets` is the node's `serialize_widgets` flag; `replayed` marks a + * payload that was replayed from a previous save rather than built in this process. + */ +export function proveWidgetForm( + widgets: readonly IBaseWidget[] | undefined, + // `widgets_values` is deliberately `unknown` rather than the serialised-node type's + // `WidgetValue[]`. Every interesting input here VIOLATES that type: an extension replaced + // the array with an object, or deleted it. Typing the parameter as the shape we expect + // would make the shapes we are checking for unrepresentable, and the checks dead. + serialised: { + widgets_values?: unknown + /** Present when the payload was replayed rather than built. */ + has_errors?: boolean + }, + producedValues: unknown, + options: { serializeWidgets?: boolean; replayed?: boolean } = {} +): WidgetFormProof { + // A replayed payload carries whatever shape some other frontend wrote, and the widget list + // beside it may be synthesised placeholders: an unregistered node type gets widgets named + // `UNKNOWN`, `UNKNOWN_1`, ... from its stored values. A form built there would be + // syntactically valid, authoritative to every consumer, and meaningless. Refuse first, so + // no later check can accidentally accept it. + if (options.replayed || serialised.has_errors) + return refuse('replayed_serialization') + + if (!widgets?.length || !options.serializeWidgets) { + // No values were written. A form with no array to describe is not a weaker claim than + // usual — it is a claim about nothing, and `order` would be read as authoritative. + return refuse('widgets_not_serialized') + } + + const values = serialised.widgets_values + if (producedValues === undefined || values !== producedValues) { + // Identity, deliberately, not deep equality. A subclass or extension that rebuilt an + // equal-looking array did so from a source we cannot see, and a coincidental match is + // not evidence. This is the check that catches `SubgraphNode` and the packs that + // override `serialize` to write values after `super` returns. + return refuse( + Array.isArray(values) ? 'values_replaced' : 'values_not_positional' + ) + } + if (!Array.isArray(values)) return refuse('values_not_positional') + + const serializing = serializingWidgets(widgets) + if (serializing.length !== values.length) { + // Reachable even with an untouched array: a widget mutated its own `serialize` flag + // between the write and this check, or `widgets` was spliced in between. + return refuse('length_mismatch') + } + + const order: string[] = [] + const seen = new Set() + for (const widget of serializing) { + const name = widget.name + if (typeof name !== 'string' || name.length === 0) + return refuse('unnameable_widget') + // `serialiseWidgetValues` builds its named projection with `defineProperty`, so a repeat + // silently overwrites the earlier value and the two become one key. An `order` array + // would keep both and promise an address for each, but the document rejects the second + // (`name#1` is an unknown widget there). Promising an address that does not resolve is + // worse than declining to describe the node. + if (seen.has(name)) return refuse('duplicate_widget_name') + seen.add(name) + order.push(name) + } + + return { provable: true, refusal: null, order } +} + +/** + * True when a node's values are object-shaped with no form to interpret them. + * + * This is the population that cannot be read back today: an object-shaped `widgets_values` is + * stored whole and opaquely, so it round-trips but is not name-addressable, and the follower + * drops it outright because it only accepts an array. Those nodes are exactly the ones a form + * would rescue, and there is currently no way to count them — which is why the gap has stayed + * invisible and unowned. Report it and the question "which classes still need this?" becomes a + * number instead of an argument. + */ +export function needsFormButHasNone(serialised: { + widgets_values?: unknown + widgets_values_form?: unknown +}): boolean { + const values = serialised.widgets_values + return ( + values !== null && + typeof values === 'object' && + !Array.isArray(values) && + serialised.widgets_values_form === undefined + ) +} From 8cfcda4f793dbfd2cc5fdc4333b27386e75190c9 Mon Sep 17 00:00:00 2001 From: operator Date: Mon, 26 Oct 2026 18:05:07 -0700 Subject: [PATCH 02/11] fix(litegraph): refuse when the node's class can still rewrite the payload Fixes a wrong acceptance in the predicate, found by driving it through the real serialize path rather than reasoning about it (#22017). The defect was in the prescribed call site, not the checks. This module documented `serialised` as the payload "after the extension serialize hook" and assumed that was final. It is not: at the end of LGraphNode.serializeFromStoreState a SubgraphNode's widgets_values is STILL core's own array, because the subclass replaces it only after super returns. So the identity check -- which exists precisely to catch that subclass -- passed. The proof ACCEPTED, returning an order of two names for a payload that ended up holding one value. An acceptance is the one outcome this design cannot tolerate, since a form-carrying node consults no catalog and a wrong form is authoritative. The fix is not a better call site. It is to stop trusting the caller to know it stands at the last writer: coreIsLastWriter is now a REQUIRED option with no default, compared against the base prototype by the caller. Required rather than derived for two reasons -- tsc refuses any new call site until the question has been answered, so the assumption cannot creep back silently; and the comparison needs both the instance and LGraphNode.prototype in scope, which is true at the call site but would mean importing across the node-widgets -> graph-model boundary this repo's architecture gate enforces. Checked BEFORE every other refusal, because a non-final payload makes the rest moot: reporting duplicate_widget_name on a payload about to be replaced sends a reader to the wrong problem. There is a test asserting that ordering, and one asserting the trap directly -- identical values accepted with coreIsLastWriter true, refused with it false, which is the whole point: nothing about the payload reveals the problem, so it has to be told to us. Note for #22017, which is stacked on this branch: its `it.fails` pin plus the live-defect baseline entry should now go red, which is what it was designed to do. The pin can flip to a passing assertion of class_may_rewrite_payload. 19 tests. The refusal-set closure assertion uses arrayContaining + toHaveLength per the repo's prefer-array-containing rule rather than sorting to compare. --- ...023-widget-entities-with-a-legacy-layer.md | 33 ++++ .../{node => widgets}/widgetFormProof.test.ts | 139 ++++++++++++-- .../src/{node => widgets}/widgetFormProof.ts | 173 +++++++++++++----- 3 files changed, 284 insertions(+), 61 deletions(-) rename src/lib/litegraph/src/{node => widgets}/widgetFormProof.test.ts (68%) rename src/lib/litegraph/src/{node => widgets}/widgetFormProof.ts (54%) diff --git a/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md b/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md index b23a8640459..247d190a463 100644 --- a/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md +++ b/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md @@ -233,6 +233,39 @@ valid, authoritative, and meaningless, so it is refused before any other check c collapses them via `defineProperty`, and the document rejects the second address outright, so listing both would promise an address that does not resolve. +### The call site is part of the rule, not an implementation detail + +The first version of this amendment said the form is emitted "after the extension serialize hook" +and left it there. That is wrong, and driving the predicate through the real serialize path proved +it: at the end of `LGraphNode.serializeFromStoreState` a `SubgraphNode`'s `widgets_values` is +**still core's own array** — the subclass replaces it only after `super` returns. So the identity +check, which exists precisely to catch that subclass, passed. The proof **accepted**, returning an +order of two names for a payload that ended up holding one value. + +An acceptance is the one outcome this design cannot tolerate, so the fix is not a better call site — +it is to stop trusting the caller to know it stands at the last writer. `coreIsLastWriter` is a +**required** option with no default: + +```ts +coreIsLastWriter: node.serializeFromStoreState === + LGraphNode.prototype.serializeFromStoreState && + node.serialize === LGraphNode.prototype.serialize +``` + +Required rather than derived for two reasons. `tsc` then refuses any new call site until the +question has been answered, so the assumption cannot creep back in silently. And the comparison +needs both the instance and the base prototype in scope, which is true at the call site and not +inside the widgets layer — deriving it here would mean importing `LGraphNode` across the +`node-widgets` → `graph-model` boundary that this repo's own architecture gate enforces. + +It is checked **before** every other refusal, because a payload that is not final makes the rest +moot: reporting `duplicate_widget_name` on a payload about to be replaced sends a reader to the +wrong problem. The refusal is `class_may_rewrite_payload`, and it covers packs that override +`serialize` exactly as it covers `SubgraphNode`. + +Passing a hardcoded `true` to silence the type error reintroduces the defect. That is worth saying +out loud, because it is the cheapest wrong fix available. + ### Scope This amendment adds the predicate and a diagnostic (`needsFormButHasNone`, which identifies diff --git a/src/lib/litegraph/src/node/widgetFormProof.test.ts b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts similarity index 68% rename from src/lib/litegraph/src/node/widgetFormProof.test.ts rename to src/lib/litegraph/src/widgets/widgetFormProof.test.ts index 6b9786ab512..9cbf54dc96c 100644 --- a/src/lib/litegraph/src/node/widgetFormProof.test.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts @@ -3,7 +3,8 @@ import { describe, expect, it } from 'vitest' import { needsFormButHasNone, proveWidgetForm -} from '@/lib/litegraph/src/node/widgetFormProof' +} from '@/lib/litegraph/src/widgets/widgetFormProof' +import type { WidgetFormRefusal } from '@/lib/litegraph/src/widgets/widgetFormProof' import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets' /** @@ -38,7 +39,8 @@ describe('proveWidgetForm', () => { const { values, serialised } = produce(widgets) const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true + serializeWidgets: true, + coreIsLastWriter: true }) expect(proof.provable).toBe(true) @@ -63,7 +65,8 @@ describe('proveWidgetForm', () => { expect(values).toHaveLength(2) const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true + serializeWidgets: true, + coreIsLastWriter: true }) expect(proof.provable).toBe(true) @@ -78,7 +81,8 @@ describe('proveWidgetForm', () => { const { values, serialised } = produce(widgets) const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true + serializeWidgets: true, + coreIsLastWriter: true }) expect(proof.provable).toBe(true) @@ -96,7 +100,8 @@ describe('proveWidgetForm', () => { const replaced = { widgets_values: [1, 2] } // equal-looking, different array const proof = proveWidgetForm(widgets, replaced, values, { - serializeWidgets: true + serializeWidgets: true, + coreIsLastWriter: true }) expect(proof.provable).toBe(false) @@ -111,7 +116,8 @@ describe('proveWidgetForm', () => { const { values } = produce(widgets) const proof = proveWidgetForm(widgets, {}, values, { - serializeWidgets: true + serializeWidgets: true, + coreIsLastWriter: true }) expect(proof.provable).toBe(false) @@ -131,7 +137,8 @@ describe('proveWidgetForm', () => { } const proof = proveWidgetForm(widgets, dict, values, { - serializeWidgets: true + serializeWidgets: true, + coreIsLastWriter: true }) expect(proof.provable).toBe(false) @@ -150,7 +157,8 @@ describe('proveWidgetForm', () => { const proof = proveWidgetForm(widgets, serialised, values, { serializeWidgets: true, - replayed: true + replayed: true, + coreIsLastWriter: true }) expect(proof.provable).toBe(false) @@ -166,7 +174,7 @@ describe('proveWidgetForm', () => { widgets, { ...serialised, has_errors: true }, values, - { serializeWidgets: true } + { serializeWidgets: true, coreIsLastWriter: true } ) expect(proof.refusal).toBe('replayed_serialization') @@ -179,7 +187,8 @@ describe('proveWidgetForm', () => { const widgets = [widget('mode'), widget('filter')] const proof = proveWidgetForm(widgets, {}, undefined, { - serializeWidgets: false + serializeWidgets: false, + coreIsLastWriter: true }) expect(proof.provable).toBe(false) @@ -192,7 +201,8 @@ describe('proveWidgetForm', () => { widgets.pop() // a pack truncating node.widgets mid-serialize const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true + serializeWidgets: true, + coreIsLastWriter: true }) expect(proof.provable).toBe(false) @@ -211,7 +221,8 @@ describe('proveWidgetForm', () => { const { values, serialised } = produce(widgets) const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true + serializeWidgets: true, + coreIsLastWriter: true }) expect(proof.provable).toBe(false) @@ -223,7 +234,8 @@ describe('proveWidgetForm', () => { const { values, serialised } = produce(widgets) const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true + serializeWidgets: true, + coreIsLastWriter: true }) expect(proof.provable).toBe(false) @@ -231,6 +243,52 @@ describe('proveWidgetForm', () => { }) }) + it('refuses a node whose class can still rewrite the payload', () => { + // The defect found by driving the proof through the real serialize path: at the end of + // LGraphNode.serializeFromStoreState a SubgraphNode's widgets_values is STILL core's own + // array -- the subclass replaces it afterwards -- so the identity check passed and the + // proof accepted, returning an order of two names for a payload that ended up holding + // one value. Everything about the values looks right here; only the knowledge that + // something downstream will rewrite them makes it wrong, which is why this cannot be + // inferred from the payload and has to be told to us. + const widgets = [ + widget('promoted_a', { value: 1 }), + widget('promoted_b', { value: 2 }) + ] + const { values, serialised } = produce(widgets) + + const accepted = proveWidgetForm(widgets, serialised, values, { + serializeWidgets: true, + coreIsLastWriter: true + }) + expect(accepted.provable).toBe(true) // identical input, and this is the trap + + const proof = proveWidgetForm(widgets, serialised, values, { + serializeWidgets: true, + coreIsLastWriter: false + }) + + expect(proof.provable).toBe(false) + expect(proof.refusal).toBe('class_may_rewrite_payload') + expect(proof.order).toBeNull() + }) + + it('checks the last writer before anything else', () => { + // Ordering matters: a non-final payload makes every later check moot, so this refusal must + // win even when another one would also apply. Otherwise the reported reason sends a reader + // to the wrong problem. + const widgets = [widget('dup', { value: 1 }), widget('dup', { value: 2 })] + const { values, serialised } = produce(widgets) + + const proof = proveWidgetForm(widgets, serialised, values, { + serializeWidgets: true, + replayed: true, + coreIsLastWriter: false + }) + + expect(proof.refusal).toBe('class_may_rewrite_payload') + }) + it('never returns an order alongside a refusal', () => { // The one-directional invariant, asserted directly: no refusal path may leak a partial // order, because a caller that reads `order` without checking `provable` would then emit @@ -239,16 +297,27 @@ describe('proveWidgetForm', () => { const { values, serialised } = produce(widgets) for (const proof of [ - proveWidgetForm(widgets, serialised, values, { serializeWidgets: true }), proveWidgetForm(widgets, serialised, values, { serializeWidgets: true, - replayed: true + coreIsLastWriter: true + }), + proveWidgetForm(widgets, serialised, values, { + serializeWidgets: true, + replayed: true, + coreIsLastWriter: true }), proveWidgetForm(widgets, { widgets_values: { a: 1 } }, values, { - serializeWidgets: true + serializeWidgets: true, + coreIsLastWriter: true }), - proveWidgetForm(widgets, {}, undefined, { serializeWidgets: false }), - proveWidgetForm(undefined, {}, undefined, { serializeWidgets: true }) + proveWidgetForm(widgets, {}, undefined, { + serializeWidgets: false, + coreIsLastWriter: true + }), + proveWidgetForm(undefined, {}, undefined, { + serializeWidgets: true, + coreIsLastWriter: true + }) ]) { expect(proof.provable).toBe(false) expect(proof.order).toBeNull() @@ -282,3 +351,37 @@ describe('needsFormButHasNone', () => { expect(needsFormButHasNone({ widgets_values: null })).toBe(false) }) }) + +describe('the refusal set', () => { + it('is covered case-for-case by the tests above', () => { + // Pins the union so a new refusal cannot be added without a test that reaches it, and a + // retired one cannot linger. Each entry below is asserted by a named case above; this + // list is the index, not a second source of truth. + const exercised: Record = { + class_may_rewrite_payload: true, + replayed_serialization: true, + widgets_not_serialized: true, + values_replaced: true, + values_not_positional: true, + length_mismatch: true, + duplicate_widget_name: true, + unnameable_widget: true + } + + // arrayContaining plus toHaveLength, per the repo's prefer-array-containing rule: the + // length is what makes this a closed set, so a new refusal added without a case here fails. + expect(Object.keys(exercised)).toEqual( + expect.arrayContaining([ + 'class_may_rewrite_payload', + 'replayed_serialization', + 'widgets_not_serialized', + 'values_replaced', + 'values_not_positional', + 'length_mismatch', + 'duplicate_widget_name', + 'unnameable_widget' + ]) + ) + expect(Object.keys(exercised)).toHaveLength(8) + }) +}) diff --git a/src/lib/litegraph/src/node/widgetFormProof.ts b/src/lib/litegraph/src/widgets/widgetFormProof.ts similarity index 54% rename from src/lib/litegraph/src/node/widgetFormProof.ts rename to src/lib/litegraph/src/widgets/widgetFormProof.ts index c92e1c48e30..a72c11610ab 100644 --- a/src/lib/litegraph/src/node/widgetFormProof.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.ts @@ -13,8 +13,10 @@ import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets' * **Emit only where we can prove the final `widgets_values` is the array we produced from * `node.widgets`. Otherwise do not emit.** * - * The naive version of this — "derive the order from `node.widgets` after the extension - * serialize hook" — is wrong, and measurably so. `node.widgets` is a public JavaScript API + * Two things are wrong with the naive version — "derive the order from `node.widgets` after + * the extension serialize hook". The order must be proven rather than derived, AND that call + * site is not the last writer, so being handed a payload there proves nothing. Both are + * measurable. `node.widgets` is a public JavaScript API * that extensions splice, truncate, reorder and replace wholesale (see ADR-ECS-WIDGETS-0023), * and `LGraphNode.serialize` is not the last writer: `SubgraphNode.serializeFromStoreState` * calls `super` — hook included — and then rebuilds `widgets_values` from a different @@ -27,6 +29,11 @@ import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets' /** Why a node's widget values could not be proven. `null` reason means they were. */ export type WidgetFormRefusal = + /** + * The node's class can still rewrite the payload after this point, so whatever we are + * looking at is not final and proving anything about it would be premature. + */ + | 'class_may_rewrite_payload' /** Replayed verbatim from a previous save; this process never built these values. */ | 'replayed_serialization' /** `serialize_widgets` is falsy: widgets exist, values were never written. */ @@ -42,6 +49,36 @@ export type WidgetFormRefusal = /** A widget's name is absent or not a string, so it cannot be an address. */ | 'unnameable_widget' +export interface WidgetFormOptions { + /** The node's `serialize_widgets` flag. */ + serializeWidgets?: boolean + /** True when the payload was replayed from a previous save rather than built here. */ + replayed?: boolean + /** + * Whether core is the LAST thing that will write `widgets_values` for this node. + * + * Required, deliberately, with no default. The previous version of this module documented a + * call site ("after the extension serialize hook") and assumed it was final, which is false + * for any class that overrides serialization — `SubgraphNode` rewrites the values after + * `super` returns, and packs override `serialize` to do the same. Assuming it is how the + * proof came to accept a subgraph host. + * + * The only correct value is a comparison against the base implementation, made by the + * caller because that is where both sides are in scope: + * + * ```ts + * coreIsLastWriter: + * node.serializeFromStoreState === LGraphNode.prototype.serializeFromStoreState && + * node.serialize === LGraphNode.prototype.serialize + * ``` + * + * It is a required field rather than a derived one so that a new call site cannot omit the + * question: `tsc` refuses until it has been answered. Passing a hardcoded `true` to silence + * it reintroduces exactly the defect above. + */ + coreIsLastWriter: boolean +} + export interface WidgetFormProof { /** True only when every check below passed. Emit a form if and only if this is true. */ provable: boolean @@ -82,73 +119,123 @@ function serializingWidgets(widgets: readonly IBaseWidget[]): IBaseWidget[] { * @param producedValues the array `serialiseWidgetValues` returned BEFORE the hook ran, or * `undefined` if it never ran. Identity is the proof: if the post-hook value is not this * same array, something replaced it and we know nothing about what the replacement means. - * @param options `serializeWidgets` is the node's `serialize_widgets` flag; `replayed` marks a - * payload that was replayed from a previous save rather than built in this process. + * @param options see {@link WidgetFormOptions}. `coreIsLastWriter` is required and is the + * check that keeps this a proof rather than an assumption. */ -export function proveWidgetForm( +/** + * Phase 1: did core produce these exact values? + * + * Returns the array when yes, or the refusal when no. Split out because it is the only part + * that reasons about provenance; everything after it reasons about names. + */ +function provenValues( widgets: readonly IBaseWidget[] | undefined, - // `widgets_values` is deliberately `unknown` rather than the serialised-node type's - // `WidgetValue[]`. Every interesting input here VIOLATES that type: an extension replaced - // the array with an object, or deleted it. Typing the parameter as the shape we expect - // would make the shapes we are checking for unrepresentable, and the checks dead. - serialised: { - widgets_values?: unknown - /** Present when the payload was replayed rather than built. */ - has_errors?: boolean - }, + serialised: { widgets_values?: unknown; has_errors?: boolean }, producedValues: unknown, - options: { serializeWidgets?: boolean; replayed?: boolean } = {} -): WidgetFormProof { + options: WidgetFormOptions +): { values: unknown[] } | { refusal: WidgetFormRefusal } { + // FIRST, because every check below reasons about a payload it assumes is final. If the + // node's class can still rewrite `widgets_values` after this point, the identity check + // further down compares against an array that is about to be discarded, and it PASSES -- + // which is an acceptance, the one outcome this module exists to prevent. Measured on + // `SubgraphNode`: at the end of `LGraphNode.serializeFromStoreState` its values are still + // core's own array, and only the subclass's own override replaces them afterwards. The + // proof accepted, returning an order of two names for a payload that ended up holding one + // value. + if (!options.coreIsLastWriter) return { refusal: 'class_may_rewrite_payload' } + // A replayed payload carries whatever shape some other frontend wrote, and the widget list // beside it may be synthesised placeholders: an unregistered node type gets widgets named // `UNKNOWN`, `UNKNOWN_1`, ... from its stored values. A form built there would be - // syntactically valid, authoritative to every consumer, and meaningless. Refuse first, so - // no later check can accidentally accept it. - if (options.replayed || serialised.has_errors) - return refuse('replayed_serialization') - + // syntactically valid, authoritative to every consumer, and meaningless. + if (options.replayed || serialised.has_errors) { + return { refusal: 'replayed_serialization' } + } + // No values were written. A form with no array to describe is not a weaker claim than + // usual — it is a claim about nothing, and `order` would be read as authoritative. if (!widgets?.length || !options.serializeWidgets) { - // No values were written. A form with no array to describe is not a weaker claim than - // usual — it is a claim about nothing, and `order` would be read as authoritative. - return refuse('widgets_not_serialized') + return { refusal: 'widgets_not_serialized' } } const values = serialised.widgets_values + // Identity, deliberately, not deep equality. A subclass or extension that rebuilt an + // equal-looking array did so from a source we cannot see, and a coincidental match is not + // evidence. This is the check that catches `SubgraphNode` and the packs that override + // `serialize` to write values after `super` returns. if (producedValues === undefined || values !== producedValues) { - // Identity, deliberately, not deep equality. A subclass or extension that rebuilt an - // equal-looking array did so from a source we cannot see, and a coincidental match is - // not evidence. This is the check that catches `SubgraphNode` and the packs that - // override `serialize` to write values after `super` returns. - return refuse( - Array.isArray(values) ? 'values_replaced' : 'values_not_positional' - ) - } - if (!Array.isArray(values)) return refuse('values_not_positional') - - const serializing = serializingWidgets(widgets) - if (serializing.length !== values.length) { - // Reachable even with an untouched array: a widget mutated its own `serialize` flag - // between the write and this check, or `widgets` was spliced in between. - return refuse('length_mismatch') + return { + refusal: Array.isArray(values) + ? 'values_replaced' + : 'values_not_positional' + } } + if (!Array.isArray(values)) return { refusal: 'values_not_positional' } + return { values } +} +/** + * Phase 2: can every serializing widget's name serve as an address? + */ +function addressableOrder( + serializing: readonly IBaseWidget[] +): { order: string[] } | { refusal: WidgetFormRefusal } { const order: string[] = [] const seen = new Set() for (const widget of serializing) { const name = widget.name - if (typeof name !== 'string' || name.length === 0) - return refuse('unnameable_widget') + if (typeof name !== 'string' || name.length === 0) { + return { refusal: 'unnameable_widget' } + } // `serialiseWidgetValues` builds its named projection with `defineProperty`, so a repeat // silently overwrites the earlier value and the two become one key. An `order` array // would keep both and promise an address for each, but the document rejects the second // (`name#1` is an unknown widget there). Promising an address that does not resolve is // worse than declining to describe the node. - if (seen.has(name)) return refuse('duplicate_widget_name') + if (seen.has(name)) return { refusal: 'duplicate_widget_name' } seen.add(name) order.push(name) } + return { order } +} + +/** + * Prove — or refuse to prove — that `serialised.widgets_values` describes `widgets`. + * + * @param widgets the node's live widget list at serialization time + * @param serialised the node payload as it stands AFTER the extension serialize hook + * @param producedValues the array `serialiseWidgetValues` returned BEFORE the hook ran, or + * `undefined` if it never ran. Identity is the proof: if the post-hook value is not this + * same array, something replaced it and we know nothing about what the replacement means. + * @param options see {@link WidgetFormOptions}. `coreIsLastWriter` is required and is the + * check that keeps this a proof rather than an assumption. + */ +export function proveWidgetForm( + widgets: readonly IBaseWidget[] | undefined, + // `widgets_values` is deliberately `unknown` rather than the serialised-node type's + // `WidgetValue[]`. Every interesting input here VIOLATES that type: an extension replaced + // the array with an object, or deleted it. Typing the parameter as the shape we expect + // would make the shapes we are checking for unrepresentable, and the checks dead. + serialised: { + widgets_values?: unknown + /** Present when the payload was replayed rather than built. */ + has_errors?: boolean + }, + producedValues: unknown, + options: WidgetFormOptions +): WidgetFormProof { + const proven = provenValues(widgets, serialised, producedValues, options) + if ('refusal' in proven) return refuse(proven.refusal) + + const serializing = serializingWidgets(widgets ?? []) + // Reachable even with an untouched array: a widget mutated its own `serialize` flag between + // the write and this check, or `widgets` was spliced in between. + if (serializing.length !== proven.values.length) + return refuse('length_mismatch') + + const addressed = addressableOrder(serializing) + if ('refusal' in addressed) return refuse(addressed.refusal) - return { provable: true, refusal: null, order } + return { provable: true, refusal: null, order: addressed.order } } /** From 3adac83b7b709087d469cbbbfd4aa3539594fb5f Mon Sep 17 00:00:00 2001 From: operator Date: Mon, 26 Oct 2026 18:06:18 -0700 Subject: [PATCH 03/11] refactor(litegraph): split the payload preconditions out of provenValues Two complexity findings from the repo's push gates, both fixed rather than suppressed. provenValues had grown to 11 cyclomatic / 10 cognitive by absorbing the two new whole-payload checks, and they were the wrong concern for it anyway: coreIsLastWriter and replayed ask 'is this payload even a subject for proof', which no inspection of widgets_values could answer, while provenValues asks 'are these our values'. preconditionRefusal now owns the former and runs first. The test file also had a 153-line describe block. Split into three by what each group refuses on -- the values themselves, a payload we did not build, and a disagreement between the widget list and the values. --- .../src/widgets/widgetFormProof.test.ts | 4 ++ .../litegraph/src/widgets/widgetFormProof.ts | 48 ++++++++++++------- 2 files changed, 35 insertions(+), 17 deletions(-) diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.test.ts b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts index 9cbf54dc96c..5374001cac5 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.test.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts @@ -144,7 +144,9 @@ describe('proveWidgetForm', () => { expect(proof.provable).toBe(false) expect(proof.refusal).toBe('values_not_positional') }) + }) + describe('refuses a payload it did not build', () => { it('when the payload was replayed from a previous save', () => { // An unregistered node type is replayed verbatim and never reaches the hook, and its // widgets are synthesised placeholders built FROM the stored values. A form there would @@ -179,7 +181,9 @@ describe('proveWidgetForm', () => { expect(proof.refusal).toBe('replayed_serialization') }) + }) + describe('refuses when the widget list and the values disagree', () => { it('when serialize_widgets is falsy', () => { // `this.serialize_widgets = false` is in the low hundreds of repositories -- rgthree's // group muters, was-node-suite's fast groups, Crystools' debugger. Widgets exist and no diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.ts b/src/lib/litegraph/src/widgets/widgetFormProof.ts index a72c11610ab..da62a857abf 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.ts @@ -122,6 +122,34 @@ function serializingWidgets(widgets: readonly IBaseWidget[]): IBaseWidget[] { * @param options see {@link WidgetFormOptions}. `coreIsLastWriter` is required and is the * check that keeps this a proof rather than an assumption. */ +/** + * Preconditions on the PAYLOAD, before any question about the values themselves. + * + * Both are things no inspection of `widgets_values` could reveal, which is why they have to be + * told to us rather than derived. + */ +function preconditionRefusal( + serialised: { has_errors?: boolean }, + options: WidgetFormOptions +): WidgetFormRefusal | null { + // FIRST, because every later check reasons about a payload it assumes is final. If the node's + // class can still rewrite `widgets_values`, the identity check compares against an array that + // is about to be discarded, and it PASSES -- an acceptance, the one outcome this module exists + // to prevent. Measured on `SubgraphNode`: at the end of `LGraphNode.serializeFromStoreState` + // its values are still core's own array, and only the subclass's override replaces them + // afterwards. The proof accepted, returning an order of two names for a payload that ended up + // holding one value. + if (!options.coreIsLastWriter) return 'class_may_rewrite_payload' + + // A replayed payload carries whatever shape some other frontend wrote, and the widget list + // beside it may be synthesised placeholders: an unregistered node type gets widgets named + // `UNKNOWN`, `UNKNOWN_1`, ... from its stored values. A form built there would be syntactically + // valid, authoritative to every consumer, and meaningless. + if (options.replayed || serialised.has_errors) return 'replayed_serialization' + + return null +} + /** * Phase 1: did core produce these exact values? * @@ -134,23 +162,6 @@ function provenValues( producedValues: unknown, options: WidgetFormOptions ): { values: unknown[] } | { refusal: WidgetFormRefusal } { - // FIRST, because every check below reasons about a payload it assumes is final. If the - // node's class can still rewrite `widgets_values` after this point, the identity check - // further down compares against an array that is about to be discarded, and it PASSES -- - // which is an acceptance, the one outcome this module exists to prevent. Measured on - // `SubgraphNode`: at the end of `LGraphNode.serializeFromStoreState` its values are still - // core's own array, and only the subclass's own override replaces them afterwards. The - // proof accepted, returning an order of two names for a payload that ended up holding one - // value. - if (!options.coreIsLastWriter) return { refusal: 'class_may_rewrite_payload' } - - // A replayed payload carries whatever shape some other frontend wrote, and the widget list - // beside it may be synthesised placeholders: an unregistered node type gets widgets named - // `UNKNOWN`, `UNKNOWN_1`, ... from its stored values. A form built there would be - // syntactically valid, authoritative to every consumer, and meaningless. - if (options.replayed || serialised.has_errors) { - return { refusal: 'replayed_serialization' } - } // No values were written. A form with no array to describe is not a weaker claim than // usual — it is a claim about nothing, and `order` would be read as authoritative. if (!widgets?.length || !options.serializeWidgets) { @@ -223,6 +234,9 @@ export function proveWidgetForm( producedValues: unknown, options: WidgetFormOptions ): WidgetFormProof { + const precondition = preconditionRefusal(serialised, options) + if (precondition !== null) return refuse(precondition) + const proven = provenValues(widgets, serialised, producedValues, options) if ('refusal' in proven) return refuse(proven.refusal) From cc6195e863cdd33ace8d4481793d92254fcfff3f Mon Sep 17 00:00:00 2001 From: operator Date: Thu, 29 Oct 2026 13:32:25 -0700 Subject: [PATCH 04/11] docs(adr): stop claiming test coverage this PR does not have Addresses the review. Three valid findings; two declined with reasons below. The substantive one: the ADR said the KSampler=7 and LoadImage=2 lengths were "pinned as literals" here. They are not. This file pins the RULE on a synthetic two-widget node and never instantiates either class, so those two numbers are measurements of production code, not regression cover. Pinning them against the real widget lists needs the extension constructors and lives in the stacked test PR. Claiming otherwise is the more expensive error, because the whole argument for this module is that it does not assume what it has not checked. Also fixed the ADR's source path -- the predicate moved to widgets/ when the layer-boundary gate rejected node/, and the ADR still pointed at the old path, so a reader following the reference reached a missing file. And replaced the for-loop in the closure test with assertions over the whole collection, per the repo's no-loops-in-tests rule. Declined, with reasons rather than silence: "Remove export from WidgetFormRefusal (knip fails)" -- stale. knip reports no finding for it on this head; the earlier commit that uses the type in a Record keyed by the union cleared it, which also makes a new refusal impossible to add without a case that reaches it. "Delete the explanatory comments" (x2, both marked trivial/low value) -- kept deliberately. Each comment records a MEASURED fact that the code cannot state: why identity and not deep equality, why the options-bag flag still occupies a slot, why a replayed payload's widget names are fabricated. This module exists because the obvious implementation was confidently wrong twice, and the comments are the record of how. Density matches the surrounding litegraph code. --- ...ETS-0023-widget-entities-with-a-legacy-layer.md | 14 ++++++++++---- .../litegraph/src/widgets/widgetFormProof.test.ts | 12 ++++++------ 2 files changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md b/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md index 247d190a463..e0b2cc87061 100644 --- a/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md +++ b/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md @@ -181,7 +181,7 @@ So the rule is not "derive the order from `node.widgets`". It is: > produced from `node.widgets`. Where it cannot prove that, emit nothing.** Deriving is a guess dressed as a declaration; proving is not. `proveWidgetForm` -(`src/lib/litegraph/src/node/widgetFormProof.ts`) is that predicate, and it returns an order +(`src/lib/litegraph/src/widgets/widgetFormProof.ts`) is that predicate, and it returns an order **only** alongside `provable: true` — never a partial order beside a refusal. ### Why deriving does not work, measured @@ -216,9 +216,15 @@ Three predicates look interchangeable and are deliberately different: `addWidget` does not hoist the options-bag flag onto the widget, so a widget flagged only there **does occupy a positional slot.** That is why every `KSampler` serializes 7 values -(`control_after_generate`) and every `LoadImage` serializes 2 (its upload button). A form built -from `options.serialize` is one slot short on both, and both lengths are pinned as literals in -`widgetFormProof.test.ts` so the mistake cannot land twice. +(`control_after_generate`) and every `LoadImage` serializes 2 (its upload button). A form built from `options.serialize` is one slot +short on both. + +`widgetFormProof.test.ts` pins the _rule_ on a synthetic node — a two-widget case where the +second is options-bag-flagged and still occupies a slot. It does **not** instantiate a real +`KSampler` or `LoadImage`, so the 7 and the 2 above are measurements of production code, not +assertions this file makes. Pinning them against the real widget lists needs the extension +constructors and so lives in the stacked test PR; until that lands, treat those two numbers as +evidence for the rule rather than as regression cover for it. ### Refusals, each a measured shape diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.test.ts b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts index 5374001cac5..19858decc10 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.test.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts @@ -300,7 +300,7 @@ describe('proveWidgetForm', () => { const widgets = [widget('dup', { value: 1 }), widget('dup', { value: 2 })] const { values, serialised } = produce(widgets) - for (const proof of [ + const proofs = [ proveWidgetForm(widgets, serialised, values, { serializeWidgets: true, coreIsLastWriter: true @@ -322,11 +322,11 @@ describe('proveWidgetForm', () => { serializeWidgets: true, coreIsLastWriter: true }) - ]) { - expect(proof.provable).toBe(false) - expect(proof.order).toBeNull() - expect(proof.refusal).not.toBeNull() - } + ] + + expect(proofs.map((p) => p.provable)).toEqual(proofs.map(() => false)) + expect(proofs.map((p) => p.order)).toEqual(proofs.map(() => null)) + expect(proofs.filter((p) => p.refusal === null)).toEqual([]) }) }) From 01d923f7b92ca7832aecc971b6ab4845a341b340 Mon Sep 17 00:00:00 2001 From: bymyself Date: Fri, 30 Oct 2026 01:50:45 +0000 Subject: [PATCH 05/11] fix(litegraph): refresh widget form proof checks --- .../src/widgets/widgetFormProof.test.ts | 80 ++++++------------- .../litegraph/src/widgets/widgetFormProof.ts | 17 ++-- 2 files changed, 36 insertions(+), 61 deletions(-) diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.test.ts b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts index 19858decc10..a09a23a8127 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.test.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts @@ -4,29 +4,23 @@ import { needsFormButHasNone, proveWidgetForm } from '@/lib/litegraph/src/widgets/widgetFormProof' -import type { WidgetFormRefusal } from '@/lib/litegraph/src/widgets/widgetFormProof' -import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets' - -/** - * Each case below is a shape measured in the real frontend or in a shipping custom-node pack, - * not a hypothetical. The invariant under test is one-directional and is the whole point: - * - * **either no form, or a form that agrees. Never a form that disagrees.** - * - * A form-carrying node consults no widget catalog, so a wrong form is authoritative and - * cannot be detected downstream. Every `provable: false` assertion here is therefore a - * success, not a limitation. - */ - -function widget(name: string, extra: Partial = {}): IBaseWidget { - return { name, type: 'number', value: 0, ...extra } as IBaseWidget +interface TestWidget { + name: string + type: string + value: unknown + serialize?: boolean + options?: { serialize?: boolean } +} + +function widget(name: string, extra: Partial = {}): TestWidget { + return { name, type: 'number', value: 0, ...extra } } /** Serialize the way `serialiseWidgetValues` does, and hand back the array identity. */ -function produce(widgets: IBaseWidget[]) { +function produce(widgets: TestWidget[]) { const values = widgets .filter((w) => w.serialize !== false) - .map((w) => w.value as unknown) + .map((w) => w.value) return { values, serialised: { widgets_values: values } } } @@ -324,9 +318,19 @@ describe('proveWidgetForm', () => { }) ] - expect(proofs.map((p) => p.provable)).toEqual(proofs.map(() => false)) - expect(proofs.map((p) => p.order)).toEqual(proofs.map(() => null)) - expect(proofs.filter((p) => p.refusal === null)).toEqual([]) + expect( + proofs.map(({ provable, order, refusal }) => ({ + provable, + order, + refusal + })) + ).toEqual([ + { provable: false, order: null, refusal: 'duplicate_widget_name' }, + { provable: false, order: null, refusal: 'replayed_serialization' }, + { provable: false, order: null, refusal: 'values_not_positional' }, + { provable: false, order: null, refusal: 'widgets_not_serialized' }, + { provable: false, order: null, refusal: 'widgets_not_serialized' } + ]) }) }) @@ -355,37 +359,3 @@ describe('needsFormButHasNone', () => { expect(needsFormButHasNone({ widgets_values: null })).toBe(false) }) }) - -describe('the refusal set', () => { - it('is covered case-for-case by the tests above', () => { - // Pins the union so a new refusal cannot be added without a test that reaches it, and a - // retired one cannot linger. Each entry below is asserted by a named case above; this - // list is the index, not a second source of truth. - const exercised: Record = { - class_may_rewrite_payload: true, - replayed_serialization: true, - widgets_not_serialized: true, - values_replaced: true, - values_not_positional: true, - length_mismatch: true, - duplicate_widget_name: true, - unnameable_widget: true - } - - // arrayContaining plus toHaveLength, per the repo's prefer-array-containing rule: the - // length is what makes this a closed set, so a new refusal added without a case here fails. - expect(Object.keys(exercised)).toEqual( - expect.arrayContaining([ - 'class_may_rewrite_payload', - 'replayed_serialization', - 'widgets_not_serialized', - 'values_replaced', - 'values_not_positional', - 'length_mismatch', - 'duplicate_widget_name', - 'unnameable_widget' - ]) - ) - expect(Object.keys(exercised)).toHaveLength(8) - }) -}) diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.ts b/src/lib/litegraph/src/widgets/widgetFormProof.ts index da62a857abf..cca31ea4957 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.ts @@ -1,4 +1,7 @@ -import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets' +interface WidgetForFormProof { + name: string + serialize?: boolean +} /** * Whether a node's serialized widget values can be *proven* to describe its own widget list. @@ -28,7 +31,7 @@ import type { IBaseWidget } from '@/lib/litegraph/src/types/widgets' */ /** Why a node's widget values could not be proven. `null` reason means they were. */ -export type WidgetFormRefusal = +type WidgetFormRefusal = /** * The node's class can still rewrite the payload after this point, so whatever we are * looking at is not final and proving anything about it would be premature. @@ -107,7 +110,9 @@ function refuse(refusal: WidgetFormRefusal): WidgetFormProof { * every `LoadImage` serializes 2 (the upload button is too). Reading `options.serialize` here * would silently drop both and produce a form one slot short. */ -function serializingWidgets(widgets: readonly IBaseWidget[]): IBaseWidget[] { +function serializingWidgets( + widgets: readonly WidgetForFormProof[] +): WidgetForFormProof[] { return widgets.filter((widget) => widget.serialize !== false) } @@ -157,7 +162,7 @@ function preconditionRefusal( * that reasons about provenance; everything after it reasons about names. */ function provenValues( - widgets: readonly IBaseWidget[] | undefined, + widgets: readonly WidgetForFormProof[] | undefined, serialised: { widgets_values?: unknown; has_errors?: boolean }, producedValues: unknown, options: WidgetFormOptions @@ -188,7 +193,7 @@ function provenValues( * Phase 2: can every serializing widget's name serve as an address? */ function addressableOrder( - serializing: readonly IBaseWidget[] + serializing: readonly WidgetForFormProof[] ): { order: string[] } | { refusal: WidgetFormRefusal } { const order: string[] = [] const seen = new Set() @@ -221,7 +226,7 @@ function addressableOrder( * check that keeps this a proof rather than an assumption. */ export function proveWidgetForm( - widgets: readonly IBaseWidget[] | undefined, + widgets: readonly WidgetForFormProof[] | undefined, // `widgets_values` is deliberately `unknown` rather than the serialised-node type's // `WidgetValue[]`. Every interesting input here VIOLATES that type: an extension replaced // the array with an object, or deleted it. Typing the parameter as the shape we expect From aa73dffdf465e599e552859d0b9a275fdadae2e5 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 30 Oct 2026 06:33:29 -0700 Subject: [PATCH 06/11] refactor(litegraph): strip the rationale out of the code and into the ADR Addresses the review findings on #22007 that survive at head 01d923f7b9. Comments. The repo rule (docs/guidance/engineering.md, AGENTS.md #6) allows only curt JSDoc on an exported API and treats every other added comment as a blocking finding. Both files carried a module essay, multi-paragraph JSDoc on private helpers, and inline rationale throughout; one JSDoc block was also duplicated verbatim onto the wrong function. All of it is gone, and the reasoning it carried now lives in the ADR amendment, which is where a reader looking for the design will go anyway. values_missing. An absent widgets_values was reported as values_not_positional, a reason defined for object-shaped values, so the refusal sent a reader to the wrong problem. It gets its own reason, asserted in the deleted-values case and in the collected invariant test. The flag trap is now pinned against production. The flag cases built their own copy of `widget.serialize !== false`, so they could not notice production changing, and the options-bag case never went through addWidget. They now build an LGraphNode in a graph, add widgets through addWidget, and read node.serialize(). Measured: addWidget leaves widget.serialize undefined with options.serialize false, and the widget still occupies a positional slot, so widgets_values is [1, 'randomize'] for the two-widget case. coreIsLastWriter is computed from the documented prototype comparison rather than hardcoded. These live in LGraphNode.widgetFormProof.test.ts because importing LGraphNode is what the node-widgets -> litegraph-api boundary forbids; the widgets/ test keeps the pure-predicate cases and stays inside it. What the proof does not guarantee is now stated. Array identity does not prove contents: a hook can reorder node.widgets or mutate the produced array in place while preserving identity and length. The ADR says so, and says a producer must close it before calling this. The ADR no longer claims nothing emits a form. docOpMinter.wireNodeSnapshot already attaches widgets_values_form from provenWidgetValuesForm; the claim is scoped to proveWidgetForm and that producer is named, so the follow-up is reconciling the two rather than writing a first one. --- ...023-widget-entities-with-a-legacy-layer.md | 66 +++++-- .../src/LGraphNode.widgetFormProof.test.ts | 90 ++++++++++ .../src/widgets/widgetFormProof.test.ts | 96 ++-------- .../litegraph/src/widgets/widgetFormProof.ts | 165 ++---------------- 4 files changed, 173 insertions(+), 244 deletions(-) create mode 100644 src/lib/litegraph/src/LGraphNode.widgetFormProof.test.ts diff --git a/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md b/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md index e0b2cc87061..4b574e85934 100644 --- a/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md +++ b/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md @@ -219,25 +219,57 @@ Three predicates look interchangeable and are deliberately different: (`control_after_generate`) and every `LoadImage` serializes 2 (its upload button). A form built from `options.serialize` is one slot short on both. -`widgetFormProof.test.ts` pins the _rule_ on a synthetic node — a two-widget case where the -second is options-bag-flagged and still occupies a slot. It does **not** instantiate a real -`KSampler` or `LoadImage`, so the 7 and the 2 above are measurements of production code, not -assertions this file makes. Pinning them against the real widget lists needs the extension -constructors and so lives in the stacked test PR; until that lands, treat those two numbers as -evidence for the rule rather than as regression cover for it. +`LGraphNode.widgetFormProof.test.ts` pins the _rule_ against the real serializer: the flag cases +build an `LGraphNode` in a graph, add widgets through `addWidget`, and read `node.serialize()`, so +the assertion is on production's own `widgets_values` rather than on a filter the test duplicates. +Measured there: `addWidget('combo', …, { serialize: false, values: [...] })` leaves +`widget.serialize` `undefined` with `widget.options.serialize === false`, and the widget still +occupies a slot. It lives beside `LGraphNode` rather than in `widgets/` because importing +`LGraphNode` is what the `node-widgets` → `litegraph-api` boundary below forbids; +`widgetFormProof.test.ts` keeps the pure-predicate cases and stays inside that boundary. + +It does **not** instantiate a real `KSampler` or `LoadImage`, so the 7 and the 2 above remain +measurements of production code rather than assertions this file makes. Pinning them against the +real widget lists needs the extension constructors and so lives in the stacked test PR; until +that lands, treat those two numbers as evidence for the rule rather than as regression cover for +it. ### Refusals, each a measured shape -`replayed_serialization` · `widgets_not_serialized` · `values_replaced` · -`values_not_positional` · `length_mismatch` · `duplicate_widget_name` · `unnameable_widget` +`class_may_rewrite_payload` · `replayed_serialization` · `widgets_not_serialized` · +`values_missing` · `values_replaced` · `values_not_positional` · `length_mismatch` · +`duplicate_widget_name` · `unnameable_widget` -Two are worth calling out. **`replayed_serialization`** covers an unregistered node type, whose +Four are worth calling out. **`replayed_serialization`** covers an unregistered node type, whose payload is replayed verbatim and never reaches the hook, and whose widgets are _synthesised from the stored values_ with names `UNKNOWN`, `UNKNOWN_1`, … A form there would be syntactically valid, authoritative, and meaningless, so it is refused before any other check can accept it. **`duplicate_widget_name`** covers two serializing widgets sharing a name: the named projection collapses them via `defineProperty`, and the document rejects the second address outright, so -listing both would promise an address that does not resolve. +listing both would promise an address that does not resolve. Measured in the corpus: `RecordAudio` +stores 2 values under 1 name and `LoadAudio` 3 under 2. + +**`values_missing`** and **`values_replaced`** are deliberately distinct, because they send a +reader to different problems. `values_missing` is an absent `widgets_values` — the +`delete serialized.widgets_values` branch a `SubgraphNode` takes when every promoted store value +is `undefined`. `values_replaced` is an array core did not produce, which is the shape a pack's +own `serialize` override leaves behind. `values_not_positional` is reserved for an +object-shaped payload: the VHS family's `onSerialize` writes a dict keyed by every widget name, +including widgets flagged `serialize === false`, so its keys and any derived order disagree. +`widgets_not_serialized` covers `this.serialize_widgets = false`, which rgthree's group muters, +was-node-suite's fast groups and Crystools' debugger all set. + +### What the proof does not guarantee + +Array identity proves the payload is still core's own array. It does not prove the array's +_contents_ were untouched: a serialize hook can reorder `node.widgets`, or mutate the produced +array in place, while preserving both identity and length. `proveWidgetForm` would then report +`provable: true` with an order that does not match the values. + +That is a known limit, not an oversight, and it is why nothing calls this predicate yet. A +producer must close it first — by snapshotting the pre-hook order, or by validating contents +rather than identity — and that belongs in the change that adds the producer, where the pre-hook +state is in scope. ### The call site is part of the rule, not an implementation detail @@ -276,5 +308,15 @@ out loud, because it is the cheapest wrong fix available. This amendment adds the predicate and a diagnostic (`needsFormButHasNone`, which identifies object-shaped values with no form — the population a form would rescue and that nothing can -currently count). **Nothing emits a form yet.** The producer is deliberately a later change, so -the predicate can be landed, measured against the custom-node ecosystem, and trusted first. +currently count). **Nothing emits a form through `proveWidgetForm` yet.** The producer is +deliberately a later change, so the predicate can be landed, measured against the custom-node +ecosystem, and trusted first. + +That is narrower than "no form is emitted anywhere", and the difference matters to whoever wires +this up. The Agent wire already declares forms on its own `add_node` path: +`docOpMinter.wireNodeSnapshot` attaches `widgets_values_form` from +`provenWidgetValuesForm` (`src/workbench/extensions/agent/crdt/widgetValuesForm.ts`, per +[ADR-WIDGET-SERIALIZATION-0047](WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md)). +That producer reads the post-hook payload and reaches the same conclusion by a different route; +reconciling the two, so core serialization and the Agent wire share one predicate, is the +follow-up this amendment makes possible rather than something it does. diff --git a/src/lib/litegraph/src/LGraphNode.widgetFormProof.test.ts b/src/lib/litegraph/src/LGraphNode.widgetFormProof.test.ts new file mode 100644 index 00000000000..726718d4d29 --- /dev/null +++ b/src/lib/litegraph/src/LGraphNode.widgetFormProof.test.ts @@ -0,0 +1,90 @@ +import { describe, expect, it } from 'vitest' + +import { LGraph, LGraphNode } from '@/lib/litegraph/src/litegraph' +import { proveWidgetForm } from '@/lib/litegraph/src/widgets/widgetFormProof' + +function nodeInGraph(): LGraphNode { + const graph = new LGraph() + const node = new LGraphNode('test') + node.serialize_widgets = true + graph.add(node) + return node +} + +function coreIsLastWriter(node: LGraphNode): boolean { + return ( + node.serialize === LGraphNode.prototype.serialize && + node.serializeFromStoreState === + LGraphNode.prototype.serializeFromStoreState + ) +} + +function proveRealSerialization(node: LGraphNode) { + const serialised = node.serialize() + return { + serialised, + proof: proveWidgetForm( + node.widgets, + serialised, + serialised.widgets_values, + { + serializeWidgets: node.serialize_widgets, + coreIsLastWriter: coreIsLastWriter(node) + } + ) + } +} + +describe('proveWidgetForm, driven through LGraphNode.serialize', () => { + it('counts a widget flagged only in its options bag, because widgets_values does', () => { + const node = nodeInGraph() + node.addWidget('number', 'seed', 1, () => undefined, {}) + const optionsBagFlagged = node.addWidget( + 'combo', + 'control_after_generate', + 'randomize', + () => undefined, + { serialize: false, values: ['randomize', 'fixed'] } + ) + + expect(optionsBagFlagged.options.serialize).toBe(false) + expect(optionsBagFlagged.serialize).toBeUndefined() + + const { serialised, proof } = proveRealSerialization(node) + + expect(serialised.widgets_values).toEqual([1, 'randomize']) + expect(proof.provable).toBe(true) + expect(proof.order).toEqual(['seed', 'control_after_generate']) + expect(proof.refusal).toBeNull() + }) + + it('excludes a widget flagged on the widget itself, because widgets_values does too', () => { + const node = nodeInGraph() + node.addWidget('text', 'audio', 'clip.mp3', () => undefined, {}) + const widgetFlagged = node.addWidget( + 'button', + 'audioUI', + '', + () => undefined, + {} + ) + widgetFlagged.serialize = false + + const { serialised, proof } = proveRealSerialization(node) + + expect(serialised.widgets_values).toEqual(['clip.mp3']) + expect(proof.provable).toBe(true) + expect(proof.order).toEqual(['audio']) + }) + + it('refuses a node whose serialize_widgets flag is off', () => { + const node = nodeInGraph() + node.addWidget('number', 'mode', 1, () => undefined, {}) + node.serialize_widgets = false + + const { proof } = proveRealSerialization(node) + + expect(proof.provable).toBe(false) + expect(proof.refusal).toBe('widgets_not_serialized') + }) +}) diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.test.ts b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts index a09a23a8127..ab08ab6dc72 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.test.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts @@ -4,19 +4,18 @@ import { needsFormButHasNone, proveWidgetForm } from '@/lib/litegraph/src/widgets/widgetFormProof' + interface TestWidget { name: string type: string value: unknown serialize?: boolean - options?: { serialize?: boolean } } function widget(name: string, extra: Partial = {}): TestWidget { return { name, type: 'number', value: 0, ...extra } } -/** Serialize the way `serialiseWidgetValues` does, and hand back the array identity. */ function produce(widgets: TestWidget[]) { const values = widgets .filter((w) => w.serialize !== false) @@ -42,56 +41,11 @@ describe('proveWidgetForm', () => { expect(proof.refusal).toBeNull() }) - it('counts a widget flagged only in its options bag, because widgets_values does', () => { - // The trap that would have shipped a wrong form. `options.serialize === false` excludes a - // widget from the API prompt but NOT from widgets_values, and `addWidget` does not hoist - // the flag. Reading the options bag here yields an order one slot short of the values. - // Measured: every KSampler serializes 7 values because `control_after_generate` is - // options-bag-only, and every LoadImage serializes 2 because its upload button is. - const widgets = [ - widget('seed', { value: 1 }), - widget('control_after_generate', { - value: 'randomize', - options: { serialize: false } - }) - ] - const { values, serialised } = produce(widgets) - - expect(values).toHaveLength(2) - const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true, - coreIsLastWriter: true - }) - - expect(proof.provable).toBe(true) - expect(proof.order).toEqual(['seed', 'control_after_generate']) - }) - - it('excludes a widget flagged on the widget itself, because widgets_values does too', () => { - const widgets = [ - widget('audio', { value: 'clip.mp3' }), - widget('audioUI', { serialize: false }) - ] - const { values, serialised } = produce(widgets) - - const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true, - coreIsLastWriter: true - }) - - expect(proof.provable).toBe(true) - expect(proof.order).toEqual(['audio']) - }) - describe('refuses rather than guessing', () => { - it('when a subclass or extension replaced the array after we wrote it', () => { - // SubgraphNode.serializeFromStoreState calls super -- hook included -- and then - // rebuilds widgets_values from `inputs` filtered to those carrying a widgetId. That is - // a different collection from node.widgets, so an order derived from node.widgets - // describes the wrong thing. Identity, not deep equality, is what catches it. + it('when a subclass or extension replaced the array with an equal-looking one', () => { const widgets = [widget('a', { value: 1 }), widget('b', { value: 2 })] const { values } = produce(widgets) - const replaced = { widgets_values: [1, 2] } // equal-looking, different array + const replaced = { widgets_values: [1, 2] } const proof = proveWidgetForm(widgets, replaced, values, { serializeWidgets: true, @@ -104,8 +58,6 @@ describe('proveWidgetForm', () => { }) it('when a subgraph deleted the values entirely', () => { - // The `delete serialized.widgets_values` branch, taken when every promoted store value - // is undefined. A non-empty order beside no values would promise addresses for nothing. const widgets = [widget('promoted_a'), widget('promoted_b')] const { values } = produce(widgets) @@ -115,12 +67,11 @@ describe('proveWidgetForm', () => { }) expect(proof.provable).toBe(false) + expect(proof.refusal).toBe('values_missing') expect(proof.order).toBeNull() }) - it('when an extension replaced the array with an object', () => { - // The VHS family: onSerialize sets widgets_values to a dict keyed by every widget name, - // including ones flagged serialize === false, so the keys and any derived order differ. + it('when an extension replaced the array with a name-keyed object', () => { const widgets = [ widget('video', { value: 'clip.mp4' }), widget('vhslatentpreview', { serialize: false }) @@ -142,9 +93,6 @@ describe('proveWidgetForm', () => { describe('refuses a payload it did not build', () => { it('when the payload was replayed from a previous save', () => { - // An unregistered node type is replayed verbatim and never reaches the hook, and its - // widgets are synthesised placeholders built FROM the stored values. A form there would - // read order: ['UNKNOWN', 'UNKNOWN_1'] -- valid, authoritative, meaningless. const widgets = [ widget('UNKNOWN', { value: 1 }), widget('UNKNOWN_1', { value: 2 }) @@ -179,9 +127,6 @@ describe('proveWidgetForm', () => { describe('refuses when the widget list and the values disagree', () => { it('when serialize_widgets is falsy', () => { - // `this.serialize_widgets = false` is in the low hundreds of repositories -- rgthree's - // group muters, was-node-suite's fast groups, Crystools' debugger. Widgets exist and no - // values are written. const widgets = [widget('mode'), widget('filter')] const proof = proveWidgetForm(widgets, {}, undefined, { @@ -196,7 +141,7 @@ describe('proveWidgetForm', () => { it('when the widget list was spliced after the values were written', () => { const widgets = [widget('a', { value: 1 }), widget('b', { value: 2 })] const { values, serialised } = produce(widgets) - widgets.pop() // a pack truncating node.widgets mid-serialize + widgets.pop() const proof = proveWidgetForm(widgets, serialised, values, { serializeWidgets: true, @@ -208,10 +153,6 @@ describe('proveWidgetForm', () => { }) it('when two serializing widgets share a name', () => { - // Measured in the corpus: RecordAudio stores 2 values under 1 name, LoadAudio 3 under - // 2. `serialiseWidgetValues` collapses them via defineProperty, and the document - // rejects the second address outright, so an order listing both promises an address - // that does not resolve. const widgets = [ widget('audio', { value: 'a' }), widget('audio', { value: 'b' }) @@ -242,13 +183,6 @@ describe('proveWidgetForm', () => { }) it('refuses a node whose class can still rewrite the payload', () => { - // The defect found by driving the proof through the real serialize path: at the end of - // LGraphNode.serializeFromStoreState a SubgraphNode's widgets_values is STILL core's own - // array -- the subclass replaces it afterwards -- so the identity check passed and the - // proof accepted, returning an order of two names for a payload that ended up holding - // one value. Everything about the values looks right here; only the knowledge that - // something downstream will rewrite them makes it wrong, which is why this cannot be - // inferred from the payload and has to be told to us. const widgets = [ widget('promoted_a', { value: 1 }), widget('promoted_b', { value: 2 }) @@ -259,7 +193,7 @@ describe('proveWidgetForm', () => { serializeWidgets: true, coreIsLastWriter: true }) - expect(accepted.provable).toBe(true) // identical input, and this is the trap + expect(accepted.provable).toBe(true) const proof = proveWidgetForm(widgets, serialised, values, { serializeWidgets: true, @@ -271,10 +205,7 @@ describe('proveWidgetForm', () => { expect(proof.order).toBeNull() }) - it('checks the last writer before anything else', () => { - // Ordering matters: a non-final payload makes every later check moot, so this refusal must - // win even when another one would also apply. Otherwise the reported reason sends a reader - // to the wrong problem. + it('checks the last writer before any other refusal that also applies', () => { const widgets = [widget('dup', { value: 1 }), widget('dup', { value: 2 })] const { values, serialised } = produce(widgets) @@ -288,9 +219,6 @@ describe('proveWidgetForm', () => { }) it('never returns an order alongside a refusal', () => { - // The one-directional invariant, asserted directly: no refusal path may leak a partial - // order, because a caller that reads `order` without checking `provable` would then emit - // a wrong form -- the exact outcome this module prevents. const widgets = [widget('dup', { value: 1 }), widget('dup', { value: 2 })] const { values, serialised } = produce(widgets) @@ -308,6 +236,10 @@ describe('proveWidgetForm', () => { serializeWidgets: true, coreIsLastWriter: true }), + proveWidgetForm(widgets, {}, values, { + serializeWidgets: true, + coreIsLastWriter: true + }), proveWidgetForm(widgets, {}, undefined, { serializeWidgets: false, coreIsLastWriter: true @@ -328,6 +260,7 @@ describe('proveWidgetForm', () => { { provable: false, order: null, refusal: 'duplicate_widget_name' }, { provable: false, order: null, refusal: 'replayed_serialization' }, { provable: false, order: null, refusal: 'values_not_positional' }, + { provable: false, order: null, refusal: 'values_missing' }, { provable: false, order: null, refusal: 'widgets_not_serialized' }, { provable: false, order: null, refusal: 'widgets_not_serialized' } ]) @@ -336,9 +269,6 @@ describe('proveWidgetForm', () => { describe('needsFormButHasNone', () => { it('flags an object-shaped payload with no form', () => { - // This is the population a form would rescue and that nothing can currently count: stored - // whole and opaquely, round-trips but is not name-addressable, and the follower drops it - // because it only accepts an array. expect(needsFormButHasNone({ widgets_values: { video: 'clip.mp4' } })).toBe( true ) diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.ts b/src/lib/litegraph/src/widgets/widgetFormProof.ts index cca31ea4957..baad9e32b04 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.ts @@ -3,94 +3,36 @@ interface WidgetForFormProof { serialize?: boolean } -/** - * Whether a node's serialized widget values can be *proven* to describe its own widget list. - * - * This is the gate for emitting `widgets_values_form` — a per-node declaration of which - * widgets serialize and in what order. A node carrying a form is addressed through that form - * and consults no widget catalog on any leg, so **a wrong form is authoritative**: it would - * silently misplace values with no mismatch anywhere to detect it. A node with no form keeps - * today's catalog behaviour, which is merely imperfect. So the asymmetry is total, and the - * rule follows from it: - * - * **Emit only where we can prove the final `widgets_values` is the array we produced from - * `node.widgets`. Otherwise do not emit.** - * - * Two things are wrong with the naive version — "derive the order from `node.widgets` after - * the extension serialize hook". The order must be proven rather than derived, AND that call - * site is not the last writer, so being handed a payload there proves nothing. Both are - * measurable. `node.widgets` is a public JavaScript API - * that extensions splice, truncate, reorder and replace wholesale (see ADR-ECS-WIDGETS-0023), - * and `LGraphNode.serialize` is not the last writer: `SubgraphNode.serializeFromStoreState` - * calls `super` — hook included — and then rebuilds `widgets_values` from a different - * collection entirely. Deriving an order is a guess dressed as a declaration. Proving one is - * not. - * - * Nothing here emits a form. This is the predicate and the diagnosis only, so it can be - * landed, measured and trusted before any producer depends on it. - */ - -/** Why a node's widget values could not be proven. `null` reason means they were. */ type WidgetFormRefusal = - /** - * The node's class can still rewrite the payload after this point, so whatever we are - * looking at is not final and proving anything about it would be premature. - */ | 'class_may_rewrite_payload' - /** Replayed verbatim from a previous save; this process never built these values. */ | 'replayed_serialization' - /** `serialize_widgets` is falsy: widgets exist, values were never written. */ | 'widgets_not_serialized' - /** Values are not the array we produced — an extension or subclass replaced them. */ + | 'values_missing' | 'values_replaced' - /** Values are an object; shape is the producer's own, not a positional array. */ | 'values_not_positional' - /** Length disagrees with the serializable widget list. */ | 'length_mismatch' - /** Two serializing widgets share a name, so a name-keyed order cannot address both. */ | 'duplicate_widget_name' - /** A widget's name is absent or not a string, so it cannot be an address. */ | 'unnameable_widget' +/** Options for {@link proveWidgetForm}. See ADR-ECS-WIDGETS-0023. */ export interface WidgetFormOptions { /** The node's `serialize_widgets` flag. */ serializeWidgets?: boolean /** True when the payload was replayed from a previous save rather than built here. */ replayed?: boolean /** - * Whether core is the LAST thing that will write `widgets_values` for this node. - * - * Required, deliberately, with no default. The previous version of this module documented a - * call site ("after the extension serialize hook") and assumed it was final, which is false - * for any class that overrides serialization — `SubgraphNode` rewrites the values after - * `super` returns, and packs override `serialize` to do the same. Assuming it is how the - * proof came to accept a subgraph host. - * - * The only correct value is a comparison against the base implementation, made by the - * caller because that is where both sides are in scope: - * - * ```ts - * coreIsLastWriter: - * node.serializeFromStoreState === LGraphNode.prototype.serializeFromStoreState && - * node.serialize === LGraphNode.prototype.serialize - * ``` - * - * It is a required field rather than a derived one so that a new call site cannot omit the - * question: `tsc` refuses until it has been answered. Passing a hardcoded `true` to silence - * it reintroduces exactly the defect above. + * Whether core is the last thing that will write `widgets_values` for this node: + * `node.serializeFromStoreState === LGraphNode.prototype.serializeFromStoreState && + * node.serialize === LGraphNode.prototype.serialize`. Required with no default so a new + * call site cannot omit the question; a hardcoded `true` reintroduces the defect. */ coreIsLastWriter: boolean } +/** The verdict from {@link proveWidgetForm}. `order` is present only when `provable`. */ export interface WidgetFormProof { - /** True only when every check below passed. Emit a form if and only if this is true. */ provable: boolean - /** Set when `provable` is false. */ refusal: WidgetFormRefusal | null - /** - * The order, present only when `provable`. Never returned alongside a refusal — a partial - * order is the failure mode this module exists to prevent. - */ order: string[] | null } @@ -98,86 +40,33 @@ function refuse(refusal: WidgetFormRefusal): WidgetFormProof { return { provable: false, refusal, order: null } } -/** - * The widgets that contribute a positional value, in order. - * - * `widget.serialize === false` is the ONLY predicate that governs `widgets_values`, and that - * is easy to get wrong because two other spellings look interchangeable: - * `widget.options.serialize === false` excludes a widget from the API prompt but NOT from - * `widgets_values`, and promotion checks either. `addWidget` does not hoist the options-bag - * flag onto the widget, so widgets flagged only there DO occupy positional slots — which is - * why every `KSampler` serializes 7 values (`control_after_generate` is options-bag-only) and - * every `LoadImage` serializes 2 (the upload button is too). Reading `options.serialize` here - * would silently drop both and produce a form one slot short. - */ function serializingWidgets( widgets: readonly WidgetForFormProof[] ): WidgetForFormProof[] { return widgets.filter((widget) => widget.serialize !== false) } -/** - * Prove — or refuse to prove — that `serialised.widgets_values` describes `widgets`. - * - * @param widgets the node's live widget list at serialization time - * @param serialised the node payload as it stands AFTER the extension serialize hook - * @param producedValues the array `serialiseWidgetValues` returned BEFORE the hook ran, or - * `undefined` if it never ran. Identity is the proof: if the post-hook value is not this - * same array, something replaced it and we know nothing about what the replacement means. - * @param options see {@link WidgetFormOptions}. `coreIsLastWriter` is required and is the - * check that keeps this a proof rather than an assumption. - */ -/** - * Preconditions on the PAYLOAD, before any question about the values themselves. - * - * Both are things no inspection of `widgets_values` could reveal, which is why they have to be - * told to us rather than derived. - */ function preconditionRefusal( serialised: { has_errors?: boolean }, options: WidgetFormOptions ): WidgetFormRefusal | null { - // FIRST, because every later check reasons about a payload it assumes is final. If the node's - // class can still rewrite `widgets_values`, the identity check compares against an array that - // is about to be discarded, and it PASSES -- an acceptance, the one outcome this module exists - // to prevent. Measured on `SubgraphNode`: at the end of `LGraphNode.serializeFromStoreState` - // its values are still core's own array, and only the subclass's override replaces them - // afterwards. The proof accepted, returning an order of two names for a payload that ended up - // holding one value. if (!options.coreIsLastWriter) return 'class_may_rewrite_payload' - - // A replayed payload carries whatever shape some other frontend wrote, and the widget list - // beside it may be synthesised placeholders: an unregistered node type gets widgets named - // `UNKNOWN`, `UNKNOWN_1`, ... from its stored values. A form built there would be syntactically - // valid, authoritative to every consumer, and meaningless. if (options.replayed || serialised.has_errors) return 'replayed_serialization' - return null } -/** - * Phase 1: did core produce these exact values? - * - * Returns the array when yes, or the refusal when no. Split out because it is the only part - * that reasons about provenance; everything after it reasons about names. - */ function provenValues( widgets: readonly WidgetForFormProof[] | undefined, serialised: { widgets_values?: unknown; has_errors?: boolean }, producedValues: unknown, options: WidgetFormOptions ): { values: unknown[] } | { refusal: WidgetFormRefusal } { - // No values were written. A form with no array to describe is not a weaker claim than - // usual — it is a claim about nothing, and `order` would be read as authoritative. if (!widgets?.length || !options.serializeWidgets) { return { refusal: 'widgets_not_serialized' } } const values = serialised.widgets_values - // Identity, deliberately, not deep equality. A subclass or extension that rebuilt an - // equal-looking array did so from a source we cannot see, and a coincidental match is not - // evidence. This is the check that catches `SubgraphNode` and the packs that override - // `serialize` to write values after `super` returns. + if (values === undefined) return { refusal: 'values_missing' } if (producedValues === undefined || values !== producedValues) { return { refusal: Array.isArray(values) @@ -189,9 +78,6 @@ function provenValues( return { values } } -/** - * Phase 2: can every serializing widget's name serve as an address? - */ function addressableOrder( serializing: readonly WidgetForFormProof[] ): { order: string[] } | { refusal: WidgetFormRefusal } { @@ -202,11 +88,6 @@ function addressableOrder( if (typeof name !== 'string' || name.length === 0) { return { refusal: 'unnameable_widget' } } - // `serialiseWidgetValues` builds its named projection with `defineProperty`, so a repeat - // silently overwrites the earlier value and the two become one key. An `order` array - // would keep both and promise an address for each, but the document rejects the second - // (`name#1` is an unknown widget there). Promising an address that does not resolve is - // worse than declining to describe the node. if (seen.has(name)) return { refusal: 'duplicate_widget_name' } seen.add(name) order.push(name) @@ -215,25 +96,19 @@ function addressableOrder( } /** - * Prove — or refuse to prove — that `serialised.widgets_values` describes `widgets`. + * Prove — or refuse to prove — that `serialised.widgets_values` describes `widgets`, and so + * whether a `widgets_values_form` may be emitted for this node. See ADR-ECS-WIDGETS-0023. * * @param widgets the node's live widget list at serialization time - * @param serialised the node payload as it stands AFTER the extension serialize hook - * @param producedValues the array `serialiseWidgetValues` returned BEFORE the hook ran, or - * `undefined` if it never ran. Identity is the proof: if the post-hook value is not this - * same array, something replaced it and we know nothing about what the replacement means. - * @param options see {@link WidgetFormOptions}. `coreIsLastWriter` is required and is the - * check that keeps this a proof rather than an assumption. + * @param serialised the node payload as it stands after the extension serialize hook + * @param producedValues the array `serialiseWidgetValues` returned before the hook ran, or + * `undefined` if it never ran; array identity against it is the proof + * @param options see {@link WidgetFormOptions} */ export function proveWidgetForm( widgets: readonly WidgetForFormProof[] | undefined, - // `widgets_values` is deliberately `unknown` rather than the serialised-node type's - // `WidgetValue[]`. Every interesting input here VIOLATES that type: an extension replaced - // the array with an object, or deleted it. Typing the parameter as the shape we expect - // would make the shapes we are checking for unrepresentable, and the checks dead. serialised: { widgets_values?: unknown - /** Present when the payload was replayed rather than built. */ has_errors?: boolean }, producedValues: unknown, @@ -246,8 +121,6 @@ export function proveWidgetForm( if ('refusal' in proven) return refuse(proven.refusal) const serializing = serializingWidgets(widgets ?? []) - // Reachable even with an untouched array: a widget mutated its own `serialize` flag between - // the write and this check, or `widgets` was spliced in between. if (serializing.length !== proven.values.length) return refuse('length_mismatch') @@ -258,14 +131,8 @@ export function proveWidgetForm( } /** - * True when a node's values are object-shaped with no form to interpret them. - * - * This is the population that cannot be read back today: an object-shaped `widgets_values` is - * stored whole and opaquely, so it round-trips but is not name-addressable, and the follower - * drops it outright because it only accepts an array. Those nodes are exactly the ones a form - * would rescue, and there is currently no way to count them — which is why the gap has stayed - * invisible and unowned. Report it and the question "which classes still need this?" becomes a - * number instead of an argument. + * True when a node's values are object-shaped with no form to interpret them — the population + * a form would rescue, and which nothing can currently count. */ export function needsFormButHasNone(serialised: { widgets_values?: unknown From 6ad64a78b4875a45943ed1114566c26464923553 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 30 Oct 2026 08:08:43 -0700 Subject: [PATCH 07/11] docs(litegraph): keep widget proof contracts concise --- .../litegraph/src/widgets/widgetFormProof.ts | 23 +++---------------- 1 file changed, 3 insertions(+), 20 deletions(-) diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.ts b/src/lib/litegraph/src/widgets/widgetFormProof.ts index baad9e32b04..7efb59ce10c 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.ts @@ -20,12 +20,7 @@ export interface WidgetFormOptions { serializeWidgets?: boolean /** True when the payload was replayed from a previous save rather than built here. */ replayed?: boolean - /** - * Whether core is the last thing that will write `widgets_values` for this node: - * `node.serializeFromStoreState === LGraphNode.prototype.serializeFromStoreState && - * node.serialize === LGraphNode.prototype.serialize`. Required with no default so a new - * call site cannot omit the question; a hardcoded `true` reintroduces the defect. - */ + /** True when the node uses core's base serialization implementations. */ coreIsLastWriter: boolean } @@ -95,16 +90,7 @@ function addressableOrder( return { order } } -/** - * Prove — or refuse to prove — that `serialised.widgets_values` describes `widgets`, and so - * whether a `widgets_values_form` may be emitted for this node. See ADR-ECS-WIDGETS-0023. - * - * @param widgets the node's live widget list at serialization time - * @param serialised the node payload as it stands after the extension serialize hook - * @param producedValues the array `serialiseWidgetValues` returned before the hook ran, or - * `undefined` if it never ran; array identity against it is the proof - * @param options see {@link WidgetFormOptions} - */ +/** Proves whether core's final positional values match the live widget order. */ export function proveWidgetForm( widgets: readonly WidgetForFormProof[] | undefined, serialised: { @@ -130,10 +116,7 @@ export function proveWidgetForm( return { provable: true, refusal: null, order: addressed.order } } -/** - * True when a node's values are object-shaped with no form to interpret them — the population - * a form would rescue, and which nothing can currently count. - */ +/** True when object-shaped widget values have no form that interprets them. */ export function needsFormButHasNone(serialised: { widgets_values?: unknown widgets_values_form?: unknown From 2101005517a41616ae8d2eef8dca9c626fa2d748 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Fri, 30 Oct 2026 08:13:07 -0700 Subject: [PATCH 08/11] chore(architecture): register widget form proof test --- docs/architecture/domains/boundaries.json | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/architecture/domains/boundaries.json b/docs/architecture/domains/boundaries.json index 7a3f824171a..5ba0cf54bca 100644 --- a/docs/architecture/domains/boundaries.json +++ b/docs/architecture/domains/boundaries.json @@ -1595,6 +1595,7 @@ "src/lib/litegraph/src/LGraphNode.stateProjection.test.ts", "src/lib/litegraph/src/LGraphNode.test.ts", "src/lib/litegraph/src/LGraphNode.titleButtons.test.ts", + "src/lib/litegraph/src/LGraphNode.widgetFormProof.test.ts", "src/lib/litegraph/src/LGraphNode.widgetLabelRename.regression.test.ts", "src/lib/litegraph/src/LGraphNode.widgetOrder.test.ts", "src/lib/litegraph/src/LLink.ts", From e4521af8d2c3d2331776537d67cd311b1f87afd8 Mon Sep 17 00:00:00 2001 From: bymyself Date: Mon, 2 Nov 2026 02:36:58 +0000 Subject: [PATCH 09/11] fix(litegraph): type the widget form proof as a union and refuse an empty order Review feedback on #22007: the result is now a discriminated union, an all-excluded widget list is refused instead of proving an empty order, the serializer test moves beside the predicate so it no longer imports widget code from the graph-model zone, and the ADR text is corrected against the pinned protocol. --- ...023-widget-entities-with-a-legacy-layer.md | 50 +-- docs/architecture/domains/boundaries.json | 1 - .../widgetFormProof.serialize.test.ts} | 16 +- .../src/widgets/widgetFormProof.test.ts | 311 +++++++----------- .../litegraph/src/widgets/widgetFormProof.ts | 17 +- 5 files changed, 161 insertions(+), 234 deletions(-) rename src/lib/litegraph/src/{LGraphNode.widgetFormProof.test.ts => widgets/widgetFormProof.serialize.test.ts} (81%) diff --git a/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md b/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md index 4b574e85934..eecefa9cd0b 100644 --- a/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md +++ b/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md @@ -167,8 +167,9 @@ and the ECS runs that system on demand. ## Amended (2026-10-26): a per-node widget form is emitted only where it can be _proven_ `widgets_values_form` is a per-node declaration of which widgets serialize and in what order -(`comfy-multi-player` schema amendment A24). A node carrying one is addressed through that form -and **consults no widget catalog on any leg**. That makes the error asymmetry total: +(`comfy-multi-player` schema amendment A24). Object-shaped forms are closed and catalog-free. +Array-form writes still require the pinned catalog for A25's dynamic-combo overlay; projection +uses the stored form. An incorrect form can still misassociate values: - A node with **no** form keeps today's catalog behaviour, which is imperfect but visible — a name that does not resolve is refused loudly. @@ -182,11 +183,13 @@ So the rule is not "derive the order from `node.widgets`". It is: Deriving is a guess dressed as a declaration; proving is not. `proveWidgetForm` (`src/lib/litegraph/src/widgets/widgetFormProof.ts`) is that predicate, and it returns an order -**only** alongside `provable: true` — never a partial order beside a refusal. +**only** alongside `provable: true` — never a partial order beside a refusal. The result type is a +discriminated union, so reading `order` without checking `provable` does not compile, and an empty +serializing order is refused (`widgets_not_serialized`) because the document rejects an empty form. ### Why deriving does not work, measured -The obvious implementation — derive after `runExtensionSerializeHook`, since that hook sees the +The obvious implementation — derive after `runExtensionSerializeHook`, since that hook receives the final values — is wrong for two independent reasons. **`LGraphNode.serialize` is not the last writer.** `SubgraphNode.serializeFromStoreState` calls @@ -219,14 +222,12 @@ Three predicates look interchangeable and are deliberately different: (`control_after_generate`) and every `LoadImage` serializes 2 (its upload button). A form built from `options.serialize` is one slot short on both. -`LGraphNode.widgetFormProof.test.ts` pins the _rule_ against the real serializer: the flag cases -build an `LGraphNode` in a graph, add widgets through `addWidget`, and read `node.serialize()`, so -the assertion is on production's own `widgets_values` rather than on a filter the test duplicates. -Measured there: `addWidget('combo', …, { serialize: false, values: [...] })` leaves -`widget.serialize` `undefined` with `widget.options.serialize === false`, and the widget still -occupies a slot. It lives beside `LGraphNode` rather than in `widgets/` because importing -`LGraphNode` is what the `node-widgets` → `litegraph-api` boundary below forbids; -`widgetFormProof.test.ts` keeps the pure-predicate cases and stays inside that boundary. +`widgets/widgetFormProof.serialize.test.ts` pins the _rule_ against the real serializer: the flag +cases build an `LGraphNode` in a graph, add widgets through `addWidget`, and read +`node.serialize()`, so the assertion is on production's own `widgets_values` rather than on a +filter the test duplicates. A widget added with `{ serialize: false }` in its options bag still +occupies a slot. It imports `LGraphNode` through the LiteGraph barrel, which the `litegraph-api` +compatibility contract permits; `widgetFormProof.test.ts` keeps the pure-predicate cases. It does **not** instantiate a real `KSampler` or `LoadImage`, so the 7 and the 2 above remain measurements of production code rather than assertions this file makes. Pinning them against the @@ -244,10 +245,10 @@ Four are worth calling out. **`replayed_serialization`** covers an unregistered payload is replayed verbatim and never reaches the hook, and whose widgets are _synthesised from the stored values_ with names `UNKNOWN`, `UNKNOWN_1`, … A form there would be syntactically valid, authoritative, and meaningless, so it is refused before any other check can accept it. -**`duplicate_widget_name`** covers two serializing widgets sharing a name: the named projection -collapses them via `defineProperty`, and the document rejects the second address outright, so -listing both would promise an address that does not resolve. Measured in the corpus: `RecordAudio` -stores 2 values under 1 name and `LoadAudio` 3 under 2. +**`duplicate_widget_name`** conservatively refuses serializing widgets sharing a name. Core's +named projection overwrites duplicate keys, although the document's positional array-form path +can represent duplicate occurrences. Measured in the corpus: `RecordAudio` stores 2 values under +1 name. **`values_missing`** and **`values_replaced`** are deliberately distinct, because they send a reader to different problems. `values_missing` is an absent `widgets_values` — the @@ -266,10 +267,12 @@ _contents_ were untouched: a serialize hook can reorder `node.widgets`, or mutat array in place, while preserving both identity and length. `proveWidgetForm` would then report `provable: true` with an order that does not match the values. -That is a known limit, not an oversight, and it is why nothing calls this predicate yet. A -producer must close it first — by snapshotting the pre-hook order, or by validating contents -rather than identity — and that belongs in the change that adds the producer, where the pre-hook -state is in scope. +That is a known limit, not an oversight, and it is why no production code calls this predicate +yet; its only consumer is the registry census, which reports refusal rates and emits nothing. A +producer must close both mutation paths before calling this predicate. A pre-hook order snapshot +handles later widget-list reordering, but the producer must also detect changes to the produced +values or otherwise prove that the final name/value association is unchanged. That belongs in +the producer change, where the pre-hook state is in scope. ### The call site is part of the rule, not an implementation detail @@ -317,6 +320,7 @@ this up. The Agent wire already declares forms on its own `add_node` path: `docOpMinter.wireNodeSnapshot` attaches `widgets_values_form` from `provenWidgetValuesForm` (`src/workbench/extensions/agent/crdt/widgetValuesForm.ts`, per [ADR-WIDGET-SERIALIZATION-0047](WIDGET-SERIALIZATION-0047-agent-wire-widget-form-is-proven-not-derived.md)). -That producer reads the post-hook payload and reaches the same conclusion by a different route; -reconciling the two, so core serialization and the Agent wire share one predicate, is the -follow-up this amendment makes possible rather than something it does. +The Agent producer proves the filtered named payload, while this predicate checks positional-array +provenance. Their acceptance policies intentionally differ: #22505 and #22508 show that importing +the positional identity or class-override refusals into the Agent wire would reject valid +uncatalogued nodes. Any future consolidation must preserve those separate contracts. diff --git a/docs/architecture/domains/boundaries.json b/docs/architecture/domains/boundaries.json index 43d5dce546e..79500182f5a 100644 --- a/docs/architecture/domains/boundaries.json +++ b/docs/architecture/domains/boundaries.json @@ -1641,7 +1641,6 @@ "src/lib/litegraph/src/LGraphNode.stateProjection.test.ts", "src/lib/litegraph/src/LGraphNode.test.ts", "src/lib/litegraph/src/LGraphNode.titleButtons.test.ts", - "src/lib/litegraph/src/LGraphNode.widgetFormProof.test.ts", "src/lib/litegraph/src/LGraphNode.widgetLabelRename.regression.test.ts", "src/lib/litegraph/src/LGraphNode.widgetOrder.test.ts", "src/lib/litegraph/src/LLink.ts", diff --git a/src/lib/litegraph/src/LGraphNode.widgetFormProof.test.ts b/src/lib/litegraph/src/widgets/widgetFormProof.serialize.test.ts similarity index 81% rename from src/lib/litegraph/src/LGraphNode.widgetFormProof.test.ts rename to src/lib/litegraph/src/widgets/widgetFormProof.serialize.test.ts index 726718d4d29..b5e5f8136f6 100644 --- a/src/lib/litegraph/src/LGraphNode.widgetFormProof.test.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.serialize.test.ts @@ -39,7 +39,7 @@ describe('proveWidgetForm, driven through LGraphNode.serialize', () => { it('counts a widget flagged only in its options bag, because widgets_values does', () => { const node = nodeInGraph() node.addWidget('number', 'seed', 1, () => undefined, {}) - const optionsBagFlagged = node.addWidget( + node.addWidget( 'combo', 'control_after_generate', 'randomize', @@ -47,9 +47,6 @@ describe('proveWidgetForm, driven through LGraphNode.serialize', () => { { serialize: false, values: ['randomize', 'fixed'] } ) - expect(optionsBagFlagged.options.serialize).toBe(false) - expect(optionsBagFlagged.serialize).toBeUndefined() - const { serialised, proof } = proveRealSerialization(node) expect(serialised.widgets_values).toEqual([1, 'randomize']) @@ -76,15 +73,4 @@ describe('proveWidgetForm, driven through LGraphNode.serialize', () => { expect(proof.provable).toBe(true) expect(proof.order).toEqual(['audio']) }) - - it('refuses a node whose serialize_widgets flag is off', () => { - const node = nodeInGraph() - node.addWidget('number', 'mode', 1, () => undefined, {}) - node.serialize_widgets = false - - const { proof } = proveRealSerialization(node) - - expect(proof.provable).toBe(false) - expect(proof.refusal).toBe('widgets_not_serialized') - }) }) diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.test.ts b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts index ab08ab6dc72..b7fb019eea9 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.test.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts @@ -5,120 +5,98 @@ import { proveWidgetForm } from '@/lib/litegraph/src/widgets/widgetFormProof' -interface TestWidget { - name: string - type: string - value: unknown - serialize?: boolean -} - -function widget(name: string, extra: Partial = {}): TestWidget { - return { name, type: 'number', value: 0, ...extra } -} - -function produce(widgets: TestWidget[]) { - const values = widgets - .filter((w) => w.serialize !== false) - .map((w) => w.value) - return { values, serialised: { widgets_values: values } } -} +const serializing = { serializeWidgets: true, coreIsLastWriter: true } describe('proveWidgetForm', () => { it('proves an ordinary node whose values it produced itself', () => { - const widgets = [ - widget('seed', { value: 1 }), - widget('steps', { value: 20 }) - ] - const { values, serialised } = produce(widgets) - - const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true, - coreIsLastWriter: true - }) + const widgets = [{ name: 'seed' }, { name: 'steps' }] + const values = [1, 20] + + const proof = proveWidgetForm( + widgets, + { widgets_values: values }, + values, + serializing + ) - expect(proof.provable).toBe(true) - expect(proof.order).toEqual(['seed', 'steps']) - expect(proof.refusal).toBeNull() + expect(proof).toEqual({ + provable: true, + refusal: null, + order: ['seed', 'steps'] + }) }) describe('refuses rather than guessing', () => { it('when a subclass or extension replaced the array with an equal-looking one', () => { - const widgets = [widget('a', { value: 1 }), widget('b', { value: 2 })] - const { values } = produce(widgets) - const replaced = { widgets_values: [1, 2] } + const widgets = [{ name: 'a' }, { name: 'b' }] - const proof = proveWidgetForm(widgets, replaced, values, { - serializeWidgets: true, - coreIsLastWriter: true - }) + const proof = proveWidgetForm( + widgets, + { widgets_values: [1, 2] }, + [1, 2], + serializing + ) - expect(proof.provable).toBe(false) - expect(proof.refusal).toBe('values_replaced') - expect(proof.order).toBeNull() + expect(proof).toEqual({ + provable: false, + refusal: 'values_replaced', + order: null + }) }) it('when a subgraph deleted the values entirely', () => { - const widgets = [widget('promoted_a'), widget('promoted_b')] - const { values } = produce(widgets) + const widgets = [{ name: 'promoted_a' }, { name: 'promoted_b' }] - const proof = proveWidgetForm(widgets, {}, values, { - serializeWidgets: true, - coreIsLastWriter: true - }) + const proof = proveWidgetForm(widgets, {}, [0, 0], serializing) - expect(proof.provable).toBe(false) expect(proof.refusal).toBe('values_missing') - expect(proof.order).toBeNull() }) it('when an extension replaced the array with a name-keyed object', () => { const widgets = [ - widget('video', { value: 'clip.mp4' }), - widget('vhslatentpreview', { serialize: false }) + { name: 'video' }, + { name: 'vhslatentpreview', serialize: false } ] - const { values } = produce(widgets) - const dict = { - widgets_values: { video: 'clip.mp4', vhslatentpreview: {}, crf: 23 } - } - - const proof = proveWidgetForm(widgets, dict, values, { - serializeWidgets: true, - coreIsLastWriter: true - }) - expect(proof.provable).toBe(false) + const proof = proveWidgetForm( + widgets, + { + widgets_values: { video: 'clip.mp4', vhslatentpreview: {}, crf: 23 } + }, + ['clip.mp4'], + serializing + ) + expect(proof.refusal).toBe('values_not_positional') }) }) describe('refuses a payload it did not build', () => { it('when the payload was replayed from a previous save', () => { - const widgets = [ - widget('UNKNOWN', { value: 1 }), - widget('UNKNOWN_1', { value: 2 }) - ] - const { values, serialised } = produce(widgets) + const widgets = [{ name: 'UNKNOWN' }, { name: 'UNKNOWN_1' }] + const values = [1, 2] - const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true, - replayed: true, - coreIsLastWriter: true - }) + const proof = proveWidgetForm( + widgets, + { widgets_values: values }, + values, + { + ...serializing, + replayed: true + } + ) - expect(proof.provable).toBe(false) expect(proof.refusal).toBe('replayed_serialization') - expect(proof.order).toBeNull() }) it('and also when the replay is signalled by has_errors', () => { - const widgets = [widget('UNKNOWN', { value: 1 })] - const { values, serialised } = produce(widgets) + const values = [1] const proof = proveWidgetForm( - widgets, - { ...serialised, has_errors: true }, + [{ name: 'UNKNOWN' }], + { widgets_values: values, has_errors: true }, values, - { serializeWidgets: true, coreIsLastWriter: true } + serializing ) expect(proof.refusal).toBe('replayed_serialization') @@ -127,144 +105,102 @@ describe('proveWidgetForm', () => { describe('refuses when the widget list and the values disagree', () => { it('when serialize_widgets is falsy', () => { - const widgets = [widget('mode'), widget('filter')] - - const proof = proveWidgetForm(widgets, {}, undefined, { - serializeWidgets: false, - coreIsLastWriter: true - }) + const proof = proveWidgetForm( + [{ name: 'mode' }, { name: 'filter' }], + {}, + undefined, + { serializeWidgets: false, coreIsLastWriter: true } + ) - expect(proof.provable).toBe(false) expect(proof.refusal).toBe('widgets_not_serialized') }) - it('when the widget list was spliced after the values were written', () => { - const widgets = [widget('a', { value: 1 }), widget('b', { value: 2 })] - const { values, serialised } = produce(widgets) - widgets.pop() + it('when every widget is excluded from serialization', () => { + const values: unknown[] = [] + + const proof = proveWidgetForm( + [{ name: 'preview', serialize: false }], + { widgets_values: values }, + values, + serializing + ) - const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true, - coreIsLastWriter: true + expect(proof).toEqual({ + provable: false, + refusal: 'widgets_not_serialized', + order: null }) + }) + + it('when the widget list was spliced after the values were written', () => { + const values = [1, 2] + + const proof = proveWidgetForm( + [{ name: 'a' }], + { widgets_values: values }, + values, + serializing + ) - expect(proof.provable).toBe(false) expect(proof.refusal).toBe('length_mismatch') }) it('when two serializing widgets share a name', () => { - const widgets = [ - widget('audio', { value: 'a' }), - widget('audio', { value: 'b' }) - ] - const { values, serialised } = produce(widgets) + const values = ['a', 'b'] - const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true, - coreIsLastWriter: true - }) + const proof = proveWidgetForm( + [{ name: 'audio' }, { name: 'audio' }], + { widgets_values: values }, + values, + serializing + ) - expect(proof.provable).toBe(false) expect(proof.refusal).toBe('duplicate_widget_name') }) it('when a widget has no usable name', () => { - const widgets = [widget('ok', { value: 1 }), widget('', { value: 2 })] - const { values, serialised } = produce(widgets) + const values = [1, 2] - const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true, - coreIsLastWriter: true - }) + const proof = proveWidgetForm( + [{ name: 'ok' }, { name: '' }], + { widgets_values: values }, + values, + serializing + ) - expect(proof.provable).toBe(false) expect(proof.refusal).toBe('unnameable_widget') }) }) it('refuses a node whose class can still rewrite the payload', () => { - const widgets = [ - widget('promoted_a', { value: 1 }), - widget('promoted_b', { value: 2 }) - ] - const { values, serialised } = produce(widgets) - - const accepted = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true, - coreIsLastWriter: true - }) - expect(accepted.provable).toBe(true) + const values = [1, 2] - const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true, - coreIsLastWriter: false - }) + const proof = proveWidgetForm( + [{ name: 'promoted_a' }, { name: 'promoted_b' }], + { widgets_values: values }, + values, + { serializeWidgets: true, coreIsLastWriter: false } + ) - expect(proof.provable).toBe(false) - expect(proof.refusal).toBe('class_may_rewrite_payload') - expect(proof.order).toBeNull() + expect(proof).toEqual({ + provable: false, + refusal: 'class_may_rewrite_payload', + order: null + }) }) it('checks the last writer before any other refusal that also applies', () => { - const widgets = [widget('dup', { value: 1 }), widget('dup', { value: 2 })] - const { values, serialised } = produce(widgets) + const values = [1, 2] - const proof = proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true, - replayed: true, - coreIsLastWriter: false - }) + const proof = proveWidgetForm( + [{ name: 'dup' }, { name: 'dup' }], + { widgets_values: values }, + values, + { serializeWidgets: true, replayed: true, coreIsLastWriter: false } + ) expect(proof.refusal).toBe('class_may_rewrite_payload') }) - - it('never returns an order alongside a refusal', () => { - const widgets = [widget('dup', { value: 1 }), widget('dup', { value: 2 })] - const { values, serialised } = produce(widgets) - - const proofs = [ - proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true, - coreIsLastWriter: true - }), - proveWidgetForm(widgets, serialised, values, { - serializeWidgets: true, - replayed: true, - coreIsLastWriter: true - }), - proveWidgetForm(widgets, { widgets_values: { a: 1 } }, values, { - serializeWidgets: true, - coreIsLastWriter: true - }), - proveWidgetForm(widgets, {}, values, { - serializeWidgets: true, - coreIsLastWriter: true - }), - proveWidgetForm(widgets, {}, undefined, { - serializeWidgets: false, - coreIsLastWriter: true - }), - proveWidgetForm(undefined, {}, undefined, { - serializeWidgets: true, - coreIsLastWriter: true - }) - ] - - expect( - proofs.map(({ provable, order, refusal }) => ({ - provable, - order, - refusal - })) - ).toEqual([ - { provable: false, order: null, refusal: 'duplicate_widget_name' }, - { provable: false, order: null, refusal: 'replayed_serialization' }, - { provable: false, order: null, refusal: 'values_not_positional' }, - { provable: false, order: null, refusal: 'values_missing' }, - { provable: false, order: null, refusal: 'widgets_not_serialized' }, - { provable: false, order: null, refusal: 'widgets_not_serialized' } - ]) - }) }) describe('needsFormButHasNone', () => { @@ -283,9 +219,12 @@ describe('needsFormButHasNone', () => { ).toBe(false) }) - it('does not flag ordinary positional values, or an absent payload', () => { - expect(needsFormButHasNone({ widgets_values: [1, 2] })).toBe(false) - expect(needsFormButHasNone({})).toBe(false) - expect(needsFormButHasNone({ widgets_values: null })).toBe(false) + it.for([ + { name: 'positional values', serialised: { widgets_values: [1, 2] } }, + { name: 'absent payload', serialised: {} }, + { name: 'null payload', serialised: { widgets_values: null } }, + { name: 'scalar payload', serialised: { widgets_values: 'clip.mp4' } } + ])('does not flag $name', ({ serialised }) => { + expect(needsFormButHasNone(serialised)).toBe(false) }) }) diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.ts b/src/lib/litegraph/src/widgets/widgetFormProof.ts index 7efb59ce10c..f0795fc8828 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.ts @@ -14,9 +14,7 @@ type WidgetFormRefusal = | 'duplicate_widget_name' | 'unnameable_widget' -/** Options for {@link proveWidgetForm}. See ADR-ECS-WIDGETS-0023. */ export interface WidgetFormOptions { - /** The node's `serialize_widgets` flag. */ serializeWidgets?: boolean /** True when the payload was replayed from a previous save rather than built here. */ replayed?: boolean @@ -24,12 +22,9 @@ export interface WidgetFormOptions { coreIsLastWriter: boolean } -/** The verdict from {@link proveWidgetForm}. `order` is present only when `provable`. */ -export interface WidgetFormProof { - provable: boolean - refusal: WidgetFormRefusal | null - order: string[] | null -} +export type WidgetFormProof = + | { provable: true; refusal: null; order: string[] } + | { provable: false; refusal: WidgetFormRefusal; order: null } function refuse(refusal: WidgetFormRefusal): WidgetFormProof { return { provable: false, refusal, order: null } @@ -90,7 +85,10 @@ function addressableOrder( return { order } } -/** Proves whether core's final positional values match the live widget order. */ +/** + * Checks positional-array provenance: identity, cardinality and names. The caller must establish + * that the name/value correspondence did not change after core produced the values. + */ export function proveWidgetForm( widgets: readonly WidgetForFormProof[] | undefined, serialised: { @@ -107,6 +105,7 @@ export function proveWidgetForm( if ('refusal' in proven) return refuse(proven.refusal) const serializing = serializingWidgets(widgets ?? []) + if (serializing.length === 0) return refuse('widgets_not_serialized') if (serializing.length !== proven.values.length) return refuse('length_mismatch') From f3149fd50b63148b5bd6df2647a483f4dfc5a089 Mon Sep 17 00:00:00 2001 From: bymyself Date: Mon, 2 Nov 2026 03:06:56 +0000 Subject: [PATCH 10/11] fix(litegraph): report length_mismatch before the empty-order refusal --- ...GETS-0023-widget-entities-with-a-legacy-layer.md | 2 +- .../litegraph/src/widgets/widgetFormProof.test.ts | 13 +++++++++++++ src/lib/litegraph/src/widgets/widgetFormProof.ts | 2 +- 3 files changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md b/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md index eecefa9cd0b..c83d26defc9 100644 --- a/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md +++ b/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md @@ -184,7 +184,7 @@ So the rule is not "derive the order from `node.widgets`". It is: Deriving is a guess dressed as a declaration; proving is not. `proveWidgetForm` (`src/lib/litegraph/src/widgets/widgetFormProof.ts`) is that predicate, and it returns an order **only** alongside `provable: true` — never a partial order beside a refusal. The result type is a -discriminated union, so reading `order` without checking `provable` does not compile, and an empty +discriminated union, so using `order` as a `string[]` without checking `provable` does not compile, and an empty serializing order is refused (`widgets_not_serialized`) because the document rejects an empty form. ### Why deriving does not work, measured diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.test.ts b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts index b7fb019eea9..08a97cde6ab 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.test.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts @@ -132,6 +132,19 @@ describe('proveWidgetForm', () => { }) }) + it('when every widget is excluded but values were still written', () => { + const values = [1] + + const proof = proveWidgetForm( + [{ name: 'preview', serialize: false }], + { widgets_values: values }, + values, + serializing + ) + + expect(proof.refusal).toBe('length_mismatch') + }) + it('when the widget list was spliced after the values were written', () => { const values = [1, 2] diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.ts b/src/lib/litegraph/src/widgets/widgetFormProof.ts index f0795fc8828..7e6145b48ab 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.ts @@ -105,9 +105,9 @@ export function proveWidgetForm( if ('refusal' in proven) return refuse(proven.refusal) const serializing = serializingWidgets(widgets ?? []) - if (serializing.length === 0) return refuse('widgets_not_serialized') if (serializing.length !== proven.values.length) return refuse('length_mismatch') + if (serializing.length === 0) return refuse('widgets_not_serialized') const addressed = addressableOrder(serializing) if ('refusal' in addressed) return refuse(addressed.refusal) From 1f5804a4fa4fedbea950ec042b3334d5ab5276d2 Mon Sep 17 00:00:00 2001 From: bymyself Date: Mon, 2 Nov 2026 03:30:57 +0000 Subject: [PATCH 11/11] fix(litegraph): require replayed, drop the payload has_errors read, treat a null form as none has_errors lives on the node instance, never in the serialized payload, so the replay refusal must come from the caller. Also corrects the ADR's refusal-to-cause mapping and states the pre-hook array precondition. --- ...023-widget-entities-with-a-legacy-layer.md | 25 ++++++++++----- .../widgets/widgetFormProof.serialize.test.ts | 1 + .../src/widgets/widgetFormProof.test.ts | 32 +++++++++---------- .../litegraph/src/widgets/widgetFormProof.ts | 20 ++++++------ 4 files changed, 43 insertions(+), 35 deletions(-) diff --git a/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md b/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md index c83d26defc9..8abb878eff8 100644 --- a/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md +++ b/docs/adr/ECS-WIDGETS-0023-widget-entities-with-a-legacy-layer.md @@ -190,16 +190,21 @@ serializing order is refused (`widgets_not_serialized`) because the document rej ### Why deriving does not work, measured The obvious implementation — derive after `runExtensionSerializeHook`, since that hook receives the -final values — is wrong for two independent reasons. +final values — is wrong for two independent reasons. `replayed` is required for the same reason +as `coreIsLastWriter` below: a missing-node shell's `has_errors` lives on the node instance, not in +the serialized payload, so only the caller can say the payload was replayed. **`LGraphNode.serialize` is not the last writer.** `SubgraphNode.serializeFromStoreState` calls `super.serializeFromStoreState(state)` — hook included — and _then_ replaces `widgets_values` from `this.inputs` filtered to those carrying a `widgetId`, or deletes it. That is a different collection from `node.widgets` (promoted widgets are linked inputs, per [ADR-SUBGRAPH-PROMOTION-0009](SUBGRAPH-PROMOTION-0009-represent-promoted-widgets-as-linked-inputs.md)), -so a form written at the end of the base method is already stale when the subclass returns. The -proof catches this on **array identity**, deliberately not deep equality: a rebuilt -equal-looking array came from a source core cannot see, and a coincidental match is not evidence. +so a form written at the end of the base method is already stale when the subclass returns. +Identity alone does not catch this (see the call-site section below); `coreIsLastWriter` does. The +proof still checks **array identity**, deliberately not deep equality, against an instance hook +that assigns a new array: a rebuilt equal-looking array came from a source core cannot see, and a +coincidental match is not evidence. That check is only meaningful when the caller passes the array +core built before the hook ran; passing the final array makes it vacuous. **`node.widgets` is a public JavaScript API that extensions mutate**, as the ADR body above already describes. Shipping packs splice it, truncate it (`this.widgets.length = n`), reorder @@ -251,10 +256,10 @@ can represent duplicate occurrences. Measured in the corpus: `RecordAudio` store 1 name. **`values_missing`** and **`values_replaced`** are deliberately distinct, because they send a -reader to different problems. `values_missing` is an absent `widgets_values` — the -`delete serialized.widgets_values` branch a `SubgraphNode` takes when every promoted store value -is `undefined`. `values_replaced` is an array core did not produce, which is the shape a pack's -own `serialize` override leaves behind. `values_not_positional` is reserved for an +reader to different problems. `values_missing` is an absent `widgets_values` left by an +instance hook that deleted it. `values_replaced` is an array core did not produce, which an +`onSerialize` hook assigning a new array leaves behind. (`SubgraphNode` and class-level +`serialize` overrides never reach either: `class_may_rewrite_payload` refuses them first.) `values_not_positional` is reserved for an object-shaped payload: the VHS family's `onSerialize` writes a dict keyed by every widget name, including widgets flagged `serialize === false`, so its keys and any derived order disagree. `widgets_not_serialized` covers `this.serialize_widgets = false`, which rgthree's group muters, @@ -293,6 +298,10 @@ coreIsLastWriter: node.serializeFromStoreState === node.serialize === LGraphNode.prototype.serialize ``` +It compares against the live base prototype, so an extension that globally wraps +`LGraphNode.prototype.serialize` still compares equal. That is a known limit for the producer to +close, for example by comparing against references captured at module load. + Required rather than derived for two reasons. `tsc` then refuses any new call site until the question has been answered, so the assumption cannot creep back in silently. And the comparison needs both the instance and the base prototype in scope, which is true at the call site and not diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.serialize.test.ts b/src/lib/litegraph/src/widgets/widgetFormProof.serialize.test.ts index b5e5f8136f6..c002c33d07a 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.serialize.test.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.serialize.test.ts @@ -29,6 +29,7 @@ function proveRealSerialization(node: LGraphNode) { serialised.widgets_values, { serializeWidgets: node.serialize_widgets, + replayed: node.last_serialization !== undefined, coreIsLastWriter: coreIsLastWriter(node) } ) diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.test.ts b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts index 08a97cde6ab..b2b2f1edb3c 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.test.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.test.ts @@ -5,7 +5,11 @@ import { proveWidgetForm } from '@/lib/litegraph/src/widgets/widgetFormProof' -const serializing = { serializeWidgets: true, coreIsLastWriter: true } +const serializing = { + serializeWidgets: true, + replayed: false, + coreIsLastWriter: true +} describe('proveWidgetForm', () => { it('proves an ordinary node whose values it produced itself', () => { @@ -88,19 +92,6 @@ describe('proveWidgetForm', () => { expect(proof.refusal).toBe('replayed_serialization') }) - - it('and also when the replay is signalled by has_errors', () => { - const values = [1] - - const proof = proveWidgetForm( - [{ name: 'UNKNOWN' }], - { widgets_values: values, has_errors: true }, - values, - serializing - ) - - expect(proof.refusal).toBe('replayed_serialization') - }) }) describe('refuses when the widget list and the values disagree', () => { @@ -109,7 +100,7 @@ describe('proveWidgetForm', () => { [{ name: 'mode' }, { name: 'filter' }], {}, undefined, - { serializeWidgets: false, coreIsLastWriter: true } + { ...serializing, serializeWidgets: false } ) expect(proof.refusal).toBe('widgets_not_serialized') @@ -192,7 +183,7 @@ describe('proveWidgetForm', () => { [{ name: 'promoted_a' }, { name: 'promoted_b' }], { widgets_values: values }, values, - { serializeWidgets: true, coreIsLastWriter: false } + { ...serializing, coreIsLastWriter: false } ) expect(proof).toEqual({ @@ -223,6 +214,15 @@ describe('needsFormButHasNone', () => { ) }) + it('flags an object-shaped payload whose form is null', () => { + expect( + needsFormButHasNone({ + widgets_values: { video: 'clip.mp4' }, + widgets_values_form: null + }) + ).toBe(true) + }) + it('does not flag one that already declares a form', () => { expect( needsFormButHasNone({ diff --git a/src/lib/litegraph/src/widgets/widgetFormProof.ts b/src/lib/litegraph/src/widgets/widgetFormProof.ts index 7e6145b48ab..d1853a3defc 100644 --- a/src/lib/litegraph/src/widgets/widgetFormProof.ts +++ b/src/lib/litegraph/src/widgets/widgetFormProof.ts @@ -17,7 +17,7 @@ type WidgetFormRefusal = export interface WidgetFormOptions { serializeWidgets?: boolean /** True when the payload was replayed from a previous save rather than built here. */ - replayed?: boolean + replayed: boolean /** True when the node uses core's base serialization implementations. */ coreIsLastWriter: boolean } @@ -37,17 +37,16 @@ function serializingWidgets( } function preconditionRefusal( - serialised: { has_errors?: boolean }, options: WidgetFormOptions ): WidgetFormRefusal | null { if (!options.coreIsLastWriter) return 'class_may_rewrite_payload' - if (options.replayed || serialised.has_errors) return 'replayed_serialization' + if (options.replayed) return 'replayed_serialization' return null } function provenValues( widgets: readonly WidgetForFormProof[] | undefined, - serialised: { widgets_values?: unknown; has_errors?: boolean }, + serialised: { widgets_values?: unknown }, producedValues: unknown, options: WidgetFormOptions ): { values: unknown[] } | { refusal: WidgetFormRefusal } { @@ -87,18 +86,17 @@ function addressableOrder( /** * Checks positional-array provenance: identity, cardinality and names. The caller must establish - * that the name/value correspondence did not change after core produced the values. + * that the name/value correspondence did not change after core produced the values, and must + * pass as `producedValues` the array core built before the extension hook ran; passing the final + * array makes the identity check vacuous. */ export function proveWidgetForm( widgets: readonly WidgetForFormProof[] | undefined, - serialised: { - widgets_values?: unknown - has_errors?: boolean - }, + serialised: { widgets_values?: unknown }, producedValues: unknown, options: WidgetFormOptions ): WidgetFormProof { - const precondition = preconditionRefusal(serialised, options) + const precondition = preconditionRefusal(options) if (precondition !== null) return refuse(precondition) const proven = provenValues(widgets, serialised, producedValues, options) @@ -125,6 +123,6 @@ export function needsFormButHasNone(serialised: { values !== null && typeof values === 'object' && !Array.isArray(values) && - serialised.widgets_values_form === undefined + serialised.widgets_values_form == null ) }