diff --git a/docs/INVARIANTS.md b/docs/INVARIANTS.md index 52c0092..8c7fbac 100644 --- a/docs/INVARIANTS.md +++ b/docs/INVARIANTS.md @@ -126,8 +126,22 @@ 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. 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) 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. **Enforced by:** `test/roundtrip.test.ts`, `test/catalog-sha-binding-integration.test.ts`, `test/node-local-widget-form.test.ts` (A24's catalog-free object path, and that an undeclared node still takes the catalogued one), `test/node-local-order-overlay.test.ts` (A25's pinned dynamic overlay), [`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 506b6c3..948cb67 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; amended 2026-10-20 by schema A25) | 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. 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. **A25's only composition is for ARRAY forms:** `order` is the realized producer order, any pinned dynamic-combo option child is legal independent of selection, and a winning selector replaces only catalog-owned dynamic children in that same stored order; OBJECT/custom-serializer forms remain closed. `SCHEMA_VERSION` stays 5 because `test/node-local-order-overlay.test.ts` proves the real published 0.3.10 reader projects every state the new writer persists identically. **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/dynamic-combos.ts` `widgetOrderForProducerOrder`; `src/doc.ts` `widgetStorageFor`/`widgetStorageOf`/`storeWidgetValues`; `src/project.ts` `projectWidgets`; `src/applier.ts` `validateWidgetName`/`writeWidgetValue`/`rejectIfOpaqueWidgets`/`hostWriteStorage`/`createAddedNode`/`rejectUnprojectableWidgets`; `src/read.ts`; `fixtures/golden-vectors/wire-layout.json`; `fixtures/golden-vectors/node-local-order-overlay.json`; `test/node-local-widget-form.test.ts`; `test/node-local-order-overlay.test.ts`; schema Amendments A24/A25 | 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 | A26 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/A26 | 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 new file mode 100644 index 0000000..f7607a9 --- /dev/null +++ b/docs/dynamic-groups.md @@ -0,0 +1,55 @@ +# 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. 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. + +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). + +## 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 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 + +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. | + +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). + +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/multiplayer-schema.md b/docs/multiplayer-schema.md index 3793420..70af540 100644 --- a/docs/multiplayer-schema.md +++ b/docs/multiplayer-schema.md @@ -2390,7 +2390,11 @@ A node carrying the field is **self-described**, and for it: or occurrence `order` does not list is `unknown_widget`, exactly as a missing `widget_order` entry would be. Amendment A25 narrows that closed-list statement for ARRAY forms only: a pinned dynamic-combo option child is also - legal and a winning selector persists the recomputed realized order; + legal and a winning selector persists the recomputed realized order. + Amendment A26 uses supplied `dynamic_groups` metadata only for count + validation: it 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 declared widget taking its live value and every other key its verbatim @@ -2591,3 +2595,9 @@ persists, so KA-11 does not require a layout bump or migration. - Reverting the array-form catalog overlay in `validateWidgetName` makes the named child-first vector fail `unknown_widget`; reverting selector-order refresh makes the selector-first vector project the stale option-A layout. + +## Amendment A26 — 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; 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 validation applies 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/docs/upstream-pins.json b/docs/upstream-pins.json index 477a64f..9a5af6e 100644 --- a/docs/upstream-pins.json +++ b/docs/upstream-pins.json @@ -186,6 +186,42 @@ }, "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." + }, + "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 9629412..bd007dd 100644 --- a/src/applier.ts +++ b/src/applier.ts @@ -155,6 +155,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, @@ -1146,7 +1147,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)}`); } @@ -1307,7 +1309,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, @@ -1490,7 +1492,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)"}`, @@ -1647,6 +1649,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; @@ -1966,6 +1970,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, occurrence, op.value); writeWidgetValue(target, catalog, op.widget, occurrence, op.value); updateOrderedWidgetValue(target, op.widget, occurrence, op.value); updateNamedWidgetValue(target, catalog, op.widget, occurrence, op.value); @@ -2020,6 +2025,18 @@ function validateWidgetOp(op: SetWidgetOp) { return { interior, promoted }; } +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, occurrence)) !== 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 @@ -2071,6 +2088,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, 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); @@ -2110,6 +2128,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, 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. writeWidgetValue(node, catalog, op.widget, occurrence, op.value); diff --git a/src/dynamic-combos.ts b/src/dynamic-combos.ts index fb8dd9b..c39698f 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 @@ -19,11 +19,12 @@ * 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 { assertDynamicGroupCatalog, fieldGroupOf, groupCountRefusal, groupLayout, groupOf, isDynamicGroupField } from "./dynamic-groups.js"; import type { DynamicComboEntry, WidgetCatalogEntry } from "./types.js"; import { widgetOccurrenceAt, widgetStorageKey } from "./widget-identity.js"; @@ -34,9 +35,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). */ @@ -76,16 +77,38 @@ 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); 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); + }; + // 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) { - order.push(name); - if (depth > 32 || !Object.hasOwn(combos, name)) continue; + 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)); + appendRows(name, 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); @@ -97,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)), 0); + walk(producerOrder.filter((name) => !owned.has(name) + && (!isDynamicGroupField(entry, name) || declaredGroups.has(fieldGroupOf(entry, name)!))), 0); return { order, defaults }; } @@ -105,20 +129,26 @@ 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; + 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; + 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)), ); } @@ -145,11 +175,14 @@ export function widgetOrderForProducerOrder( ): 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, (name, _index, occurrence) => widgets?.get(widgetStorageKey(name, occurrence)), producerOrder, + declaredGroups, ).order; } diff --git a/src/dynamic-groups.ts b/src/dynamic-groups.ts new file mode 100644 index 0000000..aae8d99 --- /dev/null +++ b/src/dynamic-groups.ts @@ -0,0 +1,137 @@ +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; +} + +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(entry) + && fields.includes(suffix.slice(dot + 1)); +} + +/** 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 { + 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 { + return fieldGroupOf(entry, name) !== undefined; +} + +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(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 + || 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; +} + +/** 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(entry, 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 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) + || 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`); + } + } + 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`); + } + 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`); + assertSingleSelection(entry, name, baseOrder, optionOrders); + } +} + +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(entry!)) { + return `${name}: expected an integer row count from the group minimum to 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/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/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 d395c40..df0c20e 100644 --- a/src/types.ts +++ b/src/types.ts @@ -651,6 +651,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/src/widget-form.ts b/src/widget-form.ts index 4fc75d6..e101da0 100644 --- a/src/widget-form.ts +++ b/src/widget-form.ts @@ -62,8 +62,9 @@ * needs no catalog. Amendment A25 lets an ARRAY form additionally compose * with catalog-owned dynamic-combo children; that overlay uses only the * pinned catalog and persists the resulting realized order back into this - * same form. An undeclared node is unaffected — same catalog, same - * rejections. + * same form. Amendment A26 still uses supplied DynamicGroup metadata to + * validate count writes without replacing that mapping. An undeclared node is + * unaffected — same catalog, same rejections. */ import type * as Y from "yjs"; diff --git a/test/dynamic-group.test.ts b/test/dynamic-group.test.ts new file mode 100644 index 0000000..704f38f --- /dev/null +++ b/test/dynamic-group.test.ts @@ -0,0 +1,590 @@ +import { readFileSync } from "node:fs"; +import * as Y from "yjs"; +import { describe, expect, it } from "vitest"; +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"; + +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 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 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"], +} satisfies TopLevelSetWidgetOp); + +describe("DynamicGroup catalog layout", () => { + it("accepts a controller offered by several options of one selector", () => { + const entry: WidgetCatalogEntry = { + ...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); + workflow.nodes[0]!.widgets_values = { before: "first", mode: "on", loras: 0, after: "last" }; + const doc = mint(workflow, selectedCatalog); + + 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", () => { + 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], + ["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"] } } }], + ["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 } } }, + }], + ["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 } } }], + ] 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"]); + 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)); + }); + + 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("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; + 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; + 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.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: [], + 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(); + }); +}); + +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(); + }); +}); 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" +} 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": [] + } + } +}