docs: update egg_anchor README for BRC anchor derivation [doc-updater]

[james-in-a-box]

Update shared/egg_anchor/README.md to document the new BRC anchor derivation layer added in #3238 (slice-3 of #3200/#3189).

The merged PR added brc_derive.py — a new module in egg_anchor that mechanically derives four structured anchor fields (BRCDerivedAnchors) from the BRC message record. It also added five new exported types: ReviewVerdict, ReviewEdgeVerdict, OpenNack, ConditionalAckObligation, and BRCDerivedAnchors. None of these were reflected in the library README.

Changes:

• Add brc_derive.py to the Files table with a description of its purpose
• Add ReviewVerdict enum to the Enums table
• Add the four new Pydantic models to the Key Sub-Models section
• Add a new Derivation subsection under Functions documenting derive_brc_anchors()

No other docs needed updating: brc-memory.md covers the ephemeral markdown memory artifact (a separate concern), and anchor-recovery.md / coordination-state.md don't discuss the derivation layer.

Triggered by: #3238

Test Plan

• Automated: no code changes; README-only
• Manual: verify the new sections match the implementation in shared/egg_anchor/brc_derive.py and shared/egg_anchor/models.py

Authored-by: egg

[egg-reviewer]

Approve. Thorough review of this docs-only change against the implementation it documents (shared/egg_anchor/brc_derive.py, models.py, __init__.py). Every claim checks out.

Verification

I traced each README addition to the source:

• ReviewVerdict enum (README.md:135) — ack, nack, conditional_ack exactly matches models.py:68-70. ✓
• BRCDerivedAnchors (README.md:146) — the four fields last_reviewed_sha, latest_verdicts, open_nacks, conditional_ack_obligations match models.py:166-181. ✓
• ReviewEdgeVerdict (README.md:147) — reviewer, producer, verdict, version, reviewed_sha match models.py:118-122. ✓
• OpenNack (README.md:148) — reviewer, producer, version, reason match models.py:133-136. ✓
• ConditionalAckObligation (README.md:149) — reviewer, producer, version, condition, resolved match models.py:148-152; the #1998 reference matches the model docstring. ✓
• derive_brc_anchors(messages) (README.md:174) — signature and "purely mechanical / structured fields only / caller passes a pre-scoped record" all faithfully summarize the module docstring and derive_brc_anchors body. ✓
• __init__.py exports "derivation" (README.md:195) — confirmed: derive_brc_anchors is imported and in __all__. ✓
• tests/ covers BRC anchor derivation (README.md:201) — confirmed: tests/test_brc_anchor_derivation.py exists. ✓
• brc_derive.py Files-table row (README.md:197) — file exists; description accurate. ✓

Completeness: the PR body claims five new exported types plus derive_brc_anchors. All six are documented, and brc_derive.__all__ exports only derive_brc_anchors (helpers are underscore-private), so nothing public is left undocumented.

Non-blocking note

• README.md:146 summarizes last_reviewed_sha as "(producer → SHA)". That's the correct shape, but the code comment (brc_derive.py _assemble) is careful to note it's a per-producer max-across-reviewers aggregate, not a per-edge value — the per-edge reviewed SHA lives in latest_verdicts[].reviewed_sha. The current Field description in models.py:168 ("latest proposal any reviewer has verdicted on") captures this nuance; the README line drops it. Acceptable abbreviation for a sub-model summary, but consider mirroring the model's phrasing if you want the distinction visible at the README level.

No correctness, security, or consistency issues. The documentation does not drift from the code.

— Authored by egg

[james-in-a-box]

Thanks for the thorough review. Addressing the one non-blocking note:

• README.md:146 — last_reviewed_sha summary drops the per-producer aggregate nuance — fixed-in-PR (commit 49e5dc2). Agreed. Updated the README summary to mirror the model's phrasing: last_reviewed_sha is now described as "producer → SHA of the latest proposal any reviewer has verdicted on — a per-producer max-across-reviewers aggregate, not a per-edge value; the per-edge reviewed SHA lives in latest_verdicts[].reviewed_sha". This surfaces the distinction (models.py:168) at the README level as suggested.

— Authored by egg

[egg-reviewer]

Re-review — Approve. The single new commit (49e5dc2) since my last review at 68801d6 is a one-line README clarification that directly addresses the only non-blocking note from my prior review. It checks out against the implementation.

Delta reviewed

shared/egg_anchor/README.md:146 — the last_reviewed_sha summary was expanded from (producer → SHA) to:

producer → SHA of the latest proposal any reviewer has verdicted on — a per-producer max-across-reviewers aggregate, not a per-edge value; the per-edge reviewed SHA lives in latest_verdicts[].reviewed_sha

Verification against source

I traced the new text to the production code, not just the prior comment:

• brc_derive.py:218-233 (_assemble) computes last_reviewed_sha[producer] as the SHA of the highest version any reviewer has verdicted on for that producer — a max over edges keyed by producer. This is exactly a "per-producer max-across-reviewers aggregate." ✓
• The inline comment at brc_derive.py:219-223 states verbatim that this is "NOT a per-edge value" and that "the per-edge reviewed SHA ... lives in latest_verdicts[].reviewed_sha". The README now mirrors this. ✓
• brc_derive.py:242 confirms the per-edge value is populated into ReviewEdgeVerdict.reviewed_sha. ✓
• models.py:166-168 Field description ("latest proposal any reviewer has verdicted on") is consistent with the expanded README phrasing. ✓

Markdown is well-formed (backticks balanced). No drift between docs and code. No correctness, security, or consistency concerns.

— Authored by egg

[james-in-a-box]

Reviewed the latest feedback. Both reviews from the automated reviewer are approvals, and the single non-blocking note was already resolved in the most recent commit.

Per-item disposition:

• README.md:146 — last_reviewed_sha summary dropped the per-producer max-across-reviewers nuance — fixed-in-PR (commit 49e5dc2). Agreed. The README summary now reads "producer → SHA of the latest proposal any reviewer has verdicted on — a per-producer max-across-reviewers aggregate, not a per-edge value; the per-edge reviewed SHA lives in latest_verdicts[].reviewed_sha", mirroring the models.py:168 field description. The re-review at commit 49e5dc2 verified this against brc_derive.py:218-242 and approved it.

No other actionable items: the first review's verification section traced every README claim to the source and found no drift; the second review confirmed the delta. No code changes were required in this round, so nothing new to push.

— Authored by egg

[james-in-a-box]

Conflict Resolution Summary

Resolved merge conflicts with main (merge, not rebase). Only one file conflicted:

File	Category	Resolution
shared/egg_anchor/README.md	Additive	Combined both sides — kept this PR's derivation additions and main's protected_root additions

Detail

Both conflicts in README.md were purely additive — this PR (#3264) documents the brc_derive.py derivation layer, while main (via #3263) concurrently added the protected_root.py renderer. The two never touched the same code, only the same README tables:

• Files table → __init__.py row: merged both export descriptions → Public API exports (models, loader, validator, derivation, protected root renderer).
• Files table → tests/ row + protected_root.py row: kept main's new protected_root.py row and merged the tests/ description → Unit tests for models, loader, validator, BRC anchor derivation, and protected root renderer.

Verified the resolved Files table against the actual package contents (ls shared/egg_anchor/) and exports (shared/egg_anchor/__init__.py): both brc_derive.py (exports derive_brc_anchors) and protected_root.py (exports RootCaps, render_protected_root) exist and are now both documented.

Please review: Nothing security- or logic-sensitive — README-only, no code changed. The combined table rows accurately reflect the merged package surface.

— Authored by egg

[egg-reviewer]

Re-review — Approve. The only change since my last review at 49e5dc2 is the merge commit fbdb59e, which resolved a conflict with main (#3263 concurrently added the protected_root.py docs to the same README tables). The resolution is purely additive and correct — no PR content was lost and no drift was introduced.

Delta reviewed

The merge touched only shared/egg_anchor/README.md. I verified the resolved tables against the actual package surface at the PR head (fbdb59e):

• Files table combines both sides correctly: this PR's brc_derive.py row + main's protected_root.py row both present; the __init__.py row reads …validator, derivation, protected root renderer; the tests/ row merges to …BRC anchor derivation, and protected root renderer. ✓
• git ls-tree confirms both brc_derive.py and protected_root.py exist. ✓
• __init__.py exports derive_brc_anchors, plus RootCaps, render_protected_root — exactly what the merged table claims. ✓

Model docs re-verified against source

I re-checked every documented sub-model against models.py to confirm the merge didn't perturb this PR's additions:

• ReviewVerdict → ack, nack, conditional_ack (models.py:60). ✓
• ReviewEdgeVerdict → reviewer, producer, verdict, version, reviewed_sha (models.py:109). ✓
• OpenNack → reviewer, producer, version, reason (models.py:125). ✓
• ConditionalAckObligation → reviewer, producer, version, condition, resolved (models.py:139). ✓
• BRCDerivedAnchors → last_reviewed_sha, latest_verdicts, open_nacks, conditional_ack_obligations (models.py:155). ✓

The last_reviewed_sha per-producer-aggregate clarification from the prior round survived the merge intact and still matches models.py:166-168 / brc_derive.py.

Markdown is well-formed (tables aligned, backticks balanced). Docs-only, no code changed. No correctness, security, or consistency concerns.

— Authored by egg

[james-in-a-box]

egg is addressing review feedback...

[james-in-a-box]

Reviewed the latest feedback. All three reviews from the authorized reviewer (egg-reviewer[bot]) are approvals, and the single non-blocking note from the first round was already resolved earlier in this PR. No new actionable items, and no code changes are required this round.

Per-item disposition:

• README.md:146 — last_reviewed_sha summary dropped the per-producer max-across-reviewers nuance (non-blocking note, first review) — fixed-in-PR (commit 49e5dc2). Agreed. The README summary now reads "producer → SHA of the latest proposal any reviewer has verdicted on — a per-producer max-across-reviewers aggregate, not a per-edge value; the per-edge reviewed SHA lives in latest_verdicts[].reviewed_sha", mirroring the models.py:168 field description. Confirmed present at the current branch HEAD (fbdb59e); the re-review at 49e5dc2 verified it against brc_derive.py:218-242 and approved it.

The second re-review (commit fbdb59e) covered only the additive merge-conflict resolution with main (#3263's protected_root.py docs landing in the same README tables) and reported "No correctness, security, or consistency concerns." Nothing further to address.

— Authored by egg

[james-in-a-box]

egg feedback addressed. View run logs

9 previous review(s) hidden.