Skip to content

docs(adr): propose same-page operation replay policy - #19314

Merged
christian-byrne merged 3 commits into
mainfrom
codex/testpin-policy-record-1
Sep 30, 2026
Merged

christian-byrne merged 3 commits into
mainfrom
codex/testpin-policy-record-1

Conversation

@christian-byrne

Copy link
Copy Markdown
Contributor

Summary

Proposes a self-contained frontend decision for retaining transport-exhausted operations within the same page session, so reviewers can evaluate the already-ratified policy without access to the program repository.

Changes

  • What: opSender retains exhausted operations in the same page session, replay preserves the original op_id, and transport retry exhaustion is not terminal discard.
  • Scope: Full page-reload persistence remains undecided. Unbind, retarget, and doc_reset behavior are unchanged. This PR changes no runtime code and does not mark the proposal Accepted.

Review Focus

Ratification wake: Christian and DrJKL must agree that CRDT-REPLAY-0039 accurately records the same-page policy, then an authorized maintainer must change its status from Proposed to Accepted.

Then-#18754 wake: after that Accepted frontend record is immutable on main, #18754 may cite it; DrJKL must verify the citation against the then-current exact head, retire the outstanding policy objection, and submit a fresh review. Required hosted checks must also be green. This PR does not modify #18754.

@christian-byrne
christian-byrne requested a review from a team September 28, 2026 23:11
@DrJKL
DrJKL self-requested a review September 28, 2026 23:11
@christian-byrne
christian-byrne removed the request for review from DrJKL September 28, 2026 23:11
@coderabbitai

coderabbitai Bot commented Sep 28, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository: Comfy-Org/ComfyUI_frontend/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Team

Run ID: d79b90a4-8ceb-4e3d-abea-f9a1858c3f4d

📥 Commits

Reviewing files that changed from the base of the PR and between 9b895cd and 07fb993.

📒 Files selected for processing (1)
  • docs/adr/README.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 6 remain after this review. Your free on-demand review promotion remains active until October 9, 2026 at 6:00 PM UTC.


📝 Walkthrough

Walkthrough

The pull request adds a proposed ADR for retaining operations after transport retries are exhausted and replaying them in the same page session. It adds the ADR to the index. The proposal does not claim current runtime support or require persistence across page reloads.

Changes

Same-Page Replay Proposal

Layer / File(s) Summary
Replay policy and ADR index
docs/adr/CRDT-REPLAY-0039-retain-exhausted-operations-for-same-page-replay.md, docs/adr/README.md
The proposed ADR describes same-session retention and replay using the original op_id, with host results governing settlement. It states that unbinds, workflow retargets, and doc_reset lineage breaks remain unchanged. It records alternatives, consequences, and approval status. The index lists the ADR as Proposed.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Suggested reviewers: drjkl

Merge Risk: ⚪ Minimal · up to 07fb9

This PR adds a Proposed ADR and matching index entry without changing runtime behavior. No concrete inconsistency or merge blocker is established; normal checks remain.

🚥 Pre-merge checks | ✅ 7
✅ Passed checks (7 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the proposal to define a same-page operation replay policy.
Description check ✅ Passed The description includes a summary, the main change, scope, and review focus. It does not use the template’s Breaking and Dependencies bullets, but it states that the PR changes no runtime code and do…
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.
End-To-End Regression Coverage For Fixes ✅ Passed The PR changes only documentation: an ADR and the ADR index. The title and commit subjects use no bug-fix language. The check also exempts documentation-only changes, so it does not require a Playwrig…
Website End-To-End Regression Coverage ✅ Passed No changed file is under apps/website/src/ or apps/website/public/. The PR changes only ADR documentation, so this check does not apply.
Adr Compliance For Entity/Litegraph Changes ✅ Passed The listed changed files are docs/adr/CRDT-REPLAY-0039-retain-exhausted-operations-for-same-page-replay.md and docs/adr/README.md. Neither is under src/lib/litegraph/ or src/ecs/, and neither …
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR

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

coderabbitai[bot]
coderabbitai Bot previously approved these changes Sep 28, 2026
coderabbitai[bot]
coderabbitai Bot previously approved these changes Sep 28, 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 because the replay contract leaves the promised same-page lifetime undefined.

Pre-merge blockers:

  • P1: Define what sender or panel teardown does to retained operations while the page remains open, or narrow the retention promise to the sender lifetime.
Existing finding confirmed
  • P2: CodeRabbit's risk note says the cited program ADR remains unverified. I confirmed that the authenticated reviewer receives HTTP 404 for the repository and commit. My inline finding asks for accessible evidence or a qualified provenance statement; it does not prevent this repository from deciding the self-contained policy on its own merits.
Checked and cleared
  • The author changed opSender "may replay" to "replays" in 5d08cf1, so replay is now required after reconnect and subscription acknowledgement.
  • FIFO ordering is sufficiently established by keeping the retained operation in opSender, naming it as the existing ordering owner, and rejecting a second retry queue. The current sender serializes the in-flight head ahead of later work.
  • Full-envelope identity is sufficiently established by replaying the retained locally minted operation and rejecting re-minting. The current sender stores and resends the same Op[]; the separate op_id sentence explains idempotence rather than authorizing other fields to change.
  • A separate ADR is intentional here. It is self-contained, names the exact clauses it would supersede, and the repository has no rule requiring edits to the older record.
Coverage
  • Depth: standard.
  • Lanes run: correctness, maintainability, and documentation.
  • Tests lane skipped because the diff changes policy documentation without runtime or test changes. Idiomaticity skipped because no TypeScript, Vue, Tailwind, or Astro changed.
  • Standard correctness, maintainability, and documentation lenses ran. Fallow was skipped because both changed files are Markdown.
  • Checks at 5d08cf1: pnpm adr:check passed; changed-file oxfmt --check passed; focused current-behavior Vitest passed with 1 test and 39 skipped.
  • The first broad Vitest invocation routed to the full suite and hit unrelated network-dependent failures. The corrected focused command passed.

### Negative

- `opSender` can retain exhausted operations in memory for the rest of the page
session, so it needs an explicit terminal settlement or teardown policy.

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 leaves an essential part of the decision unresolved. opSender is owned by useAgentCrdtFollower, and detach() currently clears its in-flight and queued state without settlement even though the browser page can remain open. Please define the retained operation's outcome on sender or panel teardown, or narrow the guarantee from the page session to the actual sender lifetime.

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.

Addressed at exact head 9b895cd25e. The Proposed ADR now defines the accepted same-page lifetime across panel/sender teardown: panel close or remount cannot discard retained ops; teardown must transfer the unchanged ordered state to a page-session owner, or the sender itself must be page-session-owned. It records the verified current gap (useAgentCrdtFollower is panel-scope-owned and sender.detach() clears in-flight, queued, and admitted state without settlement) as implementation evidence, not authority to narrow the contract. Focused current-behavior Vitest passes; changing its detach assertion from pending 0 to 1 fails with received 0.


## Notes

The ratified source for this proposal is the 2026-09-28 clarification in

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: I cannot verify that this is the ratified source or that this record transcribes it exactly: authenticated REST access to the cited repository and commit returns HTTP 404. The frontend decision is self-contained enough to judge on its own merits, but this provenance claim needs an accessible immutable copy or quoted decision and approval record, or wording that marks the external provenance as unverified 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.

Addressed at exact head 9b895cd25e. The frontend ADR now embeds Christian Byrne’s 2026-09-26 approval quote, names the 2026-09-28 clarification and approver, transcribes the full normative clarification (same-page/suspended-tab lifetime, opSender ownership, original op_id, reload undecided), and explicitly labels the private immutable ADR-012 link as provenance rather than required reading. The record remains Proposed pending independent frontend-maintainer ratification.

@github-actions

github-actions Bot commented Sep 28, 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 76a2b8e93c4595ec3a02cfcd05b8ccd1414431dd

Full docs: ADR-DEVEX-LINT-0015

@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 head now defines same-page teardown retention and records enough approval context for independent frontend ratification.

No findings remain open at this head.

Review record
  • P1, replay obligation: fixed before the first-round review in 5d08cf1 by changing opSender from "may replay" to "replays."
  • P1, same-page teardown lifetime: raised in the first-round review, then addressed in 9b895cd. Panel close or remount can no longer narrow the page-session contract; the author's reply confirms the change.
  • P2, private provenance: raised in the first-round review, then answered in 9b895cd. The ADR now embeds the dated approval and normative clarification, labels the private record as non-required provenance, and remains Proposed for independent frontend ratification; see the author's reply.
  • P2, teardown ownership alternatives: withdrawn at 9b895cd. An exclusive transfer of unchanged ordered sender state and a page-owned sender are two implementations of the same lifecycle invariant; the lifecycle holder does not become a concurrent delivery queue.

Checks at 9b895cd: pnpm adr:check passed; changed-file oxfmt --check passed; focused opSender Vitest passed with 2 tests and 38 skipped. Standard correctness, maintainability, and documentation lanes reviewed the full follow-up delta. Tests and idiomaticity lanes remained inapplicable to this Markdown-only change.

@github-actions github-actions Bot added the risk:high PR risk grade (advisory shadow check; grader-owned) label Sep 29, 2026
christian-byrne added a commit that referenced this pull request Sep 29, 2026
## Summary

Carries the current-main behavioral tests from #18754 without its branch
history, plus focused repairs requested during review.

## Changes

- Preserves the current-main frontend behavior pins and the existing
`setOptions` test.
- Adds a recorded-conversation assertion that an agent widget edit is
visible as steps `30` and cfg `5.0`.
- Proves retry identity and acknowledgment within the active retry
budget.
- Removes post-exhaustion discard/replay assertions. Those depend on the
separate replay-policy decision in #19314 and no longer block these
current-behavior pins.
- Tests only. No runtime or breaking change.

## Review focus

Please verify that the remaining tests pin current frontend behavior
without establishing post-exhaustion replay policy. The retry cases
reach a real send, preserve the original `op_id`, prove acknowledged
settlement, and prove a later reconnect does not resend it.

## Validation

- `crossWorkflowPending.test.ts`: 8 passed, 0 expected failures.
- Scoped ESLint and oxfmt passed.
- `typecheck:app`, Knip, and diff-scoped Fallow passed in commit and
push hooks.
- Earlier focused validation for the unchanged companion files passed,
including the recorded cloud replay and mutation checks described in the
review threads.

Current head: `8324a3530a30b631a5ebd2bc24e47e50959c3749`.

Justification: DrJKL’s exact-head review states that all blockers are
addressed and the PR is ready to approve; GitHub recorded that verdict
as a comment rather than an approval. Exact-head CI is green, and the 22
newer main commits have zero file overlap with this test-only change.

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.

This wasn't written for people, was it?

@DrJKL DrJKL removed their assignment Sep 29, 2026
@christian-byrne

Copy link
Copy Markdown
Contributor Author

Justification: exact head 07fb993 is approved and required-check green; it is five commits behind current main with zero changed-file overlap against the untested delta, so the independently reviewed delta cannot interact. Enqueueing through the normal merge queue.

@christian-byrne
christian-byrne added this pull request to the merge queue Sep 30, 2026
Merged via the queue into main with commit 836aea2 Sep 30, 2026
76 checks passed
@christian-byrne
christian-byrne deleted the codex/testpin-policy-record-1 branch September 30, 2026 16:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants