Repository navigation
Conversation
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: true
Comment |
|
On hold (2026-10-13), pending review. Edited 2026-10-14: first posted as "Deferred". I've proposed that Agent row changes use whole-group replacement expanded by the CLI into existing ops (comfy-cli #1004). If that is agreed, this row-level protocol is not a first-release prerequisite, and it stays a draft for a possible later fine-grained merge model. The proposal has not been agreed yet; see the architecture review. |
|
Closing along with #281. Whole-group replacement (comfy-cli #1004) uses the existing ops, so atomic row operations aren't needed in the shared document. |
… not row operations (#293) * docs: ADR-040 — DynamicGroup row changes are whole-group replacement Ratifies the contract #276's docs already assert but nothing decides: a DynamicGroup row change is the complete desired row list, expanded at the command site into the existing count and row-field set_widget ops. No structural row operation, no schema bump; #281/#282 and cloud #13279 stay closed as the named V2. Records the four acceptance verdicts, the two residuals that are accepted rather than solved (lost update at group granularity, non-atomic application), and the one invariant that would force row operations, so the revisit is testable rather than a matter of taste. * docs: tighten DynamicGroup replacement guarantees * docs: align ADR-040 hidden-row verdict with the local-Add ruling * docs: cite the package invariant registry in ADR-040
ELI5
A row keeps its identity when another row is inserted or removed, so a delayed edit cannot change whichever row moved into the old position. This adds the shared operations needed to create, edit, remove and connect rows, including existing promoted widgets.
Motivation
#281 — feat: prepare DynamicGroup row identity reader preserves row identities but leaves structural editing for the next contract. Agents need an atomic row operation rather than separate count and numbered-field writes, because those writes can arrive in different orders. This draft supplies that package contract before CLI, frontend and document-host adoption.
Provenance
npm ci, build, typecheck, lint, purity/imports/pins/profile-claims/CodeRabbit configuration/corpus/stateless. Full unit suite: 1,904 passed, 2 other-tier skips. Exhaustive tier: 2 passed, 2 representative-tier skips, covering 50,176 pair executions and 1,696 seeded streams. After a default-equivalent/type-only test-helper cleanup, typecheck/lint and all 49 row tests passed again. 24 selected revert probes produced named failures; source hunks were restored. A real v6 reader from the parent refused the v7 encoded snapshot without changing its bytes.Reviewer context
Summary
The normative payload/layout description is schema Amendment A27. Existing unexpected-risk taxonomy for unrelated
delete_node.removed_linksaliases remains explicit; this draft does not claim to fix it or every possible workflow composition.Verification
npm run buildnpm run typechecknpm run lintnpm run check:puritynpm run check:importsnpm run check:pins(offline citation/registry verification)npm run check:profile-claimsnpm run check:coderabbitnpm run verify:corpus(retained producer expectations, no regeneration)npm run check:statelessnpm test -- --maxWorkers=1npm run test:exhaustive -- --maxWorkers=1The normal permutation tier evaluates 196 kind pairs × 8 states × 2 arrival orders × 2 batch modes = 6,272 executions, plus 128 sampled streams. The dedicated tier adds 2 actor pairs × 4 stamp pairs: 50,176 executions, plus 1,696 sampled streams. This is bounded/sampled coverage, not a proof over arbitrary graphs.
Invariants
KA-1/KA-2/KA-4/KA-5/KA-10: semantic operations, creator-owned identities/stamps, stable addressing, exact retry bytes and common-bootstrap replay. KA-3/KA-13 and FC-3/FC-4/FC-5: one portable implementation, caller-owned state and no document replacement as a mutation primitive. KA-11/KA-12 and FC-2/FC-7/FC-8/FC-10: schema refusal, catalog-dependent membership, no transport-only ordering or replay-time defaults. A27's package-local vocabulary/catalog dependency is recorded as PROPOSED, awaiting maintainer/consumer sign-off, in
docs/decisions/EXCEPTIONS.md.Test plan
24 targeted revert probes: source hunks and actual failing checks
Each hunk was confirmed in the local diff, tested alone, and restored. These are selected behavioral probes, not a Stryker score. Every run exited 1 with a named assertion failure; final normal tests passed. The target-lifetime probe first survived projection-only assertions: the final test checks the raw live-link map as well, so a hidden stale tuple is detected.
src/types.ts:26— wire-keyexport const DYNAMIC_GROUP_STATE_KEY = "__dynamic_group_state_mutant";AssertionError: __dynamic_group_state: expected false to be true // Object.is equality
src/dynamic-row-ops.ts:89— creator-stampconst key: StampKey = [op.base_version, op.actor, op.op_id];AssertionError: expected { before: 'head', loras: 3, …(16) } to match object { 'loras.2.strength': 0.9 }
src/dynamic-row-ops.ts:102— field-lwwif (false && prior && compareStampKeys(key, prior) <= 0) return false;AssertionError: expected { before: 'head', loras: 3, …(16) } to match object { …(3) }
src/dynamic-row-state.ts:169— row-deletelive.push(id);AssertionError: expected { dynamicGroupRows: { …(2) } } to deeply equal { dynamicGroupRows: { …(2) } }
src/dynamic-row-state.ts:146— anchor-cycle// mutant: skip anchor validationAssertionError: expected [Function] to throw an error
src/dynamic-row-ops.ts:108— full-field-preflightsrc/project.ts:268— ordered-sidecar// mutant: do not update the ordered sidecarAssertionError: expected [ { name: 'before', …(3) }, …(17) ] to deeply equal ArrayContaining{…}
src/compact.ts:90— row-checkpointif (false && rowTopologySnapshot(doc) !== null) {AssertionError: expected { dynamicGroupRows: { …(2) } } to match object { dynamicGroupRows: { …(1) } }
src/applier.ts:3759— row-restoreif (state.destination.kind === "dynamic_group") return false;AssertionError: expected [ Array(2) ] to deep equally contain [ 31, 103, +0, 1, 3, 'FLOAT' ]
src/applier.ts:651— retained-disconnect// mutant: keep absent-source descriptorsAssertionError: expected true to be false // Object.is equality
src/applier.ts:3006— joint-link-registerif (!claimLinkIdentity(doc, op)) return false;; const identityWon = true;AssertionError: expected [ Array(4) ] to deeply equal [ Array(3) ]
src/applier.ts:622— structural-host-shape// mutant: omit host-shape preflightAssertionError: expected { code: undefined, …(5) } to deeply equal { code: 'malformed_op', …(5) }
src/applier.ts:2248— numeric-row-addressif (false && index >= boundary) throw new OpRejectedError("malformed_op", "row-controlled inputs require a row-ID connection address");AssertionError: expected { code: undefined, …(5) } to deeply equal { code: 'malformed_op', …(5) }
src/applier.ts:804— max-admissionif (false && count > max) throw new OpRejectedError("malformed_op", "DynamicGroup: insertion exceeds max rows");AssertionError: expected [Function] to throw an error
src/applier.ts:808— min-admissionif (false && count < min) throw new OpRejectedError("malformed_op", "DynamicGroup: deletion falls below min rows");AssertionError: expected [Function] to throw an error
src/doc.ts:819— slot-forgeryif (false && Object.hasOwn(slot, DYNAMIC_GROUP_SLOT_KEY)) throw new TypeError(${what}: reserved DynamicGroup slot marker);AssertionError: expected [Function] to throw an error
src/read.ts:387— derived-read// mutant: leave baseline widget values in the snapshotAssertionError: expected { before: 'head', loras: 3, …(7) } to match object { loras: 2, …(2) }
src/dynamic-row-topology.ts:435— proxy-order// mutant: fall back to port orderAssertionError: expected { id: 9, …(5) } to match object { widgets_values: [ 0.9, 0.4 ], …(1) }
src/applier.ts:2980— autogrow-link-gateif (!claimLinkIdentity(doc, op)) return "lww-dropped";; if (!src) return "no-op";; return growInputSlot(doc, dst, op, count, catalog);AssertionError: expected [ { name: 'value', …(2) }, …(1) ] to deeply equal [ { name: 'value', …(2) }, …(2) ]
src/applier.ts:3355— grow-rank-ownerif (Array.isArray(link)) {AssertionError: expected [ Array(4) ] to deep equally contain [ 31, 103, +0, 1, 3, 'FLOAT' ]
src/dynamic-row-state.ts:219— escaped-controllerresult.set(name, ids.length);TypeError: dynamicGroupRows.widget-occurrence:loras: row IDs must match the stored row count
src/applier.ts:3109— interior-id-ownerconst targetKey = JSON.stringify(["link", ...(scope && op.path ? [op.path.map(String)] : []), normalizedId]);AssertionError: expected [ …(2) ] to deeply equal ArrayContaining{…}
src/dynamic-row-ops.ts:33— creator-stamp-required// mutant: allow omitted creator stampAssertionError: expected { code: undefined, …(5) } to deeply equal { code: 'malformed_op', …(5) }
src/applier.ts:3771— target-lifetimeif (destination.kind !== "dynamic_group") return false;AssertionError: expected true to be false // Object.is equality