From c0005b6ca5694e5394e35be3f4211f5c052cfaf0 Mon Sep 17 00:00:00 2001 From: jaeone94 <89377375+jaeone94@users.noreply.github.com> Date: Mon, 5 Oct 2026 21:05:10 +0900 Subject: [PATCH 01/10] fix: preserve DynamicGroup widget identities in documents --- docs/dynamic-groups.md | 15 ++ docs/multiplayer-schema.md | 6 + docs/upstream-pins.json | 18 ++ src/applier.ts | 19 +- src/dynamic-combos.ts | 34 ++-- src/dynamic-groups.ts | 47 +++++ src/project.ts | 7 +- src/types.ts | 7 + test/dynamic-group.test.ts | 158 +++++++++++++++ test/fixtures/dynamic-group.json | 336 +++++++++++++++++++++++++++++++ 10 files changed, 630 insertions(+), 17 deletions(-) create mode 100644 docs/dynamic-groups.md create mode 100644 src/dynamic-groups.ts create mode 100644 test/dynamic-group.test.ts create mode 100644 test/fixtures/dynamic-group.json diff --git a/docs/dynamic-groups.md b/docs/dynamic-groups.md new file mode 100644 index 0000000..68e99e3 --- /dev/null +++ b/docs/dynamic-groups.md @@ -0,0 +1,15 @@ +# DynamicGroup catalog support + +The fixture and catalog are derived from [comfy-cli `65769ee31183cd1e1049321c2fb42296f03bf4b5`](https://github.com/Comfy-Org/comfy-cli/blob/65769ee31183cd1e1049321c2fb42296f03bf4b5/comfy_cli/cql/widget_catalog.py). The registered functions are `build_types` and `build_catalog`. + +To regenerate `test/fixtures/dynamic-group.json` at that revision, load `tests/comfy_cli/fixtures/dynamic_group.json`, pass its `object_info` through `Graph.from_object_info` and `build_catalog`, and copy each case's `workflow`. The `editing` case applies `workflow_ops.set_widget` to `loras.1.strength=0.7` and `after="edited tail"`, with consecutive base versions, and records both emitted ops plus `workflow_ops.canonical` of the final workflow. The `source_commit` records that revision. Expected edits in `test/dynamic-group.test.ts` are authored independently of this package. The source fixture records its frontend/core capture provenance. + +`dynamic_groups` maps a row-count controller to `min`, `max`, relative `widgets`, and field `defaults`. Each row expands immediately after its controller under `..`. Remove any default rows already present in `widget_order` before expanding the saved count. + +The catalog controls layout, not prompt validity. Saved rows above an advertised `max` are retained; CLI/core validation decides whether they can execute. Counts must be non-negative safe integers and cannot expand a group beyond the existing `MAX_OVERFLOW_WIDGETS` allocation bound. + +Like dynamic-combo selections, count changes only change projection. Fields in hidden rows retain their name-keyed registers, and newly visible fields without a stored value show template defaults. This avoids receiver-side writes whose outcome depends on op arrival order (KA-2, KA-4). It is not a destructive row-delete operation: deleting a row and its links is a separate producer responsibility. + +An explicit `widgets_values_form` remains authoritative. Existing row fields can be edited through it; a count change that requires replacing that declaration is refused before mutation. This PR does not introduce an op for changing producer-owned forms. + +No wire key or op kind changes. New catalog content changes the catalog hash. Consumers must adopt this reader before receiving a DynamicGroup catalog; old documents remain tied to their original catalog and must be re-minted to adopt a new layout (KA-11, KA-12, FC-10). diff --git a/docs/multiplayer-schema.md b/docs/multiplayer-schema.md index 9527a79..bc88283 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -2494,3 +2494,9 @@ on that path and the retention on every other — rather than papered over. map directly, maintains neither passthrough register (A23's gap), and does not consult a declared order either. Pre-existing, one op over, and not addressed here. + +## Amendment A25 — 2026-10-05 — DynamicGroup catalog layout + +An opt-in `dynamic_groups` catalog entry expands a saved row-count controller into indexed widget identities. These use the existing name-keyed registers; no op kind or on-document key changes. The new catalog hash requires coordinated reader adoption. Existing documents retain their original catalog and are re-minted to adopt the new layout. + +Count writes change the projected layout, retaining hidden registers and applying fresh-row defaults only at read time. They do not delete rows or links. Explicit `widgets_values_form` declarations remain authoritative; a count write requiring a new declaration is rejected before mutation. See [DynamicGroup catalog support](dynamic-groups.md) for the producer contract, bounds, and fixture provenance. diff --git a/docs/upstream-pins.json b/docs/upstream-pins.json index 477a64f..a7ba540 100644 --- a/docs/upstream-pins.json +++ b/docs/upstream-pins.json @@ -186,6 +186,24 @@ }, "former_branch_citation": null, "branch_status": "NEVER BRANCH-CITED. Registered directly at the PR head SHA; the PR's branch name is recorded only in the drift note as provenance, never as the citation." + }, + "comfy-cli/widget-catalog@dynamic-group": { + "repo": "https://github.com/Comfy-Org/comfy-cli.git", + "path": "comfy_cli/cql/widget_catalog.py", + "commit": "65769ee31183cd1e1049321c2fb42296f03bf4b5", + "blob_sha1": "5d55445fab9c14d8166069ea72e18cab4ce866af", + "content_sha256": "c392af1660ac0961d43fa108ad1d584e72c41d3a6609605615e94ea60c2e5f6d", + "sections_cited": [ + "build_types", + "build_catalog" + ], + "established_by": "Generated test/fixtures/dynamic-group.json by passing the object_info from tests/comfy_cli/fixtures/dynamic_group.json at this commit to Graph.from_object_info and build_catalog. Read build_types and the relative-name/default expansion; the fixture copies the same commit's empty and populated workflow cases. No output was generated by this package.", + "cited_by": [ + "docs/dynamic-groups.md", + "test/fixtures/dynamic-group.json" + ], + "former_branch_citation": null, + "branch_status": "NEVER BRANCH-CITED. Registered directly at the fixture-generating commit." } } } diff --git a/src/applier.ts b/src/applier.ts index dcc76b2..aacb8b2 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -152,6 +152,7 @@ import { type WireOp, } from "./types.js"; import { addInteriorLinkOrder, removeInteriorLinkOrder } from "./interior-link-order.js"; +import { groupCountRefusal, groupOf, isDynamicGroupField } from "./dynamic-groups.js"; import { optionOwnedWidgets, projectedLength, widgetLayoutForWidgets, widgetOrderForValues, widgetOrderForWidgets } from "./dynamic-combos.js"; import { NODE_INCARNATION_KEY, WRITABLE_NODE_FIELDS } from "./types.js"; @@ -1484,7 +1485,7 @@ function validateWidgetName( // stored and not projected until that option is selected. const widgets = node?.get("widgets"); const order = widgetOrderForWidgets(entry, widgets instanceof Y.Map ? widgets : undefined); - if (widgetIndexOf(order, widget, occurrence) < 0 && !(occurrence === 0 && optionOwnedWidgets(entry).has(widget))) { + if (widgetIndexOf(order, widget, occurrence) < 0 && !(occurrence === 0 && (optionOwnedWidgets(entry).has(widget) || isDynamicGroupField(entry, widget)))) { throw new OpRejectedError( "unknown_widget", `widget '${widget}' not found on ${nodeType}; available: ${order.join(", ") || "(none — all inputs are links)"}`, @@ -1585,6 +1586,8 @@ function isFinalWidgetOccurrence( if (!catalog) return false; const entry = catalogEntry(catalog, String(node.get("type") ?? "")); if (!entry) return false; + // Indexed group field names remain unique while their rows are hidden. + if (occurrence === 0 && isDynamicGroupField(entry, name)) return true; const widgets = node.get("widgets"); const order = widgetOrderForWidgets(entry, widgets instanceof Y.Map ? widgets : undefined); return widgetIndexOf(order, name, occurrence) >= 0 && widgetIndexOf(order, name, occurrence + 1) < 0; @@ -1952,6 +1955,18 @@ function validateWidgetOp(op: SetWidgetOp) { return { interior, promoted }; } +function validateDynamicGroupValue(node: Y.Map, catalog: WidgetCatalog | undefined, widget: string, value: unknown): void { + const entry = catalogEntry(catalog, String(node.get("type") ?? "")); + const refusal = groupCountRefusal(entry, widget, value); + if (refusal) throw new OpRejectedError("malformed_op", refusal); + if (groupOf(entry, widget) && storedWidgetFormOf(node)) { + const widgets = node.get("widgets"); + if (widgets instanceof Y.Map && widgets.get(widgetStorageKey(widget, 0)) !== value) { + throw new OpRejectedError("malformed_op", "row count changes require an updated widgets_values_form declaration"); + } + } +} + function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): SuccessfulOutcome { const { interior, promoted } = validateWidgetOp(op); // Interior paths have several legal spellings (definition id and instance @@ -2003,6 +2018,7 @@ function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): S // than falling through the `if (entry)` block as an accepted write (#13). const occurrence = op.widget_occurrence ?? 0; validateWidgetName(catalog, nodeType, widget, target, occurrence); + validateDynamicGroupValue(target, catalog, widget, op.value); // OWN-property lookup (#13): an inherited key such as `__proto__` must read // as "absent from the catalog", not resolve to a prototype object. const entry = catalogEntry(catalog, nodeType); @@ -2042,6 +2058,7 @@ function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): S rejectIfOpaqueWidgets(node, op.widget); const occurrence = op.widget_occurrence ?? 0; validateWidgetName(catalog, String(node.get("type") ?? ""), op.widget, node, occurrence); + validateDynamicGroupValue(node, catalog, op.widget, op.value); // Top-level writes may extend past the current positional length — comfy-cli // pads with None; here the name-keyed map makes padding a projection concern. mset(widgetsOf(node), widgetStorageKey(op.widget, occurrence), structuredClone(op.value)); diff --git a/src/dynamic-combos.ts b/src/dynamic-combos.ts index 350fe07..e2aec60 100644 --- a/src/dynamic-combos.ts +++ b/src/dynamic-combos.ts @@ -1,5 +1,5 @@ /** - * Selection-aware widget order for `COMFY_DYNAMICCOMBO_V3` inputs. + * Value-dependent widget order for dynamic combos and repeated widget groups. * * A catalog entry's `widget_order` is value-blind: comfy-cli expands every * dynamic combo at its FIRST key. When the entry also carries @@ -17,11 +17,12 @@ * does not depend on the selection either (every option's slots are * accepted), so no op's outcome depends on its arrival order. * - * An entry WITHOUT `dynamic_combos` is returned unchanged everywhere here, so + * An entry without `dynamic_combos` or `dynamic_groups` is unchanged, so * the value-blind behaviour (BE-9176 `_extra_N` placeholders) is untouched. */ import * as Y from "yjs"; +import { groupLayout, isDynamicGroupField } from "./dynamic-groups.js"; import type { DynamicComboEntry, WidgetCatalogEntry } from "./types.js"; import { widgetOccurrenceAt, widgetStorageKey } from "./widget-identity.js"; @@ -32,9 +33,9 @@ function combosOf(entry: WidgetCatalogEntry | undefined): Combos | undefined { return combos && Object.keys(combos).length > 0 ? combos : undefined; } -/** Whether `entry` carries dynamic-combo options, so its order depends on the selection. */ -export function hasDynamicCombos(entry: WidgetCatalogEntry | undefined): boolean { - return combosOf(entry) !== undefined; +/** Whether widget order depends on selectors or row counts. */ +export function hasDynamicWidgetLayout(entry: WidgetCatalogEntry | undefined): boolean { + return combosOf(entry) !== undefined || Object.keys(entry?.dynamic_groups ?? {}).length > 0; } /** Every name some option of some selector owns (any selection, any depth). */ @@ -80,16 +81,23 @@ function expand( const walk = (names: readonly string[], depth: number): void => { for (const name of names) { order.push(name); - if (depth > 32 || !Object.hasOwn(combos, name)) continue; + if (depth > 32) continue; const index = order.length - 1; const stored = valueAt(name, index, widgetOccurrenceAt(order, index)); + const group = groupLayout(entry, name, stored); + if (group) { + group.defaults.forEach((value, child) => defaults.set(child, value)); + order.push(...group.order); + continue; + } + if (!Object.hasOwn(combos, name)) continue; const option = selectedOption(combos[name]!, stored === undefined ? defaults.get(name) : stored); if (!option) continue; for (const [child, value] of Object.entries(option.defaults)) defaults.set(child, value); walk(option.widgets, depth + 1); } }; - walk(entry.widget_order.filter((name) => !owned.has(name)), 0); + walk(entry.widget_order.filter((name) => !owned.has(name) && !isDynamicGroupField(entry, name)), 0); return { order, defaults }; } @@ -97,20 +105,20 @@ function expand( export function widgetOrderForValues(entry: WidgetCatalogEntry | undefined, wv: unknown): readonly string[] | undefined { if (!entry) return undefined; const combos = combosOf(entry); - if (!combos) return entry.widget_order; - if (Array.isArray(wv)) return expand(entry, combos, (_name, index) => wv[index]).order; + if (!hasDynamicWidgetLayout(entry)) return entry.widget_order; + if (Array.isArray(wv)) return expand(entry, combos ?? {}, (_name, index) => wv[index]).order; if (typeof wv === "object" && wv !== null) { const named = wv as Record; - return expand(entry, combos, (name) => (Object.hasOwn(named, name) ? named[name] : undefined)).order; + return expand(entry, combos ?? {}, (name) => (Object.hasOwn(named, name) ? named[name] : undefined)).order; } - return expand(entry, combos, () => undefined).order; + return expand(entry, combos ?? {}, () => undefined).order; } /** The layout for a document node's name-keyed widgets map: order plus read-time defaults. */ export function widgetLayoutForWidgets(entry: WidgetCatalogEntry, widgets: Y.Map | undefined): WidgetLayout { const combos = combosOf(entry); - if (!combos) return { order: entry.widget_order, defaults: new Map() }; - return expand(entry, combos, (name, _index, occurrence) => + if (!hasDynamicWidgetLayout(entry)) return { order: entry.widget_order, defaults: new Map() }; + return expand(entry, combos ?? {}, (name, _index, occurrence) => widgets?.get(widgetStorageKey(name, occurrence)), ); } diff --git a/src/dynamic-groups.ts b/src/dynamic-groups.ts new file mode 100644 index 0000000..a8fd21d --- /dev/null +++ b/src/dynamic-groups.ts @@ -0,0 +1,47 @@ +import { MAX_OVERFLOW_WIDGETS } from "./limits.js"; +import type { WidgetCatalogEntry } from "./types.js"; + +export function groupOf(entry: WidgetCatalogEntry | undefined, name: string) { + const groups = entry?.dynamic_groups; + return groups && Object.hasOwn(groups, name) ? groups[name] : undefined; +} + +export function isDynamicGroupField(entry: WidgetCatalogEntry | undefined, name: string): boolean { + return Object.entries(entry?.dynamic_groups ?? {}).some(([prefix, group]) => { + if (!name.startsWith(`${prefix}.`)) return false; + const suffix = name.slice(prefix.length + 1); + const dot = suffix.indexOf("."); + const index = suffix.slice(0, dot); + return dot > 0 && /^(0|[1-9]\d*)$/.test(index) && Number.isSafeInteger(Number(index)) + && group.widgets.includes(suffix.slice(dot + 1)); + }); +} + +export function groupCountRefusal(entry: WidgetCatalogEntry | undefined, name: string, value: unknown): string | null { + const group = groupOf(entry, name); + if (!group) return null; + if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 + || group.widgets.length === 0 || value > Math.floor(MAX_OVERFLOW_WIDGETS / group.widgets.length)) { + return `${name}: expected a non-negative integer row count within the widget allocation bound`; + } + return null; +} + +export function groupLayout(entry: WidgetCatalogEntry, name: string, value: unknown) { + const group = groupOf(entry, name); + if (!group) return undefined; + const count = value === undefined ? group.min : value; + const refusal = groupCountRefusal(entry, name, count); + if (refusal) throw new TypeError(refusal); + const order: string[] = []; + const defaults = new Map(); + defaults.set(name, group.min); + for (let row = 0; row < (count as number); row++) { + for (const field of group.widgets) { + const child = `${name}.${String(row)}.${field}`; + order.push(child); + if (Object.hasOwn(group.defaults, field)) defaults.set(child, group.defaults[field]); + } + } + return { order, defaults }; +} diff --git a/src/project.ts b/src/project.ts index 39bc234..ac3e866 100644 --- a/src/project.ts +++ b/src/project.ts @@ -48,7 +48,8 @@ import { assertNever } from "./exhaustive.js"; import { projectInteriorLinkOrder } from "./interior-link-order.js"; import { assertReadableSchema } from "./schema-version.js"; import { NODE_INCARNATION_KEY, type WidgetCatalog, type WorkflowJSON, type WorkflowNode } from "./types.js"; -import { hasDynamicCombos, optionOwnedWidgets, projectedLength, widgetLayoutForWidgets } from "./dynamic-combos.js"; +import { isDynamicGroupField } from "./dynamic-groups.js"; +import { hasDynamicWidgetLayout, optionOwnedWidgets, projectedLength, widgetLayoutForWidgets } from "./dynamic-combos.js"; import { widgetIdentityFromStorageKey, widgetOccurrenceAt, widgetStorageKey, widgetIndexOf } from "./widget-identity.js"; import { WIDGET_FORM_FIELD, @@ -143,7 +144,7 @@ function widgetsToPositional( const layout = widgetLayoutForWidgets(entry, widgets); const order = layout.order; const inactive = optionOwnedWidgets(entry); - const selectionDependent = hasDynamicCombos(entry); + const selectionDependent = hasDynamicWidgetLayout(entry); let max = -1; widgets.forEach((_v, storageKey) => { const { name, occurrence } = widgetIdentityFromStorageKey(storageKey); @@ -157,7 +158,7 @@ function widgetsToPositional( const i = occurrence === 0 ? positionalIndexOf(order, name) : widgetIndexOf(order, name, occurrence); // A sub-widget of an option the node does not select owns no slot; its // value is kept for when that option is selected again. - if (i < 0 && inactive.has(name)) return; + if (i < 0 && (inactive.has(name) || isDynamicGroupField(entry, name))) return; // A legacy overflow slot (`_extra_N`) whose position the CURRENT selection // gives to a real name is shadowed: the real name owns that position (its // written value, else its read-time default) and the overflow value stays diff --git a/src/types.ts b/src/types.ts index ee9ef11..4ffa061 100644 --- a/src/types.ts +++ b/src/types.ts @@ -647,6 +647,13 @@ export interface WidgetCatalogEntry { * (see `dynamic-combos.ts`). */ dynamic_combos?: Record; + /** Row-count controllers with relative field names and fresh-row defaults. */ + dynamic_groups?: Record; + }>; } /** One dynamic-combo selector: its fresh-node key and each option's slots. */ diff --git a/test/dynamic-group.test.ts b/test/dynamic-group.test.ts new file mode 100644 index 0000000..a37fbd5 --- /dev/null +++ b/test/dynamic-group.test.ts @@ -0,0 +1,158 @@ +import { readFileSync } from "node:fs"; +import * as Y from "yjs"; +import { describe, expect, it } from "vitest"; +import { applyOps, mint, project, type Op, type TopLevelSetWidgetOp, type WidgetCatalog, type WorkflowJSON } from "../src/index.js"; +import { canonicalize } from "./helpers.js"; +import { assertRejectedWithoutMutation } from "./rejection-test-helpers.js"; + +const fixture = JSON.parse(readFileSync(new URL("./fixtures/dynamic-group.json", import.meta.url), "utf8")) as { + catalog: WidgetCatalog; + cases: Record<"empty" | "populated", WorkflowJSON>; + editing: { ops: Op[]; expected: WorkflowJSON }; +}; +const { catalog, cases } = fixture; +const edit = (widget: string, value: unknown, counter = 1) => ({ + op: "set_widget", node_id: 1, widget, value, + op_id: counter.toString(16).padStart(32, "0"), actor: "agent:a", base_version: counter, stamp: [counter, "agent:a"], +} satisfies TopLevelSetWidgetOp); + +describe("DynamicGroup catalog layout", () => { + it("replays CLI-authored field and trailing-widget edits exactly", () => { + const doc = mint(cases.populated, catalog); + expect(applyOps(doc, fixture.editing.ops, catalog).outcomes.map((o) => o.outcome)).toEqual(["applied", "applied"]); + expect(canonicalize(project(doc, catalog))).toEqual(canonicalize(fixture.editing.expected)); + doc.destroy(); + }); + it.each(["empty", "populated"] as const)("round-trips the %s frontend workflow", (name) => { + const doc = mint(cases[name], catalog); + expect(canonicalize(project(doc, catalog))).toEqual(canonicalize(cases[name])); + doc.destroy(); + }); + + it.each([ + ["loras.1.strength", 0.7, ["head", 2, "A.safetensors", 1, true, "C.safetensors", 0.7, false, "tail"]], + ["after", "edited", ["head", 2, "A.safetensors", 1, true, "C.safetensors", 0.5, false, "edited"]], + ])("edits %s without shifting its siblings", (widget, value, expected) => { + const doc = mint(cases.populated, catalog); + const op = edit(widget as string, value); + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).toBe("applied"); + const node = project(doc, catalog).nodes[0]!; + expect(node.widgets_values).toEqual(expected); + expect(node["widgets_values_named"]).toMatchObject({ [widget as string]: value }); + const beforeRetry = Y.encodeStateAsUpdate(doc); + applyOps(doc, [op], catalog); + expect(Y.encodeStateAsUpdate(doc)).toEqual(beforeRetry); + doc.destroy(); + }); + + it("reads defaults for newly shown rows without shifting the trailing widget", () => { + const doc = mint(cases.empty, catalog); + expect(applyOps(doc, [edit("loras", 1)], catalog).outcomes[0]?.outcome).toBe("applied"); + expect(project(doc, catalog).nodes[0]!.widgets_values).toEqual(["first", 1, "A.safetensors", 1, true, "last"]); + doc.destroy(); + }); + + it("keeps hidden row values when the count changes", () => { + const doc = mint(cases.populated, catalog); + applyOps(doc, [edit("loras", 0)], catalog); + expect(project(doc, catalog).nodes[0]!.widgets_values).toEqual(["head", 0, "tail"]); + applyOps(doc, [edit("loras", 2, 2)], catalog); + expect(project(doc, catalog).nodes[0]!.widgets_values).toEqual(cases.populated.nodes[0]!.widgets_values); + doc.destroy(); + }); + + it("converges when the row count and a row value arrive in either order", () => { + const seed = mint(cases.empty, catalog); + const snapshot = Y.encodeStateAsUpdate(seed); + const ops = [edit("loras", 1), edit("loras.0.strength", 0.7, 2)]; + for (const ordered of [ops, [...ops].reverse()]) { + const doc = new Y.Doc(); + Y.applyUpdate(doc, snapshot); + expect(applyOps(doc, ordered, catalog).outcomes.map((o) => o.outcome)).toEqual(["applied", "applied"]); + expect(project(doc, catalog).nodes[0]!.widgets_values).toEqual(["first", 1, "A.safetensors", 0.7, true, "last"]); + doc.destroy(); + } + seed.destroy(); + }); + + it("keeps named values coherent when a row edit races with hiding that row", () => { + const seed = mint(cases.populated, catalog); + const snapshot = Y.encodeStateAsUpdate(seed); + const ops = [edit("loras", 0), edit("loras.1.strength", 0.7, 2)]; + for (const ordered of [ops, [...ops].reverse()]) { + const doc = new Y.Doc(); + Y.applyUpdate(doc, snapshot); + expect(applyOps(doc, ordered, catalog).outcomes.map((o) => o.outcome)).toEqual(["applied", "applied"]); + applyOps(doc, [edit("loras", 2, 3)], catalog); + const node = project(doc, catalog).nodes[0]!; + expect(node.widgets_values).toEqual(["head", 2, "A.safetensors", 1, true, "C.safetensors", 0.7, false, "tail"]); + expect(node["widgets_values_named"]).toMatchObject({ "loras.1.strength": 0.7 }); + doc.destroy(); + } + seed.destroy(); + }); + + it.each([-1, 1.5, "2", 1_000_000])("refuses unsafe row count %s before writing", (count) => { + assertRejectedWithoutMutation(cases.populated, edit("loras", count), "malformed_op", catalog, + edit("after", "must not run", 2)); + }); + + it("refuses a malformed saved count before minting a misaligned document", () => { + const workflow = structuredClone(cases.populated); + (workflow.nodes[0]!.widgets_values as unknown[])[1] = -1; + expect(() => mint(workflow, catalog)).toThrow(/row count/); + }); + + it("preserves rows above a newer catalog's advertised maximum", () => { + const smaller = structuredClone(catalog); + smaller.types["DevToolsNodeWithDynamicGroup"]!.dynamic_groups!["loras"]!.max = 1; + const doc = mint(cases.populated, smaller); + expect(project(doc, smaller).nodes[0]!.widgets_values).toEqual(cases.populated.nodes[0]!.widgets_values); + applyOps(doc, [edit("loras", 0)], smaller); + expect(project(doc, smaller).nodes[0]!.widgets_values).toEqual(["head", 0, "tail"]); + doc.destroy(); + }); + + it("does not duplicate the default minimum rows in the catalog order", () => { + const minimum = structuredClone(catalog); + const entry = minimum.types["DevToolsNodeWithDynamicGroup"]!; + entry.dynamic_groups!["loras"]!.min = 1; + entry.widget_order = ["before", "loras", "loras.0.lora_name", "loras.0.strength", "loras.0.enabled", "after"]; + const doc = mint(cases.populated, minimum); + expect(project(doc, minimum).nodes[0]!.widgets_values).toEqual(cases.populated.nodes[0]!.widgets_values); + doc.destroy(); + }); + + it("respects an explicit widget form and refuses to silently invalidate its order", () => { + const workflow = structuredClone(cases.populated); + workflow.nodes[0]!["widgets_values_form"] = { order: [ + "before", "loras", "loras.0.lora_name", "loras.0.strength", "loras.0.enabled", + "loras.1.lora_name", "loras.1.strength", "loras.1.enabled", "after", + ] }; + const doc = mint(workflow, catalog); + expect(applyOps(doc, [edit("loras.1.strength", 0.7)], catalog).outcomes[0]?.outcome).toBe("applied"); + expect(project(doc, catalog).nodes[0]!.widgets_values).toEqual([ + "head", 2, "A.safetensors", 1, true, "C.safetensors", 0.7, false, "tail", + ]); + assertRejectedWithoutMutation(workflow, edit("loras", 0), "malformed_op", catalog, + edit("after", "must not run", 2)); + doc.destroy(); + }); + + it("edits interior rows and rejects invalid interior counts without mutation", () => { + const workflow: WorkflowJSON = { + nodes: [{ id: 9, type: "group-definition" }], links: [], + definitions: { subgraphs: [{ id: "group-definition", nodes: cases.populated.nodes, links: [] }] }, + }; + const op: Op = { ...edit("loras.1.strength", 0.7), path: ["9", "1"], inner_widget: "loras.1.strength" }; + const doc = mint(workflow, catalog); + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).toBe("applied"); + const definitions = project(doc, catalog)["definitions"] as { subgraphs: WorkflowJSON[] }; + expect(definitions.subgraphs[0]!.nodes[0]!.widgets_values).toEqual([ + "head", 2, "A.safetensors", 1, true, "C.safetensors", 0.7, false, "tail", + ]); + const invalid: Op = { ...edit("loras", -1), path: ["9", "1"], inner_widget: "loras" }; + assertRejectedWithoutMutation(workflow, invalid, "malformed_op", catalog, { ...op, op_id: "b".repeat(32) }); + doc.destroy(); + }); +}); diff --git a/test/fixtures/dynamic-group.json b/test/fixtures/dynamic-group.json new file mode 100644 index 0000000..a575493 --- /dev/null +++ b/test/fixtures/dynamic-group.json @@ -0,0 +1,336 @@ +{ + "source_commit": "65769ee31183cd1e1049321c2fb42296f03bf4b5", + "catalog": { + "catalog_version": "sha256:52da4957ce9495873344210047eba2f289ccfc8efc603d203ad06643c014b9d4", + "class_count": 1, + "types": { + "DevToolsNodeWithDynamicGroup": { + "widget_order": [ + "before", + "loras", + "after" + ], + "dynamic_groups": { + "loras": { + "min": 0, + "max": 3, + "widgets": [ + "lora_name", + "strength", + "enabled" + ], + "defaults": { + "lora_name": "A.safetensors", + "strength": 1.0, + "enabled": true + } + } + } + } + } + }, + "cases": { + "empty": { + "nodes": [ + { + "id": 1, + "type": "DevToolsNodeWithDynamicGroup", + "pos": [ + 100, + 150 + ], + "size": [ + 350, + 140 + ], + "flags": {}, + "order": 0, + "mode": 0, + "inputs": [], + "outputs": [ + { + "name": "rows", + "type": "STRING", + "links": [] + } + ], + "properties": { + "Node name for S&R": "DevToolsNodeWithDynamicGroup" + }, + "widgets_values": [ + "first", + 0, + "last" + ] + } + ], + "links": [] + }, + "populated": { + "nodes": [ + { + "id": 1, + "type": "DevToolsNodeWithDynamicGroup", + "pos": [ + 100, + 150 + ], + "size": [ + 350, + 106 + ], + "flags": {}, + "order": 0, + "mode": 0, + "inputs": [ + { + "label": "LoRA #1 lora_name", + "localized_name": "LoRA #1 lora_name", + "name": "loras.0.lora_name", + "type": "COMBO", + "widget": { + "name": "loras.0.lora_name" + }, + "link": null + }, + { + "label": "LoRA #1 strength", + "localized_name": "LoRA #1 strength", + "name": "loras.0.strength", + "type": "FLOAT", + "widget": { + "name": "loras.0.strength" + }, + "link": null + }, + { + "label": "LoRA #1 enabled", + "localized_name": "LoRA #1 enabled", + "name": "loras.0.enabled", + "shape": 7, + "type": "BOOLEAN", + "widget": { + "name": "loras.0.enabled" + }, + "link": null + }, + { + "label": "LoRA #2 lora_name", + "localized_name": "LoRA #2 lora_name", + "name": "loras.1.lora_name", + "type": "COMBO", + "widget": { + "name": "loras.1.lora_name" + }, + "link": null + }, + { + "label": "LoRA #2 strength", + "localized_name": "LoRA #2 strength", + "name": "loras.1.strength", + "type": "FLOAT", + "widget": { + "name": "loras.1.strength" + }, + "link": null + }, + { + "label": "LoRA #2 enabled", + "localized_name": "LoRA #2 enabled", + "name": "loras.1.enabled", + "shape": 7, + "type": "BOOLEAN", + "widget": { + "name": "loras.1.enabled" + }, + "link": null + } + ], + "outputs": [ + { + "localized_name": "rows", + "name": "rows", + "type": "STRING", + "links": [] + } + ], + "properties": { + "Node name for S&R": "DevToolsNodeWithDynamicGroup" + }, + "widgets_values": [ + "head", + 2, + "A.safetensors", + 1, + true, + "C.safetensors", + 0.5, + false, + "tail" + ], + "widgets_values_named": { + "before": "head", + "loras": 2, + "loras.0.lora_name": "A.safetensors", + "loras.0.strength": 1, + "loras.0.enabled": true, + "loras.1.lora_name": "C.safetensors", + "loras.1.strength": 0.5, + "loras.1.enabled": false, + "after": "tail" + } + } + ], + "links": [] + } + }, + "editing": { + "ops": [ + { + "op": "set_widget", + "op_id": "813921d971aa439ea121b13f00904192", + "actor": "agent:dynamic-group-probe", + "base_version": 0, + "stamp": [ + 0, + "agent:dynamic-group-probe" + ], + "node_id": 1, + "widget": "loras.1.strength", + "value": 0.7, + "old": 0.5 + }, + { + "op": "set_widget", + "op_id": "c3e0f30f0a9a4978ba0c37ad8e34c9e5", + "actor": "agent:dynamic-group-probe", + "base_version": 1, + "stamp": [ + 1, + "agent:dynamic-group-probe" + ], + "node_id": 1, + "widget": "after", + "value": "edited tail", + "old": "tail" + } + ], + "expected": { + "nodes": [ + { + "id": 1, + "type": "DevToolsNodeWithDynamicGroup", + "pos": [ + 100, + 150 + ], + "size": [ + 350, + 106 + ], + "flags": {}, + "order": 0, + "mode": 0, + "inputs": [ + { + "label": "LoRA #1 lora_name", + "localized_name": "LoRA #1 lora_name", + "name": "loras.0.lora_name", + "type": "COMBO", + "widget": { + "name": "loras.0.lora_name" + }, + "link": null + }, + { + "label": "LoRA #1 strength", + "localized_name": "LoRA #1 strength", + "name": "loras.0.strength", + "type": "FLOAT", + "widget": { + "name": "loras.0.strength" + }, + "link": null + }, + { + "label": "LoRA #1 enabled", + "localized_name": "LoRA #1 enabled", + "name": "loras.0.enabled", + "shape": 7, + "type": "BOOLEAN", + "widget": { + "name": "loras.0.enabled" + }, + "link": null + }, + { + "label": "LoRA #2 lora_name", + "localized_name": "LoRA #2 lora_name", + "name": "loras.1.lora_name", + "type": "COMBO", + "widget": { + "name": "loras.1.lora_name" + }, + "link": null + }, + { + "label": "LoRA #2 strength", + "localized_name": "LoRA #2 strength", + "name": "loras.1.strength", + "type": "FLOAT", + "widget": { + "name": "loras.1.strength" + }, + "link": null + }, + { + "label": "LoRA #2 enabled", + "localized_name": "LoRA #2 enabled", + "name": "loras.1.enabled", + "shape": 7, + "type": "BOOLEAN", + "widget": { + "name": "loras.1.enabled" + }, + "link": null + } + ], + "outputs": [ + { + "localized_name": "rows", + "name": "rows", + "type": "STRING", + "links": [] + } + ], + "properties": { + "Node name for S&R": "DevToolsNodeWithDynamicGroup" + }, + "widgets_values": [ + "head", + 2, + "A.safetensors", + 1, + true, + "C.safetensors", + 0.7, + false, + "edited tail" + ], + "widgets_values_named": { + "before": "head", + "loras": 2, + "loras.0.lora_name": "A.safetensors", + "loras.0.strength": 1, + "loras.0.enabled": true, + "loras.1.lora_name": "C.safetensors", + "loras.1.strength": 0.7, + "loras.1.enabled": false, + "after": "edited tail" + } + } + ], + "links": [] + } + } +} From c26ca2d795f4c63d95906d92007e629997079eb6 Mon Sep 17 00:00:00 2001 From: jaeone94 <89377375+jaeone94@users.noreply.github.com> Date: Sat, 10 Oct 2026 15:23:46 +0900 Subject: [PATCH 02/10] fix: reject ambiguous DynamicGroup document layouts --- docs/dynamic-groups.md | 42 +- docs/upstream-pins.json | 18 + src/applier.ts | 1 + src/dynamic-combos.ts | 16 +- src/dynamic-groups.ts | 58 ++- test/dynamic-group.test.ts | 154 ++++++- test/fixtures/dynamic-group-composite.json | 457 +++++++++++++++++++++ 7 files changed, 733 insertions(+), 13 deletions(-) create mode 100644 test/fixtures/dynamic-group-composite.json diff --git a/docs/dynamic-groups.md b/docs/dynamic-groups.md index 68e99e3..bc807bd 100644 --- a/docs/dynamic-groups.md +++ b/docs/dynamic-groups.md @@ -8,8 +8,48 @@ To regenerate `test/fixtures/dynamic-group.json` at that revision, load `tests/c The catalog controls layout, not prompt validity. Saved rows above an advertised `max` are retained; CLI/core validation decides whether they can execute. Counts must be non-negative safe integers and cannot expand a group beyond the existing `MAX_OVERFLOW_WIDGETS` allocation bound. -Like dynamic-combo selections, count changes only change projection. Fields in hidden rows retain their name-keyed registers, and newly visible fields without a stored value show template defaults. This avoids receiver-side writes whose outcome depends on op arrival order (KA-2, KA-4). It is not a destructive row-delete operation: deleting a row and its links is a separate producer responsibility. +Like dynamic-combo selections, count changes only change projection. Fields in hidden rows retain their name-keyed registers, and newly visible fields without a stored value show template defaults. This avoids receiver-side writes whose outcome depends on op arrival order (KA-2, KA-4). This is not a live structural row operation: it does not remove a middle row, reindex surviving identities, or update connections and promotions. Those changes require the separate atomic row-operation protocol. An explicit `widgets_values_form` remains authoritative. Existing row fields can be edited through it; a count change that requires replacing that declaration is refused before mutation. This PR does not introduce an op for changing producer-owned forms. No wire key or op kind changes. New catalog content changes the catalog hash. Consumers must adopt this reader before receiving a DynamicGroup catalog; old documents remain tied to their original catalog and must be re-minted to adopt a new layout (KA-11, KA-12, FC-10). + +## Namespace safety + +Relative group fields must be distinct. A controller cannot also be a DynamicCombo selector or another group's row field. Each source widget order may declare a controller once, and any generated names already present must be its contiguous minimum-row block. The selected layout also refuses duplicate generated fields/controllers before they can share a register. Ordinary duplicate names keep their existing occurrence identities; unrelated dotted names are not rejected merely for sharing a group prefix. Seed companions such as `weights.0.seed.0` remain legal when declared by the template metadata. + +## Reader and producer adoption + +The released reader `0.3.10` and this draft both use schema v5. The schema gate and a catalog hash do **not** prove that an old reader understands `dynamic_groups`. An offline probe with the CLI composite fixture demonstrated that the old reader can mint a new positional workflow, acknowledge an `after` edit, and write that value into the first row's enabled position while leaving the real trailing value unchanged. Omitting group metadata produces the same unsupported mapping even with the current reader. + +| Producer declaration | Reader/catalog combination | Supported scope | +| --- | --- | --- | +| Positional array without a node-local form | Complete group metadata plus this reader | Existing field edits and lossless projection, including two groups, a nondefault DynamicCombo, trailing widgets, and seed companions. | +| Positional array without a node-local form | Released `0.3.10`, or group metadata omitted | Unsupported: trailing writes can target a row value. Schema v5 does not reject this combination. | +| Explicit `widgets_values_form` | Either reader, group metadata omitted | Existing field edits retain the declared mapping. Count changes are not safe live row operations. | +| Explicit `widgets_values_form` | This reader plus complete group metadata | Existing field edits work; count changes requiring a new declaration are refused before mutation. | + +Deploy the producer, complete catalog, package reader, and document host together. Re-mint source workflows when adopting the new pinned catalog. The caller owns compatibility admission; this package cannot recognize missing metadata as a DynamicGroup without guessing. Full Agent row insertion/deletion, declarations, connections, promotions, and convergence remain blocked on the separate atomic row-operation protocol. + +`test/fixtures/dynamic-group-composite.json` records an actual CLI capture from the main-merged working tree. Its implemented producer is pinned at [comfy-cli `acc3b822d428db6c8572dd056bbb58ee217ed77b`](https://github.com/Comfy-Org/comfy-cli/blob/acc3b822d428db6c8572dd056bbb58ee217ed77b/comfy_cli/cql/widget_catalog.py), with `build_types` and `build_catalog` registered in `docs/upstream-pins.json`. The fixture records the capture base and the committed safety follow-up separately. A committed revision is not a released deployment; adopt compatible producer and reader pins together (KA-11, KA-12, FC-10). + +To reproduce the trailing-write probe from this checkout, set `CMP_READER` to the released `0.3.10` package's `dist/index.js`, then repeat with this branch's built `dist/index.js`: + +```sh +CMP_READER=/absolute/path/to/dist/index.js node --input-type=module <<'JS' +import { readFileSync } from "node:fs"; +import { pathToFileURL } from "node:url"; +const reader = await import(pathToFileURL(process.env.CMP_READER).href); +const fixture = JSON.parse(readFileSync("test/fixtures/dynamic-group-composite.json", "utf8")); +const doc = reader.mint(fixture.workflow, fixture.catalog, fixture.catalog.catalog_version); +try { + const op = { ...fixture.op, widget: "after", value: "edited tail" }; + console.log(reader.applyOps(doc, [op], fixture.catalog).outcomes); + console.log(reader.project(doc, fixture.catalog).nodes[0].widgets_values); +} finally { + doc.destroy(); +} +JS +``` + +The released reader acknowledges the write at position 4, replacing the enabled value. This reader edits the final `tail` position. Both readers accept an existing-field edit with the fixture's explicit form; that is a separate supported path, not evidence of live row-resize support. diff --git a/docs/upstream-pins.json b/docs/upstream-pins.json index a7ba540..9a5af6e 100644 --- a/docs/upstream-pins.json +++ b/docs/upstream-pins.json @@ -204,6 +204,24 @@ ], "former_branch_citation": null, "branch_status": "NEVER BRANCH-CITED. Registered directly at the fixture-generating commit." + }, + "comfy-cli/widget-catalog@dynamic-group-safety": { + "repo": "https://github.com/Comfy-Org/comfy-cli.git", + "path": "comfy_cli/cql/widget_catalog.py", + "commit": "acc3b822d428db6c8572dd056bbb58ee217ed77b", + "blob_sha1": "5d55445fab9c14d8166069ea72e18cab4ce866af", + "content_sha256": "c392af1660ac0961d43fa108ad1d584e72c41d3a6609605615e94ea60c2e5f6d", + "sections_cited": [ + "build_types", + "build_catalog" + ], + "established_by": "Captured test/fixtures/dynamic-group-composite.json using Graph.from_object_info, build_catalog, and workflow_ops.set_widget from the main-merged PR #973 working tree based on 69cfb0070f82eb2491f0fe0d5ab238b8167a49d2. The local namespace/form safety changes were then committed and pushed as acc3b822d428db6c8572dd056bbb58ee217ed77b. Re-read build_types and build_catalog at that committed revision; their byte-identical widget_catalog.py blob matches the original DynamicGroup pin, while the producer safety changes are in engine.py. Expected workflow/op results were generated by the CLI, not this package. This is an immutable source pin, not evidence of a released deployment.", + "cited_by": [ + "docs/dynamic-groups.md", + "test/fixtures/dynamic-group-composite.json" + ], + "former_branch_citation": null, + "branch_status": "NEVER BRANCH-CITED. Registered at the committed producer safety follow-up; rollout still requires coordinated consumer adoption." } } } diff --git a/src/applier.ts b/src/applier.ts index aacb8b2..e424700 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -1901,6 +1901,7 @@ function applyPromotedHostWrite( const occurrence = op.widget_occurrence ?? 0; requirePromotedFormAgreement(target, op.widget, occurrence, promoted.valueIndex); validateWidgetName(catalog, String(target.get("type") ?? ""), op.widget, target, occurrence); + validateDynamicGroupValue(target, catalog, op.widget, op.value); mset(widgetsOf(target), widgetStorageKey(op.widget, occurrence), structuredClone(op.value)); updateOrderedWidgetValue(target, op.widget, occurrence, op.value); updateNamedWidgetValue(target, catalog, op.widget, occurrence, op.value); diff --git a/src/dynamic-combos.ts b/src/dynamic-combos.ts index e2aec60..e537a5b 100644 --- a/src/dynamic-combos.ts +++ b/src/dynamic-combos.ts @@ -22,7 +22,7 @@ */ import * as Y from "yjs"; -import { groupLayout, isDynamicGroupField } from "./dynamic-groups.js"; +import { assertDynamicGroupCatalog, groupLayout, groupOf, isDynamicGroupField } from "./dynamic-groups.js"; import type { DynamicComboEntry, WidgetCatalogEntry } from "./types.js"; import { widgetOccurrenceAt, widgetStorageKey } from "./widget-identity.js"; @@ -75,19 +75,29 @@ function expand( combos: Combos, valueAt: (name: string, index: number, occurrence: number) => unknown, ): WidgetLayout { + assertDynamicGroupCatalog(entry); const owned = optionOwnedWidgets(entry); const order: string[] = []; + const seen = new Set(); const defaults = new Map(); + const append = (name: string): void => { + if (seen.has(name) && (groupOf(entry, name) || isDynamicGroupField(entry, name))) { + const kind = groupOf(entry, name) ? "controller" : "field"; + throw new TypeError(`DynamicGroup ${kind} '${name}' is duplicated in the selected layout`); + } + order.push(name); + seen.add(name); + }; const walk = (names: readonly string[], depth: number): void => { for (const name of names) { - order.push(name); + append(name); if (depth > 32) continue; const index = order.length - 1; const stored = valueAt(name, index, widgetOccurrenceAt(order, index)); const group = groupLayout(entry, name, stored); if (group) { group.defaults.forEach((value, child) => defaults.set(child, value)); - order.push(...group.order); + group.order.forEach(append); continue; } if (!Object.hasOwn(combos, name)) continue; diff --git a/src/dynamic-groups.ts b/src/dynamic-groups.ts index a8fd21d..cdbf7d6 100644 --- a/src/dynamic-groups.ts +++ b/src/dynamic-groups.ts @@ -6,15 +6,57 @@ export function groupOf(entry: WidgetCatalogEntry | undefined, name: string) { return groups && Object.hasOwn(groups, name) ? groups[name] : undefined; } +function isGroupField(prefix: string, fields: readonly string[], name: string): boolean { + if (!name.startsWith(`${prefix}.`)) return false; + const suffix = name.slice(prefix.length + 1); + const dot = suffix.indexOf("."); + const index = suffix.slice(0, dot); + return dot > 0 && /^(0|[1-9]\d*)$/.test(index) && Number.isSafeInteger(Number(index)) + && fields.includes(suffix.slice(dot + 1)); +} + export function isDynamicGroupField(entry: WidgetCatalogEntry | undefined, name: string): boolean { - return Object.entries(entry?.dynamic_groups ?? {}).some(([prefix, group]) => { - if (!name.startsWith(`${prefix}.`)) return false; - const suffix = name.slice(prefix.length + 1); - const dot = suffix.indexOf("."); - const index = suffix.slice(0, dot); - return dot > 0 && /^(0|[1-9]\d*)$/.test(index) && Number.isSafeInteger(Number(index)) - && group.widgets.includes(suffix.slice(dot + 1)); - }); + return Object.entries(entry?.dynamic_groups ?? {}).some(([prefix, group]) => isGroupField(prefix, group.widgets, name)); +} + +function assertDynamicGroupOrder(entry: WidgetCatalogEntry, name: string, order: readonly string[]): boolean { + const group = groupOf(entry, name)!; + const controllerIndex = order.indexOf(name); + if (controllerIndex !== order.lastIndexOf(name)) { + throw new TypeError(`DynamicGroup controller '${name}' is duplicated in widget order`); + } + const generated = order.filter((widget) => isGroupField(name, group.widgets, widget)); + if (generated.length === 0) return controllerIndex >= 0; + const minimum = groupLayout(entry, name, group.min)!.order; + if (controllerIndex < 0 || generated.length !== minimum.length + || minimum.some((widget, index) => generated[index] !== widget || order[controllerIndex + 1 + index] !== widget)) { + throw new TypeError(`DynamicGroup '${name}' generated widget names collide with its minimum-row layout`); + } + return controllerIndex >= 0; +} + +export function assertDynamicGroupCatalog(entry: WidgetCatalogEntry): void { + const groups = Object.entries(entry.dynamic_groups ?? {}); + if (groups.length === 0) return; + const orders = [entry.widget_order, ...Object.values(entry.dynamic_combos ?? {}).flatMap((combo) => + Object.values(combo.options).map((option) => option.widgets), + )]; + for (const [name, group] of groups) { + if (!Array.isArray(group.widgets) || group.widgets.length === 0 + || group.widgets.some((field) => typeof field !== "string" || field.length === 0) + || new Set(group.widgets).size !== group.widgets.length) { + throw new TypeError(`DynamicGroup '${name}' must declare distinct nonempty relative widget names`); + } + if (Object.hasOwn(entry.dynamic_combos ?? {}, name) || isDynamicGroupField(entry, name)) { + throw new TypeError(`DynamicGroup controller '${name}' collides with another dynamic widget`); + } + let controllerFound = false; + for (const order of orders) { + const present = assertDynamicGroupOrder(entry, name, order); + controllerFound ||= present; + } + if (!controllerFound) throw new TypeError(`DynamicGroup controller '${name}' is missing from widget order`); + } } export function groupCountRefusal(entry: WidgetCatalogEntry | undefined, name: string, value: unknown): string | null { diff --git a/test/dynamic-group.test.ts b/test/dynamic-group.test.ts index a37fbd5..85f2325 100644 --- a/test/dynamic-group.test.ts +++ b/test/dynamic-group.test.ts @@ -1,7 +1,7 @@ import { readFileSync } from "node:fs"; import * as Y from "yjs"; import { describe, expect, it } from "vitest"; -import { applyOps, mint, project, type Op, type TopLevelSetWidgetOp, type WidgetCatalog, type WorkflowJSON } from "../src/index.js"; +import { applyOps, mint, project, type Op, type TopLevelSetWidgetOp, type WidgetCatalog, type WidgetCatalogEntry, type WorkflowJSON } from "../src/index.js"; import { canonicalize } from "./helpers.js"; import { assertRejectedWithoutMutation } from "./rejection-test-helpers.js"; @@ -11,12 +11,122 @@ const fixture = JSON.parse(readFileSync(new URL("./fixtures/dynamic-group.json", editing: { ops: Op[]; expected: WorkflowJSON }; }; const { catalog, cases } = fixture; +const composite = JSON.parse(readFileSync(new URL("./fixtures/dynamic-group-composite.json", import.meta.url), "utf8")) as { + catalog: WidgetCatalog; + workflow: WorkflowJSON; + op: TopLevelSetWidgetOp; + expected_workflow: WorkflowJSON; + explicit_form_workflow: WorkflowJSON; + standalone_count_op: TopLevelSetWidgetOp; +}; +const groupEntry = catalog.types["DevToolsNodeWithDynamicGroup"]!; +const loras = groupEntry.dynamic_groups!["loras"]!; const edit = (widget: string, value: unknown, counter = 1) => ({ op: "set_widget", node_id: 1, widget, value, op_id: counter.toString(16).padStart(32, "0"), actor: "agent:a", base_version: counter, stamp: [counter, "agent:a"], } satisfies TopLevelSetWidgetOp); describe("DynamicGroup catalog layout", () => { + it.each([ + ["duplicate controller", { ...groupEntry, widget_order: ["before", "loras", "loras", "after"] }], + ["duplicate relative field", { ...groupEntry, dynamic_groups: { loras: { ...loras, widgets: ["strength", "strength"] } } }], + ["ordinary generated-name alias", { ...groupEntry, widget_order: ["before", "loras", "after", "loras.0.strength"] }], + ["duplicate minimum-row field", { + ...groupEntry, + widget_order: ["before", "loras", "loras.0.lora_name", "loras.0.strength", "loras.0.enabled", "loras.0.strength", "after"], + dynamic_groups: { loras: { ...loras, min: 1 } }, + }], + ["misplaced minimum-row field", { + ...groupEntry, + widget_order: ["loras.0.lora_name", "before", "loras", "loras.0.strength", "loras.0.enabled", "after"], + dynamic_groups: { loras: { ...loras, min: 1 } }, + }], + ["controller also used by DynamicCombo", { + ...groupEntry, + dynamic_combos: { loras: { default: "none", options: { none: { widgets: [], defaults: {} } } } }, + }], + ["missing controller", { ...groupEntry, widget_order: ["before", "after"] }], + ["other group controller aliases a row field", { + ...groupEntry, + widget_order: ["before", "loras", "loras.0.strength", "after"], + dynamic_groups: { ...groupEntry.dynamic_groups, "loras.0.strength": { min: 0, max: 3, widgets: ["value"], defaults: { value: 1 } } }, + }], + ] satisfies [string, WidgetCatalogEntry][])("refuses %s catalog metadata before naming values", (_label, entry) => { + const malformed = structuredClone(catalog); + malformed.types["DevToolsNodeWithDynamicGroup"] = entry; + const workflow = structuredClone(cases.empty); + workflow.nodes[0]!.widgets_values = { before: "first", loras: 0, after: "last" }; + + expect(() => mint(workflow, malformed)).toThrow(/DynamicGroup/); + }); + + it("refuses a malformed catalog on projection or apply without changing the document", () => { + const doc = mint(cases.populated, catalog); + const malformed = structuredClone(catalog); + malformed.types["DevToolsNodeWithDynamicGroup"]!.dynamic_groups!["loras"]!.widgets.push("strength"); + const op = edit("after", "must not land"); + const trailing = edit("before", "must not land either", 2); + const before = Y.encodeStateAsUpdate(doc); + + expect(() => project(doc, malformed)).toThrow(/DynamicGroup/); + expect(applyOps(doc, [op, trailing], malformed).outcomes).toMatchObject([ + { outcome: "rejected", reason: { code: "apply_failed" } }, + { outcome: "rejected", reason: { code: "batch_aborted" } }, + ]); + expect(applyOps(doc, [op], malformed).outcomes[0]).toMatchObject({ outcome: "rejected", reason: { code: "apply_failed" } }); + expect(Y.encodeStateAsUpdate(doc)).toEqual(before); + expect(doc.getMap("__applied").has(op.op_id)).toBe(false); + expect(doc.getMap("__applied").has(trailing.op_id)).toBe(false); + expect(project(doc, catalog).nodes[0]!.widgets_values).toEqual(cases.populated.nodes[0]!.widgets_values); + doc.destroy(); + }); + + it("keeps ordinary duplicate occurrences and unrelated dotted names distinct", () => { + const duplicateCatalog = structuredClone(catalog); + duplicateCatalog.types["DevToolsNodeWithDynamicGroup"]!.widget_order = ["before", "before", "loras", "loras.note", "after", "after"]; + const workflow = structuredClone(cases.empty); + delete workflow.nodes[0]!["widgets_values_named"]; + workflow.nodes[0]!.widgets_values = ["first", "second", 1, "A.safetensors", 1, true, "ordinary dotted value", "tail one", "tail two"]; + const doc = mint(workflow, duplicateCatalog); + + expect(project(doc, duplicateCatalog).nodes[0]!.widgets_values).toEqual(workflow.nodes[0]!.widgets_values); + expect(applyOps(doc, [{ ...edit("before", "edited second"), widget_occurrence: 1 }], duplicateCatalog).outcomes[0]?.outcome).toBe("applied"); + expect(project(doc, duplicateCatalog).nodes[0]!.widgets_values).toEqual(["first", "edited second", 1, "A.safetensors", 1, true, "ordinary dotted value", "tail one", "tail two"]); + doc.destroy(); + }); + + it("round-trips the CLI two-group, nondefault-combo, seed-companion composition and replays its field edit", () => { + const doc = mint(composite.workflow, composite.catalog); + expect(canonicalize(project(doc, composite.catalog))).toEqual(canonicalize(composite.workflow)); + + expect(applyOps(doc, [composite.op], composite.catalog).outcomes[0]?.outcome).toBe("applied"); + expect(canonicalize(project(doc, composite.catalog))).toEqual(canonicalize(composite.expected_workflow)); + const beforeRetry = Y.encodeStateAsUpdate(doc); + applyOps(doc, [composite.op], composite.catalog); + expect(Y.encodeStateAsUpdate(doc)).toEqual(beforeRetry); + doc.destroy(); + }); + + it("uses an explicit producer form for existing field edits without group metadata", () => { + const withoutGroups = structuredClone(composite.catalog); + delete withoutGroups.types["CompositeDynamicGroup"]!.dynamic_groups; + const doc = mint(composite.explicit_form_workflow, withoutGroups); + + expect(applyOps(doc, [composite.op], withoutGroups).outcomes[0]?.outcome).toBe("applied"); + const expected = structuredClone(composite.expected_workflow); + expected.nodes[0]!.widgets_values_form = composite.explicit_form_workflow.nodes[0]!.widgets_values_form; + expect(canonicalize(project(doc, withoutGroups))).toEqual(canonicalize(expected)); + doc.destroy(); + }); + + it("refuses the CLI standalone count op when replay cannot update the producer form", () => { + const workflow = structuredClone(composite.explicit_form_workflow); + const before = structuredClone(workflow); + assertRejectedWithoutMutation(workflow, composite.standalone_count_op, + "malformed_op", composite.catalog, { ...composite.op, op_id: "d".repeat(32) }); + expect(workflow).toEqual(before); + }); + it("replays CLI-authored field and trailing-widget edits exactly", () => { const doc = mint(cases.populated, catalog); expect(applyOps(doc, fixture.editing.ops, catalog).outcomes.map((o) => o.outcome)).toEqual(["applied", "applied"]); @@ -139,6 +249,48 @@ describe("DynamicGroup catalog layout", () => { doc.destroy(); }); + it.each([0, -1])("refuses promoted count %s without invalidating the declared row form", (count) => { + const workflow = structuredClone(cases.populated); + workflow.nodes[0]!.widgets_values_form = { order: [ + "before", "loras", "loras.0.lora_name", "loras.0.strength", "loras.0.enabled", + "loras.1.lora_name", "loras.1.strength", "loras.1.enabled", "after", + ] }; + const op: TopLevelSetWidgetOp = { + ...edit("loras", count), + promoted: { + value_index: 1, instance_path: ["1"], + host_widgets_values: ["head", count, "A.safetensors", 1, true, "C.safetensors", 0.5, false, "tail"], + }, + }; + assertRejectedWithoutMutation(workflow, op, "malformed_op", catalog, + edit("after", "must not run", 2)); + }); + + it("preserves promoted ordinary row field edits through the declared form", () => { + const workflow = structuredClone(cases.populated); + workflow.nodes[0]!.widgets_values_form = { order: [ + "before", "loras", "loras.0.lora_name", "loras.0.strength", "loras.0.enabled", + "loras.1.lora_name", "loras.1.strength", "loras.1.enabled", "after", + ] }; + const op: TopLevelSetWidgetOp = { + ...edit("loras.1.strength", 0.7), + promoted: { + value_index: 6, instance_path: ["1"], + host_widgets_values: ["head", 2, "A.safetensors", 1, true, "C.safetensors", 0.7, false, "tail"], + }, + }; + const doc = mint(workflow, catalog); + + expect(applyOps(doc, [op], catalog).outcomes[0]?.outcome).toBe("applied"); + const node = project(doc, catalog).nodes[0]!; + expect(node.widgets_values).toEqual(["head", 2, "A.safetensors", 1, true, "C.safetensors", 0.7, false, "tail"]); + expect(node.widgets_values_form).toEqual(workflow.nodes[0]!.widgets_values_form); + const beforeRetry = Y.encodeStateAsUpdate(doc); + applyOps(doc, [op], catalog); + expect(Y.encodeStateAsUpdate(doc)).toEqual(beforeRetry); + doc.destroy(); + }); + it("edits interior rows and rejects invalid interior counts without mutation", () => { const workflow: WorkflowJSON = { nodes: [{ id: 9, type: "group-definition" }], links: [], diff --git a/test/fixtures/dynamic-group-composite.json b/test/fixtures/dynamic-group-composite.json new file mode 100644 index 0000000..c82285d --- /dev/null +++ b/test/fixtures/dynamic-group-composite.json @@ -0,0 +1,457 @@ +{ + "provenance": { + "repo": "https://github.com/Comfy-Org/comfy-cli", + "base_commit": "69cfb0070f82eb2491f0fe0d5ab238b8167a49d2", + "capture": "Graph.from_object_info + widget_catalog.build_catalog + workflow_ops.set_widget, captured from the PR #973 working tree based on the main-merge commit before its safety changes were committed as producer_commit on 2026-10-10. This records a committed producer revision, not a released package version.", + "producer_commit": "acc3b822d428db6c8572dd056bbb58ee217ed77b" + }, + "catalog": { + "catalog_version": "sha256:cb2331dec98aa715eed8f7f4527e9bf49fb681f7fc5edbcc20f9162efa5afbab", + "class_count": 2, + "types": { + "CompositeDynamicGroup": { + "widget_order": [ + "before", + "loras", + "mode", + "weights", + "after" + ], + "dynamic_combos": { + "mode": { + "default": "basic", + "options": { + "basic": { + "widgets": [], + "defaults": {} + }, + "advanced": { + "widgets": [ + "mode.steps" + ], + "defaults": { + "mode.steps": 4 + } + } + } + } + }, + "dynamic_groups": { + "loras": { + "min": 0, + "max": 3, + "widgets": [ + "lora_name", + "strength", + "enabled" + ], + "defaults": { + "lora_name": "A.safetensors", + "strength": 1.0, + "enabled": true + } + }, + "weights": { + "min": 0, + "max": 3, + "widgets": [ + "seed", + "seed.0", + "weight" + ], + "defaults": { + "seed": 5, + "seed.0": "fixed", + "weight": 1 + } + } + } + }, + "DevToolsNodeWithDynamicGroup": { + "widget_order": [ + "before", + "loras", + "after" + ], + "dynamic_groups": { + "loras": { + "min": 0, + "max": 3, + "widgets": [ + "lora_name", + "strength", + "enabled" + ], + "defaults": { + "lora_name": "A.safetensors", + "strength": 1.0, + "enabled": true + } + } + } + } + } + }, + "workflow": { + "nodes": [ + { + "id": 1, + "type": "CompositeDynamicGroup", + "pos": [ + 100, + 150 + ], + "size": [ + 350, + 106 + ], + "flags": {}, + "order": 0, + "mode": 0, + "inputs": [], + "outputs": [ + { + "localized_name": "rows", + "name": "rows", + "type": "STRING", + "links": [] + } + ], + "properties": { + "Node name for S&R": "CompositeDynamicGroup" + }, + "widgets_values": [ + "head", + 2, + "A.safetensors", + 1, + true, + "C.safetensors", + 0.5, + false, + "advanced", + 7, + 1, + 5, + "fixed", + 0.25, + "tail" + ], + "widgets_values_named": { + "before": "head", + "loras": 2, + "loras.0.lora_name": "A.safetensors", + "loras.0.strength": 1, + "loras.0.enabled": true, + "loras.1.lora_name": "C.safetensors", + "loras.1.strength": 0.5, + "loras.1.enabled": false, + "mode": "advanced", + "mode.steps": 7, + "weights": 1, + "weights.0.seed": 5, + "weights.0.seed.0": "fixed", + "weights.0.weight": 0.25, + "after": "tail" + } + } + ], + "links": [] + }, + "op": { + "op": "set_widget", + "op_id": "9078cec4400a4b1d8dc6f786c019c77c", + "actor": "cli", + "base_version": 0, + "stamp": [ + 0, + "cli" + ], + "node_id": 1, + "widget": "weights.0.weight", + "value": 0.9, + "old": 0.25 + }, + "expected_workflow": { + "nodes": [ + { + "id": 1, + "type": "CompositeDynamicGroup", + "pos": [ + 100, + 150 + ], + "size": [ + 350, + 106 + ], + "flags": {}, + "order": 0, + "mode": 0, + "inputs": [], + "outputs": [ + { + "localized_name": "rows", + "name": "rows", + "type": "STRING", + "links": [] + } + ], + "properties": { + "Node name for S&R": "CompositeDynamicGroup" + }, + "widgets_values": [ + "head", + 2, + "A.safetensors", + 1, + true, + "C.safetensors", + 0.5, + false, + "advanced", + 7, + 1, + 5, + "fixed", + 0.9, + "tail" + ], + "widgets_values_named": { + "before": "head", + "loras": 2, + "loras.0.lora_name": "A.safetensors", + "loras.0.strength": 1, + "loras.0.enabled": true, + "loras.1.lora_name": "C.safetensors", + "loras.1.strength": 0.5, + "loras.1.enabled": false, + "mode": "advanced", + "mode.steps": 7, + "weights": 1, + "weights.0.seed": 5, + "weights.0.seed.0": "fixed", + "weights.0.weight": 0.9, + "after": "tail" + } + } + ], + "links": [] + }, + "expected_prompt": { + "1": { + "inputs": { + "before": "head", + "mode": "advanced", + "after": "tail", + "loras.0.lora_name": "A.safetensors", + "loras.0.strength": 1, + "loras.0.enabled": true, + "loras.1.lora_name": "C.safetensors", + "loras.1.strength": 0.5, + "loras.1.enabled": false, + "mode.steps": 7, + "weights.0.seed": 5, + "weights.0.weight": 0.9 + }, + "class_type": "CompositeDynamicGroup", + "_meta": { + "title": "Node With Dynamic Group" + } + } + }, + "explicit_form_workflow": { + "nodes": [ + { + "id": 1, + "type": "CompositeDynamicGroup", + "pos": [ + 100, + 150 + ], + "size": [ + 350, + 106 + ], + "flags": {}, + "order": 0, + "mode": 0, + "inputs": [], + "outputs": [ + { + "localized_name": "rows", + "name": "rows", + "type": "STRING", + "links": [] + } + ], + "properties": { + "Node name for S&R": "CompositeDynamicGroup" + }, + "widgets_values": [ + "head", + 2, + "A.safetensors", + 1, + true, + "C.safetensors", + 0.5, + false, + "advanced", + 7, + 1, + 5, + "fixed", + 0.25, + "tail" + ], + "widgets_values_named": { + "before": "head", + "loras": 2, + "loras.0.lora_name": "A.safetensors", + "loras.0.strength": 1, + "loras.0.enabled": true, + "loras.1.lora_name": "C.safetensors", + "loras.1.strength": 0.5, + "loras.1.enabled": false, + "mode": "advanced", + "mode.steps": 7, + "weights": 1, + "weights.0.seed": 5, + "weights.0.seed.0": "fixed", + "weights.0.weight": 0.25, + "after": "tail" + }, + "widgets_values_form": { + "order": [ + "before", + "loras", + "loras.0.lora_name", + "loras.0.strength", + "loras.0.enabled", + "loras.1.lora_name", + "loras.1.strength", + "loras.1.enabled", + "mode", + "mode.steps", + "weights", + "weights.0.seed", + "weights.0.seed.0", + "weights.0.weight", + "after" + ] + } + } + ], + "links": [] + }, + "standalone_count_op": { + "op": "set_widget", + "op_id": "75864944d6b84990b660fa64b553b554", + "actor": "cli", + "base_version": 0, + "stamp": [ + 0, + "cli" + ], + "node_id": 1, + "widget": "weights", + "value": 2, + "old": 1 + }, + "standalone_count_result": { + "nodes": [ + { + "id": 1, + "type": "CompositeDynamicGroup", + "pos": [ + 100, + 150 + ], + "size": [ + 350, + 106 + ], + "flags": {}, + "order": 0, + "mode": 0, + "inputs": [], + "outputs": [ + { + "localized_name": "rows", + "name": "rows", + "type": "STRING", + "links": [] + } + ], + "properties": { + "Node name for S&R": "CompositeDynamicGroup" + }, + "widgets_values": [ + "head", + 2, + "A.safetensors", + 1, + true, + "C.safetensors", + 0.5, + false, + "advanced", + 7, + 2, + 5, + "fixed", + 0.25, + 5, + "fixed", + 1, + "tail" + ], + "widgets_values_named": { + "before": "head", + "loras": 2, + "loras.0.lora_name": "A.safetensors", + "loras.0.strength": 1, + "loras.0.enabled": true, + "loras.1.lora_name": "C.safetensors", + "loras.1.strength": 0.5, + "loras.1.enabled": false, + "mode": "advanced", + "mode.steps": 7, + "weights": 2, + "weights.0.seed": 5, + "weights.0.seed.0": "fixed", + "weights.0.weight": 0.25, + "after": "tail", + "weights.1.seed": 5, + "weights.1.seed.0": "fixed", + "weights.1.weight": 1 + }, + "widgets_values_form": { + "order": [ + "before", + "loras", + "loras.0.lora_name", + "loras.0.strength", + "loras.0.enabled", + "loras.1.lora_name", + "loras.1.strength", + "loras.1.enabled", + "mode", + "mode.steps", + "weights", + "weights.0.seed", + "weights.0.seed.0", + "weights.0.weight", + "weights.1.seed", + "weights.1.seed.0", + "weights.1.weight", + "after" + ] + } + } + ], + "links": [] + }, + "source_commit": "acc3b822d428db6c8572dd056bbb58ee217ed77b" +} From ae2f91c01bc278cdb2f94da262a82bc3bec30f15 Mon Sep 17 00:00:00 2001 From: jaeone94 <89377375+jaeone94@users.noreply.github.com> Date: Sat, 10 Oct 2026 15:44:21 +0900 Subject: [PATCH 03/10] fix: validate inactive named group counts --- src/applier.ts | 5 +-- src/dynamic-combos.ts | 8 ++++- src/mint.ts | 7 ++-- test/dynamic-group.test.ts | 69 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 84 insertions(+), 5 deletions(-) diff --git a/src/applier.ts b/src/applier.ts index e424700..ccac2f7 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -1137,7 +1137,8 @@ function applyInsertWorkflow(doc: Y.Doc, op: InsertWorkflowOp, catalog?: WidgetC rejectUnprojectableWidgets(node, node.type, wv, entry); } try { - nodeWrites.push([String(node.id), node.id, createNodeMap(node, widgetOrderForValues(entry, node.widgets_values))]); + nodeWrites.push([String(node.id), node.id, createNodeMap(node, + declaresWidgetForm(node) ? undefined : widgetOrderForValues(entry, node.widgets_values))]); } catch (err) { throw new OpRejectedError("invalid_node_payload", `insert_workflow(${node.type}): ${err instanceof Error ? err.message : String(err)}`); } @@ -1298,7 +1299,7 @@ function requireAddNodeValid(op: AddNodeOp): void { function createAddedNode(op: AddNodeOp, catalog?: WidgetCatalog): Y.Map { const wv = op.node.widgets_values; const entry = catalogEntry(catalog, op.node.type); - const order = widgetOrderForValues(entry, wv); + const order = declaresWidgetForm(op.node) ? undefined : widgetOrderForValues(entry, wv); // A24: a payload that declares its own `widgets_values_form` needs neither // check. Both exist because a payload the catalog cannot describe would // become unprojectable — and a declared node projects WITHOUT the catalog, diff --git a/src/dynamic-combos.ts b/src/dynamic-combos.ts index e537a5b..f0da13b 100644 --- a/src/dynamic-combos.ts +++ b/src/dynamic-combos.ts @@ -22,7 +22,7 @@ */ import * as Y from "yjs"; -import { assertDynamicGroupCatalog, groupLayout, groupOf, isDynamicGroupField } from "./dynamic-groups.js"; +import { assertDynamicGroupCatalog, groupCountRefusal, groupLayout, groupOf, isDynamicGroupField } from "./dynamic-groups.js"; import type { DynamicComboEntry, WidgetCatalogEntry } from "./types.js"; import { widgetOccurrenceAt, widgetStorageKey } from "./widget-identity.js"; @@ -119,6 +119,12 @@ export function widgetOrderForValues(entry: WidgetCatalogEntry | undefined, wv: if (Array.isArray(wv)) return expand(entry, combos ?? {}, (_name, index) => wv[index]).order; if (typeof wv === "object" && wv !== null) { const named = wv as Record; + assertDynamicGroupCatalog(entry); + for (const name of Object.keys(entry.dynamic_groups ?? {})) { + if (!Object.hasOwn(named, name)) continue; + const refusal = groupCountRefusal(entry, name, named[name]); + if (refusal) throw new TypeError(refusal); + } return expand(entry, combos ?? {}, (name) => (Object.hasOwn(named, name) ? named[name] : undefined)).order; } return expand(entry, combos ?? {}, () => undefined).order; diff --git a/src/mint.ts b/src/mint.ts index a3159f5..5b6d9b7 100644 --- a/src/mint.ts +++ b/src/mint.ts @@ -32,6 +32,7 @@ import { type WorkflowNode, } from "./types.js"; import { widgetOrderForValues } from "./dynamic-combos.js"; +import { declaresWidgetForm } from "./widget-form.js"; /** Top-level keys that are NOT meta passthrough: structural keys get their own root maps; comfy-cli bookkeeping is never imported. */ const NON_META_KEYS = ["nodes", "links", "definitions", "_applied_ops", "_widget_stamps"] as const; @@ -105,7 +106,8 @@ export function mint(workflow: WorkflowJSON, catalog: WidgetCatalog, catalogVers const nodes = nodesMap(doc); for (const node of workflow.nodes ?? []) { - nodes.set(String(node.id), createNodeMap(node, widgetOrderFor(catalog, node.type, node.widgets_values))); + nodes.set(String(node.id), createNodeMap(node, + declaresWidgetForm(node) ? undefined : widgetOrderFor(catalog, node.type, node.widgets_values))); } const links = linksMap(doc); @@ -254,7 +256,8 @@ function mintDefinitionNodes(dm: Y.Map, nodes: WorkflowNode[], catalog: const key = String(node.id); if (order.includes(key)) throw new TypeError(`mint: duplicate definition node id '${key}'`); order.push(key); - nm.set(key, createNodeMap(node, widgetOrderFor(catalog, node.type, node.widgets_values))); + nm.set(key, createNodeMap(node, + declaresWidgetForm(node) ? undefined : widgetOrderFor(catalog, node.type, node.widgets_values))); } dm.set("nodes", nm); dm.set("node_order", order); diff --git a/test/dynamic-group.test.ts b/test/dynamic-group.test.ts index 85f2325..a561b42 100644 --- a/test/dynamic-group.test.ts +++ b/test/dynamic-group.test.ts @@ -21,6 +21,14 @@ const composite = JSON.parse(readFileSync(new URL("./fixtures/dynamic-group-comp }; const groupEntry = catalog.types["DevToolsNodeWithDynamicGroup"]!; const loras = groupEntry.dynamic_groups!["loras"]!; +const conditionalCatalog: WidgetCatalog = { types: { DevToolsNodeWithDynamicGroup: { + ...groupEntry, + widget_order: ["before", "mode", "after"], + dynamic_combos: { mode: { default: "off", options: { + off: { widgets: [], defaults: {} }, + on: { widgets: ["loras"], defaults: { loras: 0 } }, + } } }, +} } }; const edit = (widget: string, value: unknown, counter = 1) => ({ op: "set_widget", node_id: 1, widget, value, op_id: counter.toString(16).padStart(32, "0"), actor: "agent:a", base_version: counter, stamp: [counter, "agent:a"], @@ -213,6 +221,67 @@ describe("DynamicGroup catalog layout", () => { expect(() => mint(workflow, catalog)).toThrow(/row count/); }); + it.each([-1, 1.5, "2", 1_000_000])("refuses inactive named group count %s during mint", (count) => { + const workflow = structuredClone(cases.empty); + delete workflow.nodes[0]!["widgets_values_named"]; + workflow.nodes[0]!.widgets_values = { before: "first", mode: "off", loras: count, after: "last" }; + + expect(() => mint(workflow, conditionalCatalog)).toThrow(/row count/); + }); + + it("keeps a valid inactive named group available when its option is selected", () => { + const workflow = structuredClone(cases.empty); + delete workflow.nodes[0]!["widgets_values_named"]; + workflow.nodes[0]!.widgets_values = { before: "first", mode: "off", loras: 2, after: "last" }; + const doc = mint(workflow, conditionalCatalog); + + expect(project(doc, conditionalCatalog).nodes[0]!.widgets_values).toEqual(["first", "off", "last"]); + expect(applyOps(doc, [edit("mode", "on")], conditionalCatalog).outcomes[0]?.outcome).toBe("applied"); + expect(project(doc, conditionalCatalog).nodes[0]!.widgets_values).toEqual([ + "first", "on", 2, "A.safetensors", 1, true, "A.safetensors", 1, true, "last", + ]); + doc.destroy(); + }); + + it.each(["mint", "interior_mint", "add_node", "insert_workflow"] as const)( + "preserves declared-form residue independently of group metadata on %s", + (path) => { + const workflow = structuredClone(cases.empty); + const node = workflow.nodes[0]!; + delete node["widgets_values_named"]; + node.widgets_values = { before: "first", mode: "on", loras: -1, after: "last" }; + node.widgets_values_form = { order: ["before", "mode", "after"] }; + if (path === "mint") { + const doc = mint(workflow, conditionalCatalog); + expect(project(doc, conditionalCatalog).nodes[0]!.widgets_values).toEqual(node.widgets_values); + expect(project(doc, conditionalCatalog).nodes[0]!.widgets_values_form).toEqual(node.widgets_values_form); + doc.destroy(); + } else if (path === "interior_mint") { + const doc = mint({ + nodes: [{ id: 9, type: "group-definition" }], links: [], + definitions: { subgraphs: [{ id: "group-definition", nodes: [node], links: [] }] }, + }, conditionalCatalog); + expect(project(doc, conditionalCatalog)).toMatchObject({ definitions: { subgraphs: [{ nodes: [{ + widgets_values: node.widgets_values, widgets_values_form: node.widgets_values_form, + }] }] } }); + doc.destroy(); + } else { + const envelope = { + op_id: "a".repeat(32), actor: "agent:a", base_version: 1, stamp: [1, "agent:a"], + } satisfies Pick; + const op: Op = path === "add_node" + ? { ...envelope, op: "add_node", node_id: node.id, class_type: node.type, pos: [0, 0], node } + : { ...envelope, op: "insert_workflow", workflow }; + const doc = mint({ nodes: [], links: [] }, conditionalCatalog); + expect(applyOps(doc, [op], conditionalCatalog).outcomes[0]?.outcome).toBe("applied"); + const restored = project(doc, conditionalCatalog).nodes.find((candidate) => candidate.type === node.type)!; + expect(restored.widgets_values).toEqual(node.widgets_values); + expect(restored.widgets_values_form).toEqual(node.widgets_values_form); + doc.destroy(); + } + }, + ); + it("preserves rows above a newer catalog's advertised maximum", () => { const smaller = structuredClone(catalog); smaller.types["DevToolsNodeWithDynamicGroup"]!.dynamic_groups!["loras"]!.max = 1; From 7c39f5bd8323b88bcf69d013bd13023e261a40b3 Mon Sep 17 00:00:00 2001 From: jaeone94 <89377375+jaeone94@users.noreply.github.com> Date: Sun, 11 Oct 2026 10:51:41 +0900 Subject: [PATCH 04/10] fix: validate declared group counts at the addressed occurrence --- docs/INVARIANTS.md | 2 +- docs/decisions/EXCEPTIONS.md | 1 + docs/dynamic-groups.md | 2 +- docs/multiplayer-schema.md | 11 ++++-- src/applier.ts | 10 ++--- src/widget-form.ts | 8 ++-- test/dynamic-group.test.ts | 74 +++++++++++++++++++++++++++++++++++- 7 files changed, 91 insertions(+), 17 deletions(-) diff --git a/docs/INVARIANTS.md b/docs/INVARIANTS.md index 85a1657..0049de3 100644 --- a/docs/INVARIANTS.md +++ b/docs/INVARIANTS.md @@ -114,7 +114,7 @@ which is the SHA-pinned-consumer consequence A1 and A2 both document, and why the pins move in one coordinated step. ### KA-12 — Catalog pinned at mint -**Rule:** `meta.catalog_version` cites the catalog by SHA, not branch; reject NAMED widget writes to uncatalogued classes loudly. A subgraph instance's `type` is a definition UUID that no catalog describes, and its promoted widget values are POSITIONAL by frontend contract (ADR 0009), so a promoted host write (schema Amendment A15) is not a widget-name resolution and needs no catalog entry for the instance — it still needs A CATALOG (`catalog_required` without one) to tell an instance from an unseen class, and still refuses (`uncatalogued_widget_write`) to lay a positional array over named values the catalog cannot describe. A node that DECLARES its own ordered widget identity (`widgets_values_form`, schema Amendment A24) is resolved from that declaration and consults no catalog, which does not relax this rule: the clause bans this package GUESSING a name→position mapping it was never given, and a declaration is the mapping, supplied by the only party that knows it. An undeclared node keeps every refusal above, and `meta.catalog_version` still pins the catalog every other node projects against. +**Rule:** `meta.catalog_version` cites the catalog by SHA, not branch; reject NAMED widget writes to uncatalogued classes loudly. A subgraph instance's `type` is a definition UUID that no catalog describes, and its promoted widget values are POSITIONAL by frontend contract (ADR 0009), so a promoted host write (schema Amendment A15) is not a widget-name resolution and needs no catalog entry for the instance — it still needs A CATALOG (`catalog_required` without one) to tell an instance from an unseen class, and still refuses (`uncatalogued_widget_write`) to lay a positional array over named values the catalog cannot describe. A node that DECLARES its own ordered widget identity (`widgets_values_form`, schema Amendment A24) resolves names and occurrences from that declaration without a catalog mapping. A25 makes one validation exception: supplied `dynamic_groups` metadata identifies count fields for allocation-bound checks and refuses a count change that would invalidate the declaration, using the addressed occurrence's current value. The declaration still owns ordering; the catalog does not replace it. Without that metadata, the package cannot identify a count field, so callers must enforce compatible producer, catalog, and reader adoption. An undeclared node keeps every refusal above, and `meta.catalog_version` still pins the catalog every other node projects against. **Why:** Replay semantics must not drift with a moving vocabulary. **Enforced by:** `test/roundtrip.test.ts`, `test/catalog-sha-binding-integration.test.ts`, `test/node-local-widget-form.test.ts` (A24's catalog-free path, and that an undeclared node still takes the catalogued one), [`catalog-pinning`](../.agents/checks/catalog-pinning.md), [ADR-003](decisions/ADR-003-catalog-sha-at-mint.md), and — for the *citations* rather than `meta.catalog_version` itself — `scripts/check-pins.mjs` (`npm run check:pins`) with `docs/upstream-pins.json` and `test/upstream-pins.test.ts`. `test/doc-mint-mutation-survivors.test.ts` additionally pins that an imported workflow cannot forge `catalog_version`/`schema_version` or any `__`-prefixed meta key, and that an unpinned mint records an EMPTY catalog version rather than a plausible-looking default (FC-10). The rule's second clause is narrower than it looks: **`meta.catalog_version` is still UNGUARDED at the write sites — see roadmap.** Neither `mint()` nor `initDoc()` rejects a branch-shaped catalog version; only the citations are linted. diff --git a/docs/decisions/EXCEPTIONS.md b/docs/decisions/EXCEPTIONS.md index 74d2ec4..1ae8919 100644 --- a/docs/decisions/EXCEPTIONS.md +++ b/docs/decisions/EXCEPTIONS.md @@ -24,3 +24,4 @@ is retained as history, not authorization to accept unprojectable writes. | ~~2026-09-22 (APPROVED)~~ **AMENDED AND APPROVED 2026-09-23** | KA-5 | ~~`insert_workflow`'s numeric link-id mint consulted mutable document state (a document-verified retry), unlike every other id this op derives.~~ Christian Byrne's review of that design (PR #245, inline on `src/remap.ts:65`) found it made link identity depend on LOCAL ARRIVAL ORDER — two replicas applying the same concurrent op set in opposite orders could project different link ids for the same logical links, the exact class of bug KA-4/KA-2 exist to rule out — and asked for either a fix plus explicit ratification, or a return to pure derivation. **This row now describes the amended design: `derivedLinkId` mints PURELY from the op's own content (`opId`, `scope`, the raw link), with NO document read, no caller-supplied reservation, and no retry.** It spends the FULL safe-integer range (`[1, Number.MAX_SAFE_INTEGER]`, 53 bits, widened from the original's 52-bit window) rather than checking for a collision. ComfyUI_frontend's `LinkId` (a branded `number`, unlike the string-or-number `NodeId`) is still why a link needs a numeric mint at all — ADR-031's pure STRING scheme still can't satisfy it — but the mint no longer tries to guarantee collision-freedom against the document; it accepts a quantified residual risk instead. Residual probability: two independently derived 53-bit candidates collide with probability `1/(2^53-1) ≈ 1.11×10⁻¹⁶` per pair; for `k` links minted into one document the birthday-bound chance ANY two collide is `≈ k²/2^54` — about `2.2×10⁻¹²` at `k=200` (this package's own scale test), about `5.5×10⁻⁵` even at an unrealistic `k=1,000,000` — the same order of "cosmically unlikely, not impossible" risk this package already accepts for UUID4 `op_id` collisions (KA-2). A REALIZED collision is not specially detected: it is caught by `applier.ts`'s pre-existing `acceptsLink`/`seenLinks` apply-time id-collision handling (the same ordinary, order-independent LWW-gated check every other `insert_workflow` id kind already goes through), rejecting the whole op `link_id_collision` byte-identically rather than silently reassigning a different id — this check is REACHABLE via realistic input now (not merely via deliberate id-space exhaustion, since there is no more exhaustion to construct). **Separately, a pre-existing, unresolved gap** (out of scope for this amendment): a `connect` op's client-minted `link_id` can collide with an `insert_workflow`-derived numeric id, and `applier.ts`'s `claimLinkIdentity` does not guard against it at all, silently overwriting the `insert_workflow` link when `connect` arrives second — this predates and is unaffected by this amendment either way (the removed retry only ever protected the OPPOSITE arrival order, and only when the `connect` had already landed on that replica). See ADR-033's "Amendment (2026-09-23)" section for the full writeup, including this cross-mechanism note. | `src/remap.ts` `derivedLinkId`; `src/applier.ts` `prepareInsertedWorkflow`, `acceptsLink`, `claimLinkIdentity`; ADR-033 | Owner: Christian Byrne. The amended pure-derivation design was ratified after exact-head review confirmed that the document-state retry was removed, opposite-order convergence coverage was added, and realized collisions remain loud and byte-identical. Sunset (unchanged from the original row): revisit only if ComfyUI_frontend widens `LinkId` to `string \| number` (matching `NodeId`), at which point ADR-031's string form becomes sufficient for links too and this exception can be retired outright. | | 2026-10-03 (PROPOSED) | KA-5 | **`insert_workflow` derives numeric group ids by the same pure 53-bit hash as KA-5's link ids, and accepts the same residual collision risk** (PR #264). ComfyUI_frontend's workflow schema declares `groups[].id` as `z.number()` (root and `definitions.subgraphs[].groups`) and refuses the whole workflow on a string, so the string `derivedId` groups used to carry made inserted workflows unloadable. `derivedGroupId` folds `insert:::group:` into `[1, Number.MAX_SAFE_INTEGER]` from the op's own content only (no document read, no retry), so replicas converge regardless of arrival order. Residual probability is the KA-5 row's: `≈ k²/2^54` for `k` groups in one document. **Unlike links, a realized group-id collision is NOT detected**: `applier.ts` merges groups by canonical JSON, not by id, so two distinct groups sharing an id both stay in the document and project with the same id; the frontend's behaviour on duplicate group ids is unverified. `project.ts` coerces a stored string group id to a number ONLY when it matches the derived form (`DERIVED_GROUP_ID`), so a workflow's own string group id round-trips `project(mint(wf))` unchanged and still fails the frontend schema exactly as it would without this package. | `src/remap.ts` `derivedGroupId`, `numericId`; `src/project.ts` `projectGroups`, `DERIVED_GROUP_ID`; `test/insert-workflow-numeric-group-ids.regression.test.ts` | Owner and approval: maintainer's to assign (proposed for Christian Byrne, who reviewed #264). Sunset: revisit if ComfyUI_frontend widens a group's `id` to `string \| number`, at which point the string `derivedId` suffices and this exception can be retired; add id-level collision detection to the groups merge before then if duplicate ids prove harmful on the canvas. | | 2026-10-04 (PROPOSED) | FC-10 | **`widgets_values_form` is a package-local, provisional workflow FIELD** (schema Amendment A24), because the pinned catalog is per-class while the two shapes that need describing are per-instance: a node with two same-named serializable widgets, and a node whose custom serializer emits an object whose non-widget keys must survive a widget write. Neither is derivable from the end state, so the producer declares its instance's ordered widget identity and this package decomposes, addresses and projects through that declaration with no catalog lookup. comfy-cli's frozen `op-vocabulary-v1.md` does not define the field, so the deviation is from FC-10's cite-the-pinned-vocabulary rule rather than from KA-12 (a declaration is the name-to-position mapping, supplied by the party that knows it, not a guess at one). Bounded deliberately: ONE declared key, closed to `{order}` and refused rather than ignored when malformed; every other part of the form is derived; an undeclared node keeps the catalog path and all of its existing refusals; `SCHEMA_VERSION` is unchanged on A2's precedent and under A2's exact condition. **Two residuals, both stated rather than discovered later:** `insert_workflow` strips every `__`-prefixed key at every depth (`prepareInsertedWorkflow` / `scrubPrivateKeys`, a pre-existing anti-forgery guard), so a serializer's own `__`-prefixed data key inside `widgets_values` does not survive THAT path — pinned by test rather than papered over; and the §8.3 autogrow `inputcount` bump still writes the `widgets` map directly and consults no declared order, which is A23's pre-existing gap one op over. | `src/widget-form.ts`; `src/doc.ts` `widgetStorageFor`/`widgetStorageOf`/`storeWidgetValues`; `src/project.ts` `projectWidgets`; `src/applier.ts` `validateWidgetName`/`rejectIfOpaqueWidgets`/`hostWriteStorage`/`createAddedNode`/`rejectUnprojectableWidgets`; `src/read.ts`; `fixtures/golden-vectors/wire-layout.json`; `test/node-local-widget-form.test.ts`; schema Amendment A24 | Owner and approval: maintainer's to assign (FE-3036's owner). Sunset: amend comfy-cli's frozen vocabulary to define the field and pin the adopted definition here, reconciling the name and shape if upstream differs; retire outright if the catalog acquisition ever becomes per-instance, at which point the declaration becomes redundant rather than merely unneeded. | +| 2026-10-11 (PROPOSED) | KA-12 | A25 uses supplied DynamicGroup metadata to validate count writes even on an A24 self-described node. Name/occurrence resolution and projection still use the producer declaration; metadata only checks allocation bounds and refuses changing the addressed occurrence's count without an updated form. Metadata omission cannot identify a controller and remains a caller admission concern. | `src/applier.ts` `validateDynamicGroupValue`; `test/dynamic-group.test.ts`; schema Amendments A24/A25 | Owner and approval: maintainer's to assign. Reconcile when count safety becomes part of the producer declaration or atomic row-operation protocol. | diff --git a/docs/dynamic-groups.md b/docs/dynamic-groups.md index bc807bd..85dac89 100644 --- a/docs/dynamic-groups.md +++ b/docs/dynamic-groups.md @@ -10,7 +10,7 @@ The catalog controls layout, not prompt validity. Saved rows above an advertised Like dynamic-combo selections, count changes only change projection. Fields in hidden rows retain their name-keyed registers, and newly visible fields without a stored value show template defaults. This avoids receiver-side writes whose outcome depends on op arrival order (KA-2, KA-4). This is not a live structural row operation: it does not remove a middle row, reindex surviving identities, or update connections and promotions. Those changes require the separate atomic row-operation protocol. -An explicit `widgets_values_form` remains authoritative. Existing row fields can be edited through it; a count change that requires replacing that declaration is refused before mutation. This PR does not introduce an op for changing producer-owned forms. +An explicit `widgets_values_form` remains authoritative for names, occurrences, and projection order. Supplied group metadata is used for count validation only: allocation bounds are checked, and a change from the addressed occurrence's stored count that requires replacing the declaration is refused before mutation. A catalog-free declaration cannot identify group controllers, so that path does not provide count safety. This PR does not introduce an op for changing producer-owned forms. No wire key or op kind changes. New catalog content changes the catalog hash. Consumers must adopt this reader before receiving a DynamicGroup catalog; old documents remain tied to their original catalog and must be re-minted to adopt a new layout (KA-11, KA-12, FC-10). diff --git a/docs/multiplayer-schema.md b/docs/multiplayer-schema.md index bc88283..50d2526 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -2372,10 +2372,13 @@ A node carrying the field is **self-described**, and for it: the verbatim residue of keys `order` does not name (`extra`). The residue is one whole plain value under one key — whole-value LWW, never merged element-wise, the same justification A2 gives `__widgets_opaque`; -- `set_widget` resolves `(widget, widget_occurrence)` against `order` and does - **not consult the catalog at all**, so neither `opaque_widgets` nor +- `set_widget` resolves `(widget, widget_occurrence)` against `order` without + using the catalog for that mapping, so neither `opaque_widgets` nor `uncatalogued_widget_write` can arise. A name or occurrence `order` does not - list is `unknown_widget`, exactly as a missing `widget_order` entry would be; + list is `unknown_widget`, exactly as a missing `widget_order` entry would be. + A25 uses supplied `dynamic_groups` metadata only for count validation: it + checks the allocation bound and refuses a change from the addressed + occurrence's stored count that would require replacing the declaration; - `project()` rebuilds `widgets_values` in the shape the producer serialized — an array of `order.length`, or the object in its original key order with each declared widget taking its live value and every other key its verbatim @@ -2499,4 +2502,4 @@ here. An opt-in `dynamic_groups` catalog entry expands a saved row-count controller into indexed widget identities. These use the existing name-keyed registers; no op kind or on-document key changes. The new catalog hash requires coordinated reader adoption. Existing documents retain their original catalog and are re-minted to adopt the new layout. -Count writes change the projected layout, retaining hidden registers and applying fresh-row defaults only at read time. They do not delete rows or links. Explicit `widgets_values_form` declarations remain authoritative; a count write requiring a new declaration is rejected before mutation. See [DynamicGroup catalog support](dynamic-groups.md) for the producer contract, bounds, and fixture provenance. +Count writes change the projected layout, retaining hidden registers and applying fresh-row defaults only at read time. They do not delete rows or links. Explicit `widgets_values_form` declarations remain authoritative; supplied group metadata adds allocation-bound validation and rejects a count change requiring a new declaration before mutation. This is A24's one catalog-validation exception, applied to the addressed occurrence in top-level, interior, and promoted writes. Without group metadata, the package cannot identify count fields; compatible producer/catalog/reader admission remains the caller's responsibility. See [DynamicGroup catalog support](dynamic-groups.md) for the producer contract, bounds, and fixture provenance. diff --git a/src/applier.ts b/src/applier.ts index ccac2f7..1661baf 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -1902,7 +1902,7 @@ function applyPromotedHostWrite( const occurrence = op.widget_occurrence ?? 0; requirePromotedFormAgreement(target, op.widget, occurrence, promoted.valueIndex); validateWidgetName(catalog, String(target.get("type") ?? ""), op.widget, target, occurrence); - validateDynamicGroupValue(target, catalog, op.widget, op.value); + validateDynamicGroupValue(target, catalog, op.widget, occurrence, op.value); mset(widgetsOf(target), widgetStorageKey(op.widget, occurrence), structuredClone(op.value)); updateOrderedWidgetValue(target, op.widget, occurrence, op.value); updateNamedWidgetValue(target, catalog, op.widget, occurrence, op.value); @@ -1957,13 +1957,13 @@ function validateWidgetOp(op: SetWidgetOp) { return { interior, promoted }; } -function validateDynamicGroupValue(node: Y.Map, catalog: WidgetCatalog | undefined, widget: string, value: unknown): void { +function validateDynamicGroupValue(node: Y.Map, catalog: WidgetCatalog | undefined, widget: string, occurrence: number, value: unknown): void { const entry = catalogEntry(catalog, String(node.get("type") ?? "")); const refusal = groupCountRefusal(entry, widget, value); if (refusal) throw new OpRejectedError("malformed_op", refusal); if (groupOf(entry, widget) && storedWidgetFormOf(node)) { const widgets = node.get("widgets"); - if (widgets instanceof Y.Map && widgets.get(widgetStorageKey(widget, 0)) !== value) { + if (widgets instanceof Y.Map && widgets.get(widgetStorageKey(widget, occurrence)) !== value) { throw new OpRejectedError("malformed_op", "row count changes require an updated widgets_values_form declaration"); } } @@ -2020,7 +2020,7 @@ function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): S // than falling through the `if (entry)` block as an accepted write (#13). const occurrence = op.widget_occurrence ?? 0; validateWidgetName(catalog, nodeType, widget, target, occurrence); - validateDynamicGroupValue(target, catalog, widget, op.value); + validateDynamicGroupValue(target, catalog, widget, occurrence, op.value); // OWN-property lookup (#13): an inherited key such as `__proto__` must read // as "absent from the catalog", not resolve to a prototype object. const entry = catalogEntry(catalog, nodeType); @@ -2060,7 +2060,7 @@ function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): S rejectIfOpaqueWidgets(node, op.widget); const occurrence = op.widget_occurrence ?? 0; validateWidgetName(catalog, String(node.get("type") ?? ""), op.widget, node, occurrence); - validateDynamicGroupValue(node, catalog, op.widget, op.value); + validateDynamicGroupValue(node, catalog, op.widget, occurrence, op.value); // Top-level writes may extend past the current positional length — comfy-cli // pads with None; here the name-keyed map makes padding a projection concern. mset(widgetsOf(node), widgetStorageKey(op.widget, occurrence), structuredClone(op.value)); diff --git a/src/widget-form.ts b/src/widget-form.ts index ae1a72c..22f8933 100644 --- a/src/widget-form.ts +++ b/src/widget-form.ts @@ -57,11 +57,9 @@ * merge corruption cannot arise and the residue cannot drift from the values * (it never holds one). * - * It does not relax KA-12. A self-described node does not consult the catalog - * because it does not need to: the name↔position mapping arrived WITH the - * node from the only party that knows it. KA-12 exists to stop this package - * guessing a mapping it was never given, and a declaration is not a guess. An - * undeclared node is unaffected — same catalog, same rejections. + * It does not relax KA-12. The declaration supplies name↔position mapping. + * A25 still uses supplied DynamicGroup metadata to validate count writes + * without replacing that mapping. An undeclared node keeps catalog resolution. */ import type * as Y from "yjs"; diff --git a/test/dynamic-group.test.ts b/test/dynamic-group.test.ts index a561b42..ee9846c 100644 --- a/test/dynamic-group.test.ts +++ b/test/dynamic-group.test.ts @@ -1,7 +1,7 @@ import { readFileSync } from "node:fs"; import * as Y from "yjs"; import { describe, expect, it } from "vitest"; -import { applyOps, mint, project, type Op, type TopLevelSetWidgetOp, type WidgetCatalog, type WidgetCatalogEntry, type WorkflowJSON } from "../src/index.js"; +import { applyOps, mint, project, type Op, type SetWidgetOp, type TopLevelSetWidgetOp, type WidgetCatalog, type WidgetCatalogEntry, type WorkflowJSON } from "../src/index.js"; import { canonicalize } from "./helpers.js"; import { assertRejectedWithoutMutation } from "./rejection-test-helpers.js"; @@ -35,6 +35,78 @@ const edit = (widget: string, value: unknown, counter = 1) => ({ } satisfies TopLevelSetWidgetOp); describe("DynamicGroup catalog layout", () => { + it("refuses a controller duplicated only by the selected combo composition", () => { + const entry: WidgetCatalogEntry = { + ...groupEntry, + widget_order: ["before", "mode", "other_mode", "after"], + dynamic_combos: { + ...conditionalCatalog.types["DevToolsNodeWithDynamicGroup"]!.dynamic_combos, + other_mode: { default: "off", options: { + off: { widgets: [], defaults: {} }, + on: { widgets: ["loras"], defaults: { loras: 0 } }, + } }, + }, + }; + const selectedCatalog: WidgetCatalog = { types: { DevToolsNodeWithDynamicGroup: entry } }; + const workflow = structuredClone(cases.empty); + const values = { before: "first", mode: "on", loras: 0, other_mode: "off", after: "last" }; + workflow.nodes[0]!.widgets_values = values; + const doc = mint(workflow, selectedCatalog); + expect(project(doc, selectedCatalog).nodes[0]!.widgets_values).toEqual(["first", "on", 0, "off", "last"]); + doc.destroy(); + + workflow.nodes[0]!.widgets_values = { ...values, other_mode: "on" }; + expect(() => mint(workflow, selectedCatalog)).toThrow("controller 'loras' is duplicated in the selected layout"); + }); + + it.each([ + ["top-level", 0], ["top-level", 1], + ["interior", 0], ["interior", 1], + ["promoted", 0], ["promoted", 1], + ] as const)("checks a declared count for %s occurrence %s", (route, occurrence) => { + let workflow = structuredClone(cases.empty); + const node = workflow.nodes[0]!; + node.widgets_values = [0, 1, "tail"]; + node.widgets_values_form = { order: ["loras", "loras", "after"] }; + delete node["widgets_values_named"]; + let op: SetWidgetOp = { ...edit("loras", occurrence), widget_occurrence: occurrence }; + let trailing: SetWidgetOp = { ...edit("after", "edited tail", 2), actor: "agent:b", base_version: 1, stamp: [1, "agent:b"] }; + if (route === "interior") { + workflow = { + nodes: [{ id: 9, type: "def", inputs: [], outputs: [], widgets_values: [] }], links: [], + definitions: { subgraphs: [{ id: "def", nodes: [node], links: [] }] }, + }; + op = { ...op, path: ["9", "1"], inner_widget: "loras", promoted: null }; + trailing = { ...trailing, path: ["9", "1"], inner_widget: "after", promoted: null }; + } else if (route === "promoted") { + op = { ...op, promoted: { value_index: occurrence, instance_path: ["1"], host_widgets_values: [0, 1, "tail"] } }; + trailing = { ...trailing, promoted: { value_index: 2, instance_path: ["1"], host_widgets_values: [0, 1, "edited tail"] } }; + } + const seed = mint(workflow, catalog); + const snapshot = Y.encodeStateAsUpdate(seed); + for (const ordered of [[op, trailing], [trailing, op]]) { + const doc = new Y.Doc(); + Y.applyUpdate(doc, snapshot); + expect(applyOps(doc, ordered, catalog).outcomes.map((outcome) => outcome.outcome)).toEqual(["applied", "applied"]); + const projected = project(doc, catalog); + const target = route === "interior" + ? (projected["definitions"] as { subgraphs: WorkflowJSON[] }).subgraphs[0]!.nodes[0]! + : projected.nodes[0]!; + expect(target.widgets_values).toEqual([0, 1, "edited tail"]); + const beforeRetry = Y.encodeStateAsUpdate(doc); + applyOps(doc, ordered, catalog); + expect(Y.encodeStateAsUpdate(doc)).toEqual(beforeRetry); + doc.destroy(); + } + seed.destroy(); + + const invalid: SetWidgetOp = route === "promoted" ? { + ...edit("loras", 1 - occurrence), widget_occurrence: occurrence, + promoted: { value_index: occurrence, instance_path: ["1"], host_widgets_values: [1 - occurrence, 1 - occurrence, "tail"] }, + } : { ...op, value: 1 - occurrence }; + assertRejectedWithoutMutation(workflow, invalid, "malformed_op", catalog, trailing); + }); + it.each([ ["duplicate controller", { ...groupEntry, widget_order: ["before", "loras", "loras", "after"] }], ["duplicate relative field", { ...groupEntry, dynamic_groups: { loras: { ...loras, widgets: ["strength", "strength"] } } }], From 664f96542e80f72570d35207eac304ebf7bd3d8d Mon Sep 17 00:00:00 2001 From: jaeone94 <89377375+jaeone94@users.noreply.github.com> Date: Tue, 13 Oct 2026 23:25:31 +0900 Subject: [PATCH 05/10] fix: bound DynamicGroup row counts by the group minimum The frontend raises a remote count below `min` to `min`, so accepting it left the document and canvas with different row counts. Refuse counts below `min`, require integer catalog bounds with 0 <= min <= max, and bound row-field indices by the existing allocation bound. Update the docs for the whole-group replacement decision. Co-Authored-By: Claude Opus 5.5 --- docs/INVARIANTS.md | 2 +- docs/decisions/EXCEPTIONS.md | 2 +- docs/dynamic-groups.md | 6 +++--- docs/multiplayer-schema.md | 4 ++-- src/dynamic-groups.ts | 14 ++++++++++---- test/dynamic-group.test.ts | 37 ++++++++++++++++++++++++++++++++++++ 6 files changed, 54 insertions(+), 11 deletions(-) diff --git a/docs/INVARIANTS.md b/docs/INVARIANTS.md index 0049de3..eeb89ee 100644 --- a/docs/INVARIANTS.md +++ b/docs/INVARIANTS.md @@ -114,7 +114,7 @@ which is the SHA-pinned-consumer consequence A1 and A2 both document, and why the pins move in one coordinated step. ### KA-12 — Catalog pinned at mint -**Rule:** `meta.catalog_version` cites the catalog by SHA, not branch; reject NAMED widget writes to uncatalogued classes loudly. A subgraph instance's `type` is a definition UUID that no catalog describes, and its promoted widget values are POSITIONAL by frontend contract (ADR 0009), so a promoted host write (schema Amendment A15) is not a widget-name resolution and needs no catalog entry for the instance — it still needs A CATALOG (`catalog_required` without one) to tell an instance from an unseen class, and still refuses (`uncatalogued_widget_write`) to lay a positional array over named values the catalog cannot describe. A node that DECLARES its own ordered widget identity (`widgets_values_form`, schema Amendment A24) resolves names and occurrences from that declaration without a catalog mapping. A25 makes one validation exception: supplied `dynamic_groups` metadata identifies count fields for allocation-bound checks and refuses a count change that would invalidate the declaration, using the addressed occurrence's current value. The declaration still owns ordering; the catalog does not replace it. Without that metadata, the package cannot identify a count field, so callers must enforce compatible producer, catalog, and reader adoption. An undeclared node keeps every refusal above, and `meta.catalog_version` still pins the catalog every other node projects against. +**Rule:** `meta.catalog_version` cites the catalog by SHA, not branch; reject NAMED widget writes to uncatalogued classes loudly. A subgraph instance's `type` is a definition UUID that no catalog describes, and its promoted widget values are POSITIONAL by frontend contract (ADR 0009), so a promoted host write (schema Amendment A15) is not a widget-name resolution and needs no catalog entry for the instance — it still needs A CATALOG (`catalog_required` without one) to tell an instance from an unseen class, and still refuses (`uncatalogued_widget_write`) to lay a positional array over named values the catalog cannot describe. A node that DECLARES its own ordered widget identity (`widgets_values_form`, schema Amendment A24) resolves names and occurrences from that declaration without a catalog mapping. A25 makes one validation exception: supplied `dynamic_groups` metadata identifies count fields for row-count bound checks and refuses a count change that would invalidate the declaration, using the addressed occurrence's current value. The declaration still owns ordering; the catalog does not replace it. Without that metadata, the package cannot identify a count field, so callers must enforce compatible producer, catalog, and reader adoption. An undeclared node keeps every refusal above, and `meta.catalog_version` still pins the catalog every other node projects against. **Why:** Replay semantics must not drift with a moving vocabulary. **Enforced by:** `test/roundtrip.test.ts`, `test/catalog-sha-binding-integration.test.ts`, `test/node-local-widget-form.test.ts` (A24's catalog-free path, and that an undeclared node still takes the catalogued one), [`catalog-pinning`](../.agents/checks/catalog-pinning.md), [ADR-003](decisions/ADR-003-catalog-sha-at-mint.md), and — for the *citations* rather than `meta.catalog_version` itself — `scripts/check-pins.mjs` (`npm run check:pins`) with `docs/upstream-pins.json` and `test/upstream-pins.test.ts`. `test/doc-mint-mutation-survivors.test.ts` additionally pins that an imported workflow cannot forge `catalog_version`/`schema_version` or any `__`-prefixed meta key, and that an unpinned mint records an EMPTY catalog version rather than a plausible-looking default (FC-10). The rule's second clause is narrower than it looks: **`meta.catalog_version` is still UNGUARDED at the write sites — see roadmap.** Neither `mint()` nor `initDoc()` rejects a branch-shaped catalog version; only the citations are linted. diff --git a/docs/decisions/EXCEPTIONS.md b/docs/decisions/EXCEPTIONS.md index 1ae8919..2145fc4 100644 --- a/docs/decisions/EXCEPTIONS.md +++ b/docs/decisions/EXCEPTIONS.md @@ -24,4 +24,4 @@ is retained as history, not authorization to accept unprojectable writes. | ~~2026-09-22 (APPROVED)~~ **AMENDED AND APPROVED 2026-09-23** | KA-5 | ~~`insert_workflow`'s numeric link-id mint consulted mutable document state (a document-verified retry), unlike every other id this op derives.~~ Christian Byrne's review of that design (PR #245, inline on `src/remap.ts:65`) found it made link identity depend on LOCAL ARRIVAL ORDER — two replicas applying the same concurrent op set in opposite orders could project different link ids for the same logical links, the exact class of bug KA-4/KA-2 exist to rule out — and asked for either a fix plus explicit ratification, or a return to pure derivation. **This row now describes the amended design: `derivedLinkId` mints PURELY from the op's own content (`opId`, `scope`, the raw link), with NO document read, no caller-supplied reservation, and no retry.** It spends the FULL safe-integer range (`[1, Number.MAX_SAFE_INTEGER]`, 53 bits, widened from the original's 52-bit window) rather than checking for a collision. ComfyUI_frontend's `LinkId` (a branded `number`, unlike the string-or-number `NodeId`) is still why a link needs a numeric mint at all — ADR-031's pure STRING scheme still can't satisfy it — but the mint no longer tries to guarantee collision-freedom against the document; it accepts a quantified residual risk instead. Residual probability: two independently derived 53-bit candidates collide with probability `1/(2^53-1) ≈ 1.11×10⁻¹⁶` per pair; for `k` links minted into one document the birthday-bound chance ANY two collide is `≈ k²/2^54` — about `2.2×10⁻¹²` at `k=200` (this package's own scale test), about `5.5×10⁻⁵` even at an unrealistic `k=1,000,000` — the same order of "cosmically unlikely, not impossible" risk this package already accepts for UUID4 `op_id` collisions (KA-2). A REALIZED collision is not specially detected: it is caught by `applier.ts`'s pre-existing `acceptsLink`/`seenLinks` apply-time id-collision handling (the same ordinary, order-independent LWW-gated check every other `insert_workflow` id kind already goes through), rejecting the whole op `link_id_collision` byte-identically rather than silently reassigning a different id — this check is REACHABLE via realistic input now (not merely via deliberate id-space exhaustion, since there is no more exhaustion to construct). **Separately, a pre-existing, unresolved gap** (out of scope for this amendment): a `connect` op's client-minted `link_id` can collide with an `insert_workflow`-derived numeric id, and `applier.ts`'s `claimLinkIdentity` does not guard against it at all, silently overwriting the `insert_workflow` link when `connect` arrives second — this predates and is unaffected by this amendment either way (the removed retry only ever protected the OPPOSITE arrival order, and only when the `connect` had already landed on that replica). See ADR-033's "Amendment (2026-09-23)" section for the full writeup, including this cross-mechanism note. | `src/remap.ts` `derivedLinkId`; `src/applier.ts` `prepareInsertedWorkflow`, `acceptsLink`, `claimLinkIdentity`; ADR-033 | Owner: Christian Byrne. The amended pure-derivation design was ratified after exact-head review confirmed that the document-state retry was removed, opposite-order convergence coverage was added, and realized collisions remain loud and byte-identical. Sunset (unchanged from the original row): revisit only if ComfyUI_frontend widens `LinkId` to `string \| number` (matching `NodeId`), at which point ADR-031's string form becomes sufficient for links too and this exception can be retired outright. | | 2026-10-03 (PROPOSED) | KA-5 | **`insert_workflow` derives numeric group ids by the same pure 53-bit hash as KA-5's link ids, and accepts the same residual collision risk** (PR #264). ComfyUI_frontend's workflow schema declares `groups[].id` as `z.number()` (root and `definitions.subgraphs[].groups`) and refuses the whole workflow on a string, so the string `derivedId` groups used to carry made inserted workflows unloadable. `derivedGroupId` folds `insert:::group:` into `[1, Number.MAX_SAFE_INTEGER]` from the op's own content only (no document read, no retry), so replicas converge regardless of arrival order. Residual probability is the KA-5 row's: `≈ k²/2^54` for `k` groups in one document. **Unlike links, a realized group-id collision is NOT detected**: `applier.ts` merges groups by canonical JSON, not by id, so two distinct groups sharing an id both stay in the document and project with the same id; the frontend's behaviour on duplicate group ids is unverified. `project.ts` coerces a stored string group id to a number ONLY when it matches the derived form (`DERIVED_GROUP_ID`), so a workflow's own string group id round-trips `project(mint(wf))` unchanged and still fails the frontend schema exactly as it would without this package. | `src/remap.ts` `derivedGroupId`, `numericId`; `src/project.ts` `projectGroups`, `DERIVED_GROUP_ID`; `test/insert-workflow-numeric-group-ids.regression.test.ts` | Owner and approval: maintainer's to assign (proposed for Christian Byrne, who reviewed #264). Sunset: revisit if ComfyUI_frontend widens a group's `id` to `string \| number`, at which point the string `derivedId` suffices and this exception can be retired; add id-level collision detection to the groups merge before then if duplicate ids prove harmful on the canvas. | | 2026-10-04 (PROPOSED) | FC-10 | **`widgets_values_form` is a package-local, provisional workflow FIELD** (schema Amendment A24), because the pinned catalog is per-class while the two shapes that need describing are per-instance: a node with two same-named serializable widgets, and a node whose custom serializer emits an object whose non-widget keys must survive a widget write. Neither is derivable from the end state, so the producer declares its instance's ordered widget identity and this package decomposes, addresses and projects through that declaration with no catalog lookup. comfy-cli's frozen `op-vocabulary-v1.md` does not define the field, so the deviation is from FC-10's cite-the-pinned-vocabulary rule rather than from KA-12 (a declaration is the name-to-position mapping, supplied by the party that knows it, not a guess at one). Bounded deliberately: ONE declared key, closed to `{order}` and refused rather than ignored when malformed; every other part of the form is derived; an undeclared node keeps the catalog path and all of its existing refusals; `SCHEMA_VERSION` is unchanged on A2's precedent and under A2's exact condition. **Two residuals, both stated rather than discovered later:** `insert_workflow` strips every `__`-prefixed key at every depth (`prepareInsertedWorkflow` / `scrubPrivateKeys`, a pre-existing anti-forgery guard), so a serializer's own `__`-prefixed data key inside `widgets_values` does not survive THAT path — pinned by test rather than papered over; and the §8.3 autogrow `inputcount` bump still writes the `widgets` map directly and consults no declared order, which is A23's pre-existing gap one op over. | `src/widget-form.ts`; `src/doc.ts` `widgetStorageFor`/`widgetStorageOf`/`storeWidgetValues`; `src/project.ts` `projectWidgets`; `src/applier.ts` `validateWidgetName`/`rejectIfOpaqueWidgets`/`hostWriteStorage`/`createAddedNode`/`rejectUnprojectableWidgets`; `src/read.ts`; `fixtures/golden-vectors/wire-layout.json`; `test/node-local-widget-form.test.ts`; schema Amendment A24 | Owner and approval: maintainer's to assign (FE-3036's owner). Sunset: amend comfy-cli's frozen vocabulary to define the field and pin the adopted definition here, reconciling the name and shape if upstream differs; retire outright if the catalog acquisition ever becomes per-instance, at which point the declaration becomes redundant rather than merely unneeded. | -| 2026-10-11 (PROPOSED) | KA-12 | A25 uses supplied DynamicGroup metadata to validate count writes even on an A24 self-described node. Name/occurrence resolution and projection still use the producer declaration; metadata only checks allocation bounds and refuses changing the addressed occurrence's count without an updated form. Metadata omission cannot identify a controller and remains a caller admission concern. | `src/applier.ts` `validateDynamicGroupValue`; `test/dynamic-group.test.ts`; schema Amendments A24/A25 | Owner and approval: maintainer's to assign. Reconcile when count safety becomes part of the producer declaration or atomic row-operation protocol. | +| 2026-10-11 (PROPOSED) | KA-12 | A25 uses supplied DynamicGroup metadata to validate count writes even on an A24 self-described node. Name/occurrence resolution and projection still use the producer declaration; metadata only checks row-count bounds and refuses changing the addressed occurrence's count without an updated form. Metadata omission cannot identify a controller and remains a caller admission concern. | `src/applier.ts` `validateDynamicGroupValue`; `test/dynamic-group.test.ts`; schema Amendments A24/A25 | Owner and approval: maintainer's to assign. Reconcile when count safety becomes part of the producer declaration. | diff --git a/docs/dynamic-groups.md b/docs/dynamic-groups.md index 85dac89..f604660 100644 --- a/docs/dynamic-groups.md +++ b/docs/dynamic-groups.md @@ -6,9 +6,9 @@ To regenerate `test/fixtures/dynamic-group.json` at that revision, load `tests/c `dynamic_groups` maps a row-count controller to `min`, `max`, relative `widgets`, and field `defaults`. Each row expands immediately after its controller under `..`. Remove any default rows already present in `widget_order` before expanding the saved count. -The catalog controls layout, not prompt validity. Saved rows above an advertised `max` are retained; CLI/core validation decides whether they can execute. Counts must be non-negative safe integers and cannot expand a group beyond the existing `MAX_OVERFLOW_WIDGETS` allocation bound. +The catalog controls layout, not prompt validity. Saved rows above an advertised `max` are retained; CLI/core validation decides whether they can execute. Catalog bounds must be integers with `0 <= min <= max`. Counts must be integers from `min` to the existing `MAX_OVERFLOW_WIDGETS` allocation bound, and row-field names must address a row below that bound. A count below `min` is refused because the frontend raises it to `min`, which would leave the document and canvas with different row counts. -Like dynamic-combo selections, count changes only change projection. Fields in hidden rows retain their name-keyed registers, and newly visible fields without a stored value show template defaults. This avoids receiver-side writes whose outcome depends on op arrival order (KA-2, KA-4). This is not a live structural row operation: it does not remove a middle row, reindex surviving identities, or update connections and promotions. Those changes require the separate atomic row-operation protocol. +Like dynamic-combo selections, count changes only change projection. Fields in hidden rows retain their name-keyed registers, and newly visible fields without a stored value show template defaults. This avoids receiver-side writes whose outcome depends on op arrival order (KA-2, KA-4). This is not a structural row operation: it does not remove a middle row, reindex surviving identities, or update connections and promotions. Agent row changes use whole-group replacement instead: the producer writes the count and every visible row field in one batch, keeping linked or promoted rows in place, so this package needs no structural operation. An explicit `widgets_values_form` remains authoritative for names, occurrences, and projection order. Supplied group metadata is used for count validation only: allocation bounds are checked, and a change from the addressed occurrence's stored count that requires replacing the declaration is refused before mutation. A catalog-free declaration cannot identify group controllers, so that path does not provide count safety. This PR does not introduce an op for changing producer-owned forms. @@ -29,7 +29,7 @@ The released reader `0.3.10` and this draft both use schema v5. The schema gate | Explicit `widgets_values_form` | Either reader, group metadata omitted | Existing field edits retain the declared mapping. Count changes are not safe live row operations. | | Explicit `widgets_values_form` | This reader plus complete group metadata | Existing field edits work; count changes requiring a new declaration are refused before mutation. | -Deploy the producer, complete catalog, package reader, and document host together. Re-mint source workflows when adopting the new pinned catalog. The caller owns compatibility admission; this package cannot recognize missing metadata as a DynamicGroup without guessing. Full Agent row insertion/deletion, declarations, connections, promotions, and convergence remain blocked on the separate atomic row-operation protocol. +Deploy the producer, complete catalog, package reader, and document host together. Re-mint source workflows when adopting the new pinned catalog. The caller owns compatibility admission; this package cannot recognize missing metadata as a DynamicGroup without guessing. Agent row changes use producer-side whole-group replacement over these existing ops. `test/fixtures/dynamic-group-composite.json` records an actual CLI capture from the main-merged working tree. Its implemented producer is pinned at [comfy-cli `acc3b822d428db6c8572dd056bbb58ee217ed77b`](https://github.com/Comfy-Org/comfy-cli/blob/acc3b822d428db6c8572dd056bbb58ee217ed77b/comfy_cli/cql/widget_catalog.py), with `build_types` and `build_catalog` registered in `docs/upstream-pins.json`. The fixture records the capture base and the committed safety follow-up separately. A committed revision is not a released deployment; adopt compatible producer and reader pins together (KA-11, KA-12, FC-10). diff --git a/docs/multiplayer-schema.md b/docs/multiplayer-schema.md index 50d2526..7b62216 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -2377,7 +2377,7 @@ A node carrying the field is **self-described**, and for it: `uncatalogued_widget_write` can arise. A name or occurrence `order` does not list is `unknown_widget`, exactly as a missing `widget_order` entry would be. A25 uses supplied `dynamic_groups` metadata only for count validation: it - checks the allocation bound and refuses a change from the addressed + checks the row-count bounds and refuses a change from the addressed occurrence's stored count that would require replacing the declaration; - `project()` rebuilds `widgets_values` in the shape the producer serialized — an array of `order.length`, or the object in its original key order with each @@ -2502,4 +2502,4 @@ here. An opt-in `dynamic_groups` catalog entry expands a saved row-count controller into indexed widget identities. These use the existing name-keyed registers; no op kind or on-document key changes. The new catalog hash requires coordinated reader adoption. Existing documents retain their original catalog and are re-minted to adopt the new layout. -Count writes change the projected layout, retaining hidden registers and applying fresh-row defaults only at read time. They do not delete rows or links. Explicit `widgets_values_form` declarations remain authoritative; supplied group metadata adds allocation-bound validation and rejects a count change requiring a new declaration before mutation. This is A24's one catalog-validation exception, applied to the addressed occurrence in top-level, interior, and promoted writes. Without group metadata, the package cannot identify count fields; compatible producer/catalog/reader admission remains the caller's responsibility. See [DynamicGroup catalog support](dynamic-groups.md) for the producer contract, bounds, and fixture provenance. +Count writes change the projected layout, retaining hidden registers and applying fresh-row defaults only at read time. They do not delete rows or links. Explicit `widgets_values_form` declarations remain authoritative; supplied group metadata adds row-count bound validation (`min` to the allocation bound) and rejects a count change requiring a new declaration before mutation. This is A24's one catalog-validation exception, applied to the addressed occurrence in top-level, interior, and promoted writes. Without group metadata, the package cannot identify count fields; compatible producer/catalog/reader admission remains the caller's responsibility. See [DynamicGroup catalog support](dynamic-groups.md) for the producer contract, bounds, and fixture provenance. diff --git a/src/dynamic-groups.ts b/src/dynamic-groups.ts index cdbf7d6..cbe130d 100644 --- a/src/dynamic-groups.ts +++ b/src/dynamic-groups.ts @@ -11,10 +11,14 @@ function isGroupField(prefix: string, fields: readonly string[], name: string): const suffix = name.slice(prefix.length + 1); const dot = suffix.indexOf("."); const index = suffix.slice(0, dot); - return dot > 0 && /^(0|[1-9]\d*)$/.test(index) && Number.isSafeInteger(Number(index)) + return dot > 0 && /^(0|[1-9]\d*)$/.test(index) && Number(index) < maxRows(fields) && fields.includes(suffix.slice(dot + 1)); } +function maxRows(fields: readonly string[]): number { + return fields.length === 0 ? 0 : Math.floor(MAX_OVERFLOW_WIDGETS / fields.length); +} + export function isDynamicGroupField(entry: WidgetCatalogEntry | undefined, name: string): boolean { return Object.entries(entry?.dynamic_groups ?? {}).some(([prefix, group]) => isGroupField(prefix, group.widgets, name)); } @@ -47,6 +51,9 @@ export function assertDynamicGroupCatalog(entry: WidgetCatalogEntry): void { || new Set(group.widgets).size !== group.widgets.length) { throw new TypeError(`DynamicGroup '${name}' must declare distinct nonempty relative widget names`); } + if (!Number.isSafeInteger(group.min) || !Number.isSafeInteger(group.max) || group.min < 0 || group.min > group.max) { + throw new TypeError(`DynamicGroup '${name}' must declare integer row bounds with 0 <= min <= max`); + } if (Object.hasOwn(entry.dynamic_combos ?? {}, name) || isDynamicGroupField(entry, name)) { throw new TypeError(`DynamicGroup controller '${name}' collides with another dynamic widget`); } @@ -62,9 +69,8 @@ export function assertDynamicGroupCatalog(entry: WidgetCatalogEntry): void { export function groupCountRefusal(entry: WidgetCatalogEntry | undefined, name: string, value: unknown): string | null { const group = groupOf(entry, name); if (!group) return null; - if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0 - || group.widgets.length === 0 || value > Math.floor(MAX_OVERFLOW_WIDGETS / group.widgets.length)) { - return `${name}: expected a non-negative integer row count within the widget allocation bound`; + if (typeof value !== "number" || !Number.isSafeInteger(value) || value < group.min || value > maxRows(group.widgets)) { + return `${name}: expected an integer row count from the group minimum to the widget allocation bound`; } return null; } diff --git a/test/dynamic-group.test.ts b/test/dynamic-group.test.ts index ee9846c..f0b9867 100644 --- a/test/dynamic-group.test.ts +++ b/test/dynamic-group.test.ts @@ -131,6 +131,9 @@ describe("DynamicGroup catalog layout", () => { widget_order: ["before", "loras", "loras.0.strength", "after"], dynamic_groups: { ...groupEntry.dynamic_groups, "loras.0.strength": { min: 0, max: 3, widgets: ["value"], defaults: { value: 1 } } }, }], + ["minimum above maximum", { ...groupEntry, dynamic_groups: { loras: { ...loras, min: 4, max: 3 } } }], + ["negative minimum", { ...groupEntry, dynamic_groups: { loras: { ...loras, min: -1 } } }], + ["fractional maximum", { ...groupEntry, dynamic_groups: { loras: { ...loras, max: 2.5 } } }], ] satisfies [string, WidgetCatalogEntry][])("refuses %s catalog metadata before naming values", (_label, entry) => { const malformed = structuredClone(catalog); malformed.types["DevToolsNodeWithDynamicGroup"] = entry; @@ -287,6 +290,40 @@ describe("DynamicGroup catalog layout", () => { edit("after", "must not run", 2)); }); + const interiorWorkflow: WorkflowJSON = { + nodes: [{ id: 9, type: "group-definition" }], links: [], + definitions: { subgraphs: [{ id: "group-definition", nodes: cases.populated.nodes, links: [] }] }, + }; + it.each([ + ["top-level", cases.populated, edit("loras", 0), edit("after", "must not run", 2)], + ["interior", interiorWorkflow, { ...edit("loras", 0), path: ["9", "1"], inner_widget: "loras" }, + { ...edit("after", "must not run", 2), path: ["9", "1"], inner_widget: "after" }], + ["promoted", cases.populated, { ...edit("loras", 0), promoted: { value_index: 1, instance_path: ["1"], host_widgets_values: ["head", 0, "tail"] } }, + edit("after", "must not run", 2)], + ] satisfies [string, WorkflowJSON, Op, Op][])("refuses %s counts below the group minimum", (_route, workflow, op, trailing) => { + const minimumOne = structuredClone(catalog); + minimumOne.types["DevToolsNodeWithDynamicGroup"]!.dynamic_groups!["loras"]!.min = 1; + assertRejectedWithoutMutation(workflow, op, "malformed_op", minimumOne, trailing); + }); + + it("refuses a saved count below the group minimum before minting", () => { + const minimumOne = structuredClone(catalog); + minimumOne.types["DevToolsNodeWithDynamicGroup"]!.dynamic_groups!["loras"]!.min = 1; + const workflow = structuredClone(cases.empty); + delete workflow.nodes[0]!["widgets_values_named"]; + workflow.nodes[0]!.widgets_values = { before: "first", loras: 0, after: "last" }; + + expect(() => mint(workflow, minimumOne)).toThrow(/row count/); + }); + + it("refuses row fields beyond the allocation bound without mutation", () => { + assertRejectedWithoutMutation(cases.populated, edit("loras.1000000.strength", 0.5), "unknown_widget", catalog, + edit("after", "must not run", 2)); + const doc = mint(cases.populated, catalog); + expect(applyOps(doc, [edit("loras.1364.strength", 0.5)], catalog).outcomes[0]?.outcome).toBe("applied"); + doc.destroy(); + }); + it("refuses a malformed saved count before minting a misaligned document", () => { const workflow = structuredClone(cases.populated); (workflow.nodes[0]!.widgets_values as unknown[])[1] = -1; From acab5c9b6dcddebd995140f59e9c989d1421fa74 Mon Sep 17 00:00:00 2001 From: jaeone94 <89377375+jaeone94@users.noreply.github.com> Date: Wed, 21 Oct 2026 21:21:03 +0900 Subject: [PATCH 06/10] fix: refuse selector writes that duplicate a DynamicGroup controller Expand the layout a selector write would select before storing it, so a second copy of a group controller is refused without changing the document. --- docs/dynamic-groups.md | 2 +- src/applier.ts | 26 +++++++++++++++++++++++++- src/dynamic-combos.ts | 28 ++++++++++++++++++---------- test/dynamic-group.test.ts | 20 ++++++++++++++++++++ 4 files changed, 64 insertions(+), 12 deletions(-) diff --git a/docs/dynamic-groups.md b/docs/dynamic-groups.md index f604660..b7c7eaf 100644 --- a/docs/dynamic-groups.md +++ b/docs/dynamic-groups.md @@ -16,7 +16,7 @@ No wire key or op kind changes. New catalog content changes the catalog hash. Co ## Namespace safety -Relative group fields must be distinct. A controller cannot also be a DynamicCombo selector or another group's row field. Each source widget order may declare a controller once, and any generated names already present must be its contiguous minimum-row block. The selected layout also refuses duplicate generated fields/controllers before they can share a register. Ordinary duplicate names keep their existing occurrence identities; unrelated dotted names are not rejected merely for sharing a group prefix. Seed companions such as `weights.0.seed.0` remain legal when declared by the template metadata. +Relative group fields must be distinct. A controller cannot also be a DynamicCombo selector or another group's row field. Each source widget order may declare a controller once, and any generated names already present must be its contiguous minimum-row block. The selected layout also refuses duplicate generated fields/controllers before they can share a register. A selector write is checked against the layout it would select, so one that selects a second copy of a controller is refused before mutation. Ordinary duplicate names keep their existing occurrence identities; unrelated dotted names are not rejected merely for sharing a group prefix. Seed companions such as `weights.0.seed.0` remain legal when declared by the template metadata. ## Reader and producer adoption diff --git a/src/applier.ts b/src/applier.ts index bd007dd..f9bd9bc 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -152,12 +152,14 @@ import { type StampKey, type SubgraphDefinition, type WidgetCatalog, + type WidgetCatalogEntry, type WireOp, } from "./types.js"; import { addInteriorLinkOrder, removeInteriorLinkOrder } from "./interior-link-order.js"; -import { groupCountRefusal, groupOf, isDynamicGroupField } from "./dynamic-groups.js"; +import { assertDynamicGroupCatalog, groupCountRefusal, groupOf, isDynamicGroupField } from "./dynamic-groups.js"; import { optionOwnedWidgets, + type PendingWidgetValue, projectedLength, widgetLayoutForWidgets, widgetOrderForProducerOrder, @@ -2029,6 +2031,9 @@ function validateDynamicGroupValue(node: Y.Map, catalog: WidgetCatalog const entry = catalogEntry(catalog, String(node.get("type") ?? "")); const refusal = groupCountRefusal(entry, widget, value); if (refusal) throw new OpRejectedError("malformed_op", refusal); + if (entry?.dynamic_groups && entry.dynamic_combos && Object.hasOwn(entry.dynamic_combos, widget)) { + validateSelectedGroupLayout(node, entry, [widgetStorageKey(widget, occurrence), value]); + } if (groupOf(entry, widget) && storedWidgetFormOf(node)) { const widgets = node.get("widgets"); if (widgets instanceof Y.Map && widgets.get(widgetStorageKey(widget, occurrence)) !== value) { @@ -2037,6 +2042,25 @@ function validateDynamicGroupValue(node: Y.Map, catalog: WidgetCatalog } } +/** + * A selector write can select a second copy of a group controller. Expand the + * layout it would produce before anything is stored, so the refusal leaves the + * document unchanged. + */ +function validateSelectedGroupLayout(node: Y.Map, entry: WidgetCatalogEntry, pending: PendingWidgetValue): void { + assertDynamicGroupCatalog(entry); + const widgets = node.get("widgets"); + const stored = widgets instanceof Y.Map ? widgets : undefined; + const form = storedWidgetFormOf(node); + try { + if (!form) widgetLayoutForWidgets(entry, stored, pending); + else if (form.shape === "array") widgetOrderForProducerOrder(entry, form.order, stored, pending); + } catch (err) { + if (!(err instanceof TypeError)) throw err; + throw new OpRejectedError("malformed_op", err.message); + } +} + function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): SuccessfulOutcome { const { interior, promoted } = validateWidgetOp(op); // Interior paths have several legal spellings (definition id and instance diff --git a/src/dynamic-combos.ts b/src/dynamic-combos.ts index 30c5d14..5d36865 100644 --- a/src/dynamic-combos.ts +++ b/src/dynamic-combos.ts @@ -138,13 +138,25 @@ export function widgetOrderForValues(entry: WidgetCatalogEntry | undefined, wv: return expand(entry, combos ?? {}, () => undefined).order; } +/** A write not yet stored: its storage key and value, read in place of the stored one. */ +export type PendingWidgetValue = readonly [storageKey: string, value: unknown]; + +function storedValue(widgets: Y.Map | undefined, pending: PendingWidgetValue | undefined) { + return (name: string, _index: number, occurrence: number): unknown => { + const key = widgetStorageKey(name, occurrence); + return pending?.[0] === key ? pending[1] : widgets?.get(key); + }; +} + /** The layout for a document node's name-keyed widgets map: order plus read-time defaults. */ -export function widgetLayoutForWidgets(entry: WidgetCatalogEntry, widgets: Y.Map | undefined): WidgetLayout { +export function widgetLayoutForWidgets( + entry: WidgetCatalogEntry, + widgets: Y.Map | undefined, + pending?: PendingWidgetValue, +): WidgetLayout { const combos = combosOf(entry); if (!hasDynamicWidgetLayout(entry)) return { order: entry.widget_order, defaults: new Map() }; - return expand(entry, combos ?? {}, (name, _index, occurrence) => - widgets?.get(widgetStorageKey(name, occurrence)), - ); + return expand(entry, combos ?? {}, storedValue(widgets, pending)); } /** The order for a document node's name-keyed widgets map. */ @@ -166,15 +178,11 @@ export function widgetOrderForProducerOrder( entry: WidgetCatalogEntry, producerOrder: readonly string[], widgets: Y.Map | undefined, + pending?: PendingWidgetValue, ): readonly string[] { const combos = combosOf(entry); if (!combos) return [...producerOrder]; - return expand( - entry, - combos, - (name, _index, occurrence) => widgets?.get(widgetStorageKey(name, occurrence)), - producerOrder, - ).order; + return expand(entry, combos, storedValue(widgets, pending), producerOrder).order; } /** diff --git a/test/dynamic-group.test.ts b/test/dynamic-group.test.ts index f0b9867..3ea516a 100644 --- a/test/dynamic-group.test.ts +++ b/test/dynamic-group.test.ts @@ -59,6 +59,26 @@ describe("DynamicGroup catalog layout", () => { expect(() => mint(workflow, selectedCatalog)).toThrow("controller 'loras' is duplicated in the selected layout"); }); + it.each([true, false])("refuses a selector write that duplicates a controller without mutation (named register %s)", (named) => { + const entry: WidgetCatalogEntry = { + ...groupEntry, + widget_order: ["before", "mode", "other_mode", "after"], + dynamic_combos: { + ...conditionalCatalog.types["DevToolsNodeWithDynamicGroup"]!.dynamic_combos, + other_mode: { default: "off", options: { + off: { widgets: [], defaults: {} }, + on: { widgets: ["loras"], defaults: { loras: 0 } }, + } }, + }, + }; + const selectedCatalog: WidgetCatalog = { types: { DevToolsNodeWithDynamicGroup: entry } }; + const workflow = structuredClone(cases.empty); + workflow.nodes[0]!.widgets_values = ["first", "on", 0, "off", "last"]; + if (named) workflow.nodes[0]!["widgets_values_named"] = { other_mode: "off" }; + assertRejectedWithoutMutation(workflow, edit("other_mode", "on"), "malformed_op", selectedCatalog, + edit("after", "must not run", 2)); + }); + it.each([ ["top-level", 0], ["top-level", 1], ["interior", 0], ["interior", 1], From 8283096112bf0adf6bca54e0e7751ee1e12e139c Mon Sep 17 00:00:00 2001 From: jaeone94 <89377375+jaeone94@users.noreply.github.com> Date: Wed, 21 Oct 2026 21:21:16 +0900 Subject: [PATCH 07/10] fix: keep declared DynamicGroup rows in place on selector refresh An array widgets_values_form owns the positions of the rows it declares. Walk them as stable widgets instead of moving them after the controller. --- docs/dynamic-groups.md | 2 +- src/dynamic-combos.ts | 16 ++++++++++++---- src/dynamic-groups.ts | 7 ++++++- test/dynamic-group.test.ts | 23 +++++++++++++++++++++++ 4 files changed, 42 insertions(+), 6 deletions(-) diff --git a/docs/dynamic-groups.md b/docs/dynamic-groups.md index b7c7eaf..daeb5a7 100644 --- a/docs/dynamic-groups.md +++ b/docs/dynamic-groups.md @@ -10,7 +10,7 @@ The catalog controls layout, not prompt validity. Saved rows above an advertised Like dynamic-combo selections, count changes only change projection. Fields in hidden rows retain their name-keyed registers, and newly visible fields without a stored value show template defaults. This avoids receiver-side writes whose outcome depends on op arrival order (KA-2, KA-4). This is not a structural row operation: it does not remove a middle row, reindex surviving identities, or update connections and promotions. Agent row changes use whole-group replacement instead: the producer writes the count and every visible row field in one batch, keeping linked or promoted rows in place, so this package needs no structural operation. -An explicit `widgets_values_form` remains authoritative for names, occurrences, and projection order. Supplied group metadata is used for count validation only: allocation bounds are checked, and a change from the addressed occurrence's stored count that requires replacing the declaration is refused before mutation. A catalog-free declaration cannot identify group controllers, so that path does not provide count safety. This PR does not introduce an op for changing producer-owned forms. +An explicit `widgets_values_form` remains authoritative for names, occurrences, and projection order. A selector refresh of an array form keeps its declared row fields where the producer placed them. Supplied group metadata is used for count validation only: allocation bounds are checked, and a change from the addressed occurrence's stored count that requires replacing the declaration is refused before mutation. A catalog-free declaration cannot identify group controllers, so that path does not provide count safety. This PR does not introduce an op for changing producer-owned forms. No wire key or op kind changes. New catalog content changes the catalog hash. Consumers must adopt this reader before receiving a DynamicGroup catalog; old documents remain tied to their original catalog and must be re-minted to adopt a new layout (KA-11, KA-12, FC-10). diff --git a/src/dynamic-combos.ts b/src/dynamic-combos.ts index 5d36865..75a4c28 100644 --- a/src/dynamic-combos.ts +++ b/src/dynamic-combos.ts @@ -24,7 +24,7 @@ */ import * as Y from "yjs"; -import { assertDynamicGroupCatalog, groupCountRefusal, groupLayout, groupOf, isDynamicGroupField } from "./dynamic-groups.js"; +import { assertDynamicGroupCatalog, fieldGroupOf, groupCountRefusal, groupLayout, groupOf, isDynamicGroupField } from "./dynamic-groups.js"; import type { DynamicComboEntry, WidgetCatalogEntry } from "./types.js"; import { widgetOccurrenceAt, widgetStorageKey } from "./widget-identity.js"; @@ -77,6 +77,7 @@ function expand( combos: Combos, valueAt: (name: string, index: number, occurrence: number) => unknown, producerOrder: readonly string[] = entry.widget_order, + declaredGroups: ReadonlySet = new Set(), ): WidgetLayout { assertDynamicGroupCatalog(entry); const owned = optionOwnedWidgets(entry); @@ -91,6 +92,10 @@ function expand( order.push(name); seen.add(name); }; + // Rows the producer declared are walked as stable widgets instead. + const appendRows = (name: string, rows: readonly string[]): void => { + if (!declaredGroups.has(name)) rows.forEach(append); + }; const walk = (names: readonly string[], depth: number): void => { for (const name of names) { append(name); @@ -100,7 +105,7 @@ function expand( const group = groupLayout(entry, name, stored); if (group) { group.defaults.forEach((value, child) => defaults.set(child, value)); - group.order.forEach(append); + appendRows(name, group.order); continue; } if (!Object.hasOwn(combos, name)) continue; @@ -115,7 +120,8 @@ function expand( // order, so preserve that order for stable widgets and only replace the // catalog-owned dynamic children. This lets a selector change recompute the // realized order without moving unrelated producer-local widgets. - walk(producerOrder.filter((name) => !owned.has(name) && !isDynamicGroupField(entry, name)), 0); + walk(producerOrder.filter((name) => !owned.has(name) + && (!isDynamicGroupField(entry, name) || declaredGroups.has(fieldGroupOf(entry, name)!))), 0); return { order, defaults }; } @@ -182,7 +188,9 @@ export function widgetOrderForProducerOrder( ): readonly string[] { const combos = combosOf(entry); if (!combos) return [...producerOrder]; - return expand(entry, combos, storedValue(widgets, pending), producerOrder).order; + const owned = optionOwnedWidgets(entry); + const declaredGroups = new Set(producerOrder.filter((name) => groupOf(entry, name) && !owned.has(name))); + return expand(entry, combos, storedValue(widgets, pending), producerOrder, declaredGroups).order; } /** diff --git a/src/dynamic-groups.ts b/src/dynamic-groups.ts index cbe130d..b57f9d0 100644 --- a/src/dynamic-groups.ts +++ b/src/dynamic-groups.ts @@ -19,8 +19,13 @@ function maxRows(fields: readonly string[]): number { return fields.length === 0 ? 0 : Math.floor(MAX_OVERFLOW_WIDGETS / fields.length); } +/** The controller whose generated row field `name` is, if any. */ +export function fieldGroupOf(entry: WidgetCatalogEntry | undefined, name: string): string | undefined { + return Object.entries(entry?.dynamic_groups ?? {}).find(([prefix, group]) => isGroupField(prefix, group.widgets, name))?.[0]; +} + export function isDynamicGroupField(entry: WidgetCatalogEntry | undefined, name: string): boolean { - return Object.entries(entry?.dynamic_groups ?? {}).some(([prefix, group]) => isGroupField(prefix, group.widgets, name)); + return fieldGroupOf(entry, name) !== undefined; } function assertDynamicGroupOrder(entry: WidgetCatalogEntry, name: string, order: readonly string[]): boolean { diff --git a/test/dynamic-group.test.ts b/test/dynamic-group.test.ts index 3ea516a..d879d09 100644 --- a/test/dynamic-group.test.ts +++ b/test/dynamic-group.test.ts @@ -79,6 +79,29 @@ describe("DynamicGroup catalog layout", () => { edit("after", "must not run", 2)); }); + it("keeps declared row fields in place when a selector refreshes the form", () => { + const formCatalog: WidgetCatalog = { types: { DevToolsNodeWithDynamicGroup: { + widget_order: ["rows", "after", "mode"], + dynamic_groups: { rows: { min: 0, max: 3, widgets: ["x"], defaults: { x: 0 } } }, + dynamic_combos: { mode: { default: "basic", options: { + basic: { widgets: [], defaults: {} }, + advanced: { widgets: ["child"], defaults: {} }, + } } }, + } } }; + const workflow = structuredClone(cases.empty); + workflow.nodes[0]!.widgets_values = [1, "tail", 42, "basic"]; + workflow.nodes[0]!.widgets_values_form = { order: ["rows", "after", "rows.0.x", "mode"] }; + const doc = mint(workflow, formCatalog); + + expect(applyOps(doc, [edit("mode", "advanced")], formCatalog).outcomes[0]?.outcome).toBe("applied"); + const node = project(doc, formCatalog).nodes[0]!; + expect(node.widgets_values_form).toEqual({ order: ["rows", "after", "rows.0.x", "mode", "child"] }); + expect(node.widgets_values).toEqual([1, "tail", 42, "advanced", null]); + expect(applyOps(doc, [edit("mode", "basic", 2)], formCatalog).outcomes[0]?.outcome).toBe("applied"); + expect(project(doc, formCatalog).nodes[0]!.widgets_values_form).toEqual(workflow.nodes[0]!.widgets_values_form); + doc.destroy(); + }); + it.each([ ["top-level", 0], ["top-level", 1], ["interior", 0], ["interior", 1], From 6ac57e4bde4a5ba614d70eb3ef13415eda7cd7e7 Mon Sep 17 00:00:00 2001 From: jaeone94 <89377375+jaeone94@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:32:43 +0900 Subject: [PATCH 08/10] fix: refuse ambiguous DynamicGroup controllers in the catalog Reject a catalog in which one selection could lay out a controller twice, or a DynamicCombo option lists generated row names. Every replica refuses it identically at mint, so a selector write no longer depends on another selector's stored value or arrival order. Drop the write-time preflight this replaces. --- docs/dynamic-groups.md | 2 +- src/applier.ts | 26 +------------- src/dynamic-combos.ts | 29 ++++++--------- src/dynamic-groups.ts | 36 +++++++++++++++++-- test/dynamic-group.test.ts | 74 +++++++++++++++++++------------------- 5 files changed, 85 insertions(+), 82 deletions(-) diff --git a/docs/dynamic-groups.md b/docs/dynamic-groups.md index daeb5a7..e2a6e34 100644 --- a/docs/dynamic-groups.md +++ b/docs/dynamic-groups.md @@ -16,7 +16,7 @@ No wire key or op kind changes. New catalog content changes the catalog hash. Co ## Namespace safety -Relative group fields must be distinct. A controller cannot also be a DynamicCombo selector or another group's row field. Each source widget order may declare a controller once, and any generated names already present must be its contiguous minimum-row block. The selected layout also refuses duplicate generated fields/controllers before they can share a register. A selector write is checked against the layout it would select, so one that selects a second copy of a controller is refused before mutation. Ordinary duplicate names keep their existing occurrence identities; unrelated dotted names are not rejected merely for sharing a group prefix. Seed companions such as `weights.0.seed.0` remain legal when declared by the template metadata. +Relative group fields must be distinct. A controller cannot also be a DynamicCombo selector or another group's row field. Each source widget order may declare a controller once, and any generated names already present must be its contiguous minimum-row block. The catalog is also refused if any selection could lay out a controller twice, such as two selectors whose options both offer it, or if a DynamicCombo option lists generated row names. This check uses only the catalog, so the outcome of a selector write never depends on another selector's stored value or on arrival order (KA-4). Several options of one selector may offer the same controller, because only one of them is selected at a time. Ordinary duplicate names keep their existing occurrence identities; unrelated dotted names are not rejected merely for sharing a group prefix. Seed companions such as `weights.0.seed.0` remain legal when declared by the template metadata. ## Reader and producer adoption diff --git a/src/applier.ts b/src/applier.ts index f9bd9bc..bd007dd 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -152,14 +152,12 @@ import { type StampKey, type SubgraphDefinition, type WidgetCatalog, - type WidgetCatalogEntry, type WireOp, } from "./types.js"; import { addInteriorLinkOrder, removeInteriorLinkOrder } from "./interior-link-order.js"; -import { assertDynamicGroupCatalog, groupCountRefusal, groupOf, isDynamicGroupField } from "./dynamic-groups.js"; +import { groupCountRefusal, groupOf, isDynamicGroupField } from "./dynamic-groups.js"; import { optionOwnedWidgets, - type PendingWidgetValue, projectedLength, widgetLayoutForWidgets, widgetOrderForProducerOrder, @@ -2031,9 +2029,6 @@ function validateDynamicGroupValue(node: Y.Map, catalog: WidgetCatalog const entry = catalogEntry(catalog, String(node.get("type") ?? "")); const refusal = groupCountRefusal(entry, widget, value); if (refusal) throw new OpRejectedError("malformed_op", refusal); - if (entry?.dynamic_groups && entry.dynamic_combos && Object.hasOwn(entry.dynamic_combos, widget)) { - validateSelectedGroupLayout(node, entry, [widgetStorageKey(widget, occurrence), value]); - } if (groupOf(entry, widget) && storedWidgetFormOf(node)) { const widgets = node.get("widgets"); if (widgets instanceof Y.Map && widgets.get(widgetStorageKey(widget, occurrence)) !== value) { @@ -2042,25 +2037,6 @@ function validateDynamicGroupValue(node: Y.Map, catalog: WidgetCatalog } } -/** - * A selector write can select a second copy of a group controller. Expand the - * layout it would produce before anything is stored, so the refusal leaves the - * document unchanged. - */ -function validateSelectedGroupLayout(node: Y.Map, entry: WidgetCatalogEntry, pending: PendingWidgetValue): void { - assertDynamicGroupCatalog(entry); - const widgets = node.get("widgets"); - const stored = widgets instanceof Y.Map ? widgets : undefined; - const form = storedWidgetFormOf(node); - try { - if (!form) widgetLayoutForWidgets(entry, stored, pending); - else if (form.shape === "array") widgetOrderForProducerOrder(entry, form.order, stored, pending); - } catch (err) { - if (!(err instanceof TypeError)) throw err; - throw new OpRejectedError("malformed_op", err.message); - } -} - function applySetWidget(doc: Y.Doc, op: SetWidgetOp, catalog?: WidgetCatalog): SuccessfulOutcome { const { interior, promoted } = validateWidgetOp(op); // Interior paths have several legal spellings (definition id and instance diff --git a/src/dynamic-combos.ts b/src/dynamic-combos.ts index 75a4c28..c39698f 100644 --- a/src/dynamic-combos.ts +++ b/src/dynamic-combos.ts @@ -144,25 +144,13 @@ export function widgetOrderForValues(entry: WidgetCatalogEntry | undefined, wv: return expand(entry, combos ?? {}, () => undefined).order; } -/** A write not yet stored: its storage key and value, read in place of the stored one. */ -export type PendingWidgetValue = readonly [storageKey: string, value: unknown]; - -function storedValue(widgets: Y.Map | undefined, pending: PendingWidgetValue | undefined) { - return (name: string, _index: number, occurrence: number): unknown => { - const key = widgetStorageKey(name, occurrence); - return pending?.[0] === key ? pending[1] : widgets?.get(key); - }; -} - /** The layout for a document node's name-keyed widgets map: order plus read-time defaults. */ -export function widgetLayoutForWidgets( - entry: WidgetCatalogEntry, - widgets: Y.Map | undefined, - pending?: PendingWidgetValue, -): WidgetLayout { +export function widgetLayoutForWidgets(entry: WidgetCatalogEntry, widgets: Y.Map | undefined): WidgetLayout { const combos = combosOf(entry); if (!hasDynamicWidgetLayout(entry)) return { order: entry.widget_order, defaults: new Map() }; - return expand(entry, combos ?? {}, storedValue(widgets, pending)); + return expand(entry, combos ?? {}, (name, _index, occurrence) => + widgets?.get(widgetStorageKey(name, occurrence)), + ); } /** The order for a document node's name-keyed widgets map. */ @@ -184,13 +172,18 @@ export function widgetOrderForProducerOrder( entry: WidgetCatalogEntry, producerOrder: readonly string[], widgets: Y.Map | undefined, - pending?: PendingWidgetValue, ): readonly string[] { const combos = combosOf(entry); if (!combos) return [...producerOrder]; const owned = optionOwnedWidgets(entry); const declaredGroups = new Set(producerOrder.filter((name) => groupOf(entry, name) && !owned.has(name))); - return expand(entry, combos, storedValue(widgets, pending), producerOrder, declaredGroups).order; + return expand( + entry, + combos, + (name, _index, occurrence) => widgets?.get(widgetStorageKey(name, occurrence)), + producerOrder, + declaredGroups, + ).order; } /** diff --git a/src/dynamic-groups.ts b/src/dynamic-groups.ts index b57f9d0..3ba8bc8 100644 --- a/src/dynamic-groups.ts +++ b/src/dynamic-groups.ts @@ -44,12 +44,43 @@ function assertDynamicGroupOrder(entry: WidgetCatalogEntry, name: string, order: return controllerIndex >= 0; } +/** The most copies of `name` one selection can lay out from `names`, walking selectors to the same depth as layout expansion. */ +function maxSelectedCopies(entry: WidgetCatalogEntry, name: string, names: readonly string[], depth: number): number { + const combos = entry.dynamic_combos ?? {}; + let copies = 0; + for (const widget of names) { + if (widget === name) copies++; + if (!Object.hasOwn(combos, widget) || depth > 32) continue; + copies += Math.max(0, ...Object.values(combos[widget]!.options).map((option) => + maxSelectedCopies(entry, name, option.widgets, depth + 1))); + } + return copies; +} + +/** + * Refuse, from the catalog alone, any selection that would lay out a controller + * or its generated rows twice. Refusing on write instead would make the outcome + * depend on which selector write arrived first. + */ +function assertSingleSelection(entry: WidgetCatalogEntry, name: string, baseOrder: readonly string[], optionOrders: readonly (readonly string[])[]): void { + if (maxSelectedCopies(entry, name, baseOrder, 0) > 1) { + throw new TypeError(`DynamicGroup controller '${name}' can be selected more than once`); + } + const fields = groupOf(entry, name)!.widgets; + if (optionOrders.some((order) => order.some((widget) => isGroupField(name, fields, widget)))) { + throw new TypeError(`DynamicGroup '${name}' generated widget names cannot be listed in a DynamicCombo option`); + } +} + export function assertDynamicGroupCatalog(entry: WidgetCatalogEntry): void { const groups = Object.entries(entry.dynamic_groups ?? {}); if (groups.length === 0) return; - const orders = [entry.widget_order, ...Object.values(entry.dynamic_combos ?? {}).flatMap((combo) => + const optionOrders = Object.values(entry.dynamic_combos ?? {}).flatMap((combo) => Object.values(combo.options).map((option) => option.widgets), - )]; + ); + const orders = [entry.widget_order, ...optionOrders]; + const owned = new Set(optionOrders.flat()); + const baseOrder = entry.widget_order.filter((widget) => !owned.has(widget)); for (const [name, group] of groups) { if (!Array.isArray(group.widgets) || group.widgets.length === 0 || group.widgets.some((field) => typeof field !== "string" || field.length === 0) @@ -68,6 +99,7 @@ export function assertDynamicGroupCatalog(entry: WidgetCatalogEntry): void { controllerFound ||= present; } if (!controllerFound) throw new TypeError(`DynamicGroup controller '${name}' is missing from widget order`); + assertSingleSelection(entry, name, baseOrder, optionOrders); } } diff --git a/test/dynamic-group.test.ts b/test/dynamic-group.test.ts index d879d09..3a2c4b8 100644 --- a/test/dynamic-group.test.ts +++ b/test/dynamic-group.test.ts @@ -35,48 +35,23 @@ const edit = (widget: string, value: unknown, counter = 1) => ({ } satisfies TopLevelSetWidgetOp); describe("DynamicGroup catalog layout", () => { - it("refuses a controller duplicated only by the selected combo composition", () => { + it("accepts a controller offered by several options of one selector", () => { const entry: WidgetCatalogEntry = { - ...groupEntry, - widget_order: ["before", "mode", "other_mode", "after"], - dynamic_combos: { - ...conditionalCatalog.types["DevToolsNodeWithDynamicGroup"]!.dynamic_combos, - other_mode: { default: "off", options: { - off: { widgets: [], defaults: {} }, - on: { widgets: ["loras"], defaults: { loras: 0 } }, - } }, - }, + ...conditionalCatalog.types["DevToolsNodeWithDynamicGroup"]!, + dynamic_combos: { mode: { default: "off", options: { + off: { widgets: [], defaults: {} }, + on: { widgets: ["loras"], defaults: { loras: 0 } }, + alt: { widgets: ["loras"], defaults: { loras: 0 } }, + } } }, }; const selectedCatalog: WidgetCatalog = { types: { DevToolsNodeWithDynamicGroup: entry } }; const workflow = structuredClone(cases.empty); - const values = { before: "first", mode: "on", loras: 0, other_mode: "off", after: "last" }; - workflow.nodes[0]!.widgets_values = values; + workflow.nodes[0]!.widgets_values = { before: "first", mode: "on", loras: 0, after: "last" }; const doc = mint(workflow, selectedCatalog); - expect(project(doc, selectedCatalog).nodes[0]!.widgets_values).toEqual(["first", "on", 0, "off", "last"]); - doc.destroy(); - workflow.nodes[0]!.widgets_values = { ...values, other_mode: "on" }; - expect(() => mint(workflow, selectedCatalog)).toThrow("controller 'loras' is duplicated in the selected layout"); - }); - - it.each([true, false])("refuses a selector write that duplicates a controller without mutation (named register %s)", (named) => { - const entry: WidgetCatalogEntry = { - ...groupEntry, - widget_order: ["before", "mode", "other_mode", "after"], - dynamic_combos: { - ...conditionalCatalog.types["DevToolsNodeWithDynamicGroup"]!.dynamic_combos, - other_mode: { default: "off", options: { - off: { widgets: [], defaults: {} }, - on: { widgets: ["loras"], defaults: { loras: 0 } }, - } }, - }, - }; - const selectedCatalog: WidgetCatalog = { types: { DevToolsNodeWithDynamicGroup: entry } }; - const workflow = structuredClone(cases.empty); - workflow.nodes[0]!.widgets_values = ["first", "on", 0, "off", "last"]; - if (named) workflow.nodes[0]!["widgets_values_named"] = { other_mode: "off" }; - assertRejectedWithoutMutation(workflow, edit("other_mode", "on"), "malformed_op", selectedCatalog, - edit("after", "must not run", 2)); + expect(applyOps(doc, [edit("mode", "alt")], selectedCatalog).outcomes[0]?.outcome).toBe("applied"); + expect(project(doc, selectedCatalog).nodes[0]!.widgets_values).toEqual(["first", "alt", 0, "last"]); + doc.destroy(); }); it("keeps declared row fields in place when a selector refreshes the form", () => { @@ -174,6 +149,33 @@ describe("DynamicGroup catalog layout", () => { widget_order: ["before", "loras", "loras.0.strength", "after"], dynamic_groups: { ...groupEntry.dynamic_groups, "loras.0.strength": { min: 0, max: 3, widgets: ["value"], defaults: { value: 1 } } }, }], + ["controller selectable from two selectors", { + ...groupEntry, + widget_order: ["before", "mode", "other_mode", "after"], + dynamic_combos: { + ...conditionalCatalog.types["DevToolsNodeWithDynamicGroup"]!.dynamic_combos, + other_mode: { default: "off", options: { + off: { widgets: [], defaults: {} }, + on: { widgets: ["loras"], defaults: { loras: 0 } }, + } }, + }, + }], + ["controller selectable through a nested selector and its parent", { + ...groupEntry, + widget_order: ["before", "mode", "after"], + dynamic_combos: { + mode: { default: "off", options: { off: { widgets: [], defaults: {} }, on: { widgets: ["loras", "inner"], defaults: {} } } }, + inner: { default: "off", options: { off: { widgets: [], defaults: {} }, on: { widgets: ["loras"], defaults: {} } } }, + }, + }], + ["generated row name listed in a DynamicCombo option", { + ...groupEntry, + widget_order: ["before", "mode", "after"], + dynamic_groups: { loras: { ...loras, min: 1 } }, + dynamic_combos: { mode: { default: "on", options: { + on: { widgets: ["loras", "loras.0.lora_name", "loras.0.strength", "loras.0.enabled"], defaults: {} }, + } } }, + }], ["minimum above maximum", { ...groupEntry, dynamic_groups: { loras: { ...loras, min: 4, max: 3 } } }], ["negative minimum", { ...groupEntry, dynamic_groups: { loras: { ...loras, min: -1 } } }], ["fractional maximum", { ...groupEntry, dynamic_groups: { loras: { ...loras, max: 2.5 } } }], From a7ccd5d066fd5864d6b79e3f5646b58cc942d141 Mon Sep 17 00:00:00 2001 From: jaeone94 <89377375+jaeone94@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:35:22 +0900 Subject: [PATCH 09/10] fix: share the DynamicGroup row bound across an entry's groups Divide MAX_OVERFLOW_WIDGETS by the total row fields of every group in the entry instead of by one group's fields, so adding controllers no longer multiplies how many row slots a projection can allocate. --- docs/dynamic-groups.md | 2 +- src/dynamic-groups.ts | 21 +++++++++++++-------- test/dynamic-group.test.ts | 21 +++++++++++++++++++++ 3 files changed, 35 insertions(+), 9 deletions(-) diff --git a/docs/dynamic-groups.md b/docs/dynamic-groups.md index e2a6e34..231869f 100644 --- a/docs/dynamic-groups.md +++ b/docs/dynamic-groups.md @@ -6,7 +6,7 @@ To regenerate `test/fixtures/dynamic-group.json` at that revision, load `tests/c `dynamic_groups` maps a row-count controller to `min`, `max`, relative `widgets`, and field `defaults`. Each row expands immediately after its controller under `..`. Remove any default rows already present in `widget_order` before expanding the saved count. -The catalog controls layout, not prompt validity. Saved rows above an advertised `max` are retained; CLI/core validation decides whether they can execute. Catalog bounds must be integers with `0 <= min <= max`. Counts must be integers from `min` to the existing `MAX_OVERFLOW_WIDGETS` allocation bound, and row-field names must address a row below that bound. A count below `min` is refused because the frontend raises it to `min`, which would leave the document and canvas with different row counts. +The catalog controls layout, not prompt validity. Saved rows above an advertised `max` are retained; CLI/core validation decides whether they can execute. Catalog bounds must be integers with `0 <= min <= max`. Counts must be integers from `min` to the allocation bound, and row-field names must address a row below that bound. The bound is shared by every group of an entry: `MAX_OVERFLOW_WIDGETS` divided by the total number of row fields across those groups. So all of an entry's rows together stay within `MAX_OVERFLOW_WIDGETS` slots, however many controllers the entry has. A count below `min` is refused because the frontend raises it to `min`, which would leave the document and canvas with different row counts. Like dynamic-combo selections, count changes only change projection. Fields in hidden rows retain their name-keyed registers, and newly visible fields without a stored value show template defaults. This avoids receiver-side writes whose outcome depends on op arrival order (KA-2, KA-4). This is not a structural row operation: it does not remove a middle row, reindex surviving identities, or update connections and promotions. Agent row changes use whole-group replacement instead: the producer writes the count and every visible row field in one batch, keeping linked or promoted rows in place, so this package needs no structural operation. diff --git a/src/dynamic-groups.ts b/src/dynamic-groups.ts index 3ba8bc8..aae8d99 100644 --- a/src/dynamic-groups.ts +++ b/src/dynamic-groups.ts @@ -6,22 +6,25 @@ export function groupOf(entry: WidgetCatalogEntry | undefined, name: string) { return groups && Object.hasOwn(groups, name) ? groups[name] : undefined; } -function isGroupField(prefix: string, fields: readonly string[], name: string): boolean { +function isGroupField(entry: WidgetCatalogEntry, prefix: string, fields: readonly string[], name: string): boolean { if (!name.startsWith(`${prefix}.`)) return false; const suffix = name.slice(prefix.length + 1); const dot = suffix.indexOf("."); const index = suffix.slice(0, dot); - return dot > 0 && /^(0|[1-9]\d*)$/.test(index) && Number(index) < maxRows(fields) + return dot > 0 && /^(0|[1-9]\d*)$/.test(index) && Number(index) < maxRows(entry) && fields.includes(suffix.slice(dot + 1)); } -function maxRows(fields: readonly string[]): number { - return fields.length === 0 ? 0 : Math.floor(MAX_OVERFLOW_WIDGETS / fields.length); +/** Every group may hold this many rows, so all of an entry's rows together stay within one allocation bound. */ +function maxRows(entry: WidgetCatalogEntry): number { + const fields = Object.values(entry.dynamic_groups ?? {}).reduce((total, group) => total + group.widgets.length, 0); + return fields === 0 ? 0 : Math.floor(MAX_OVERFLOW_WIDGETS / fields); } /** The controller whose generated row field `name` is, if any. */ export function fieldGroupOf(entry: WidgetCatalogEntry | undefined, name: string): string | undefined { - return Object.entries(entry?.dynamic_groups ?? {}).find(([prefix, group]) => isGroupField(prefix, group.widgets, name))?.[0]; + if (!entry) return undefined; + return Object.entries(entry.dynamic_groups ?? {}).find(([prefix, group]) => isGroupField(entry, prefix, group.widgets, name))?.[0]; } export function isDynamicGroupField(entry: WidgetCatalogEntry | undefined, name: string): boolean { @@ -34,7 +37,7 @@ function assertDynamicGroupOrder(entry: WidgetCatalogEntry, name: string, order: if (controllerIndex !== order.lastIndexOf(name)) { throw new TypeError(`DynamicGroup controller '${name}' is duplicated in widget order`); } - const generated = order.filter((widget) => isGroupField(name, group.widgets, widget)); + const generated = order.filter((widget) => isGroupField(entry, name, group.widgets, widget)); if (generated.length === 0) return controllerIndex >= 0; const minimum = groupLayout(entry, name, group.min)!.order; if (controllerIndex < 0 || generated.length !== minimum.length @@ -67,7 +70,7 @@ function assertSingleSelection(entry: WidgetCatalogEntry, name: string, baseOrde throw new TypeError(`DynamicGroup controller '${name}' can be selected more than once`); } const fields = groupOf(entry, name)!.widgets; - if (optionOrders.some((order) => order.some((widget) => isGroupField(name, fields, widget)))) { + if (optionOrders.some((order) => order.some((widget) => isGroupField(entry, name, fields, widget)))) { throw new TypeError(`DynamicGroup '${name}' generated widget names cannot be listed in a DynamicCombo option`); } } @@ -90,6 +93,8 @@ export function assertDynamicGroupCatalog(entry: WidgetCatalogEntry): void { if (!Number.isSafeInteger(group.min) || !Number.isSafeInteger(group.max) || group.min < 0 || group.min > group.max) { throw new TypeError(`DynamicGroup '${name}' must declare integer row bounds with 0 <= min <= max`); } + } + for (const [name] of groups) { if (Object.hasOwn(entry.dynamic_combos ?? {}, name) || isDynamicGroupField(entry, name)) { throw new TypeError(`DynamicGroup controller '${name}' collides with another dynamic widget`); } @@ -106,7 +111,7 @@ export function assertDynamicGroupCatalog(entry: WidgetCatalogEntry): void { export function groupCountRefusal(entry: WidgetCatalogEntry | undefined, name: string, value: unknown): string | null { const group = groupOf(entry, name); if (!group) return null; - if (typeof value !== "number" || !Number.isSafeInteger(value) || value < group.min || value > maxRows(group.widgets)) { + if (typeof value !== "number" || !Number.isSafeInteger(value) || value < group.min || value > maxRows(entry!)) { return `${name}: expected an integer row count from the group minimum to the widget allocation bound`; } return null; diff --git a/test/dynamic-group.test.ts b/test/dynamic-group.test.ts index 3a2c4b8..c4e0626 100644 --- a/test/dynamic-group.test.ts +++ b/test/dynamic-group.test.ts @@ -369,6 +369,27 @@ describe("DynamicGroup catalog layout", () => { doc.destroy(); }); + it("shares one allocation bound across every group of an entry", () => { + const sharedCatalog: WidgetCatalog = { types: { DevToolsNodeWithDynamicGroup: { + widget_order: ["first", "second"], + dynamic_groups: { + first: { min: 0, max: 3, widgets: ["x"], defaults: { x: 0 } }, + second: { min: 0, max: 3, widgets: ["y"], defaults: { y: 0 } }, + }, + } } }; + const workflow = structuredClone(cases.empty); + delete workflow.nodes[0]!["widgets_values_named"]; + workflow.nodes[0]!.widgets_values = [0, 0]; + assertRejectedWithoutMutation(workflow, edit("first", 2049), "malformed_op", sharedCatalog, edit("second", 1, 2)); + assertRejectedWithoutMutation(workflow, edit("first.2048.x", 1), "unknown_widget", sharedCatalog, edit("second", 1, 2)); + + const doc = mint(workflow, sharedCatalog); + expect(applyOps(doc, [edit("first", 2048), edit("second", 2048, 2)], sharedCatalog).outcomes.map((o) => o.outcome)) + .toEqual(["applied", "applied"]); + expect(project(doc, sharedCatalog).nodes[0]!.widgets_values).toHaveLength(2 + 4096); + doc.destroy(); + }); + it("refuses a malformed saved count before minting a misaligned document", () => { const workflow = structuredClone(cases.populated); (workflow.nodes[0]!.widgets_values as unknown[])[1] = -1; From c0ee52d30e120e612b41806dd20da01f0abed7c2 Mon Sep 17 00:00:00 2001 From: jaeone94 <89377375+jaeone94@users.noreply.github.com> Date: Fri, 23 Oct 2026 16:37:05 +0900 Subject: [PATCH 10/10] test: hold the A26 schema-v5 basis against the published reader Show that the published 0.3.10 reader projects every document this writer persists under a catalog without dynamic_groups, and that it cannot read a DynamicGroup catalog document safely. Record the catalog-pin basis in KA-11 and the reader-before-catalog adoption order. --- docs/INVARIANTS.md | 14 ++++++++++++++ docs/dynamic-groups.md | 2 +- test/dynamic-group.test.ts | 38 +++++++++++++++++++++++++++++++++++++- 3 files changed, 52 insertions(+), 2 deletions(-) diff --git a/docs/INVARIANTS.md b/docs/INVARIANTS.md index f6e3c1e..8c7fbac 100644 --- a/docs/INVARIANTS.md +++ b/docs/INVARIANTS.md @@ -126,6 +126,20 @@ abort-remainder, and a real published-0.3.10 mixed-reader projection check. That last check is the KA-11 basis for no bump: the old reader projects every state the new writer persists identically. +Amendment A26 also keeps schema v5, on A24's basis rather than A25's. Row +field keys such as `loras.1.lora_name` are reachable only on a node whose +pinned catalog declares `dynamic_groups`, and no catalog did before A26, so +no existing v5 document can contain them. A bump would instead make every +existing v5 document unreadable under the no-compat-reader policy above. +Backward compatibility does not hold under a DynamicGroup catalog: the +published 0.3.10 reader throws on a stored row key and silently drops rows +that hold no stored value. The protection is therefore the catalog pin, and +reader adoption must precede DynamicGroup catalog adoption. +`test/dynamic-group.test.ts` holds both sides against the published reader. +Under a catalog without `dynamic_groups`, the new writer refuses row names +and the old reader projects its documents identically. Under a DynamicGroup +catalog, the old reader is unsafe in both ways. + ### KA-12 — Catalog pinned at mint **Rule:** `meta.catalog_version` cites the catalog by SHA, not branch; reject NAMED widget writes to uncatalogued classes loudly. A subgraph instance's `type` is a definition UUID that no catalog describes, and its promoted widget values are POSITIONAL by frontend contract (ADR 0009), so a promoted host write (schema Amendment A15) is not a widget-name resolution and needs no catalog entry for the instance — it still needs A CATALOG (`catalog_required` without one) to tell an instance from an unseen class, and still refuses (`uncatalogued_widget_write`) to lay a positional array over named values the catalog cannot describe. A node that DECLARES its own ordered widget identity (`widgets_values_form`, schema Amendment A24) is resolved from that declaration. An object form stays catalog-free and closed; under Amendment A25 an array form may additionally accept names owned by the pinned `dynamic_combos` catalog and persists the resulting realized order after the winning selector write. This does not relax the rule: the package uses only mappings supplied by the producer or the immutable catalog, never guesses one. Amendment A26 adds one validation exception: supplied `dynamic_groups` metadata identifies count fields for row-count bound checks and refuses a count change that would invalidate the declaration, using the addressed occurrence's current value. The declaration still owns ordering; the catalog does not replace it. Without that metadata, the package cannot identify a count field, so callers must enforce compatible producer, catalog, and reader adoption. An undeclared node keeps every refusal above, and `meta.catalog_version` still pins the catalog every other node projects against. **Why:** Replay semantics must not drift with a moving vocabulary. diff --git a/docs/dynamic-groups.md b/docs/dynamic-groups.md index 231869f..f7607a9 100644 --- a/docs/dynamic-groups.md +++ b/docs/dynamic-groups.md @@ -29,7 +29,7 @@ The released reader `0.3.10` and this draft both use schema v5. The schema gate | Explicit `widgets_values_form` | Either reader, group metadata omitted | Existing field edits retain the declared mapping. Count changes are not safe live row operations. | | Explicit `widgets_values_form` | This reader plus complete group metadata | Existing field edits work; count changes requiring a new declaration are refused before mutation. | -Deploy the producer, complete catalog, package reader, and document host together. Re-mint source workflows when adopting the new pinned catalog. The caller owns compatibility admission; this package cannot recognize missing metadata as a DynamicGroup without guessing. Agent row changes use producer-side whole-group replacement over these existing ops. +Schema v5 is kept on A24's basis: only a DynamicGroup catalog makes row keys reachable (KA-11). The published 0.3.10 reader throws on a document with stored row values and silently drops rows that have none, so it must never receive a DynamicGroup catalog. Adopt this reader everywhere before any DynamicGroup catalog is pinned. This is the reverse of the usual order, where the catalog pin moves first. Deploy the producer, complete catalog, package reader, and document host together. Re-mint source workflows when adopting the new pinned catalog. The caller owns compatibility admission; this package cannot recognize missing metadata as a DynamicGroup without guessing. Agent row changes use producer-side whole-group replacement over these existing ops. `test/fixtures/dynamic-group-composite.json` records an actual CLI capture from the main-merged working tree. Its implemented producer is pinned at [comfy-cli `acc3b822d428db6c8572dd056bbb58ee217ed77b`](https://github.com/Comfy-Org/comfy-cli/blob/acc3b822d428db6c8572dd056bbb58ee217ed77b/comfy_cli/cql/widget_catalog.py), with `build_types` and `build_catalog` registered in `docs/upstream-pins.json`. The fixture records the capture base and the committed safety follow-up separately. A committed revision is not a released deployment; adopt compatible producer and reader pins together (KA-11, KA-12, FC-10). diff --git a/test/dynamic-group.test.ts b/test/dynamic-group.test.ts index c4e0626..704f38f 100644 --- a/test/dynamic-group.test.ts +++ b/test/dynamic-group.test.ts @@ -1,7 +1,8 @@ import { readFileSync } from "node:fs"; import * as Y from "yjs"; import { describe, expect, it } from "vitest"; -import { applyOps, mint, project, type Op, type SetWidgetOp, type TopLevelSetWidgetOp, type WidgetCatalog, type WidgetCatalogEntry, type WorkflowJSON } from "../src/index.js"; +import { SCHEMA_VERSION as SCHEMA_VERSION_0310, project as project0310 } from "comfy-multi-player-v0310"; +import { SCHEMA_VERSION, applyOps, mint, project, type Op, type SetWidgetOp, type TopLevelSetWidgetOp, type WidgetCatalog, type WidgetCatalogEntry, type WorkflowJSON } from "../src/index.js"; import { canonicalize } from "./helpers.js"; import { assertRejectedWithoutMutation } from "./rejection-test-helpers.js"; @@ -552,3 +553,38 @@ describe("DynamicGroup catalog layout", () => { doc.destroy(); }); }); + +describe("published pre-A26 reader (0.3.10)", () => { + const withoutGroups = structuredClone(catalog); + delete withoutGroups.types["DevToolsNodeWithDynamicGroup"]!.dynamic_groups; + + it("projects every state this writer persists under a catalog without dynamic_groups", () => { + expect(SCHEMA_VERSION_0310).toBe(SCHEMA_VERSION); + const workflow = structuredClone(cases.empty); + delete workflow.nodes[0]!["widgets_values_named"]; + workflow.nodes[0]!.widgets_values = ["first", 0, "last"]; + const doc = mint(workflow, withoutGroups); + + expect(applyOps(doc, [edit("loras.1.lora_name", "WRITTEN.safetensors")], withoutGroups).outcomes[0]) + .toMatchObject({ outcome: "rejected", reason: { code: "unknown_widget" } }); + expect(applyOps(doc, [edit("loras", 2, 2), edit("after", "edited", 3)], withoutGroups).outcomes.map((o) => o.outcome)) + .toEqual(["applied", "applied"]); + expect(project0310(doc, withoutGroups)).toEqual(project(doc, withoutGroups)); + doc.destroy(); + }); + + it("cannot read a document minted under a DynamicGroup catalog", () => { + const populated = mint(cases.populated, catalog); + expect(() => project0310(populated, catalog)).toThrow("widget 'loras.0.lora_name' is not in widget_order"); + populated.destroy(); + + // Rows that hold no stored value are not even refused: the old reader drops them silently. + const workflow = structuredClone(cases.empty); + delete workflow.nodes[0]!["widgets_values_named"]; + workflow.nodes[0]!.widgets_values = { before: "first", loras: 2, after: "last" }; + const doc = mint(workflow, catalog); + expect(project(doc, catalog).nodes[0]!.widgets_values).toEqual(["first", 2, "A.safetensors", 1, true, "A.safetensors", 1, true, "last"]); + expect(project0310(doc, catalog).nodes[0]!.widgets_values).toEqual(["first", 2, "last"]); + doc.destroy(); + }); +});