Skip to content

docs(crdt): decide durable link intent semantics - #16819

Merged
christian-byrne merged 4 commits into
christian-byrne/ecw-106-comfy-multi-player-workspacefrom
christian-byrne/cmp-delete-link-scope-1
Sep 22, 2026
Merged

christian-byrne merged 4 commits into
christian-byrne/ecw-106-comfy-multi-player-workspacefrom
christian-byrne/cmp-delete-link-scope-1

Conversation

@christian-byrne

Copy link
Copy Markdown
Contributor

Summary

  • Records the durable-link-intent model needed to fix the seeded-link add_node / losing delete_node convergence failure.
  • Rejects the tempting unconditional incident-link deletion because it would disconnect a node whose delete loses Amendment A7's presence gate.
  • Defines the schema-v3 root, v2 migration, compaction requirements, and permanent test matrix before implementation.

Dependency

This is intentionally stacked on #16644 (christian-byrne/ecw-106-comfy-multi-player-workspace), which is still open and already carries the canonical package plus the permanent characterization test ported from comfy-multi-player #177. It must not be retargeted to main until #16644 lands.

Scope

This PR is a reviewed implementation checkpoint, not the runtime fix. The runtime change is schema-wide: durable intent, terminal explicit-removal tombstones, schema migration, read/wire guards, and compaction retention must land together to avoid replacing one convergence bug with data loss.

Verification

@christian-byrne christian-byrne self-assigned this Sep 3, 2026
@coderabbitai

coderabbitai Bot commented Sep 3, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. 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: Team

Run ID: 4b5d267b-8c09-4b48-8be3-e22be42fd9eb

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

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

@github-actions

github-actions Bot commented Sep 3, 2026 •

Copy link
Copy Markdown
Contributor

🌐 Website E2E

Tip

All tests passed.

Status ✅ Passed
Report View Report

🎨 Storybook: ✅ Built — View Storybook

Details

⏰ Completed at: 09/21/2026, 09:32:28 PM UTC

Links

📦 Bundle Size

⏳ Size data collection in progress…

🔗 Website Preview

Website Preview: https://comfy-website-preview-pr-16819.vercel.app

Models is built and gated by PostHog (workshop-enabled), using staging Cloud.

This commit: https://website-frontend-mjcuql51t-comfyui.vercel.app

Last updated: 2026-09-21T21:32:40Z for 92f770a

@codecov

codecov Bot commented Sep 3, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

@@                                   Coverage Diff                                    @@
##           christian-byrne/ecw-106-comfy-multi-player-workspace   #16819      +/-   ##
========================================================================================
- Coverage                                                 83.64%   81.37%   -2.27%     
========================================================================================
  Files                                                      2226     2741     +515     
  Lines                                                    126658   137119   +10461     
  Branches                                                  36174    35460     -714     
========================================================================================
+ Hits                                                     105943   111585    +5642     
- Misses                                                    20407    24406    +3999     
- Partials                                                    308     1128     +820     
Flag Coverage Δ
billing-web-unit 77.35% <ø> (ø)
website-unit 74.64% <ø> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1414 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

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

Justification: restores green main after bypass merge of #16819; CI-only
change.

## Evidence

- Failing run on exact main head `fe89f7d0`: `PR: Unified Report` run
[33794070328](https://github.com/Comfy-Org/ComfyUI_frontend/actions/runs/33794070328)
(2026-09-03T19:02:26Z), step `Download perf metrics (current)`:
`##[error]no artifacts found`.
- Upstream run
[33794021109](https://github.com/Comfy-Org/ComfyUI_frontend/actions/runs/33794021109)
(`CI: Performance Report`, PR #16819 head `72952823`) concluded
`success` without uploading the `perf-metrics` artifact — its upload
step is `if-no-files-found: warn`.
- The `Download perf metrics (current)` step omitted
`if_no_artifact_found`, so the dawidd6/action-download-artifact default
`fail` applied. The sibling `Download size data` / `Download coverage
data` steps already pass `warn`, and `scripts/unified-report.ts`
explicitly handles a missing `test-results/perf-metrics.json` (renders
an unavailable-metrics section, lines 61-62). So `warn` is the intended
contract; only the artifact-download step was missing it.
- Fix: add `if_no_artifact_found: warn` — one line, no behavior change
when the artifact exists.
- Local validation: `python3 -c "yaml.safe_load(...)`` — YAML parses;
diff is one added line.

Tracked as P0 row `cifix-16770` in the fleet program todo.
@christian-byrne
christian-byrne marked this pull request as ready for review September 3, 2026 19:36

@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.

Reviewed the current diff and found no blocking issues.

@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.

The durable-intent direction addresses the reproduced race, but migration and autogrow semantics need definition before implementation. The ADR can then be tightened by deleting the pending Decider field and glossary, linking A7, A18, and the KA invariants at first use, and replacing materialize/dematerialize with add to/remove from links. Keep the test matrix, but merge its overlapping race and re-add cases.

Comment on lines +66 to +70
This adds a root map, so `SCHEMA_VERSION` must move from 2 to 3 (KA-11). The
host-owned v2 → v3 migration seeds one connect-intent entry for every live v2
`links` tuple, using its A18 `("link", normalized_id)` stamp and the current
destination-input stamp. A malformed live tuple or missing authority fails
closed rather than inventing ordering metadata.

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 migration cannot handle ordinary v2 documents minted with existing links. mint() copies tuples into links but creates no A18 link stamp or destination-input stamp, so valid imported workflows would hit this missing-authority refusal. Please define baseline intent and eligibility metadata for imported links, and reserve refusal for malformed tuples.

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.

Updated in 0fa26a3: migration now classifies imported links deterministically, preserves any complete modern authority independently, and supplies an out-of-band imported baseline wherever stamps are absent. Missing stamps no longer fail migration or fabricate op ordering; only malformed or incoherent tuples are refused. mint() seeds the same baseline directly.

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.

Tracked as FE-2697. The PR merged with this thread unresolved, so the finding is carried in Linear rather than lost here. Filed automatically; close the ticket if the finding is no longer true at main.

Comment on lines +34 to +45
Each `__link_state` entry is one of:

1. **Connect intent:** the complete normalized A18 link tuple, its winning
link-identity stamp, and the destination-input authority that admitted it.
2. **Removal tombstone:** a terminal explicit-removal marker for a link id.

The transition rules are:

- A winning `connect` stores or replaces connect intent after the existing A18
link-identity and destination-input gates pass. It materializes the tuple
only while both endpoint nodes exist and the destination authority still
owns its input.

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 state shape does not cover ordinary autogrow links. Autogrow is deliberately ungated: it has no destination-input register that admits or continues to own the link. Please model eligibility by connect kind, covering concrete input, promoted input, and autogrow separately, including how each kind is retired and restored.

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.

Updated in 0fa26a3: eligibility is now a three-kind union. Concrete and promoted intents retain their distinct input-register authorities; autogrow retains grow_id plus its request or imported slot descriptor and explicitly has no destination-input authority. The table defines retirement and endpoint-delete/re-add restoration for each kind, including kind-aware disconnects.

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.

Tracked as FE-2698. The PR merged with this thread unresolved, so the finding is carried in Linear rather than lost here. Filed automatically; close the ticket if the finding is no longer true at main.

Comment on lines +57 to +58
- `clear` follows the same node-delete dematerialization rule and writes
tombstones for explicitly removed links.

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.

ClearOp carries only removed_nodes; it has no explicit link list from which to write these tombstones. Please remove the tombstone clause and state that clear only removes live tuples incident to nodes whose presence deletion wins. Permanent severance would require changing the operation vocabulary.

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.

Updated in 0fa26a3: clear now writes no link tombstones. It removes a live incident tuple only when an endpoint's node-presence deletion wins, retains the intent for a later re-add, and states that permanent severance would require a vocabulary change carrying explicit link IDs.

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.

Tracked as FE-2699. The PR merged with this thread unresolved, so the finding is carried in Linear rather than lost here. Filed automatically; close the ticket if the finding is no longer true at main.

@vercel

vercel Bot commented Sep 4, 2026

Copy link
Copy Markdown

Deployment failed for project comfy-home-v1 with the following error:

You don't have permission to create a Preview Deployment for this Vercel project: comfy-home-v1.

View Documentation: https://vercel.com/docs/accounts/team-members-and-roles

@christian-byrne

Copy link
Copy Markdown
Contributor Author

pr-shepherd cross-reference, no stage advanced here.

This PR's stacked child #16866 rewrites the same ADR, ADR-022-durable-link-intent.md, to the opposite decision: it reuses the existing A18 rows in __stamps and keeps SCHEMA_VERSION at 2, where this PR introduces a schema-v3 __link_state root with a v2 to v3 migration. Each ADR now lists the other design under "Rejected alternatives", so the child cannot be rebased onto this branch without someone picking the winner. I stopped rather than resolve it and escalated to blocked-on-christian #448.

Flagging it here because this PR is the approved side and would otherwise merge with the collision unnoticed: whichever design wins, both ADR copies need reconciling in one commit, and the loser's design should be recorded in the survivor's "Rejected alternatives" with the reasoning.

@christian-byrne

Copy link
Copy Markdown
Contributor Author

Design and six human review records preserved in standalone replacement PR 196. The proposal remains Proposed; runtime recovery is separate. Frontend relocation stays deferred. This source PR and its review history remain intact; historical approval does not transfer.

@vercel

vercel Bot commented Sep 21, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated
billing-web Ignored Ignored Sep 21, 2026 9:30pm UTC

Request Review

@datadog-official

datadog-official Bot commented Sep 22, 2026 •

Copy link
Copy Markdown

Pipelines

This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 92f770a | Docs | View more details | Give us feedback!

@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: superseded

All three findings from the prior review are addressed: migration now defines an imported baseline, eligibility is kind-specific for concrete, promoted, and autogrow links, and clear no longer claims to write link tombstones. The ADR is byte-identical to the copy merged in Comfy-Org/comfy-multi-player#196, so this frontend relocation PR should be closed rather than merged.

Local checks passed: typecheck, changed-file ESLint, format check, and the focused website test (17 tests). Type-aware Oxlint completed with 0 errors and 91 pre-existing warnings outside the changed files. CI on this head is green aside from expected skipped jobs.

it.for(['typescript', 'python', 'http'] as const)(
'builds the %s snippet from the current values',
(language) => {
it.for([

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.

P3: This snapshot-maintenance change is unrelated to the CRDT ADR and remains unique to this superseded branch. Please move commit 92f770a9 to its own PR if the cleanup is still needed, rather than carrying it in a documentation relocation PR.

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.

Tracked as FE-2700. The PR merged with this thread unresolved, so the finding is carried in Linear rather than lost here. Filed automatically; close the ticket if the finding is no longer true at main.

@christian-byrne
christian-byrne merged commit d3d8d5f into christian-byrne/ecw-106-comfy-multi-player-workspace Sep 22, 2026
83 of 85 checks passed
@christian-byrne
christian-byrne deleted the christian-byrne/cmp-delete-link-scope-1 branch September 22, 2026 07:05
@DrJKL DrJKL added 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 agent-test-only Agent tests, fixtures and test support only; no production changes agent-test-unit Touches Agent-related unit/component tests or their support agent-website Agent product pages or promotion on the Comfy website labels Sep 24, 2026
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 agent-test-only Agent tests, fixtures and test support only; no production changes agent-test-unit Touches Agent-related unit/component tests or their support agent-website Agent product pages or promotion on the Comfy website flag-exempt 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