docs(design): refresh admin dashboard status — P2 + P4 shipped

[bootjp]

Summary

State-refresh of docs/design/2026_04_24_partial_admin_dashboard.md now that all four phases of the original P1–P4 plan have shipped.

Phase	Was	Now
P1	shipped	shipped (no change)
P2	partial — read-only #658 only	shipped (+ #669 writes + #673 forwarding)
P3	shipped	shipped (no change)
P4	mostly	shipped (+ operator doc #674, deployment runbook #669, script wiring #669+#678)

Also added the AdminDeleteBucket TOCTOU to Outstanding open items — coderabbitai flagged it during PR #669 review (pre-existing race, s3.go:deleteBucket inherits the same shape; recorded as a code comment on AdminDeleteBucket for the future fix).

Doc stays at _partial_ rather than promoting to _implemented_ because two outstanding items remain: AdminForward acceptance criterion 5 (rolling-upgrade flag, explicitly deferred at design time) and the new TOCTOU. Updated the closing rename trigger to cover both.

Test plan

• No design changes — this is a state refresh
• Status table entries cross-checked against the merge commits on main
• AdminDeleteBucket TOCTOU description matches the code comment in adapter/s3_admin.go and the operator-side workaround in docs/admin_deployment.md

[coderabbitai]

Warning

Rate limit exceeded

@bootjp has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 47 minutes and 48 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: dd4c099d-de3c-4cc9-aeda-913cce1a5d65

📥 Commits

Reviewing files that changed from the base of the PR and between a3d312f and fb39e3c.

📒 Files selected for processing (1)

• docs/design/2026_04_24_partial_admin_dashboard.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/admin-design-status-update

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[bootjp]

@claude review

[claude]

Claude finished @bootjp's task in 1m 29s —— View job

---

Review of docs/design/2026_04_24_partial_admin_dashboard.md

• Read the changed file
• Cross-check status claims against PR description
• Review TOCTOU entry accuracy
• Check lifecycle marker and closing conditions
• Post review findings

---

Overall: The status refresh is accurate and well-structured. One inaccuracy in the TOCTOU description to fix; everything else looks good.

---

Finding: stale cross-reference in TOCTOU entry

Line 20 of the updated doc says:

the operator-side workaround documented in docs/admin_deployment.md is to pause writes against the target bucket before issuing the admin delete.

After reading all 374 lines of docs/admin_deployment.md, there is no such section. The pause-writes workaround is currently only in the code comment at adapter/s3_admin.go:383:

// Operators concerned about the orphan window today should pause writes against
// the target bucket before issuing the admin delete.

The design doc is pointing to a location that doesn't contain what it claims. Either:

• (a) Add a "Known limitations — AdminDeleteBucket orphan race" subsection to docs/admin_deployment.md (probably §5.6), or
• (b) Fix the reference in the design doc to point at the code comment rather than the deployment doc.

Fix this →

---

What looks good

• Status table accuracy — P2 (shipped via admin: read-only S3 bucket endpoints (P2 slice 1) #658 + admin: S3 bucket write endpoints (P2 slice 2a) #669 + admin: AdminForward integration for S3 admin ops (P2 slice 2b) #673) and P4 (shipped via docs: add admin dashboard operator guide (P4) #674 / admin: S3 bucket write endpoints (P2 slice 2a) #669 / scripts: forward ADMIN_* env vars to remote SSH heredoc (follow-up to #669) #678) are correctly marked. The granular breakdown in the P4 "Landed via" column is a nice improvement over the previous vague "mostly shipped" note.
• TOCTOU technical description — The race description in the design doc accurately mirrors the code comment in adapter/s3_admin.go:362-384. The two proposed fixes (a: BucketGenerationKey as OCC token, b: ReadRanges in OperationGroup) are consistent with the actual OCC architecture (kv/lock_resolver.go).
• Lifecycle marker rationale — Keeping _partial_ because two items remain (criterion 5 + TOCTOU) is correct. The closing rename trigger on line 24 is updated to cover both, which matches the doc's own outstanding-items list.
• Status header — The new opening sentence clearly summarises the current state for a quick reader.

---

Minor nit (take or leave): the P4 row's "Landed via" now spans two PRs for some items (#674 / #669 / #678) but the separator is / while P2 uses +. Using consistent separators throughout the table (+ everywhere, as in P1 and P2) would be cleaner.

[gemini-code-assist]

Code Review

This pull request updates the elastickv Admin Dashboard design document to reflect that all implementation phases (P1–P4) have now shipped, while maintaining its 'partial' status due to deferred items. Specifically, it adds documentation for a TOCTOU race condition in AdminDeleteBucket that can lead to orphaned objects. Review feedback suggested refining the description of this issue to be more objective, warned of performance bottlenecks in one of the proposed fixes, and requested additional mitigation strategies for the operational risks associated with the current workaround.

[bootjp]

@claude review

[claude]

Claude finished @bootjp's task in 2m 48s —— View job

---

Review of PR #688 — docs(design): refresh admin dashboard status

• Read changed file (docs/design/2026_04_24_partial_admin_dashboard.md)
• Check cross-references and status claims
• Review TOCTOU entry accuracy
• Review lifecycle marker and closing conditions
• Post final review

---

Overall: The status refresh is accurate and the doc structure is sound. Three issues worth recording for the next update.

---

Finding 1: Test plan references a non-existent section in docs/admin_deployment.md

The PR test plan claims:

AdminDeleteBucket TOCTOU description matches the code comment in adapter/s3_admin.go and the operator-side workaround in docs/admin_deployment.md

docs/admin_deployment.md (374 lines) has no mention of TOCTOU, orphan race, AdminDeleteBucket, or the pause-writes workaround. The workaround is only documented in the code comment at adapter/s3_admin.go:383.

The design doc text at line 20 doesn't directly claim admin_deployment.md contains it — that's fine. But the test plan check was wrong at merge time. For completeness, adding a "Known Limitations" subsection to docs/admin_deployment.md would make the cross-reference valid and give operators a runtime-visible place to find the workaround.

Fix this →

---

Finding 2: Code comment at adapter/s3_admin.go:362 violates CLAUDE.md conventions

The comment reads:

// Known orphan-race limitation (coderabbitai 🔴 / 🟠 on PR #669):

CLAUDE.md: "Don't reference the current task, fix, or callers… since those belong in the PR description and rot as the codebase evolves."

The coderabbitai attribution and PR #669 reference will become meaningless noise. The comment body already describes the race precisely — the parenthetical attribution adds nothing technically.

Suggested fix:

// Known orphan-race limitation (pre-existing, shared with s3.go:deleteBucket):

Fix this →

---

Finding 3: "bridge mode" suggestion is imprecise for a bucket-scoped operation

The TOCTOU outstanding item ends with:

the design should investigate mitigation strategies like a temporary proxy or bridge mode to avoid service interruption during this state.

"Service interruption" and "bridge mode" imply cluster-wide impact. The actual scope of the workaround is narrower: pause writes to a single target bucket, not the whole service. A proxy/bridge mode would be overkill and potentially misleading to operators reading this as a future design direction.

Consider: "Future work should consider either (a) or (b) above to remove the need for a write-pause; the workaround today is bucket-scoped and does not require any cluster-level intervention."

---

What looks good

• Status table accuracy ✅ — P2 (shipped via admin: read-only S3 bucket endpoints (P2 slice 1) #658 + admin: S3 bucket write endpoints (P2 slice 2a) #669 + admin: AdminForward integration for S3 admin ops (P2 slice 2b) #673) and P4 (shipped via docs: add admin dashboard operator guide (P4) #674 / admin: S3 bucket write endpoints (P2 slice 2a) #669 / scripts: forward ADMIN_* env vars to remote SSH heredoc (follow-up to #669) #678) match the referenced PRs.
• TOCTOU technical description ✅ — The race description in the design doc (readTS scan vs. commitTS write, OCC only inspects ReadKeys not ReadRanges) accurately mirrors the code comment at adapter/s3_admin.go:362–384. The s3.go:deleteBucket at line 638 does have the same shape (confirmed by reading the code).
• Lifecycle marker ✅ — Staying at _partial_ with two outstanding items is correct. The closing rename trigger on line 24 covers both.
• Status header ✅ — The new opening paragraph is a good quick-read summary for future reviewers.

---

Minor nit: AdminForward outstanding item uses **bold** but the TOCTOU item doesn't — inconsistent formatting in the same list. Also the P4 row uses / as separator while P2 uses +.