Repository navigation
docs: ADR-040 — DynamicGroup row changes are whole-group replacement, not row operations #293
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
5 commits
Select commit
Hold shift + click to select a range
b172552
docs: ADR-040 — DynamicGroup row changes are whole-group replacement
christian-byrne 61f8ecb
docs: tighten DynamicGroup replacement guarantees
christian-byrne 91c2a3c
docs: align ADR-040 hidden-row verdict with the local-Add ruling
christian-byrne 7585049
docs: cite the package invariant registry in ADR-040
christian-byrne 07f9707
Merge remote-tracking branch 'origin/main' into pr293
christian-byrne File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
211 changes: 211 additions & 0 deletions
211
docs/decisions/ADR-040-dynamic-group-row-change-contract.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,211 @@ | ||
| # ADR-040: DynamicGroup row changes are whole-group replacement, not row operations | ||
|
|
||
| - **Status:** Accepted for V1. No structural row operation is added to this package. | ||
| - **Date:** 2026-10-23 | ||
| - **Decider:** in-app Agent program, `operator:delivery`, row `dgarch-2` | ||
| - **Depends on:** [ADR-039](ADR-039-hidden-dynamic-group-rows-are-retained-not-deleted.md) | ||
| (hidden rows are retained, not deleted). Retention keeps a shrink from claiming | ||
| a peer's hidden field registers and makes surplus losing writes non-destructive. | ||
| - **Constrains:** this package's op vocabulary; comfy-cli's `docs/op-vocabulary-v1.md` | ||
| batch-spec surface; cloud's `applyOpKinds` allowlist. | ||
|
|
||
| ## Context | ||
|
|
||
| A DynamicGroup's row count is one register and each row field is its own name-keyed | ||
| register, `<controller>.<index>.<field>`. | ||
| [#276](https://github.com/Comfy-Org/comfy-multi-player/pull/276) makes a count change a | ||
| projection change only: no reindexing, no link or promotion rewrite, hidden registers | ||
| retained. Its `docs/dynamic-groups.md` already asserts the conclusion this ADR ratifies — | ||
| "Agent row changes use whole-group replacement instead ... so this package needs no | ||
| structural operation" — but that sentence is an unreviewed assertion inside an unmerged | ||
| PR at the time this decision was opened, which is exactly the "a decision that | ||
| lives only in a doc is lost" case. #276 has since merged. | ||
|
|
||
| Two shapes were built against that gap, and the second was never chosen between: | ||
|
|
||
| - **Whole-group replacement**, [comfy-cli #1004](https://github.com/Comfy-Org/comfy-cli/pull/1004). | ||
| The producer sends the desired row list; the CLI expands it into existing `set_widget` | ||
| ops — the count, then every field of every written row. No new op kind, no schema | ||
| change, nothing for this package or the doc host to learn. | ||
| - **Row identity plus atomic row operations**, | ||
| [#281](https://github.com/Comfy-Org/comfy-multi-player/pull/281) (`properties.dynamicGroupRows`, | ||
| schema v6) and [#282](https://github.com/Comfy-Org/comfy-multi-player/pull/282) (five | ||
| operations, permanent row tombstones, schema v7). Both are complete, tested drafts. | ||
| Their author closed them on 2026-10-18, with | ||
| [cloud #13279](https://github.com/Comfy-Org/cloud/pull/13279), pending this ruling. | ||
|
|
||
| The question is not which is better engineering. #282 is strictly the stronger document | ||
| model. The question is whether any invariant this program holds *requires* it, because | ||
| adopting it costs two schema bumps, refusal and re-mint of every existing document, and | ||
| coordinated adoption across this package, the doc host, cloud, the CLI and the frontend — | ||
| against a production chain still pinned at doc host `0.3.10`, where Agent DynamicGroup | ||
| writes can still bind to the wrong position and #276 alone fixes that. | ||
|
|
||
| ## Decision | ||
|
|
||
| **Accept whole-group replacement as the V1 row-change contract. Add no structural row | ||
| operation.** #281, #282 and cloud #13279 stay closed. The producer owns row changes; this | ||
| package stays at `SCHEMA_VERSION` 5 and keeps its existing op vocabulary. | ||
|
|
||
| The contract, stated normatively so a later contributor cannot add a second row path by | ||
| accident: | ||
|
|
||
| 1. A row change is expressed as **the complete desired list of rows for one group on one | ||
| node**, expanded at the command site into the count register and every field register | ||
| of every written row. There is no row insert, delete, move or identity. | ||
| 2. **A row's identity is its index.** Nothing in the document carries a durable row | ||
| identity, and no reader may assume one. | ||
| 3. **Rows a link or a promotion binds to are not moved.** The producer refuses a | ||
| replacement that would require moving one, naming the disconnect or unpromote needed. | ||
| This is the only reason replacement is safe against topology: it never rewires, it | ||
| declines. | ||
| 4. **Row-field writes are order-independent of the count write.** Confirmed in source: | ||
| `dynamic-groups.ts` `isGroupField` admits any index below | ||
| `MAX_OVERFLOW_WIDGETS / total row fields across every group on the entry`, the shared | ||
| allocation bound, not the current count. A field write that arrives before the count | ||
| that reveals it is stored hidden and becomes visible when the count lands. KA-4 holds | ||
| for the emitted batch in any arrival order. | ||
|
|
||
| ### The five acceptance tests, each with a verdict | ||
|
|
||
| **Concurrent edits — two actors changing different rows.** Two replacements at equal | ||
| Lamport counters tie on the counter, so the actor comparison decides *every* contended | ||
| register the same way. When both producers write the same register set, one actor's | ||
| complete list survives intact and the other's is lost whole. With ADR-039 retaining the | ||
| loser's surplus hidden registers, the projection is exactly one of the two intended lists. | ||
|
|
||
| There is one bounded exception: a producer omits a linked or promoted row that it observed | ||
| as pinned, while another producer may write that row. The uncontended write can therefore | ||
| survive inside the other actor's winning list. That is not an arrival-order divergence; | ||
| it is the read-to-write topology race already accepted by condition 4. **Accepted with | ||
| that exception, rather than claimed as an unconditional group-level winner.** | ||
|
|
||
| The unclean case is a replacement racing a *scalar* `set_widget` on one row field, which | ||
| is what the frontend UI emits for a human edit. The two claim registers at different | ||
| granularity, so the scalar can win its one field while the replacement wins the rest, | ||
| leaving a row holding a new `lora_name` with a peer's `strength`. If the replacement also | ||
| changed what that index means, the peer's edit lands on a different LoRA. There is no | ||
| mitigation at the op layer without row identity; raising the producer's counter cannot | ||
| help, because a counter is not orderable against an op the producer has not seen. | ||
| **Accepted as a stated residual, not solved** — see Consequences. | ||
|
|
||
| **Idempotent retry.** Replay of the emitted ops is a true no-op by KA-4, byte-identical, | ||
| and #1004's tests replay every emitted batch to the same canonical workflow. Re-minting | ||
| the *spec* at an unchanged `base_version` is refused by #1004's claimed-register guard | ||
| rather than resolved by a coin flip, so the failure mode is fail-closed with an | ||
| instruction to re-read. **Accepted.** | ||
|
|
||
| **Stable identity.** There is none, and the contract says so rather than implying one. | ||
| The only identities external readers hold durably — a link's input slot and a promotion's | ||
| proxy — are protected by refusal (rule 3), not by rewriting. **Accepted as an explicit | ||
| non-property.** | ||
|
|
||
| **Hidden rows.** Governed by ADR-039: a shrink retains the vacated rows' registers. A | ||
| count-only regrow (remote, load, or undo/redo of a count-only transition) surfaces them | ||
| rather than template defaults; a human's explicit local Add creates a default-valued row | ||
| and announces those defaults. Replacement does not read hidden state and must not clear | ||
| it — clearing would claim registers the producer does not own and would destroy a peer's | ||
| concurrent edit at that index, which is the same objection ADR-039 raises against a delete | ||
| op. The consequence is real and new: before #1004 the Agent could not shrink a group, so | ||
| an Agent shrink followed by a count-only regrow, such as a remote count write or an undo | ||
| across the shrink, now surfaces the Agent's discarded rows. A follower must restore those | ||
| retained values rather than template defaults, and must not report hidden-row keys as | ||
| missing widgets. That is ADR-039's two | ||
| must-change frontend readers (`changed()` widening and `reportMissingWidgets()`); the | ||
| added-row announce stays. **Accepted, gated on those reader fixes, including idempotent | ||
| retry when a frame regrows a row and then fails to restore one of its retained fields.** | ||
|
|
||
| **Partial failure.** The doc host applies each op in its own transaction, so a batch is | ||
| one frame and one undo unit but is **not atomic in the document**. A rejection after the | ||
| count leaves a group whose written rows are new and whose unwritten rows show their | ||
| previous occupants — plausible-looking and wrong, with no rollback. The producer | ||
| validates on a copy first, so the only expected causes are a concurrent change or a | ||
| version mismatch. **Accepted as the single strongest argument for #282, and the named | ||
| revisit trigger below.** | ||
|
|
||
| ### The invariant that would force row operations, so the revisit is testable | ||
|
|
||
| Row-level operations become *required*, not merely better, if this product ever asserts: | ||
|
|
||
| > A per-field edit authored against a row must apply to that row, or not at all, even | ||
| > when a concurrent structural change has moved it. | ||
|
|
||
| Nothing in the KEEP-ALIVE section of this package's | ||
| [`docs/INVARIANTS.md`](../INVARIANTS.md#keep-alive), the in-app Agent program's | ||
| KEEP-ALIVE list, or any shipped product requirement asserts it today. Replacement cannot satisfy it — index-addressed | ||
| registers have no way to express it — so the day it is asserted, #281/#282 are reopened | ||
| rather than patched around. Writing it down is the point: it is the difference between a | ||
| bounded V1 and a permanent one. | ||
|
|
||
| ## Conditions on this acceptance | ||
|
|
||
| 1. **The "ops must replay in order" claim must be scoped to comfy-cli.** #1004 writes | ||
| "the emitted ops must replay in order (count first)" into | ||
| `docs/op-vocabulary-v1.md`, the frozen vocabulary this package pins. It is true of the | ||
| CLI's own local workflow model, which materializes rows from the count and answers | ||
| "widget not found" for a field above it (the mechanism in comfy-cli #1006), and it is | ||
| false of this package, by rule 4 above. Left as written, a second receiver implementing | ||
| the vocabulary literally would reject out-of-order arrival and diverge — a KA-4 | ||
| violation introduced by documentation. | ||
| 2. **#1004's same-batch claimed-register guard is an exception with a sunset.** It exists | ||
| only because every op in a CLI batch shares a stamp and the random `op_id` settles the | ||
| tie (comfy-cli #1006). comfy-cli #1007 fixes that generally. The guard is retired when | ||
| #1007 lands, or it is re-justified on its own merits. | ||
| 3. **The producer's row ceiling is not this package's.** #1004 bounds rows by | ||
| `port.options.max` falling back to a literal `20`; this package bounds counts by | ||
| `[group.min, MAX_OVERFLOW_WIDGETS / total row fields across the entry]` and deliberately | ||
| does not enforce the catalog `max` (the catalog controls layout, not prompt validity). | ||
| `ComfyUI_frontend` ADR-DYNAMIC-GROUP-0047 and #21788 have since settled ownership: | ||
| Core owns executability, producers such as comfy-cli author inside `min..max`, and | ||
| transports and followers preserve document counts inside their own resource bounds. | ||
| The remaining audit point is only whether the literal fallback `20` is the correct | ||
| producer behavior when the catalog omits `max`; it is not a shared-document ceiling. | ||
| 4. **The read-to-write link race is stated, not silently accepted.** A link added to a row | ||
| after the producer's read is not rechecked, so rule 3's refusal can be bypassed by | ||
| timing and that row rewritten under its link. This package cannot see it — links and | ||
| rows are unrelated registers here — so it belongs in the producer's user-visible | ||
| documentation, not only in a PR body. | ||
|
|
||
| ## Consequences | ||
|
|
||
| - No schema bump, no document re-mint, no new op kind, no doc-host change. The #276 | ||
| release chain — merge, publish, doc-host pin, Cloud CLI pin — is unblocked without | ||
| waiting on a row-identity model. | ||
| - Row changes are normally **lost-update at group granularity** against a concurrent peer | ||
| replacement. A producer that observed a row as linked or promoted can leave one of the | ||
| other actor's uncontended row writes inside the winning list. A concurrent scalar field | ||
| write can also produce a mixed row. These are accepted topology/positional-model | ||
| residuals and none is hidden. | ||
| - A row change is **not atomic in the document**. Partial application is observable. | ||
| - Whole-group replacement is a bounded instance of the in-app Agent program's FORECLOSE | ||
| entry 4 — it clobbers concurrent edits within its scope — but not of its other | ||
| properties: it emits explicit per-field semantic ops, so there is no ingress blowup and | ||
| op-log replay and observability are intact. Naming it is deliberate; the scope is one | ||
| group on one node, and it is the reason this is V1 and not the end state. | ||
| - It does **not** re-derive intent from end states. The desired row list is received | ||
| intent, minted where intent is known, which is why it is admissible at all. What it | ||
| loses is finer intent: "deleted row 1" and "rewrote rows 1..n" are indistinguishable to | ||
| a peer, which is precisely the information row operations would carry. | ||
|
|
||
| ## Revisit if | ||
|
|
||
| - A peer's delayed per-field edit landing on the wrong row is observed in production, or | ||
| the invariant quoted above is asserted as a product requirement. | ||
| - Partial application of a row batch is observed as a user-visible defect rather than a | ||
| theoretical one. | ||
| - Concurrent DynamicGroup editing becomes a supported multiplayer scenario rather than an | ||
| accepted race between one Agent turn and one human. | ||
|
|
||
| Any of these reopens #281/#282 and cloud #13279 as the V2, which is why they are closed | ||
| rather than deleted. | ||
|
|
||
| ## Glossary | ||
|
|
||
| - **DynamicGroup:** a repeating row of widgets on one node (a LoRA stack's `loras`), | ||
| whose row count is itself a widget. | ||
| - **LWW:** last-writer-wins ordering by the op's immutable stamp, `[counter, actor, op_id]`. | ||
| - **KA-4:** this package's invariant that the applier is deterministic and idempotent and | ||
| a duplicate `op_id` is a true no-op. | ||
| - **FORECLOSE 4:** the in-app Agent program's rule against full-document replace as the | ||
| mutation primitive. This package's register ends at FC-10 and has no equivalent id, so | ||
| the attribution is explicit rather than a dangling citation. | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.