Skip to content

docs: clarify renderer architecture rules - #15376

Closed
benjcooley wants to merge 1 commit into
mainfrom
benjcooley/clarify-renderer-architecture
Closed

benjcooley wants to merge 1 commit into
mainfrom
benjcooley/clarify-renderer-architecture

Conversation

@benjcooley

Copy link
Copy Markdown
Collaborator

Summary

Clarifies reusable renderer/entity architecture constraints surfaced while addressing viewport-culling review feedback. Split from #15030 to keep that runtime PR focused.

Changes

  • What: Documents one spatial authority, signal-driven updates, renderer lifecycle ownership, conservative geometry optimizations, and separation of decisions from scheduling.

Review Focus

Confirm these rules accurately reflect ADR 0003/0008 and the intended renderer/store boundaries.

Screenshots (if applicable)

Not applicable.

@benjcooley
benjcooley requested a review from a team August 17, 2026 20:26
@dosubot dosubot Bot added the size:XS This PR changes 0-9 lines, ignoring generated files. label Aug 17, 2026
@github-actions github-actions Bot added the risk:R2 PR risk grade (advisory shadow check; grader-owned) label Aug 17, 2026
@benjcooley
benjcooley requested a review from DrJKL August 17, 2026 20:27
@coderabbitai

coderabbitai Bot commented Aug 17, 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: Pro Plus

Run ID: d92027cb-2860-472b-860d-71fe4cf0a465

📥 Commits

Reviewing files that changed from the base of the PR and between 4cd7e00 and 2b4c4c3.

📒 Files selected for processing (1)
  • AGENTS.md

Included review availability: Your plan includes up to 4 reviews per rolling hour; 3 remain after this review.


📝 Walkthrough

Walkthrough

AGENTS.md adds five architecture constraints for layout-store ownership, signal-based updates, renderer lifecycle state, conservative geometry optimization, and separation of visibility decisions from scheduling.

Changes

Architecture Constraints

Layer / File(s) Summary
Document architecture constraints
AGENTS.md
Adds constraints that keep layout spatial indexes owned by layoutStore, require signal-based consumer updates, keep renderer coordination state outside entity stores, use exact rendering for uncertain geometry, and separate visibility decisions from scheduling.

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

Merge Risk: ⚪ Minimal · up to 2b4c4

This documentation-only change introduces no actionable merge-blocking risk and is merge-ready after normal checks and review.

Suggested reviewers: christian-byrne

🚥 Pre-merge checks | ✅ 7
✅ Passed checks (7 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly describes the main change: documenting renderer architecture rules.
Description check ✅ Passed The description includes the required summary, changes, review focus, and screenshots sections with relevant information.
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 AGENTS.md, which is documentation and not under src/ or packages/. The check explicitly excludes documentation-only changes.
Website End-To-End Regression Coverage ✅ Passed The PR changes only AGENTS.md and no files under apps/website/src/ or apps/website/public/, so this check does not apply.
Adr Compliance For Entity/Litegraph Changes ✅ Passed The available changed-file metadata lists only AGENTS.md, which is outside the covered LiteGraph, ECS, and graph-entity paths.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch benjcooley/clarify-renderer-architecture

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

pull Bot pushed a commit to Penguinjanator/ComfyUI_frontend that referenced this pull request Aug 23, 2026
## The bug

`.github/workflows/ci-binary-size-validation.yaml` subscribes to the
`labeled` and `unlabeled`
pull_request event types:

```yaml
on:
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
```

So **any** label write starts a second binary-size run on the identical
commit, and
`cancel-in-progress` kills the one already in flight. A label change
cannot alter a bundle's
size, so there is nothing for the job to re-evaluate — the second run
just recomputes the same
answer and leaves a permanent `cancelled` check run behind on the
commit.

## Why it matters beyond wasted minutes

The cancelled check does not go away when the retry succeeds. Both check
runs stay attached to
the commit, so the commit's check rollup is `FAILURE` forever.

The PR risk grader reads that rollup. Its reversibility axis treats a
non-`SUCCESS` rollup as
`no_green_checks_tier`, which `.github/risk.json` sets to **R2** — so a
PR gets bumped to R2
because a label bot wrote a `size:*` label two seconds after CI started.

The chain, end to end:

1. `dosubot[bot]` writes a `size:*` label seconds after the PR opens or
is pushed to.
2. That `labeled` event re-triggers binary-size on the same commit;
`cancel-in-progress` cancels
   the in-flight run.
3. The commit now permanently carries a `binary-size / CANCELLED` check
run.
4. The grader counts `CANCELLED` as a failing check, so the rollup is
not `SUCCESS`, so
   reversibility is pinned at R2.

## Measured (re-verified for this PR, 2026-08-18)

| measure | value |
|---|---|
| binary-size runs, 30 days (created >= 2026-07-19) | 4,307 |
| ...concluded `cancelled` | **1,128 = 26.2%** |
| ...concluded `failure` | 39 = 0.9% |
| complete 2-day window (created >= 2026-08-16) | 819 runs |
| ...cancelled | 164 = 20.0% |
| cancels superseded by a later run on the **same head SHA** | **163 of
164 = 99.4%** |
| median gap to the superseding run | **2 s** (p25 0 s, p75 4 s) |
| distinct head SHAs in that window carrying **both** a `cancelled` and
a `success` run | 110 of 613 = **17.9%** |

Cancellations outrun real findings by roughly 29 to 1.

**Timed to the second on three live PRs** (label event → new run → prior
run cancelled):

- Comfy-Org#15413 — `size:XS` at 21:31:18Z → new run 21:31:20Z, prior run
(started 21:31:17Z) cancelled
- Comfy-Org#15414 — `size:L` at 21:35:47Z → new run 21:35:49Z, prior run
(21:35:45Z) cancelled
- Comfy-Org#15412 — `size:L` at 21:02:03Z → new run 21:02:06Z, prior run
(21:02:01Z) cancelled

**A settled rollup showing the consequence.** Commit `ce9ec9b4d0`
(Comfy-Org#15414, a `browser_tests/`-only
PR) — rollup state `FAILURE` over 85 contexts: 57 `SUCCESS`, 26
`SKIPPED`, and exactly one
failing-class context, `binary-size / CANCELLED`. That PR carries
`risk:R2`.

**Across the whole label population:** of the 112 PRs currently carrying
`risk:R2`, **17 (15.2%)
have a check rollup whose only failing-class context is `binary-size /
CANCELLED`** — Comfy-Org#14546,
Comfy-Org#15138, Comfy-Org#15173, Comfy-Org#15178, Comfy-Org#15261, Comfy-Org#15280, Comfy-Org#15307, Comfy-Org#15354, Comfy-Org#15371, Comfy-Org#15376,
Comfy-Org#15380, Comfy-Org#15388, Comfy-Org#15402,
Comfy-Org#15404, Comfy-Org#15410, Comfy-Org#15411, Comfy-Org#15414.

## Why removing the trigger is the right fix, and not the concurrency
group

Keying the concurrency group on `github.event.pull_request.head.sha`
does **not** help: a label
write happens on the identical commit, so it lands in the same group and
still cancels. The
re-trigger itself is what has to go.

`binary-size` is **not** a required check for merge — the `ProtectMain`
ruleset requires `test`,
`lint-and-format`, `e2e-status` and `website-e2e`, and `CLA Check`
requires `cla-assistant`.

## Trade-off, stated plainly

The `allow-large-binaries` bypass is read from
`github.event.pull_request.labels.*.name` at the
job `if:`. With `labeled` removed, applying that label no longer
re-evaluates the check
instantly — it takes effect on the next `synchronize`/`reopened`. That
costs nothing today:
**`allow-large-binaries` has been applied to 0 PRs, ever**, and the
check does not gate merge, so
a stale red never blocks anyone.

`scripts/cicd/check-binary-size.sh:165` prints "add the
'allow-large-binaries' label to the PR"
on failure; that advice still works, it just lands on the next push
rather than instantly. I have
deliberately not touched that file — happy to reword it in a follow-up
if a reviewer wants it.

## This PR demonstrates the fix on itself

`pull_request` workflow definitions are read from the PR head, so the
change is already live
here. Timeline:

- 22:50:13Z — PR opened
- 22:50:17Z — binary-size run `32194526247` starts
- 22:50:19Z — `dosubot[bot]` applies `size:XS`, **two seconds into the
run** — the exact pattern
  that cancels the run on every other PR

Result: **one** binary-size run on this commit, no second trigger, no
cancellation,
`binary-size pass 35s`. Compare Comfy-Org#15413 / Comfy-Org#15414 / Comfy-Org#15412 above, where
the same two-second label
write killed the in-flight run and left a permanent `CANCELLED` on the
commit.

## Scope

This is half the loop. The other half is grader-side: `CANCELLED` is
counted as a *failing*
check in `Comfy-Org/github-workflows`
(`scripts/pr-risk/grade-pr-risk.sh`), which is what turns a
cancelled run into an R2. That fix has **not shipped** and is not in
this PR. So this PR removes
the largest source of the cancellations but does not fully close the
loop — a binary-size run
cancelled for any other reason would still red the rollup.

No other change to the file.
@huang47 huang47 added the risk:high PR risk grade (advisory shadow check; grader-owned) label Sep 2, 2026 — with ChatGPT Codex Connector
@huang47 huang47 removed the risk:R2 PR risk grade (advisory shadow check; grader-owned) label Sep 2, 2026
@DrJKL DrJKL closed this Oct 27, 2026
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) size:XS This PR changes 0-9 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants