Skip to content

feat: add atomic DynamicGroup row operations - #282

Closed
jaeone94 wants to merge 1 commit into
jaeone94/dynamic-group-row-identityfrom
jaeone94/atomic-dynamic-group-rows
Closed

jaeone94 wants to merge 1 commit into
jaeone94/dynamic-group-row-identityfrom
jaeone94/atomic-dynamic-group-rows

Conversation

@jaeone94

Copy link
Copy Markdown
Contributor

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

  • Authored by: interactive session
  • Verified: required repository gates passed: 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.
  • Deviations: live host sequence-CAS integration, CLI/FE producers, browser/Agent/MCP QA and realistic churn/performance validation are follow-ups. No consumer rollout or package release is included.

Reviewer context

  • Type: feature; provisional atomic row protocol and its topology projection.
  • Slots into: stacked on feat: prepare DynamicGroup row identity reader #281 — feat: prepare DynamicGroup row identity reader. Please review the operation shapes, delete-wins/anchor semantics, host admission boundary and schema-v7 adoption together.

Summary

  • Add five provisional operations: insert rows, set row fields, delete rows, connect and disconnect a row field. New row IDs derive from the creator's immutable operation ID and ordinal; inserted values are creator-supplied.
  • Keep per-field winning registers and permanent row tombstones. Pending edits/deletions can precede insertion; surviving rows retain identity across concurrent changes and encoded reconnect.
  • Derive dense widget names/counts, declared forms, named/ordered values, links, definition ports, exposures/proxies and positional host values. Cover one/two-level promotions, mixed sockets/widgets and proxy order differing from port order. Refuse unsafe positional row writes and unsupported self-described promoted-host structural edits.
  • Add readonly admission for current min/max, lifetimes, anchors, fields and source/host bindings. Callers must run it inside their existing sequence-CAS before persisting an operation; receiver replay does not recheck transient min/max.
  • Use schema v7 for private row registers/input markers and stable link destinations. Old layouts remain refused and re-minted from source. Compaction retains semantic row history while dropping old Yjs structs/ledger history. Literal prototype-looking field names survive dictionary entry encoding, and controller names use the existing widget-key escaping.
  • Apply small necessary connection integration fixes: a concrete input claim and Autogrow materialization are independent of complete-link ID ownership; grown-slot reranking only moves links owned by that destination; interior link identity uses canonical definition scope. Ordinary-node regressions reproduce without DynamicGroup and pass with the fixes.

The normative payload/layout description is schema Amendment A27. Existing unexpected-risk taxonomy for unrelated delete_node.removed_links aliases remains explicit; this draft does not claim to fix it or every possible workflow composition.

Verification

  • npm run build
  • npm run typecheck
  • npm run lint
  • npm run check:purity
  • npm run check:imports
  • npm run check:pins (offline citation/registry verification)
  • npm run check:profile-claims
  • npm run check:coderabbit
  • npm run verify:corpus (retained producer expectations, no regeneration)
  • npm run check:stateless
  • npm test -- --maxWorkers=1
  • npm run test:exhaustive -- --maxWorkers=1

The 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

  • Review the draft contract before enabling producers or releasing the package.
  • Wire host admission and compatible CLI/FE readers/producers in dependent PRs; validate stale retries and sequence-CAS conflicts end to end.
  • Run real browser/Agent/MCP workflows with insert/remove, nested promotions, reconnect and execution.
  • Validate retained semantic tombstones, realistic churn and deep/shared graph costs before rollout.
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.

Source / probe Temporary change Actual failure
src/types.ts:26 — wire-key export const DYNAMIC_GROUP_STATE_KEY = "__dynamic_group_state_mutant"; FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > spells the private row wire keys in the encoded snapshot and recovers them by their published names
AssertionError: __dynamic_group_state: expected false to be true // Object.is equality
src/dynamic-row-ops.ts:89 — creator-stamp const key: StampKey = [op.base_version, op.actor, op.op_id]; FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > takes the row-field winner from the creator stamp rather than the transport envelope
AssertionError: expected { before: 'head', loras: 3, …(16) } to match object { 'loras.2.strength': 0.9 }
src/dynamic-row-ops.ts:102 — field-lww if (false && prior && compareStampKeys(key, prior) <= 0) return false; FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > merges independent fields and resolves the overlapping field by LWW
AssertionError: expected { before: 'head', loras: 3, …(16) } to match object { …(3) }
src/dynamic-row-state.ts:169 — row-delete live.push(id); FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > deletes a middle row while preserving surviving values and siblings
AssertionError: expected { dynamicGroupRows: { …(2) } } to deeply equal { dynamicGroupRows: { …(2) } }
src/dynamic-row-state.ts:146 — anchor-cycle // mutant: skip anchor validation FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > refuses encoded anchor cycles even when they have no reachable root
AssertionError: expected [Function] to throw an error
src/dynamic-row-ops.ts:108 — full-field-preflight `if (false && (Object.keys(values).some((field) => !group.fields.includes(field))
src/project.ts:268 — ordered-sidecar // mutant: do not update the ordered sidecar FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > keeps the declared widget form and ordered sidecar aligned across middle-row deletion
AssertionError: expected [ { name: 'before', …(3) }, …(17) ] to deeply equal ArrayContaining{…}
src/compact.ts:90 — row-checkpoint if (false && rowTopologySnapshot(doc) !== null) { FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > carries row anchors and tombstones through compaction and encoded reconnect
AssertionError: expected { dynamicGroupRows: { …(2) } } to match object { dynamicGroupRows: { …(1) } }
src/applier.ts:3759 — row-restore if (state.destination.kind === "dynamic_group") return false; FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > restores a row connection after its source is removed and re-added, in both causal orders
AssertionError: expected [ Array(2) ] to deep equally contain [ 31, 103, +0, 1, 3, 'FLOAT' ]
src/applier.ts:651 — retained-disconnect // mutant: keep absent-source descriptors FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > retires a pending row connection when its source is absent during disconnect
AssertionError: expected true to be false // Object.is equality
src/applier.ts:3006 — joint-link-register if (!claimLinkIdentity(doc, op)) return false;; const identityWon = true; FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > lets a higher complete-link identity retire an input claim that already lost its ID
AssertionError: expected [ Array(4) ] to deeply equal [ Array(3) ]
src/applier.ts:622 — structural-host-shape // mutant: omit host-shape preflight FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > refuses unsupported self-described promoted-host layouts before structural writes
AssertionError: expected { code: undefined, …(5) } to deeply equal { code: 'malformed_op', …(5) }
src/applier.ts:2248 — numeric-row-address if (false && index >= boundary) throw new OpRejectedError("malformed_op", "row-controlled inputs require a row-ID connection address"); FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > refuses a numeric address that can move with row deletion but retains the fixed socket prefix
AssertionError: expected { code: undefined, …(5) } to deeply equal { code: 'malformed_op', …(5) }
src/applier.ts:804 — max-admission if (false && count > max) throw new OpRejectedError("malformed_op", "DynamicGroup: insertion exceeds max rows"); FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > checks current min/max during admission without changing the document
AssertionError: expected [Function] to throw an error
src/applier.ts:808 — min-admission if (false && count < min) throw new OpRejectedError("malformed_op", "DynamicGroup: deletion falls below min rows"); FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > checks current min/max during admission without changing the document
AssertionError: expected [Function] to throw an error
src/doc.ts:819 — slot-forgery if (false && Object.hasOwn(slot, DYNAMIC_GROUP_SLOT_KEY)) throw new TypeError(${what}: reserved DynamicGroup slot marker); FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > rejects producer-forged private row storage and slot markers
AssertionError: expected [Function] to throw an error
src/read.ts:387 — derived-read // mutant: leave baseline widget values in the snapshot FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > deletes a middle row while preserving surviving values and siblings
AssertionError: 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 order FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > resolves promoted values by proxy order when it differs from input-port order
AssertionError: expected { id: 9, …(5) } to match object { widgets_values: [ 0.9, 0.4 ], …(1) }
src/applier.ts:2980 — autogrow-link-gate if (!claimLinkIdentity(doc, op)) return "lww-dropped";; if (!src) return "no-op";; return growInputSlot(doc, dst, op, count, catalog); FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > materializes a losing Autogrow request without moving the winning row=false link
AssertionError: expected [ { name: 'value', …(2) }, …(1) ] to deeply equal [ { name: 'value', …(2) }, …(2) ]
src/applier.ts:3355 — grow-rank-owner if (Array.isArray(link)) { FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > materializes a losing Autogrow request without moving the winning row=false link
AssertionError: expected [ Array(4) ] to deep equally contain [ 31, 103, +0, 1, 3, 'FLOAT' ]
src/dynamic-row-state.ts:219 — escaped-controller result.set(name, ids.length); FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > uses the existing widget-key escaping for reserved-looking controller names
TypeError: dynamicGroupRows.widget-occurrence:loras: row IDs must match the stored row count
src/applier.ts:3109 — interior-id-owner const targetKey = JSON.stringify(["link", ...(scope && op.path ? [op.path.map(String)] : []), normalizedId]); FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > owns interior link identity by canonical definition rather than its instance-route spelling
AssertionError: expected [ …(2) ] to deeply equal ArrayContaining{…}
src/dynamic-row-ops.ts:33 — creator-stamp-required // mutant: allow omitted creator stamp FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > refuses malformed row payloads before writes: dynamic_group_set_row
AssertionError: expected { code: undefined, …(5) } to deeply equal { code: 'malformed_op', …(5) }
src/applier.ts:3771 — target-lifetime if (destination.kind !== "dynamic_group") return false; FAIL test/atomic-dynamic-group-rows.test.ts > atomic DynamicGroup row operations > does not restore an old row link into an activated new target lifetime
AssertionError: expected true to be false // Object.is equality

@coderabbitai

coderabbitai Bot commented Oct 11, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

@github-actions github-actions Bot added the risk:R3 PR risk grade (advisory shadow check; grader-owned) label Oct 11, 2026
@jaeone94

jaeone94 commented Oct 13, 2026 •

Copy link
Copy Markdown
Contributor Author

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.

@jaeone94

Copy link
Copy Markdown
Contributor Author

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.

@jaeone94 jaeone94 closed this Oct 18, 2026
christian-byrne added a commit that referenced this pull request Oct 27, 2026
… 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:R3 PR risk grade (advisory shadow check; grader-owned)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant