Skip to content

docs: ADR CRDT-RECONCILE-0035, local-only state survives authoritative reconcile - #18106

Merged
christian-byrne merged 23 commits into
mainfrom
claude/adr-crdt-rejected-ops-reconcile
Oct 9, 2026
Merged

christian-byrne merged 23 commits into
mainfrom
claude/adr-crdt-rejected-ops-reconcile

Conversation

@claude

@claude claude Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Requested by Christian Byrne · Slack thread

Before: The ADR described a per-lineage pending-op ledger, protected-state predicates consulted by a rebind reconcile, a bounded unresolved outcome, and a ledger-aware sweep, all written against the store-first apply path. #18700 replaced that path with the graph-API apply and deleted the reconcile layer, so the mechanism text no longer described any code.

After: The ADR keeps its four durable requirements as the regression contract for the apply path and describes how main meets them now: merge mode applies only the frame's change delta and never sweeps, replace runs only after doc_reset, rejections revert from the document with a throttled toast (a refused field write resyncs the whole node), own-actor echoes are dropped on entry, and widget writes are held while in flight. It states plainly which requirements hold only partially (a refused field write rewinding sibling fields, a refused widget write on a positional-array node resyncing every widget, widget hold lifting on any settlement) or not at all (no visible outcome for unacknowledged, unconfirmed or undeliverable edits; late rejections swallowed; collisions unreported), names the doc_reset replace as the one exception to requirement 1 (the accepted loss is an edit made after the draft was posted and before the new lineage's first frame), and lists the gaps as follow-ups, deferring panel-lifetime retention to CRDT-REPLAY-0039. A short "Superseded design" section maps older review threads onto the new structure.

Cross-references point at the rewritten CRDT-FOLLOWER-0025 and CRDT-REPLAY-0039 (already on main); this PR adds the index row for the ADR. Docs only.

Generated with Claude Code
https://claude.ai/code/session_01NQVcfKhCKjLstqo3mJS7fc


Generated by Claude Code

@coderabbitai

coderabbitai Bot commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration
  • Configuration used: Repository: Comfy-Org/ComfyUI_frontend/.coderabbit.yaml
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: d5d3e541-f9b8-403e-8dbd-a6d768f9fe00

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
  • 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 commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

🧩 Custom Nodes Ecosystem Matrix: 🟡 Withheld — could not measure

Executes the frontend JS of every registry pack that ships any, against this change, in both renderers. The eight ecosystem-matrix shard checks are a harness self-test; the pack verdict is matrix-verdict.

This candidate changes nothing the matrix measures, so every expensive stage was skipped.

Reproduce locally
# build one shard's fixture, then run it
python3 scripts/registry-census/build_matrix.py --shard 1/4
MATRIX_RENDERER=vue MATRIX_VUE=1 \
  npx vitest run --config vitest.matrix.config.mts

Full docs: scripts/registry-census/README.md

🌾 Fallow: ✅ Passed

Fallow audits the diff for duplication, complexity and dead code. It gates on new findings only, so when the audit completes, a red is something this PR introduced or moved — never inherited backlog. A red can also mean the audit itself did not finish; the details below say which happened.

No new findings in the changed files.

Reproduce locally
# the base the gate compared against
npx fallow audit --root . --quiet --format json \
  --changed-since 85a816b0937cca7fe432894676d3f3b27d30c740

Full docs: ADR-DEVEX-LINT-0015

@github-actions github-actions Bot added the risk:high PR risk grade (advisory shadow check; grader-owned) label Sep 19, 2026
@claude
claude Bot force-pushed the claude/adr-crdt-rejected-ops-reconcile branch from 65409c5 to 1251a3a Compare September 19, 2026 18:33
@claude
claude Bot requested a review from christian-byrne September 20, 2026 10:58
@christian-byrne
christian-byrne marked this pull request as ready for review September 20, 2026 11:09
@christian-byrne
christian-byrne requested a review from a team September 20, 2026 11:09
@github-actions github-actions Bot added risk:medium PR risk grade (advisory shadow check; grader-owned) and removed risk:high PR risk grade (advisory shadow check; grader-owned) labels Sep 20, 2026
DrJKL
DrJKL previously requested changes Sep 20, 2026

@DrJKL DrJKL left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: changes requested

Pre-merge blocker:

  • The proposed ledger lifetime ends on follower teardown even though ordinary panel unmount is not a document-lineage break. That loses unresolved delete intent and allows the next same-workflow catch-up to restore a node the user deleted.

I also found three material architecture/documentation issues in inline comments: the ADR makes current reconcile compensators durable without a deletion boundary for the semantic-apply direction in FE-2504, its define_subgraph chain starts with a closed-unmerged prerequisite, and its file/test-level rollout plan is already going stale.

Coverage

Standard-depth review at ddc65cfd054e9538bb6168fa41c4dcd2c728026a. I ran separate correctness, maintainability, and documentation lanes. The documentation lane loaded the technical-writing and simplifying-technical-documents lenses. I read both changed files in full and traced the consequential claims through the current follower, sender, pending ledger, graph mutation, materializer, panel lifecycle, layout-operation path, and cited ADRs. I also checked the relevant PR statuses through REST and read FE-2504 as a proposed High-priority Backlog direction, not an accepted contract.

Checks passed: pnpm adr:check, changed-file oxfmt --check, and git diff --check. Current CI reports ADR links, lint/format, and Fallow green. I did not run runtime tests because this is a docs-only diff and the disputed pending tracker behavior exists only on open PR #16309; the blocker follows from the proposed lifetime plus the current mount/teardown ownership.

The head matches the supplied snapshot. The effective merge base remains 81fc7223160b931e8020f66d415bf2edea6a4a54; fetched origin/main is now three commits ahead at 3a851363c48b233b3b576131dff6e1e92b0e1573, so I reviewed the exact merge-base diff rather than treating the local base tip as the PR diff.

`retarget(null)` settles the in-flight batch, so on a tab switch the ledger
is empty at the first frame after the return and (b) would have nothing to
consult. The tracker instead resets only on a lineage break (`doc_reset`,
`follower_replaced`, a bind to a different workflow) and on follower

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P1] This teardown rule breaks the lifetime stated just above. The tracker is owned by useAgentCrdtFollower inside AgentPanelRoot, and ordinary panel/mode changes unmount that component and dispose the sender, projection, and bridge. That is not a lineage break. After remount on the same workflow, a pending delete has no ledger entry to suppress the authoritative upsert, so catch-up can silently restore the node the user deleted. Lineage-aware removeMissing only protects absent local additions; it does not preserve pending deletion intent. Please move pending intent to workflow/document ownership, clear it only on a real lineage break or document destruction, and add panel close/reopen as an acceptance case.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed against current main: useAgentCrdtFollower builds the tracker's seam inside AgentPanelRoot's own effect scope, so an ordinary panel close/mode change tears it down, and lineage-aware removeMissing alone doesn't cover a pending delete. Reworked the lifetime rule in section (a): the ledger is now owned per bound workflow/document (created on first bind, cleared only on a real lineage break), with a panel close/reopen acceptance case added. The first tracker PR (stacked on #16309) still ships the follower-scoped ledger and only closes the tab-deactivation gap; hoisting ownership to workflow/document scope is the next PR in the stack (PR A1 in Sequencing), and the guarantee doesn't fully hold until that lands.


Generated by Claude Code

the delete reverts and the toast fires. The divergence is surfaced, not
silent.

### (b) `removeMissing` and the orphan sweep are ledger-aware and lineage-aware

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Please separate the durable user guarantee from this temporary reconciliation mechanism. FE-2504 is a live High-priority Backlog proposal, not an accepted contract, but it identifies store-first projection as the root cause and proposes semantic LGraph/LGraphNode apply with call-carried provenance, followed by deletion of removeMissing, reconcileNode, reconcileNextFrame, and the materializer repair pass. As written, this ADR makes ledger-aware versions of those compensators the design of record with no migration/deletion boundary. Keep the requirements that unresolved human intent is not silently discarded and collisions are reported, but mark sections (b)/(c) as interim if semantic apply is adopted and name which added state and branches must then be deleted. This does not require implementing FE-2504 here.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a "Durable guarantee vs. interim mechanism" section between (a) and (b): the no-silent-discard and collision-reported-with-document-wins guarantees are called out as durable, while (b)/(c)'s ledger-aware removeMissing/orphan sweep and the reconcile echo check are marked interim, with an explicit list of what gets deleted if the semantic-apply direction is adopted (removeMissing's awareness, reconcileNode, reconcileNextFrame, the materializer repair pass, and the gating ledger checks) versus what survives (the ledger's intent record and rejection reporting). I deliberately didn't cite the ticket ID since this repo is public; I referred to the direction only as "the proposed semantic-apply direction (store-first projection replaced by semantic LGraph/LGraphNode apply with call-carried provenance)".


Generated by Claude Code

the bound document lacks, the layout mint port emits `define_subgraph` for
that definition (nested definitions first) ahead of the host's `add_node`, in
mint order, so the applier registers the type before the node that uses it.
The op itself is #17454's. Preconditions, in order: the workspace move

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] This prerequisite chain is no longer actionable. REST shows #16644 closed unmerged on 2026-09-17, current main still consumes npm @comfyorg/comfy-multi-player@0.2.1, and #17454 remains a draft based on #16644's abandoned head branch. Please replace #16644 with the live successor package-integration path, or state that #17454 must be restacked/replaced and PR C is blocked pending a new plan.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified via the GitHub API: #16644 is closed unmerged (2026-09-17), main's package.json/pnpm-lock still resolve @comfyorg/comfy-multi-player@0.2.1 from npm, and #17454 is still a draft based on #16644's now-abandoned branch head. Rewrote the (d) prerequisite chain in the ADR to state PR C is blocked pending a new package-integration plan (not just review of the existing chain), that #17454 must be restacked onto main or replaced once that plan exists, and that #17458 is blocked on it in turn. No successor package-integration PR is currently open, so none is named.


Generated by Claude Code

first nodes mint into the previous document. Entry condition is a red test
in `layoutMintPort.test.ts`; two prior code walks disagree on whether the
window is reachable, so A0 is dropped if that test cannot be made red.
- **PR A**, after #18071 and #16309 (rebased, restacked on #16302): the (a)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] This section mixes the architecture decision with volatile stack coordination: exact files, test names, fixture wiring, assertion flips, and a list of open PRs editing the same block. It is already stale: #18081 has merged and #16644 closed unmerged. Please keep only dependency order and behavior-level acceptance criteria in the ADR, and move the file/test/assertion-level rollout checklist to the tracking issue or active PR stack where it can change without making the architecture record inaccurate.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Trimmed the Sequencing section to dependency order and behavior-level acceptance criteria only; the file/test-name/fixture-level checklist is out. Also fixed the stale statements you flagged (#18081 merged, #16644 closed unmerged) and split PR A into PR A / PR A1 to reflect the ledger-ownership hoist called out in the first thread.


Generated by Claude Code

…rim rollout detail

Address review feedback on PR #18106: own the pending-op ledger per
bound workflow/document instead of per follower mount so it survives
panel close/reopen, not just tab deactivation; separate the durable
no-silent-discard/collision-reported guarantee from the interim
removeMissing/reconcile compensators and name what a future
semantic-apply direction would delete; correct the define_subgraph
prerequisite chain now that #16644 closed unmerged with no verified
successor; and trim the Sequencing section to dependency order and
behavior-level acceptance criteria, moving file/test-level detail out
of the architecture record.
@claude
claude Bot requested a review from DrJKL September 20, 2026 11:26
@github-actions github-actions Bot added risk:high PR risk grade (advisory shadow check; grader-owned) and removed risk:medium PR risk grade (advisory shadow check; grader-owned) labels Sep 20, 2026

@DrJKL DrJKL left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: one material finding remains

The panel-lifetime blocker, dead define_subgraph prerequisite, and volatile rollout-detail findings are addressed. The semantic-apply boundary is only partially addressed: the reconcile compensators are now correctly marked interim, but the ADR still says the parallel pending ledger survives unchanged even though the proposal it summarizes explicitly deletes and replaces that ledger.

Finding without an anchorable line
  • [P3] The PR description is stale after this follow-up. It still describes four rollout slices without A1, says the tracker only needs to survive tab deactivation, presents C as blocked on the old #17454 chain, and points reviewers to exact test ownership removed from the ADR. Please update it to match the cumulative head.
Prior findings
  • Fixed: workflow/document ownership now survives panel close and includes a close/reopen acceptance case.
  • Partially addressed: reconcile machinery has a deletion boundary, but the pending-ledger boundary remains inaccurate.
  • Fixed: #16644 is identified as closed unmerged and PR C is blocked on a new integration plan.
  • Fixed: file/test/fixture-level rollout details moved outside the ADR.
Coverage and checks

Standard-depth correctness, maintainability, and documentation lanes reviewed the cumulative head 26f7974eeb7cb6e805c73d3a1b33ba841c55866e. I read the full ADR, incremental diff, author replies, current PR body, FE-2504, FE-2512, and the linked investigation. FE-2504 remains a proposed High-priority Backlog direction, not an accepted contract.

pnpm adr:check, changed-file oxfmt --check, and git diff --check passed. CI reports ADR links, lint/format, and Fallow successful. No runtime test was warranted for this docs-only correction between two proposed architectures.

The head matches the supplied snapshot. The effective merge base remains 81fc7223160b931e8020f66d415bf2edea6a4a54; fetched origin/main is six commits ahead at dad05c594f8a77b4e31c502b84621b736bb418c3.

`removeMissing`'s ledger- and lineage-awareness, `reconcileNode`,
`reconcileNextFrame`, the materializer's repair pass, and the ledger checks
in the adapter that gate those branches (all of (b) and the reconcile half
of (c)). What survives unchanged: the ledger's own intent record (the

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] The compensator deletion boundary is now clear, but this last paragraph still misstates the semantic-apply alternative. FE-2512 explicitly proposes deleting pendingOpLedger.ts and re-evaluating #16309 because command-minted operations already carry identity; the linked investigation likewise carries opId/actor provenance at the command site and retains no parallel pending ledger. Please keep the behavior requirements, including rejection and unknown-delivery handling, mechanism-independent: under the current store-first path the workflow/document ledger supplies them; if semantic apply is adopted, it may replace that ledger with command-carried provenance and ingress echo filtering. This does not require adopting or implementing FE-2504 here.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair catch — I had left the ledger's own survival unqualified. Rewrote the section's close: the four behavior requirements (no silent discard, rejections reported, unknown-delivery outcomes resolved at catch-up, collisions reported with the document winning) are now stated as mechanism-independent, with a note that the current store-first path satisfies them via the workflow/document-scoped ledger plus the (b)/(c) compensators. The paragraph now says the proposed semantic-apply direction would delete the parallel pending ledger itself (not just the compensators) and replace it with command-carried provenance plus ingress echo filtering, and the deletion/replacement list now names pendingOpLedger.ts and the ledger-gated echo check alongside removeMissing, reconcileNode, reconcileNextFrame, and the materializer repair pass. Not adopting or implementing the alternative here, per your note.


Generated by Claude Code

State the durable-vs-interim boundary as four mechanism-independent
behavior requirements (no silent discard of unresolved intent, host
rejections reported, unknown-delivery outcomes resolved at catch-up,
collisions reported with the document winning) instead of tying them
to the current ledger. Note that the current store-first path
satisfies them with the workflow/document-scoped ledger plus the
ledger-aware compensators, and that a later semantic-apply direction
could replace the ledger itself (not just the compensators) with
command-carried provenance and ingress echo filtering, naming
pendingOpLedger.ts and the ledger-gated echo check in the
deleted-or-replaced list alongside the existing compensators.
@claude

claude Bot commented Sep 20, 2026

Copy link
Copy Markdown
Contributor Author

Re: the P3 finding in review #5260500131 (stale PR description) — updated the PR body to match the cumulative head: Sequencing now reads PR A0 (landed in #18109), PR A (follower-scoped ledger), PR A1 (hoists ledger ownership to the bound workflow/document), PR B (lineage-aware removeMissing, after A1), PR C (blocked pending a new define_subgraph package-integration plan rather than the old #17454/#16644 chain). Also updated the Summary bullets and Review Focus to match, and dropped the reference to specific test names that are no longer in the ADR. The two attribution lines and the trailing Claude Code footer are unchanged.


Generated by Claude Code

@claude
claude Bot requested a review from DrJKL September 20, 2026 11:53

@DrJKL DrJKL left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: one documentation finding remains

The architecture findings are addressed. The pending intent now has workflow/document lifetime, the durable behavior is separated from the interim ledger and reconcile machinery, the dead package prerequisite is explicit, and the rollout section stays at behavior/dependency level.

One PR-description statement still conflicts with its own sequencing: Summary decision (a) says the workflow/document ledger scope “landed as two stacked PRs,” but Sequencing says only A0 landed and describes PR A and PR A1 as future slices. Please change that phrase to prospective wording such as “is split across two stacked PRs” so the description does not imply the implementation has already landed.

Coverage and checks

I reviewed cumulative head f1fd231cd5892b39854ed1d7b0ae4fa869ae9041 in separate correctness, maintainability, and documentation lanes. I reconciled all prior findings against the full ADR, live PR body and REST event history, FE-2504/FE-2512, and the current operation identity, sender, and pending-ledger contracts. FE-2504 remains proposed Backlog direction rather than accepted architecture.

pnpm adr:check, changed-file oxfmt --check, and git diff --check passed. Current CI reports ADR links, lint/format, and Fallow successful. No runtime test was warranted for this docs-only mechanism-boundary correction.

The effective merge base remains 81fc7223160b931e8020f66d415bf2edea6a4a54; fetched origin/main is eight commits ahead at 87885fcad70a5f328e05c1d71bae2df1942c9461.

@claude

claude Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor Author

Updated the Summary decision (a) wording in the PR description to be prospective: "is split across two stacked PRs, PR A then PR A1" (was "landed as two stacked PRs"). No code changed.


Generated by Claude Code

@claude
claude Bot requested a review from DrJKL September 22, 2026 06:25
@christian-byrne christian-byrne added the cursor-review Trigger multi-model Cursor agent review on this PR label Sep 22, 2026

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔍 Cursor Review — Consolidated panel

Triggered by @christian-byrne.

Found 10 finding(s).

Severity Count
🟠 High 5
🟡 Medium 5

Panel: 8/8 reviewers contributed findings.

@claude

claude Bot commented Oct 4, 2026

Copy link
Copy Markdown
Contributor Author

The record was rewritten after #18700, so most of the older threads refer to text that is gone. What stayed: the four durable requirements (now framed as the regression contract for the apply path) and the blueprint define_subgraph gap. What went: the pending-op ledger, the protected-state predicates, the unresolved outcome, the dependency contract, and the PR A/A1/B slices, because the reconcile layer they hung off was deleted. To review the new version, start with "Mechanism on main", then the Requirements table and "Remaining gaps and follow-ups", which says which requirements hold only partially or not at all. Earlier inline threads about the ledger mechanics are addressed by that removal, and I have left them for the reviewers to resolve. Head is 7276631.


Generated by Claude Code

christian-byrne
christian-byrne previously approved these changes Oct 4, 2026
@christian-byrne christian-byrne removed their assignment Oct 4, 2026

@mrseek-reviews mrseek-reviews Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: ready for human review

This head rewrites the record around the graph-API apply path on main. Every finding from my earlier rounds and the owner's unresolved finding is fixed or moot because the ledger mechanism it targeted is gone, and the four requirements now read as a regression contract that main's merge-only apply mostly satisfies by construction. I checked the mechanism claims against the code; most are accurate. I left two P2 accuracy issues and several P3 corrections inline. None blocks a human decision on the record.

Coverage and checks

Standard-depth correctness, maintainability, and documentation lanes reviewed head 72766317772649448368cc473df9c5cd963ed3e3 in a dedicated worktree. I traced the apply modes, replace arming, sender outcomes and timings, late-result credits, rejection revert and toast throttle, own-actor drop, collision handling, widget holds, root-scope minting, and disjoint id allocation into src/workbench/extensions/agent/crdt/ and idAllocation.ts. The agent CRDT source and ADR directory on this head match current main apart from this record.

pnpm install --frozen-lockfile, pnpm adr:check, changed-file oxfmt --check, and git diff --check origin/main...HEAD passed. Typecheck, lint, Knip, and runtime tests do not apply to this documentation-only diff. Every earlier inline thread of mine already has an author reply, so I posted no thread replies this round.

Effective merge base f31d207c59ca03502909deaa8d70348dbf91b477; origin/main d348bddc595545719937913514cb386c0970a721.

Review record

Round 1 (REQUEST_CHANGES, ddc65cf)

  • P1 ledger cleared on panel unmount, not lineage break: fixed by workflow/document ownership, then moot after the #18700 rewrite.
  • P2 durable guarantee vs interim reconcile mechanism (FE-2504): fixed; the four requirements are now the mechanism-independent contract.
  • P2 dead define_subgraph prerequisite chain: fixed; the gap is frontend-only.
  • P2 volatile file/test rollout checklist: fixed then partly reintroduced; see round 8.

Round 2 (COMMENT, 26f7974)

  • P2 parallel ledger survives semantic apply: fixed, then moot.
  • P3 stale PR body: fixed.

Round 3 (COMMENT, f1fd231)

  • P3 body said stacked PRs had landed: fixed.

Round 4 (REQUEST_CHANGES, b7f1ff3)

  • P1 reactivation seq mismatch bulk-reverted parked entries: fixed, then moot.
  • P1 ack generation cannot correlate duplicates: fixed; acknowledgements never settle edits.
  • P2 CRDT-PENDING-0030 missing from merge result: fixed, then moot (dependency removed).
  • P2 stale package 0.2.1 premise: fixed; capability stated without version.
  • P2 mutable rollout-status appendix: fixed.
  • P3 body claimed src/ cited decisions: fixed.

Round 5 (REQUEST_CHANGES, e3ef752)

  • P1 ack predicate consumed the duplicate: fixed, then moot.
  • P1 CRDT-FOLLOWER-0035 timeout cannot settle ledger entries: fixed, then moot.
  • P2 FE-2504 boundary contradiction in dependency summary: fixed, then moot.
  • P2 workflow close vs detached target session: fixed, then moot.
  • P2 stale package version 0.3.3: fixed.

Round 6 (REQUEST_CHANGES, c242ee9)

  • P1 idle timeout reset by every frame: fixed (absolute lifetime), then moot.
  • P1 max ack seq as destructive evidence: fixed (non-destructive outcome), then moot.
  • P2 destruction reported as rejection: fixed (abandoned), then moot.
  • P2 absence-settles contradiction: fixed; only explicit rejection reverts.
  • P2 revised deltas claimed landed in PR A: fixed.

Owner review (christian-byrne, b27a182)

  • Blocking: unresolved outside reconcile protection: addressed in 0a7312d, then moot after the rewrite removed the ledger; owner approved 7276631.

Round 8 (this review, 7276631), all open and non-blocking

  • P2 rejected set_node_field resyncs every node field.
  • P2 Requirement 1 vs reporting-only replace follow-up.
  • P3 missing useAgentCrdtFollower.humanAddTabSwitch.test.ts pin.
  • P3 retry count is six tries, not five.
  • P3 unmintable-edit report dedupes per flush, not once.
  • P3 Requirement 3 status framed three ways; unnumbered fifth table row.
  • P3 collision report needs a provenance discriminator.
  • P3 PR numbers, slice letters, and test inventory in durable text.
  • Nit identifier/slug still say reconcile.

@claude
claude Bot requested a review from christian-byrne October 4, 2026 01:57
@christian-byrne christian-byrne assigned DrJKL and unassigned DrJKL Oct 4, 2026
@christian-byrne
christian-byrne dismissed stale reviews from DrJKL, DrJKL, DrJKL, DrJKL, and themself October 9, 2026 10:11

Dismissing as stale, not refuted. This review was submitted 2026-09-24T00:13:59Z at commit e3ef752, before the ADR was substantively rewritten for the post-#18700 graph-API apply path: e55a218 (2026-10-04, "revise CRDT-RECONCILE-0035 for the graph-API apply path"), 7276631 (tightened wording), and 240d4d0 (2026-10-04T01:55, "correct mechanism details flagged in review" — addressing the automated mrseek-reviews pass). Christian's own 2026-10-03 CHANGES_REQUESTED on this same rewrite was independently addressed and dismissed 2026-10-04T01:46. A fresh re-review request was posted in #pillar5-agent-code-review 2026-10-09T09:07Z; no reply yet. Dismissing this specific stale verdict so the PR reflects live review state while a fresh DrJKL pass is pending — not a claim that the ADR is approved.

@christian-byrne

Copy link
Copy Markdown
Contributor

Adding @dante01yoon as a second reviewer — this ADR has been open for review since 2026-09-20 with DrJKL's threads addressed through multiple architecture rewrites (most recently 2026-10-04 post-#18700), but has had no review activity on this PR since 2026-09-24. All stale CHANGES_REQUESTED reviews were dismissed with evidence. Either reviewer's stamp unblocks this.

@mrseek-reviews mrseek-reviews Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: ready for human review

This head answers all nine of my round-8 comments. Eight are fixed, the remaining pin now exists on main via #20051, and the declined identifier rename is acceptable for link stability. I re-checked the new mechanism wording against current main's rejectedOpChanges.ts, liveGraphApplier.ts, opSender.ts, and docOpMinter.ts; it is accurate apart from the three P3 notes inline. None of them blocks a human decision on this record.

PR body (not anchorable)
  • [P3] The body still says rejections revert "register by register", but the ADR now says a field write resyncs the whole node; its partial-hold list also omits that gap and does not mention that the doc_reset replace is now a named exception to requirement 1. It also says the index row title is "updated", while this PR adds the row, and calls CRDT-REPLAY-0039 new although it is already on main.
Coverage and checks

Standard-depth correctness, maintainability, and documentation lanes reviewed head 240d4d02b516b944d16084ef29aac939ec6cf9c9, focusing on the incremental diff from 72766317 and its consistency with the full record, CRDT-AUTHORITY-0035, and the agent CRDT source on current main. pnpm install --frozen-lockfile, pnpm adr:check, changed-file oxfmt --check, and git diff --check origin/main...HEAD passed. Current-head CI has 36 successful and 51 skipped checks with no failures. Typecheck, lint, Knip, and runtime tests do not apply to this documentation-only diff.

Effective merge base f31d207c59ca03502909deaa8d70348dbf91b477; origin/main 85a816b0937cca7fe432894676d3f3b27d30c740. Every earlier inline thread of mine already has an author reply, so I posted no thread replies.

Review record

Round 1 (REQUEST_CHANGES, ddc65cf; later dismissed by the owner)

  • P1 ledger cleared on panel unmount, not lineage break: fixed, then moot after the #18700 rewrite.
  • P2 durable guarantee vs interim reconcile mechanism (FE-2504): fixed; the four requirements are the mechanism-independent contract.
  • P2 dead define_subgraph prerequisite chain: fixed; the gap is frontend-only.
  • P2 volatile file/test rollout checklist: fixed (round 8 follow-up resolved the remaining status leakage).

Round 2 (COMMENT, 26f7974)

  • P2 parallel ledger survives semantic apply: fixed, then moot.
  • P3 stale PR body: fixed.

Round 3 (COMMENT, f1fd231)

  • P3 body said stacked PRs had landed: fixed.

Round 4 (REQUEST_CHANGES, b7f1ff3; dismissed)

  • P1 reactivation seq mismatch bulk-reverted parked entries: fixed, then moot.
  • P1 ack generation cannot correlate duplicates: fixed; acknowledgements never settle edits.
  • P2 CRDT-PENDING-0030 missing from merge result: fixed, then moot.
  • P2 stale package 0.2.1 premise: fixed.
  • P2 mutable rollout-status appendix: fixed.
  • P3 body claimed src/ cited decisions: fixed.

Round 5 (REQUEST_CHANGES, e3ef752; dismissed)

  • P1 ack predicate consumed the duplicate: fixed, then moot.
  • P1 CRDT-FOLLOWER-0035 timeout cannot settle ledger entries: fixed, then moot.
  • P2 FE-2504 boundary contradiction: fixed, then moot.
  • P2 workflow close vs detached target session: fixed, then moot.
  • P2 stale package version 0.3.3: fixed.

Round 6 (REQUEST_CHANGES, c242ee9; dismissed)

  • P1 idle timeout reset by every frame: fixed, then moot.
  • P1 max ack seq as destructive evidence: fixed, then moot.
  • P2 destruction reported as rejection: fixed, then moot.
  • P2 absence-settles contradiction: fixed.
  • P2 revised deltas claimed landed in PR A: fixed.

Owner review (christian-byrne, b27a182)

  • Blocking unresolved outside reconcile protection: fixed in 0a7312d, then moot after the rewrite.

Round 8 (COMMENT, 7276631)

  • P2 rejected set_node_field resyncs every node field: fixed in 240d4d0 (documented as a partial hold and follow-up 5).
  • P2 requirement 1 vs reporting-only replace follow-up: fixed in 240d4d0 (named exception); rationale wording reopened as a round 9 P3.
  • P3 missing useAgentCrdtFollower.humanAddTabSwitch.test.ts pin: resolved; #20051 merged it to main and the merge result contains it.
  • P3 retry count: fixed in 240d4d0.
  • P3 unmintable-edit report dedupe: fixed in 240d4d0.
  • P3 requirement 3 status framed three ways and fifth table row: fixed in 240d4d0.
  • P3 collision report lacked provenance: fixed in 240d4d0.
  • P3 PR numbers and slice letters in durable text: fixed in 240d4d0.
  • Nit identifier/slug: declined by the author for link stability; accepted.

Round 9 (this review, 240d4d0), open and non-blocking

  • P3 replace-exception rationale misstates which edits are lost.
  • P3 status list and table assign gaps to the wrong requirement.
  • P3 refused widget write resyncs all widgets on array-shaped nodes.
  • P3 PR body stale (body-only, see above).

@dante01yoon dante01yoon left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at d0597406. Docs only, CI green (38 pass / 0 fail), MERGEABLE.

For an ADR whose whole value is that it describes what the code actually does, the useful thing a reviewer can do is check it against the code rather than read it for plausibility. So I verified a sample of the specific claims against main. Nearly all of them hold exactly:

Claim Checked against Result
Merge mode never sweeps; only replace removes absent nodes liveGraphApplier.ts:471 — if (mode === 'replace') this.removeAbsent(...) Accurate
Replace is armed only by the doc_reset handler replaceOnNextFrame has exactly one non-test caller, useAgentCrdtFollower.ts:561, inside onDocReset Accurate
doc_reset aborts the sender before the reset is announced onDocReset calls sender.abortAll() before events.onReset?.() Accurate
Toast throttled ten seconds NOTICE_LIFE_MS = 10_000 Accurate
Four keys under agent.editRejected widgetWrite, widgetWritePartial, generic, genericPartial — exactly four Accurate
Five retries, six tries, half a second apart (~2.5s) SEND_RETRY_LIMIT = 5, SEND_RETRY_INTERVAL_MS = 500 Accurate
unacknowledged at ~20s after one silent resend RESULT_TIMEOUT_MS = 10_000, resent once Accurate
A refused field write resyncs the whole node, not the named field rejectedOpChanges.ts:51 — set_node_field adds to resyncNodes Accurate
Resynced fields are title / mode / flags / properties / appearance SYNCED_NODE_FIELDS = title, mode, flags, properties, color, bgcolor, boxcolor Accurate ("appearance" = the colors)
Disjoint id minting via crdt-disjoint idAllocation.ts:142 Accurate
The collision spec is an expected failure agentNodeIdCollision.spec.ts uses test.fail() Accurate

Every cross-referenced ADR resolves, and the index row is correctly placed alphabetically with a title, status and date matching the document header. Commits carry no AI co-author trailers.

One factual error, inline and non-blocking: a cited test file does not exist.

Two things I want to call out as genuinely good, because they are unusual and I would not want a later editor to strip them:

  • The "Suspected, unverified" follow-up (item 6) is labelled as such. Three plausible-sounding race conditions are written down as needing a repro before anyone asserts them. That is the right way to record a suspicion, and it is exactly what makes the rest of the document trustworthy.
  • The gap table is honest about what does not work. Requirements 3 and 4 are marked "No" with the reason, rather than softened. An ADR that only records what works is the kind that quietly stops matching the code; this one states plainly that three terminal outcomes are invisible to the user and that collisions go unreported.

The decision itself reads correctly to me: protecting pending local intent structurally ("a frame can change only what the document changed") rather than through a per-op registry that must be kept in step with the sender is the right call, and the "Alternatives considered" entry explaining why the registry is not coming back is well argued.

node only once the new lineage's first frame arrives),
`agentCrdtProjection.localEdits.test.ts` (an unminted add and a node the
document never took survive tab return),
`useAgentCrdtFollower.humanAddTabSwitch.test.ts`,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

issue (non-blocking): useAgentCrdtFollower.humanAddTabSwitch.test.ts does not exist anywhere in the tree.

I checked every backticked file reference in this ADR — 24 of them — and this is the only one that does not resolve. There is no file by that name under src/workbench/extensions/agent/crdt/ or anywhere else.

I suspect it is a duplication slip: the Playwright spec agentHumanAddTabSwitch.spec.ts does exist, and it is already cited four lines below in the same Pins list. It looks like the browser spec's name picked up a useAgentCrdtFollower. prefix and became a phantom unit test.

Flagging it rather than ignoring it because of what this list is for. These Pins are presented as the regression contract for requirement 1 — the tests a future author is supposed to check before changing the apply path. A reader who goes looking for the unit test that pins "a human add survives a tab switch" will not find one, and the natural conclusion is that the behavior is unpinned.

It is not actually unpinned, which is why this does not block: the behavior is covered by agentCrdtProjection.localEdits.test.ts and agentDeleteTabSwitchRace.test.ts in the same list, plus the browser spec. So the fix is just to delete the phantom line.

If a unit test of that name was intended and has not been written, it would be clearer to move it into the follow-ups than to cite it here as an existing pin.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The file exists on main: src/workbench/extensions/agent/crdt/useAgentCrdtFollower.humanAddTabSwitch.test.ts landed with #20051 (merged 2026-10-04, 07b78a1). This branch's last base merge is f31d207, which predates it, so it is absent from this head's tree but present at the merge target. Leaving the pin in place; it will be in the tree once the branch takes main (merge or merge-queue update).


Generated by Claude Code

@@ -0,0 +1,420 @@
# ADR-CRDT-RECONCILE-0035: Local-Only State Survives Remote Apply

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit-pick (non-blocking): the filename still says authoritative-reconcile, which is the one concept this revision says no longer exists.

The title is now "Local-Only State Survives Remote Apply", and the body is explicit that #18700 deleted the reconcile layer and that the protection is structural rather than predicate-based. The slug underneath it still reads ...-local-only-state-survives-authoritative-reconcile.md, so anyone finding this by filename gets the superseded framing first.

I am not asking for a rename — ADR slugs are usually stable identifiers, and external review threads and Slack links point at this one. I checked, and docs/adr/README.md is the only in-repo file referencing it, so a rename would be cheap mechanically; the cost is all in the external links.

The cheapest fix is probably a half-line under the existing "Revised after the graph-API apply path landed (#18700)." noting that the slug is retained deliberately and that the reconcile it names is gone. That way the mismatch reads as a decision rather than as staleness, which matters for a document whose credibility rests on matching the code.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. I'll add that half-line under the revision note so the retained slug reads as a decision. Holding the push for now so the approval on d059740 stands; it rides the next push to this branch unless the requester wants it in before merge.


Generated by Claude Code

@dante01yoon dante01yoon removed their assignment Oct 9, 2026

@mrseek-reviews mrseek-reviews Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: ready for human review

This head fixes all three of my round-9 comments, and the PR body now matches the record. One new P2 remains: the narrowed requirement 1 Hold claim is not true for node fields, because any remote write to a synced field resyncs every field on that node in merge mode. The other notes inline are P3 or nits. None blocks a human decision on this record.

Other review feedback
  • I contest dante01yoon's missing-file finding. src/workbench/extensions/agent/crdt/useAgentCrdtFollower.humanAddTabSwitch.test.ts landed on main in #20051 (blob 5c63d93), after this branch's merge base, so it is absent from the PR tree but present in git merge-tree of this head with current main. It pins the human add across a tab switch with its op in flight, for a catalogued and a frontend-only node type. The citation is valid once merged.
  • I concur with dante01yoon's slug nit as optional. The author has agreed to add a half-line explaining the retained slug on the next push.
Coverage and checks

Standard-depth correctness, maintainability, and documentation lanes reviewed head d0597406081d40cadc10720d2843632f0963060f, focusing on the incremental diff from 240d4d02 and checking every new claim against agent CRDT source on current main and CRDT-AUTHORITY-0035. pnpm install --frozen-lockfile, pnpm adr:check, changed-file oxfmt --check, and git diff --check origin/main...HEAD passed. Current-head CI has 37 successful and 50 skipped checks with no failures. Typecheck, lint, Knip, and runtime tests do not apply to this documentation-only diff.

Effective merge base f31d207c59ca03502909deaa8d70348dbf91b477; origin/main ee36517ca384ffd970751a1a5a5fabaf7d74be87. The author replied to all three round-9 threads, so I posted no thread replies.

Review record

Round 1 (REQUEST_CHANGES, ddc65cf; later dismissed)

  • P1 ledger cleared on panel unmount, not lineage break: fixed, then moot after the #18700 rewrite.
  • P2 durable guarantee vs interim reconcile mechanism (FE-2504): fixed; the four requirements are the mechanism-independent contract.
  • P2 dead define_subgraph prerequisite chain: fixed; the gap is frontend-only.
  • P2 volatile file/test rollout checklist: fixed (round 8 resolved the remaining status leakage).

Round 2 (COMMENT, 26f7974)

  • P2 parallel ledger survives semantic apply: fixed, then moot.
  • P3 stale PR body: fixed.

Round 3 (COMMENT, f1fd231)

  • P3 body said stacked PRs had landed: fixed.

Round 4 (REQUEST_CHANGES, b7f1ff3; dismissed)

  • P1 reactivation seq mismatch bulk-reverted parked entries: fixed, then moot.
  • P1 ack generation cannot correlate duplicates: fixed; acknowledgements never settle edits.
  • P2 CRDT-PENDING-0030 missing from merge result: fixed, then moot.
  • P2 stale package 0.2.1 premise: fixed.
  • P2 mutable rollout-status appendix: fixed.
  • P3 body claimed src/ cited decisions: fixed.

Round 5 (REQUEST_CHANGES, e3ef752; dismissed)

  • P1 ack predicate consumed the duplicate: fixed, then moot.
  • P1 CRDT-FOLLOWER-0035 timeout cannot settle ledger entries: fixed, then moot.
  • P2 FE-2504 boundary contradiction: fixed, then moot.
  • P2 workflow close vs detached target session: fixed, then moot.
  • P2 stale package version 0.3.3: fixed.

Round 6 (REQUEST_CHANGES, c242ee9; dismissed)

  • P1 idle timeout reset by every frame: fixed, then moot.
  • P1 max ack seq as destructive evidence: fixed, then moot.
  • P2 destruction reported as rejection: fixed, then moot.
  • P2 absence-settles contradiction: fixed.
  • P2 revised deltas claimed landed in PR A: fixed.

Owner review (christian-byrne, b27a182)

  • Blocking unresolved outside reconcile protection: fixed in 0a7312d, then moot after the rewrite.

Round 8 (COMMENT, 7276631)

  • P2 rejected set_node_field resyncs every node field: fixed in 240d4d0.
  • P2 requirement 1 vs reporting-only replace follow-up: fixed in 240d4d0 (named exception).
  • P3 useAgentCrdtFollower.humanAddTabSwitch.test.ts pin: resolved; #20051 merged it to main and the merge result contains it.
  • P3 retry count: fixed in 240d4d0.
  • P3 unmintable-edit report dedupe: fixed in 240d4d0.
  • P3 requirement 3 status and fifth table row: fixed in 240d4d0.
  • P3 collision report lacked provenance: fixed in 240d4d0.
  • P3 PR numbers and slice letters in durable text: fixed in 240d4d0.
  • Nit identifier/slug: declined by the author for link stability; accepted.

Round 9 (COMMENT, 240d4d0)

  • P3 replace-exception rationale misstated which edits are lost: fixed in d059740.
  • P3 status list and table assigned gaps to the wrong requirement: fixed in d059740 for the replace and field resync; the late-rejection attribution remains (round 10 P3).
  • P3 refused widget write resyncs all widgets on positional-array nodes: fixed in d059740.
  • P3 stale PR body: fixed.

Second reviewer (dante01yoon, d059740)

  • Missing useAgentCrdtFollower.humanAddTabSwitch.test.ts: contested; the file is on main and in the merge result.
  • Slug nit: concur it is optional.

Round 10 (this review, d059740), open and non-blocking

  • P2 merge-mode remote field write rewinds unconfirmed sibling field edits; contradicts the requirement 1 Hold claim.
  • P3 swallowed late rejection attributed to two requirements.
  • P3 rejection-path parenthetical readability and line length.
  • P3 follow-up 5 title and action cover only the field case.
  • Nit "local adds" and two-tab qualifier against CRDT-AUTHORITY-0035.


How well main holds each one:

- **Hold.** Requirement 1 holds by construction in merge mode for any frame

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] This holds for widgets, links and node add/remove, but not for node fields, which the rejection-path text treats as separate registers. On main, a remote frame that changes any synced field on a node (title, mode, flags, properties, colors) puts the whole node in resyncNodes (docChangeCollector.ts onNodeFieldsChanged and the flags branch). Merge mode then runs syncFields/applyFields, which rewrites every field from the document. Field writes have no hold (LocalWidgetWrites tracks only set_widget), so an agent changing a node's title rewinds the human's unconfirmed mode or property edit on that node, even though the frame never named it. When the human's op later lands, its own-actor echo is dropped, so the canvas can stay diverged with no signal. Please either define the field register as the whole node, or list this merge-mode sibling-field rewind next to the rejected-field gap in the partial holds, the table, follow-up 5 and Consequences.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirmed against main: a frame that changes any synced node-map key puts the whole node in resyncNodes (docChangeCollector.ts), and merge mode then runs syncFields/applyFields (liveGraphApplier.ts), which rewrites title, mode, flags, properties and appearance with no hold (LocalWidgetWrites tracks only set_widget); the human op's own-actor echo is then dropped by the follower. The correction is prepared (the merge-mode sibling-field rewind is now listed in the partial holds, the table, follow-up 5 and Consequences, and the Hold bullet no longer claims every register) and will go in the next push to this branch; it is held for now because a push dismisses the live approval.


Generated by Claude Code

@DrJKL DrJKL assigned christian-byrne and unassigned DrJKL Oct 9, 2026
@christian-byrne
christian-byrne added this pull request to the merge queue Oct 9, 2026
Merged via the queue into main with commit b23c0d7 Oct 9, 2026
96 checks passed
@christian-byrne
christian-byrne deleted the claude/adr-crdt-rejected-ops-reconcile branch October 9, 2026 20:28
christian-byrne pushed a commit to christian-byrne/ComfyUI_frontend that referenced this pull request Oct 10, 2026
…Comfy-Org#20678)

<!-- ccr-slack-attribution -->
_Requested by **Christian Byrne** · [Slack
thread](https://comfy-organization.slack.com/archives/C0BGH348Z0C/p1789709550015299?thread_ts=1789709550.015299&cid=C0BGH348Z0C)_

## Summary

Follow-up to Comfy-Org#18106. Corrects an accuracy gap found after that PR was
approved and tightens wording.

**Before:** The ADR states that merge mode never rewinds unconfirmed
local edits. It also leaves the replace-mode exception, the hold scope,
and the rejection-revert scope loosely worded.

**After:** The ADR records that a synced or rejected node-field write
resyncs the whole node in merge mode, rewinding that node's unconfirmed
sibling fields with no hold, and names this as an accepted, tracked gap.
The hold bullet, replace exception, rejection-path scope, requirements
table, follow-up 5 and consequences are tightened to match the code on
main.

## Verification

Docs only. Edits
`docs/adr/CRDT-RECONCILE-0035-local-only-state-survives-authoritative-reconcile.md`;
no code changes. Validated with `pnpm adr:check`, oxfmt and `git diff
--check`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01NQVcfKhCKjLstqo3mJS7fc

---
_Generated by [Claude
Code](https://claude.ai/code/session_01NQVcfKhCKjLstqo3mJS7fc)_

Co-authored-by: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent Comfy Agent product, integration, tests or product documentation agent-crdt Agent document synchronization, graph projection or CRDT operations agent-docs Agent product architecture, contracts or documentation cursor-review Trigger multi-model Cursor agent review on this PR risk:medium PR risk grade (advisory shadow check; grader-owned)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants