docs(status-page): operator steps to verify distributed reportability live #10

Merged

hibryda merged 2 commits from docs/distributed-reportability-verify-note into main 2026-06-03 11:51:52 +02:00

Conversation 2 Commits 2 Files changed 1 +2 -1

hibryda commented 2026-06-03 11:44:49 +02:00

Owner

Copy link

Small operator-facing doc note: the exact Redis keys to confirm the distributed-quorum reportability live (per-leg Quorum column hash, the PHASE_ORDER-mapped progress-line phase, and the ribbon tel* totals), plus a note that the in-engine arbiter is excluded from the ribbon fold to avoid double-counting.

Doc-only; no code change. (Also serves as the controlled trigger to confirm the just-deployed reportability end-to-end on a live distributed review.)

Small operator-facing doc note: the exact Redis keys to confirm the distributed-quorum reportability live (per-leg Quorum column hash, the PHASE_ORDER-mapped progress-line phase, and the ribbon `tel*` totals), plus a note that the in-engine arbiter is excluded from the ribbon fold to avoid double-counting. Doc-only; no code change. (Also serves as the controlled trigger to confirm the just-deployed reportability end-to-end on a live distributed review.)

hibryda added 1 commit 2026-06-03 11:44:49 +02:00

docs(status-page): operator steps to verify distributed reportability live ... 7c3cf0950a

Add the exact Redis keys for confirming the per-leg Quorum column, the
PHASE_ORDER-mapped progress-line phase, and the ribbon totals during a live
distributed review. Also note the arbiter is excluded from the ribbon fold
(already tapped in-engine) to prevent double-counting.

pr-reviewer-bot commented 2026-06-03 11:48:37 +02:00

Member

Copy link

Superseded by round 2.

Show previous round

hib-pr-reviewer review — PR #10 (hib/hib-pr-reviewer)

Round 1 — head 7c3cf0950aad, base main, trigger opened

TL;DR: CONDITIONAL_APPROVE — kept 2 agreed + verified minor findings (optional arbiter field presented as unconditional; missing LRANGE command); no blocking issues.

Summary

Arbitration Summary

Both reviewers independently flagged the same two issues on line 146 of docs/status-page.md. I verified both against source before keeping them.

Verification results:

1. arbiter optionality — src/types/quorum.ts line 87 confirms arbiter?: ArbiterSnapshot (optional). The module-level JSDoc (line 12) also annotates the hash schema as { a, b, arbiter? }. The new doc text "expect a/b/arbiter state fields" presents all three as unconditionally present. Confirmed — kept.

2. Missing LRANGE command — docs/forgejo-upgrade-runbook.md line 39 confirms bq:pr-review:active is a Redis List key queried as redis-cli LRANGE bq:pr-review:active 0 -1. The new doc text only names the key without the command. Confirmed — kept.

Severity reconciliation: A rated finding 2 as info, B as minor. The practical consequence (operator receives a WRONGTYPE error if they try GET or SMEMBERS) and the established pattern in the runbook both support minor. Promoted to minor to match B.

Kept 2 agreed + verified findings. Dropped 0.

Blast Radius

Single documentation file changed (docs/status-page.md, +2/-1). No code, no exported interfaces, no Redis key schema changes. Impact is limited to operators reading this runbook section.

BLAST_SCORE: 1/10

CI status (head 7c3cf0950aad)

Overall: ✓ success

3 checks: 3 pending

Check	State	Link
pr-reviewer CI / tsc --noEmit (pull_request)	⏳ pending	details
pr-reviewer CI / vitest (pull_request)	⏳ pending	details
pr-reviewer CI / tsc build (pull_request)	⏳ pending	details

Findings (2)

[MINOR] Verify step implies arbiter field is always present, but it is optional until arbitration begins

docs/status-page.md:146

src/types/quorum.ts line 87 defines arbiter?: ArbiterSnapshot (optional) and line 12's JSDoc annotates the hash schema as { a, b, arbiter? }. The field is written by Arbiter.run only after divergent legs trigger the arbiter phase. An operator running HGETALL <prefix>:pr-reviewer:phase:quorum:<jobId> during the parallel-leg phase will see only a and b — the current wording "expect a/b/arbiter state fields" gives no indication that two fields is healthy, risking a false alarm.

Suggested fix:

- (expect `a`/`b`/`arbiter` state fields)
+ (expect `a` + `b` fields; `arbiter` appears only after divergent legs trigger the arbiter phase)

[MINOR] Job-ID retrieval step names the key but omits the Redis command (LRANGE)

docs/status-page.md:146

Line 146 instructs operators to get <jobId> from `bq:pr-review:active` without specifying the retrieval command. bq:pr-review:active is a BullMQ List key — the correct command is LRANGE bq:pr-review:active 0 -1. An operator who tries GET or SMEMBERS will receive a Redis WRONGTYPE error. docs/forgejo-upgrade-runbook.md line 39 already establishes the correct form (redis-cli LRANGE bq:pr-review:active 0 -1); this step should match it.

Suggested fix:

- `<jobId>` from `bq:pr-review:active`
+ `<jobId>` from `LRANGE bq:pr-review:active 0 -1`

Verdict

CONDITIONAL_APPROVE

---

_{hib-pr-reviewer • round 1 • 2 findings (2m) • 2026-06-03T09:44:50.512Z → 2026-06-03T09:48:36.983Z • posted-as: pr-reviewer-bot • model: auto}

<!-- hib-pr-reviewer collapsed --> > _Superseded by round 2._ <details> <summary>Show previous round</summary> <!-- hib-pr-reviewer round:1 --> ## hib-pr-reviewer review — PR #10 (hib/hib-pr-reviewer) **Round 1** — head `7c3cf0950aad`, base `main`, trigger `opened` **TL;DR:** CONDITIONAL_APPROVE — kept 2 agreed + verified minor findings (optional `arbiter` field presented as unconditional; missing LRANGE command); no blocking issues. ### Summary ## Arbitration Summary Both reviewers independently flagged the same two issues on line 146 of `docs/status-page.md`. I verified both against source before keeping them. **Verification results:** 1. **`arbiter` optionality** — `src/types/quorum.ts` line 87 confirms `arbiter?: ArbiterSnapshot` (optional). The module-level JSDoc (line 12) also annotates the hash schema as `{ a, b, arbiter? }`. The new doc text "expect `a`/`b`/`arbiter` state fields" presents all three as unconditionally present. **Confirmed — kept.** 2. **Missing LRANGE command** — `docs/forgejo-upgrade-runbook.md` line 39 confirms `bq:pr-review:active` is a Redis List key queried as `redis-cli LRANGE bq:pr-review:active 0 -1`. The new doc text only names the key without the command. **Confirmed — kept.** Severity reconciliation: A rated finding 2 as `info`, B as `minor`. The practical consequence (operator receives a `WRONGTYPE` error if they try `GET` or `SMEMBERS`) and the established pattern in the runbook both support `minor`. Promoted to `minor` to match B. Kept 2 agreed + verified findings. Dropped 0. ### Blast Radius Single documentation file changed (`docs/status-page.md`, +2/-1). No code, no exported interfaces, no Redis key schema changes. Impact is limited to operators reading this runbook section. **BLAST_SCORE: 1/10** ### CI status (head `7c3cf0950aad`) **Overall: ✓ success** 3 checks: 3 pending | Check | State | Link | |---|---|---| | pr-reviewer CI / tsc --noEmit (pull_request) | ⏳ pending | [details](/hib/hib-pr-reviewer/actions/runs/78/jobs/0) | | pr-reviewer CI / vitest (pull_request) | ⏳ pending | [details](/hib/hib-pr-reviewer/actions/runs/78/jobs/1) | | pr-reviewer CI / tsc build (pull_request) | ⏳ pending | [details](/hib/hib-pr-reviewer/actions/runs/78/jobs/2) | ### Findings (2) #### **[MINOR]** Verify step implies `arbiter` field is always present, but it is optional until arbitration begins _docs/status-page.md:146_ `src/types/quorum.ts` line 87 defines `arbiter?: ArbiterSnapshot` (optional) and line 12's JSDoc annotates the hash schema as `{ a, b, arbiter? }`. The field is written by `Arbiter.run` only after divergent legs trigger the arbiter phase. An operator running `HGETALL <prefix>:pr-reviewer:phase:quorum:<jobId>` during the parallel-leg phase will see only `a` and `b` — the current wording "expect `a`/`b`/`arbiter` state fields" gives no indication that two fields is healthy, risking a false alarm. Suggested fix: ```diff - (expect `a`/`b`/`arbiter` state fields) + (expect `a` + `b` fields; `arbiter` appears only after divergent legs trigger the arbiter phase) ``` #### **[MINOR]** Job-ID retrieval step names the key but omits the Redis command (`LRANGE`) _docs/status-page.md:146_ Line 146 instructs operators to get `<jobId>` from `` `bq:pr-review:active` `` without specifying the retrieval command. `bq:pr-review:active` is a BullMQ **List** key — the correct command is `LRANGE bq:pr-review:active 0 -1`. An operator who tries `GET` or `SMEMBERS` will receive a Redis `WRONGTYPE` error. `docs/forgejo-upgrade-runbook.md` line 39 already establishes the correct form (`redis-cli LRANGE bq:pr-review:active 0 -1`); this step should match it. Suggested fix: ```diff - `<jobId>` from `bq:pr-review:active` + `<jobId>` from `LRANGE bq:pr-review:active 0 -1` ``` ### Verdict **CONDITIONAL_APPROVE** --- _{hib-pr-reviewer • round 1 • 2 findings (2m) • 2026-06-03T09:44:50.512Z → 2026-06-03T09:48:36.983Z • posted-as: pr-reviewer-bot • model: auto} </details>

hibryda referenced this pull request from a commit 2026-06-03 11:49:31 +02:00

docs(status-page): arbiter field is divergence-only + add LRANGE for jobId

hibryda added 1 commit 2026-06-03 11:49:31 +02:00

docs(status-page): arbiter field is divergence-only + add LRANGE for jobId ... 7b1eae21a7

Address PR #10 review: the `arbiter` field in the phase:quorum hash appears
only when the legs diverge (arbitration begins), not always; and spell out the
redis-cli LRANGE command for retrieving the active jobId.

pr-reviewer-bot commented 2026-06-03 11:51:39 +02:00

Member

Copy link

hib-pr-reviewer review — PR #10 (hib/hib-pr-reviewer)

Round 2 — head 7b1eae21a72e, base main, trigger synchronize

TL;DR: NO_NEW_FINDINGS — both prior round-1 conditions satisfied; new verify sub-bullet is technically accurate against source.

Summary

[quorum-converged] A=0 = B=0. Both round-1 findings are resolved in this diff.

Finding 1 (arbiter optionality): The new sub-bullet now explicitly states "the arbiter field appears only once the legs diverge and arbitration begins" — operationally accurate and no longer implies the field is always present.

Finding 2 (LRANGE command): The new sub-bullet now supplies the full command: redis-cli LRANGE bq:pr-review:active 0 -1.

New content verified against source:

• Redis quorum key <prefix>:pr-reviewer:phase:quorum:<jobId> — confirmed by src/types/quorum.ts:12 (HASH { a, b, arbiter? }).
• Redis phase-active key <prefix>:pr-reviewer:phase:active:<jobId> — confirmed by src/phase.ts:27.
• tel* fields of <prefix>:pr-reviewer:health:engine-state — confirmed by src/health-state-mirror.ts:70-79 (telInputTokens, telOutputTokens, telCostUsd, telWindowInputTokens, etc.).
• BeeQueue active-list key bq:pr-review:active — confirmed by src/worker.ts:4306 and src/svelte-viewport/lib/queue-snapshot.ts:345.
• observeSdkMessageForTelemetry referenced for arbiter telemetry — function present in codebase (src/engine-telemetry.ts, src/reviewer.ts).

No new actionable issues found.

Blast Radius

One documentation file changed. No runtime code, configuration, or schema touched.

BLAST_SCORE: 0/10

CI status (head 7b1eae21a72e)

Overall: ✓ success

3 checks: 3 pending

Check	State	Link
pr-reviewer CI / tsc --noEmit (pull_request)	⏳ pending	details
pr-reviewer CI / vitest (pull_request)	⏳ pending	details
pr-reviewer CI / tsc build (pull_request)	⏳ pending	details

Findings

No new findings this round.

Quorum converged on empty findings (A + B both returned 0).

Verdict

NO_NEW_FINDINGS

---

_{hib-pr-reviewer • round 2 • 0 findings • 2026-06-03T09:49:32.774Z → 2026-06-03T09:51:39.518Z • posted-as: pr-reviewer-bot • model: auto}

<!-- hib-pr-reviewer round:2 --> ## hib-pr-reviewer review — PR #10 (hib/hib-pr-reviewer) **Round 2** — head `7b1eae21a72e`, base `main`, trigger `synchronize` **TL;DR:** NO_NEW_FINDINGS — both prior round-1 conditions satisfied; new verify sub-bullet is technically accurate against source. ### Summary [quorum-converged] A=0 = B=0. Both round-1 findings are resolved in this diff. **Finding 1 (arbiter optionality):** The new sub-bullet now explicitly states "the `arbiter` field appears only once the legs diverge and arbitration begins" — operationally accurate and no longer implies the field is always present. **Finding 2 (LRANGE command):** The new sub-bullet now supplies the full command: `redis-cli LRANGE bq:pr-review:active 0 -1`. **New content verified against source:** - Redis quorum key `<prefix>:pr-reviewer:phase:quorum:<jobId>` — confirmed by `src/types/quorum.ts:12` (`HASH { a, b, arbiter? }`). - Redis phase-active key `<prefix>:pr-reviewer:phase:active:<jobId>` — confirmed by `src/phase.ts:27`. - `tel*` fields of `<prefix>:pr-reviewer:health:engine-state` — confirmed by `src/health-state-mirror.ts:70-79` (`telInputTokens`, `telOutputTokens`, `telCostUsd`, `telWindowInputTokens`, etc.). - BeeQueue active-list key `bq:pr-review:active` — confirmed by `src/worker.ts:4306` and `src/svelte-viewport/lib/queue-snapshot.ts:345`. - `observeSdkMessageForTelemetry` referenced for arbiter telemetry — function present in codebase (`src/engine-telemetry.ts`, `src/reviewer.ts`). No new actionable issues found. ### Blast Radius One documentation file changed. No runtime code, configuration, or schema touched. **BLAST_SCORE: 0/10** ### CI status (head `7b1eae21a72e`) **Overall: ✓ success** 3 checks: 3 pending | Check | State | Link | |---|---|---| | pr-reviewer CI / tsc --noEmit (pull_request) | ⏳ pending | [details](/hib/hib-pr-reviewer/actions/runs/79/jobs/0) | | pr-reviewer CI / vitest (pull_request) | ⏳ pending | [details](/hib/hib-pr-reviewer/actions/runs/79/jobs/1) | | pr-reviewer CI / tsc build (pull_request) | ⏳ pending | [details](/hib/hib-pr-reviewer/actions/runs/79/jobs/2) | ### Findings **No new findings this round.** _Quorum converged on empty findings (A + B both returned 0)._ ### Verdict **NO_NEW_FINDINGS** --- _{hib-pr-reviewer • round 2 • 0 findings • 2026-06-03T09:49:32.774Z → 2026-06-03T09:51:39.518Z • posted-as: pr-reviewer-bot • model: auto}

hibryda merged commit 92b73e824a into main 2026-06-03 11:51:52 +02:00

hibryda deleted branch docs/distributed-reportability-verify-note 2026-06-03 11:51:52 +02:00

hibryda referenced this pull request from a commit 2026-06-03 11:51:52 +02:00

docs(status-page): operator steps to verify distributed reportability live (#10)

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

hib/hib-pr-reviewer!10

No description provided.