Repository navigation
docs(release): W4.3 release notes and running-guide roll-up (W4-R3) - #1014
Conversation
Copy the release note of each W4.3 source PR into docs/releases/UNRELEASED.md. The text of each note is verbatim. Each section uses the title of its issue as the heading. The W4-E4c note replaces the section "Startup proposer preparation ends when the orchestrator returns". It also replaces the paragraph that starts "`prepare_beacon_proposer` and `register_validator` run on their own task from". This commit applies the two replacements in place. Add the W4.3 migration list. W4.3 has no breaking change. The list names each behavior change and the operator action. No source PR has a running-guide delta. Thus docs/running-guide.md does not change. Refs #872
Coverage ReportTotal: 94.69% (140569 / 148449 lines)
|
rootwarp
left a comment
There was a problem hiding this comment.
PR #1014 (W4-R3 / #872) — Harper Formal R1
Overall verdict: REQUEST_CHANGES (4 BLOCKING, 6 NIT). The 13 source notes match their PR bodies word for word. Both W4-E4c in-place replacements are correct and remove only the specified text. The W4.3 migration list has four operator-alert errors. The four stale source notes that W4-E6a left behind are known and deferred to W4-R4 (#897). They are not findings.
- Head:
7963180bd95955c622e7f9731457a217febfa454(re-checked at FINAL againstgh pr view 1014and the review worktree; unchanged) - Tree:
57ea2086b9352e60dfccf1487c68795830132af0 - Develop / parent:
920a7afacce843426a54f719a198c5bc886a07e4— 1 ahead / 0 behind. Live develop stayed at this SHA during the review. - Branch
docs/w4-r3-872. DRAFT, MERGEABLE, OPEN. One signed commit sits directly on develop. This is the expected R1 shape. It is not a finding. Author = committer = Joonkyo Kim<rootwarp@gmail.com>. The commit has a Good "git" signature. Authored and committed 2026-11-19 13:02:10 KST (Asia/Seoul).
Diff versus the assigned parent: 1 file, docs/releases/UNRELEASED.md, +74/−7. No production code and no Cargo.lock change.
This review used one Codex run: gpt-6.2-sol with model_reasoning_effort=high. The wrapper started at 2026-11-19 13:09:24 KST (Asia/Seoul) and exited 0 at 13:20:34 KST.
BLOCKING
B1 — The batch-size text omits a value of 0
docs/releases/UNRELEASED.md:1187 says the process sends registrations in batches of validator_registration_batch_size. BuilderService::send_batches treats 0 as “send all registrations in one batch.” An operator who set 0 needs that behavior when they check relay load.
Rewrite: “A positive validator_registration_batch_size sets the maximum number of registrations per batch. A value of 0 sends all registrations in one batch. validator_registration_batch_delay sets the delay in milliseconds between batches. The defaults are 500 registrations and 500 ms. Before you upgrade, check both values if you use a value that differs from its default.”
Evidence: crates/builder/src/service.rs:368–395.
B2 — The unfinished-step alert can hide other failures
Line 1190 says a key that waits for activation causes this WARN once per epoch, and “An alert on this WARN must not fail for a key that waits for activation.” The WARN combines all unfinished steps in one record (abandoned_steps and last_outcomes). The same line can also name a failed step. The instruction gives no condition for an alert.
Rewrite: “When the runner starts a later epoch, it logs one WARN if the previous epoch has unfinished steps. Match epoch-boundary steps did not finish before the epoch ended. Check abandoned_steps and last_outcomes. If PrepareProposers is NotReady, check for keys that are pending activation. Keep alerts for failed steps and other unfinished steps.”
Evidence: crates/rvc/src/orchestrator/epoch_boundary.rs:343–357.
B3 — Revalidation uses a different WARN
Line 1191 says index resolver get_validators failed; retrying at the next slot shows each failed get_validators call. After a revocation, revalidate_at logs index resolver revalidation failed; indices stay hidden; retrying at the next slot. An alert that matches only the documented message misses those failures.
Rewrite: “For a failed lookup of unresolved indices, match index resolver get_validators failed; retrying at the next slot. After revocation, match index resolver revalidation failed; indices stay hidden; retrying at the next slot for a failed revalidation. If doppelganger detection is off, a failed startup lookup logs validator index resolution failed at boot; duties stay empty until the index resolver succeeds.”
Evidence: crates/rvc/src/index_resolver.rs:307–314 and :357–378. Boot WARN: crates/rvc/src/bootstrap/enablement.rs:174.
B4 — The liveness WARN is not one line in every epoch
Line 1192 says "liveness query failed" is a WARN one time in each epoch and that an alert that counts this WARN gets one line in each epoch. The code emits a WARN only for the first failed query in a tick epoch. An epoch with no failed query has zero such warnings. Later failures in the same tick epoch are at DEBUG.
Rewrite: “For liveness failures, match the message prefix liveness query failed. The first failed query in each tick epoch logs a WARN. Each subsequent failed query in that tick epoch logs at DEBUG. A tick epoch with no failed query has zero such warnings.”
Evidence: crates/rvc/src/liveness_loop.rs:535–564.
NIT
N1 — Shorten the migration introduction and the WARN list headings
Lines 1183–1189 use “breaking change,” “changes can change,” and one long WARN heading line. The meaning is clear. Concrete rewrites are in pr1014-r1/scratch/harper-logs/ste-recheck.md and in the Codex report.
N2 — Name the operator and the task in the no-action list
Lines 1194–1198 use “No operator action,” “gets its own duties,” and “this time.” The meaning is clear. Concrete rewrites are in the STE record.
N3 — Name the boot epoch check
Line 1200 uses “A doppelganger boot that moves into epoch 1.” The meaning is clear. A concrete rewrite is in the STE record.
N4 — Rewrite the live PR body summary, grep list, decisions, and size text
Words such as “docs-only roll-up,” “running-guide delta,” “verbatim,” and “gross size” have a clear meaning. Concrete rewrites are in the STE record. The grep counts, the decisions, and the size +74/−7 match the pinned diff.
N5 — Rewrite the commit message
“Verbatim,” “applies the two replacements,” and “running-guide delta” have a clear meaning. A concrete rewrite is in the STE record.
N6 — Add the pre-PR self-check to the PR body
AGENTS.md requires the four checklist items in the body. The Gates section already gives some of the evidence. Add the four items and the result for each: no new tests; no measurement claims; the recorded search matches and zero matches for the two removed strings; no new or changed signing-root tests.
Known or deferred (not findings)
Issue #872 requires the source notes word for word. W4-E6a merged first, so four notes do not match the current code. Ash keeps them as written. W4-R4 (#897) corrects them. This review does not block on them:
- W4-E5, PR #959: the note gives a fixed 10 s limit. The current budget adds one batch delay for each batch after the first.
- W4-E4c, PR #994: the note says a refused batch returns success. The current path reports an error.
- W4-E7d, PR #986: the note describes W4-E7e as future work. W4-E7e merged in #1000.
- W4-E2b, PR #969: the note lists four steps. The runner now has more steps.
Tests and CI
An independent comparison of the 13 live ## Release note sections against docs/releases/UNRELEASED.md found no byte differences in the copied notes. Both W4-E4c replacements from #994 sit at their specified locations and remove only the specified text. Five source PRs declare no change to the running guide. Eight have no running-guide section. docs/running-guide.md is unchanged.
cargo nextest run -p rvc-architecture-tests under rustc 1.99.1 (58cf8f9c3 2026-10-13, commit 58cf8f9c35b355199727627d07ae34a4e2846d67): 409 passed, 0 skipped, exit 0, including docs_freshness 9/9. The shared 1.99.1 rustup path was missing, so Harper used a private official 1.99.1 toolchain and did not change /home/box/.rustup. This review ran no mutants, because the PR changes only documentation.
Same-head CI run 44455857801 is success on 7963180bd95955c622e7f9731457a217febfa454. Harper retrieved the metadata and logs through bash -ic with gh, and rechecked them at FINAL. The Test job reports 7,781 passed, one slow, and ten skipped, in 136.581 s, at 2026-11-19 13:13:01 KST (Asia/Seoul) (job 135330573642). Rustdoc tests: 29 passed, 0 failed, 6 ignored. The Check job runs fmt, workspace Clippy, and cargo deny (job 135330573340). Architecture Gates (job 135330573235), Coverage, Scripts, Secret Scan, Spec Vectors, Trace continuity, and GitGuardian also pass. All nine required checks pass. CI uses rustc 1.100.0. This review does not rerun the full workspace suite or Clippy locally.
Every cargo command used /workspace/rvc/bin/locked-cargo, flock -x /tmp/harper-build.lock, rustc 1.99.1, CARGO_INCREMENTAL=0, PROTOC=/usr/local/bin/protoc, CARGO_BUILD_JOBS=1, and private /tmp/harper-pr1014-r1-target. The review did not use /workspace/rvc/target-shared. The private target is absent after the run. One cargo job ran at a time. Harper waited for the shared lock and left other processes alone. The worktree is clean at the pinned head and tree. No comment, review, push, merge, or source fix was made. Harper verified the pins, the verbatim notes, the four migration defects, the deferred stale notes, the architecture tests, and the CI counts, then wrote this FINAL.
Copies: lead/handoff/pr1014, pr1014-r1/out, /home/box/rvc-review-archive/pr1014. First line <!-- prepared by Harper for Ash -->. Not posted. Did not message Ash.
Correct four operator steps in the W4.3 migration section: - A batch size of 0 sends all registrations in one batch. - The unfinished-step WARN can name a failed step. Keep alerts for failed steps. - After a revocation, a failed revalidation logs its own WARN. - The liveness WARN shows only for the first failed query in a tick epoch. Later failures in that epoch log at DEBUG. This commit also changes the wording of the section for ASD-STE100. About the first commit (7963180): it copies each source note word for word. It replaces the old section and paragraph at their existing locations. It adds the W4.3 migration steps. Existing configurations, data files, and API clients work with W4.3. The source PRs require no changes to docs/running-guide.md. This commit does not change the copied notes. Refs #872
rootwarp
left a comment
There was a problem hiding this comment.
PR #1014 (W4-R3 / #872) — Harper Formal fix1 recheck
Overall verdict: CLEARED. B1 through B4 PASS. N1 through N6 PASS. The reviewed commit message stays, as expected for an additive fix.
- Head:
49d4cacdafe597490dd736da466eda660722c57a(re-checked at FINAL againstgh pr view 1014and the review worktree; unchanged) - Tree:
38b362e7abf21b35c109f58da36097e625f76284 - Develop / parent:
920a7afacce843426a54f719a198c5bc886a07e4— 2 ahead / 0 behind. Live develop stayed at this SHA during the recheck. - Reviewed R1 head (ancestor):
7963180bd95955c622e7f9731457a217febfa454. That commit did not change. One additive fix commit sits on it. This reviewed-plus-additive fast-forward shape is expected. It is not a finding. - Branch
docs/w4-r3-872. DRAFT, MERGEABLE, OPEN.
Fix1 diff versus the reviewed head: 1 file, docs/releases/UNRELEASED.md, +12/−13, migration subsection only. Total PR versus develop: +73/−7. The cited production files have no diff against develop.
This recheck used one Codex run: gpt-6.2-sol with model_reasoning_effort=high. The wrapper started at 2026-11-19 13:31:47 KST (Asia/Seoul) and exited 0 at 13:38:39 KST. The recheck covers only R1 findings B1–B4 and N1–N6. It adds no new findings.
Recheck results
B1 — PASS
Line 1187 now says a positive validator_registration_batch_size is the maximum number of registrations per batch, and a value of 0 sends all registrations in one batch. It also gives the delay setting and the defaults of 500 and 500 ms. BuilderService::send_batches uses total_count when registration_batch_size == 0 (crates/builder/src/service.rs:368–385).
B2 — PASS
Line 1190 now says: match epoch-boundary steps did not finish before the epoch ended; check abandoned_steps and last_outcomes; if PrepareProposers is NotReady, check for keys that are pending activation; keep alerts for failed steps and other unfinished steps. That matches warn_unfinished in crates/rvc/src/orchestrator/epoch_boundary.rs:343–357.
B3 — PASS
Line 1191 now names all three messages: index resolver get_validators failed; retrying at the next slot for a failed lookup of unresolved indices; index resolver revalidation failed; indices stay hidden; retrying at the next slot after revocation; and validator index resolution failed at boot; duties stay empty until the index resolver succeeds when doppelganger detection is off. These match index_resolver.rs:307–314 and :357–378, and bootstrap/enablement.rs:148–176.
B4 — PASS
Line 1192 now says to match the prefix liveness query failed. The first failed query in each tick epoch logs a WARN. Later failures in that tick epoch log at DEBUG. A tick epoch with no failed query logs no such WARN. That matches crates/rvc/src/liveness_loop.rs:519–564.
N1 — PASS
The introduction and the trace and WARN instructions use the R1 rewrites. Harper accepts the word “migration” in the heading “W4.3 migration: changes and steps for operators.” The W4.1 and W4.2 headings use the same word, and issue #872 uses “migration subsection” in its acceptance criterion.
N2 — PASS
The no-action list now starts with “Operators do not need to make changes for the items below.” It names the epoch-boundary task, the processed-slot retry, and a usual revalidation interval of one slot.
N3 — PASS
Line 1199 now says: if startup crosses from epoch 0 into epoch 1, rvc keeps the keys in the monitoring window. The liveness loop skips not-live decrements if the epoch changes before it applies the query results.
N4 — PASS
The live PR body uses the R1 wording for the summary, the grep list, the decisions, and the size. It records 73 added lines and 7 removed lines, for a total of 80 lines, which matches the pinned diff versus develop.
N5 — PASS
The fix1 commit message uses the R1 replacement wording and describes the first commit in those terms. The reviewed 7963180b message stays. That is the expected additive lineage. It is not a FAIL.
N6 — PASS
The live PR body includes the four AGENTS.md items with a result for each: no new tests; no measurement claims; zero matches for both removed strings; no new or changed signing-root or hash_tree_root tests.
Tests and CI
This recheck ran no local cargo command, no mutants, and no full workspace suite. Harper compared the migration text with the code on the pinned head and confirmed that those source files match develop.
Same-head CI run 44458464692 is success on 49d4cacdafe597490dd736da466eda660722c57a. Harper retrieved the metadata and logs through bash -ic with gh, and rechecked them at FINAL. The Test job reports 7,781 passed, one slow, and ten skipped, in 212.410 s, at 2026-11-19 13:36:48 KST (Asia/Seoul) (job 135339174308). Rustdoc tests: 29 passed, 0 failed, 6 ignored. The Check job includes workspace Clippy (job 135339174360). Architecture Gates (job 135339174496), Coverage, Scripts, Secret Scan, Spec Vectors, Trace continuity, and GitGuardian also pass. All nine required checks pass. CI uses rustc 1.100.0.
The worktree is clean at the pinned head and tree. No comment, review, push, merge, or source fix was made. Harper verified the pins, the four code comparisons, the STE and self-check items, and the CI counts, then wrote this FINAL.
Copies: lead/handoff/pr1014, pr1014-fix1/out, /home/box/rvc-review-archive/pr1014. First line <!-- prepared by Harper for Ash -->. Not posted. Did not message Ash.
Summary
This PR collects the W4.3 release notes. It copies the
## Release notesection of each of the 13 W4.3 source PRs intodocs/releases/UNRELEASED.md, word for word. It adds the migration steps.Closes #872
Refs #651
Refs #819
develop@920a7afacce843426a54f719a198c5bc886a07e4.49d4cacdafe597490dd736da466eda660722c57a(commit 17963180b, fix1 commit49d4cacd).docs/releases/UNRELEASED.mdonly.docs/running-guide.mddoes not change. The source PRs require no changes to the running guide.Sources
These are the 13 PRs that the #872 header lists.
## Release note## Running-guide delta90d7a2a33a0c50e0865d44c2fdc9f16e09227f4ddc7760289a531c63480f2c62031a9f9c6950c429f65ce003778ea1f6e110f201e356eca4dbfc5109d421f4cbd4ef98b8674f5f298f14fe1b8a46322d6a748049ba46162b6a555d7e70dba437dd0bc4793492a7824ea9a5e374fceb5e0f21301ca6ecfce744031da49f8eba3679371565b01edd06b6740680c197dabb3544d2106565f65ff827aae042dcd3894d7cb549977f6ec7299935eaf87cae3ce22bd01a2ca52a2a231f6dd73994f2087610947b7eca4a64e7c89850e5c8e2e8e6ad65e61a7239a8c74dda8db412d6482dced980eacb6304f80e2070f870ec8da386f2db55de8662933f1102db906dc62669e12ePlacement in
docs/releases/UNRELEASED.md:prepare_beacon_proposerandregister_validatorrun on their own task from" in place.W4.3 PRs that are not sources (#872 does not list them):
Grep list
Each row shows a search string and the number of matching lines in
docs/releases/UNRELEASED.mdat the head (grep -cF). The first 17 strings come from the release-note AC of the source issues. The next 2 strings must have zero matches. The last 4 strings show the fix1 corrections.validator_registration_batch_sizeindex resolverevery slotfirst processed slotrevoked beacon nodecached dutiesfetches its own dutiesretries at the next slotvalidator indicesre-checked after a beacon node is revokeddid not finish before the epoch endedno validator index yetre-checked after the boot readsunder the machine locklogged once per epochepoch-boundary taskdefault fee recipientrun on their own task fromStartup proposer preparation ends when the orchestrator returnsA value of 0 sends all registrations in one batchKeep alerts for failed stepsindex resolver revalidation failed; indices stay hidden; retrying at the next slotEach later failed query in that tick epoch logs at DEBUGNo source issue requires a change to the running guide. Thus no search string applies to
docs/running-guide.md.Decisions (intentional)
Gaps and conflicts
No source PR is without a release note.
Conflicts with the current code at
920a7afacce843426a54f719a198c5bc886a07e4. W4-E6a (W4.4) merged before this PR. This PR copies each note word for word, as #872 requires. Ash keeps these notes as written. W4-R4 (#897) corrects these sentences:503d943f). The round budget is nowBuilderService::registration_step_timeout(): 10 s plus one batch delay for each batch after the first.503d943f).Conflicts between the brief and the issue:
develop...HEAD. The localdevelopbranch is old (64c8ccb7). The gates useorigin/develop...HEAD, andorigin/developis the base.Fix log
49d4cacd), for Harper review 5969286908. This commit corrects four migration steps against the code at the base (B1–B4): a batch size of 0, the unfinished-step WARN, the revalidation WARN, and the liveness WARN. It also changes the migration wording (N1–N3). This PR body has new wording (N4) and the self-check (N6). The fix1 commit message has the STE wording for the first commit (N5), because the first commit stays as it is. The copied notes do not change.Gates
Evidence on the box:
/workspace/rvc/run-872/out/fix1/gates.md. All gates ran on the head49d4cacdafe597490dd736da466eda660722c57a.cargo nextest run -p rvc-architecture-tests --no-fail-fast(privateCARGO_TARGET_DIR, rustc 1.99.0)docs_freshness9/9,gitleaks_allow_scope1/1git diff --stat origin/develop...HEADdocs/releases/UNRELEASED.mdscripts/gitleaks_range_scan.sh(gitleaks 8.21.2, strict config) on920a7afa..HEAD--no-gitondocs/releases(strict config)verify.py)Self-check (AGENTS.md)
hash_tree_roottest.Size
git diff --shortstat origin/develop...HEAD: 1 file changed, 73 insertions(+), 7 deletions(-). The diff has 73 added lines and 7 removed lines, for a total of 80 lines. The plan estimate is 140 lines (210 after calibration).