Skip to content

docs(adr): follow-up to #16459 — record widget restoration contract - #16862

Merged
DrJKL merged 2 commits into
mainfrom
docs/16459-widget-restoration-adr
Sep 7, 2026
Merged

DrJKL merged 2 commits into
mainfrom
docs/16459-widget-restoration-adr

Conversation

@christian-byrne

Copy link
Copy Markdown
Contributor

Records the shared widget-restoration contract introduced by #16459.

  • One restoration representation; explicit late Primitive materialization.
  • ADR 0006 accepted; ADR index synchronized.
  • Docs-only; formatting and diff checks clean.
Full context for agent readers

Summary

Updates ADR 0006 for the implementation that now shares WidgetRestorationState between LGraphNode.configure() and PrimitiveNode.configure(). It documents why Primitive restoration outlives base configuration, how generic lookup and cleanup work, and why a Primitive-only store or scheduler was rejected.

This follows up the final-head review request and its review envelope.

Changes

  • Mark ADR 0006 Accepted and broaden its title to widget restoration lifecycle.
  • Add current Context, Decision, Consequences, and alternatives.
  • Synchronize the ADR index title and status.

Evidence

  • git diff --check — passed.
  • pnpm exec oxfmt --check docs/adr/0006-primitive-node-copy-paste-lifecycle.md docs/adr/README.md — passed.
  • Pre-commit staged-file formatting — passed.
  • Pre-push Knip check — passed.

@christian-byrne
christian-byrne requested a review from a team September 3, 2026 22:41
@coderabbitai

coderabbitai Bot commented Sep 3, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: 1d472233-af65-44e5-b9ee-80c15ac08cb0

📥 Commits

Reviewing files that changed from the base of the PR and between 28cfc69 and ff9a035.

📒 Files selected for processing (2)
  • docs/adr/README.md
  • docs/adr/WIDGET-SERIALIZATION-0006-preserve-primitive-widget-values-across-copy-and-paste.md

Included review availability: Your plan provides up to 10 included reviews per hour; 2 remain after this review.


📝 Walkthrough

Walkthrough

The ADR now records an accepted PrimitiveNode widget restoration lifecycle. It covers workflow loading, copy/paste, shared restoration state, deferred dynamic widget restoration, identity-based storage, cleanup, and preservation of undefined.

Changes

PrimitiveNode restoration lifecycle

Layer / File(s) Summary
Accepted restoration lifecycle decision
docs/adr/README.md, docs/adr/WIDGET-SERIALIZATION-0006-preserve-primitive-widget-values-across-copy-and-paste.md
The ADR index marks the decision as Accepted with its revised title. The ADR documents generic restoration state handling, deferred PrimitiveNode restoration, cleanup conditions, clone serialization, widget cloning, projection, and rejected alternatives.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: 🟡 Moderate · up to ff9a0

The documentation change may present an unimplemented coordinator as an accepted restoration-lifecycle requirement, which could misdirect future implementation and maintenance. Remove or separate that claim before merging.

Suggested reviewers: drjkl


Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 inconclusive)

Check name Status Explanation Resolution
End-To-End Regression Coverage For Fixes ❓ Inconclusive The changed files are available and show documentation-only changes under docs/adr/, so the source/test condition does not apply. However, the PR title and actual commit subjects are not provided in… Provide the PR title and all commit subjects, then re-evaluate the bug-fix language condition.
✅ Passed checks (6 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly identifies an ADR documentation follow-up and the widget restoration contract. It matches the main changes.
Description check ✅ Passed The description explains the purpose, key changes, scope, and validation results. It includes Summary and Changes content. Review Focus and Screenshots are not provided, but they are non-critical for …
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Website End-To-End Regression Coverage ✅ Passed The PR changes only docs/adr/README.md and docs/adr/WIDGET-SERIALIZATION-0006-preserve-primitive-widget-values-across-copy-and-paste.md. It does not change files under apps/website/src/ or `apps…
Adr Compliance For Entity/Litegraph Changes ✅ Passed The changed-file list contains only docs/adr/README.md and docs/adr/WIDGET-SERIALIZATION-0006-preserve-primitive-widget-values-across-copy-and-paste.md. No changed file is under `src/lib/litegraph…
Full details: End-To-End Regression Coverage For Fixes

Explanation

The changed files are available and show documentation-only changes under docs/adr/, so the source/test condition does not apply. However, the PR title and actual commit subjects are not provided in the review context. The custom check requires those fields to evaluate bug-fix language and says to mark the check inconclusive when commit subjects are unavailable.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/16459-widget-restoration-adr

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

@christian-byrne christian-byrne added the risk:R1 PR risk grade (advisory shadow check; grader-owned) label Sep 3, 2026
@github-actions

github-actions Bot commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

⚡ Performance

⚠️ Performance tests failed. Check the CI workflow logs.

@christian-byrne christian-byrne self-assigned this Sep 3, 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: ready to approve

I compared this ADR line by line with the merged #16459 implementation on current origin/main. The shared WidgetRestorationState, base-configure cleanup, Primitive restaging conditions, generic lookup, type-mismatch cleanup, disconnect cleanup, and graph/node store identity are represented accurately. The ADR index title, status, date, and numbering also match.

Maintainability-skill finding: the speculative future-system paragraph at line 48 should be deleted. #16459 does not implement that system, and the paragraph defines neither an invariant nor a condition for adopting it. This is non-blocking; the implemented restoration decision is otherwise complete and accurate.

Checks: Oxfmt passed on both changed files; git diff --check passed; ADR numbering remains sequential from 0001 through 0027; ADR 0006’s index title, status, and date match; referenced files and implementation symbols exist.

build consumes the state through the generic lookup path. A completed build,
type mismatch, or disconnect clears any unconsumed state.

Do not add a Primitive-specific restoration type, store, or scheduler. A general

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.

Please delete this future-system paragraph. #16459 implements no connectivity-to-widget-materialization system or authoritative coordinator, and this ADR provides no invariant or adoption condition for one. In an Accepted ADR, that speculative replacement reads as accepted design direction while adding nothing to the restoration contract. The current decision is complete without it.

# Conflicts:
#	docs/adr/README.md
#	docs/adr/WIDGET-SERIALIZATION-0006-preserve-primitive-widget-values-across-copy-and-paste.md
@github-actions github-actions Bot added the risk:medium PR risk grade (advisory shadow check; grader-owned) label Sep 4, 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: ready to approve

The only head change since my prior review is a merge from main; the PR's own ADR text is unchanged. The restoration contract still matches the implementation, every referenced file and symbol resolves on current main, WIDGET-SERIALIZATION-0006 is unique under the domain-led identifier scheme, and the index merges cleanly.

Maintainability: the existing open finding remains. The future-system paragraph still describes an unimplemented coordinator without an invariant or adoption condition. I concur with the earlier request to delete it rather than duplicating that finding in a new inline comment. This remains non-blocking, and I found no additional duplicated architectural authority or speculative representation.

Formatting and ADR index validation pass on the current head.

@DrJKL
DrJKL added this pull request to the merge queue Sep 7, 2026
Merged via the queue into main with commit a15c535 Sep 7, 2026
61 checks passed
@DrJKL
DrJKL deleted the docs/16459-widget-restoration-adr branch September 7, 2026 22:25
xeinherjer-dev pushed a commit to xeinherjer-dev/ComfyUI_frontend that referenced this pull request Nov 4, 2026
…view follow-up to PR 16862) (Comfy-Org#17590)

Resolves the surviving review request from [PR 16862 (PrimitiveNode
widget restoration ADR
follow-up)](Comfy-Org#16862):
[DrJKL asked to delete the speculative future-system
paragraph](Comfy-Org#16862 (comment))
in the widget-values copy/paste ADR (WIDGET-SERIALIZATION-0006, file
[`docs/adr/WIDGET-SERIALIZATION-0006-preserve-primitive-widget-values-across-copy-and-paste.md`](https://github.com/Comfy-Org/ComfyUI_frontend/blob/main/docs/adr/WIDGET-SERIALIZATION-0006-preserve-primitive-widget-values-across-copy-and-paste.md)).

## What changed

Removes one sentence from the Decision section:

> A general connectivity-to-widget-materialization system can replace
the remaining lifecycle ordering when the application has an
authoritative coordinator for that phase.

Per the review: [PR 16459 (the ADR's implementation
PR)](Comfy-Org#16459)
implements no connectivity-to-widget-materialization system or
authoritative coordinator, and the ADR defines no invariant or adoption
condition for one, so the sentence reads as accepted design direction
while adding nothing to the restoration contract.

## What is preserved

The accepted restoration contract is intact:

- "Do not add a Primitive-specific restoration type, store, or
scheduler." (kept, immediately preceding the removed sentence)
- The Alternatives Considered entry rejecting a Primitive-only
restoration store/System
- All Consequences unchanged

## Verification

- `grep` confirms no remaining connectivity-to-widget-materialization /
authoritative-coordinator references in the ADR
- `oxfmt --check` passes on the changed file (lint-staged hook green at
commit)

Task row: srx-20260948.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants